client

package
v2.1.0-rc.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 29, 2015 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package client provides bindings for the etcd APIs.

Create a Config and exchange it for a Client: 

import (
	"net/http"

	"github.com/coreos/etcd/client"
	"golang.org/x/net/context"
)

cfg := client.Config{
	Endpoints: []string{"http://127.0.0.1:2379"},
	Transport: DefaultTransport,
}

c, err := client.New(cfg)
if err != nil {
	// handle error
}

Create a KeysAPI using the Client, then use it to interact with etcd: 

kAPI := client.NewKeysAPI(c)

// create a new key /foo with the value "bar"
_, err = kAPI.Create(context.Background(), "/foo", "bar")
if err != nil {
	// handle error
}

// delete the newly created key only if the value is still "bar"
_, err = kAPI.Delete(context.Background(), "/foo", &DeleteOptions{PrevValue: "bar"})
if err != nil {
	// handle error
}

Use a custom context to set timeouts on your operations: 

import "time"

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

// set a new key, ignoring it's previous state
_, err := kAPI.Set(ctx, "/ping", "pong", nil)
if err != nil {
	if err == context.DeadlineExceeded {
		// request took longer than 5s
	} else {
		// handle error
	}
}

Index

Constants

View Source 
const (
	ErrorCodeKeyNotFound = 100
	ErrorCodeTestFailed  = 101
	ErrorCodeNotFile     = 102
	ErrorCodeNotDir      = 104
	ErrorCodeNodeExist   = 105
	ErrorCodeRootROnly   = 107
	ErrorCodeDirNotEmpty = 108

	ErrorCodePrevValueRequired = 201
	ErrorCodeTTLNaN            = 202
	ErrorCodeIndexNaN          = 203
	ErrorCodeInvalidField      = 209
	ErrorCodeInvalidForm       = 210

	ErrorCodeRaftInternal = 300
	ErrorCodeLeaderElect  = 301

	ErrorCodeWatcherCleared    = 400
	ErrorCodeEventIndexCleared = 401
)
View Source 
const (
	PrevIgnore  = PrevExistType("")
	PrevExist   = PrevExistType("true")
	PrevNoExist = PrevExistType("false")
)

Variables

View Source 
var (
	ErrNoEndpoints      = errors.New("client: no endpoints available")
	ErrTooManyRedirects = errors.New("client: too many redirects")
)
View Source 
var DefaultRequestTimeout = 5 * time.Second

Functions

func DisablecURLDebug added in v2.1.0 

func DisablecURLDebug()

func EnablecURLDebug added in v2.1.0 

func EnablecURLDebug()

Types

type AuthAPI added in v2.1.0 

type AuthAPI interface {
	// Enable auth.
	Enable(ctx context.Context) error

	// Disable auth.
	Disable(ctx context.Context) error
}

func NewAuthAPI added in v2.1.0 

func NewAuthAPI(c Client) AuthAPI

NewAuthAPI constructs a new AuthAPI that uses HTTP to interact with etcd's general auth features.

type AuthRoleAPI added in v2.1.0 

type AuthRoleAPI interface {
	// Add a role.
	AddRole(ctx context.Context, role string) error

	// Remove a role.
	RemoveRole(ctx context.Context, role string) error

	// Get role details.
	GetRole(ctx context.Context, role string) (*Role, error)

	// Grant a role some permission prefixes for the KV store.
	GrantRoleKV(ctx context.Context, role string, prefixes []string, permType PermissionType) (*Role, error)

	// Revoke some some permission prefixes for a role on the KV store.
	RevokeRoleKV(ctx context.Context, role string, prefixes []string, permType PermissionType) (*Role, error)

	// List roles.
	ListRoles(ctx context.Context) ([]string, error)
}

func NewAuthRoleAPI added in v2.1.0 

func NewAuthRoleAPI(c Client) AuthRoleAPI

NewAuthRoleAPI constructs a new AuthRoleAPI that uses HTTP to interact with etcd's role creation and modification features.

type AuthUserAPI added in v2.1.0 

type AuthUserAPI interface {
	// Add a user.
	AddUser(ctx context.Context, username string, password string) error

	// Remove a user.
	RemoveUser(ctx context.Context, username string) error

	// Get user details.
	GetUser(ctx context.Context, username string) (*User, error)

	// Grant a user some permission roles.
	GrantUser(ctx context.Context, username string, roles []string) (*User, error)

	// Revoke some permission roles from a user.
	RevokeUser(ctx context.Context, username string, roles []string) (*User, error)

	// Change the user's password.
	ChangePassword(ctx context.Context, username string, password string) (*User, error)

	// List users.
	ListUsers(ctx context.Context) ([]string, error)
}

func NewAuthUserAPI added in v2.1.0 

func NewAuthUserAPI(c Client) AuthUserAPI

NewAuthUserAPI constructs a new AuthUserAPI that uses HTTP to interact with etcd's user creation and modification features.

type CancelableTransport 

type CancelableTransport interface {
	http.RoundTripper
	CancelRequest(req *http.Request)
}

CancelableTransport mimics net/http.Transport, but requires that the object also support request cancellation. 

var DefaultTransport CancelableTransport = &http.Transport{
	Proxy: http.ProxyFromEnvironment,
	Dial: (&net.Dialer{
		Timeout:   30 * time.Second,
		KeepAlive: 30 * time.Second,
	}).Dial,
	TLSHandshakeTimeout: 10 * time.Second,
}

type CheckRedirectFunc added in v2.1.0 

type CheckRedirectFunc func(via int) error
var DefaultCheckRedirect CheckRedirectFunc = func(via int) error {
	if via > 10 {
		return ErrTooManyRedirects
	}
	return nil
}

DefaultCheckRedirect follows up to 10 redirects, but no more.

type Client added in v2.1.0 

type Client interface {
	// Sync updates the internal cache of the etcd cluster's membership.
	Sync(context.Context) error

	// Endpoints returns a copy of the current set of API endpoints used
	// by Client to resolve HTTP requests. If Sync has ever been called,
	// this may differ from the initial Endpoints provided in the Config.
	Endpoints() []string
	// contains filtered or unexported methods
}

func New added in v2.1.0 

func New(cfg Config) (Client, error)

type Config added in v2.1.0 

type Config struct {
	// Endpoints defines a set of URLs (schemes, hosts and ports only)
	// that can be used to communicate with a logical etcd cluster. For
	// example, a three-node cluster could be provided like so:
	//
	// 	Endpoints: []string{
	//		"http://node1.example.com:2379",
	//		"http://node2.example.com:2379",
	//		"http://node3.example.com:2379",
	//	}
	//
	// If multiple endpoints are provided, the Client will attempt to
	// use them all in the event that one or more of them are unusable.
	//
	// If Client.Sync is ever called, the Client may cache an alternate
	// set of endpoints to continue operation.
	Endpoints []string

	// Transport is used by the Client to drive HTTP requests. If not
	// provided, DefaultTransport will be used.
	Transport CancelableTransport

	// CheckRedirect specifies the policy for handling HTTP redirects.
	// If CheckRedirect is not nil, the Client calls it before
	// following an HTTP redirect. The sole argument is the number of
	// requests that have alrady been made. If CheckRedirect returns
	// an error, Client.Do will not make any further requests and return
	// the error back it to the caller.
	//
	// If CheckRedirect is nil, the Client uses its default policy,
	// which is to stop after 10 consecutive requests.
	CheckRedirect CheckRedirectFunc

	// Username specifies the user credential to add as an authorization header
	Username string

	// Password is the password for the specified user to add as an authorization header
	// to the request.
	Password string
}

type CreateInOrderOptions added in v2.1.0 

type CreateInOrderOptions struct {
	// TTL defines a period of time after-which the Node should
	// expire and no longer exist. Values <= 0 are ignored. Given
	// that the zero-value is ignored, TTL cannot be used to set
	// a TTL of 0.
	TTL time.Duration
}

type DeleteOptions added in v2.1.0 

type DeleteOptions struct {
	// PrevValue specifies what the current value of the Node must
	// be in order for the Delete operation to succeed.
	//
	// Leaving this field empty means that the caller wishes to
	// ignore the current value of the Node. This cannot be used
	// to compare the Node's current value to an empty string.
	PrevValue string

	// PrevIndex indicates what the current ModifiedIndex of the
	// Node must be in order for the Delete operation to succeed.
	//
	// If PrevIndex is set to 0 (default), no comparison is made.
	PrevIndex uint64

	// Recursive defines whether or not all children of the Node
	// should be deleted. If set to true, all children of the Node
	// identified by the given key will be deleted. If left unset
	// or explicitly set to false, only a single Node will be
	// deleted.
	Recursive bool
}

type Discoverer added in v2.1.0 

type Discoverer interface {
	// Dicover looks up the etcd servers for the domain.
	Discover(domain string) ([]string, error)
}

Discoverer is an interface that wraps the Discover method.

func NewSRVDiscover added in v2.1.0 

func NewSRVDiscover() Discoverer

NewSRVDiscover constructs a new Dicoverer that uses the stdlib to lookup SRV records.

type Error added in v2.1.0 

type Error struct {
	Code    int    `json:"errorCode"`
	Message string `json:"message"`
	Cause   string `json:"cause"`
	Index   uint64 `json:"index"`
}

func (Error) Error added in v2.1.0 

func (e Error) Error() string

type GetOptions added in v2.1.0 

type GetOptions struct {
	// Recursive defines whether or not all children of the Node
	// should be returned.
	Recursive bool

	// Sort instructs the server whether or not to sort the Nodes.
	// If true, the Nodes are sorted alphabetically by key in
	// ascending order (A to z). If false (default), the Nodes will
	// not be sorted and the ordering used should not be considered
	// predictable.
	Sort bool
}

type KeysAPI 

type KeysAPI interface {
	// Get retrieves a set of Nodes from etcd
	Get(ctx context.Context, key string, opts *GetOptions) (*Response, error)

	// Set assigns a new value to a Node identified by a given key. The caller
	// may define a set of conditions in the SetOptions. If SetOptions.Dir=true
	// than value is ignored.
	Set(ctx context.Context, key, value string, opts *SetOptions) (*Response, error)

	// Delete removes a Node identified by the given key, optionally destroying
	// all of its children as well. The caller may define a set of required
	// conditions in an DeleteOptions object.
	Delete(ctx context.Context, key string, opts *DeleteOptions) (*Response, error)

	// Create is an alias for Set w/ PrevExist=false
	Create(ctx context.Context, key, value string) (*Response, error)

	// CreateInOrder is used to atomically create in-order keys within the given directory.
	CreateInOrder(ctx context.Context, dir, value string, opts *CreateInOrderOptions) (*Response, error)

	// Update is an alias for Set w/ PrevExist=true
	Update(ctx context.Context, key, value string) (*Response, error)

	// Watcher builds a new Watcher targeted at a specific Node identified
	// by the given key. The Watcher may be configured at creation time
	// through a WatcherOptions object. The returned Watcher is designed
	// to emit events that happen to a Node, and optionally to its children.
	Watcher(key string, opts *WatcherOptions) Watcher
}

func NewKeysAPI 

func NewKeysAPI(c Client) KeysAPI

NewKeysAPI builds a KeysAPI that interacts with etcd's key-value API over HTTP.

func NewKeysAPIWithPrefix added in v2.1.0 

func NewKeysAPIWithPrefix(c Client, p string) KeysAPI

NewKeysAPIWithPrefix acts like NewKeysAPI, but allows the caller to provide a custom base URL path. This should only be used in very rare cases.

type Member added in v2.1.0 

type Member struct {
	// ID is the unique identifier of this Member.
	ID string `json:"id"`

	// Name is a human-readable, non-unique identifier of this Member.
	Name string `json:"name"`

	// PeerURLs represents the HTTP(S) endpoints this Member uses to
	// participate in etcd's consensus protocol.
	PeerURLs []string `json:"peerURLs"`

	// ClientURLs represents the HTTP(S) endpoints on which this Member
	// serves it's client-facing APIs.
	ClientURLs []string `json:"clientURLs"`
}

type MembersAPI 

type MembersAPI interface {
	// List enumerates the current cluster membership.
	List(ctx context.Context) ([]Member, error)

	// Add instructs etcd to accept a new Member into the cluster.
	Add(ctx context.Context, peerURL string) (*Member, error)

	// Remove demotes an existing Member out of the cluster.
	Remove(ctx context.Context, mID string) error
}

func NewMembersAPI 

func NewMembersAPI(c Client) MembersAPI

NewMembersAPI constructs a new MembersAPI that uses HTTP to interact with etcd's membership API.

type Node 

type Node struct {
	// Key represents the unique location of this Node (e.g. "/foo/bar").
	Key string `json:"key"`

	// Dir reports whether node describes a directory.
	Dir bool `json:"dir,omitempty"`

	// Value is the current data stored on this Node. If this Node
	// is a directory, Value will be empty.
	Value string `json:"value"`

	// Nodes holds the children of this Node, only if this Node is a directory.
	// This slice of will be arbitrarily deep (children, grandchildren, great-
	// grandchildren, etc.) if a recursive Get or Watch request were made.
	Nodes []*Node `json:"nodes"`

	// CreatedIndex is the etcd index at-which this Node was created.
	CreatedIndex uint64 `json:"createdIndex"`

	// ModifiedIndex is the etcd index at-which this Node was last modified.
	ModifiedIndex uint64 `json:"modifiedIndex"`

	// Expiration is the server side expiration time of the key.
	Expiration *time.Time `json:"expiration,omitempty"`

	// TTL is the time to live of the key in second.
	TTL int64 `json:"ttl,omitempty"`
}

func (*Node) String 

func (n *Node) String() string

func (*Node) TTLDuration added in v2.1.0 

func (n *Node) TTLDuration() time.Duration

TTLDuration returns the Node's TTL as a time.Duration object

type PermissionType added in v2.1.0 

type PermissionType int
const (
	ReadPermission PermissionType = iota
	WritePermission
	ReadWritePermission
)

type Permissions added in v2.1.0 

type Permissions struct {
	KV rwPermission `json:"kv"`
}

type PrevExistType added in v2.1.0 

type PrevExistType string

PrevExistType is used to define an existence condition when setting or deleting Nodes.

type Response 

type Response struct {
	// Action is the name of the operation that occurred. Possible values
	// include get, set, delete, update, create, compareAndSwap,
	// compareAndDelete and expire.
	Action string `json:"action"`

	// Node represents the state of the relevant etcd Node.
	Node *Node `json:"node"`

	// PrevNode represents the previous state of the Node. PrevNode is non-nil
	// only if the Node existed before the action occured and the action
	// caused a change to the Node.
	PrevNode *Node `json:"prevNode"`

	// Index holds the cluster-level index at the time the Response was generated.
	// This index is not tied to the Node(s) contained in this Response.
	Index uint64 `json:"-"`
}

type Role added in v2.1.0 

type Role struct {
	Role        string       `json:"role"`
	Permissions Permissions  `json:"permissions"`
	Grant       *Permissions `json:"grant,omitempty"`
	Revoke      *Permissions `json:"revoke,omitempty"`
}

type SetOptions added in v2.1.0 

type SetOptions struct {
	// PrevValue specifies what the current value of the Node must
	// be in order for the Set operation to succeed.
	//
	// Leaving this field empty means that the caller wishes to
	// ignore the current value of the Node. This cannot be used
	// to compare the Node's current value to an empty string.
	//
	// PrevValue is ignored if Dir=true
	PrevValue string

	// PrevIndex indicates what the current ModifiedIndex of the
	// Node must be in order for the Set operation to succeed.
	//
	// If PrevIndex is set to 0 (default), no comparison is made.
	PrevIndex uint64

	// PrevExist specifies whether the Node must currently exist
	// (PrevExist) or not (PrevNoExist). If the caller does not
	// care about existence, set PrevExist to PrevIgnore, or simply
	// leave it unset.
	PrevExist PrevExistType

	// TTL defines a period of time after-which the Node should
	// expire and no longer exist. Values <= 0 are ignored. Given
	// that the zero-value is ignored, TTL cannot be used to set
	// a TTL of 0.
	TTL time.Duration

	// Dir specifies whether or not this Node should be created as a directory.
	Dir bool
}

type User added in v2.1.0 

type User struct {
	User     string   `json:"user"`
	Password string   `json:"password,omitempty"`
	Roles    []string `json:"roles"`
	Grant    []string `json:"grant,omitempty"`
	Revoke   []string `json:"revoke,omitempty"`
}

type Watcher 

type Watcher interface {
	// Next blocks until an etcd event occurs, then returns a Response
	// represeting that event. The behavior of Next depends on the
	// WatcherOptions used to construct the Watcher. Next is designed to
	// be called repeatedly, each time blocking until a subsequent event
	// is available.
	//
	// If the provided context is cancelled, Next will return a non-nil
	// error. Any other failures encountered while waiting for the next
	// event (connection issues, deserialization failures, etc) will
	// also result in a non-nil error.
	Next(context.Context) (*Response, error)
}

type WatcherOptions added in v2.1.0 

type WatcherOptions struct {
	// AfterIndex defines the index after-which the Watcher should
	// start emitting events. For example, if a value of 5 is
	// provided, the first event will have an index >= 6.
	//
	// Setting AfterIndex to 0 (default) means that the Watcher
	// should start watching for events starting at the current
	// index, whatever that may be.
	AfterIndex uint64

	// Recursive specifices whether or not the Watcher should emit
	// events that occur in children of the given keyspace. If set
	// to false (default), events will be limited to those that
	// occur for the exact key.
	Recursive bool
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.