Documentation

Index

Constants

View Source
const (
	// Using strings rather than iota because the consistency level
	// could be persisted to disk, so it'd be better to use
	// human-readable values.
	STRONG_CONSISTENCY = "STRONG"
	WEAK_CONSISTENCY   = "WEAK"
)

    See SetConsistency for how to use these constants.

    View Source
    const (
    	ErrCodeEtcdNotReachable = 501
    )

    Variables

    View Source
    var (
    	VALID_GET_OPTIONS = validOptions{
    		"recursive":  reflect.Bool,
    		"consistent": reflect.Bool,
    		"sorted":     reflect.Bool,
    		"wait":       reflect.Bool,
    		"waitIndex":  reflect.Uint64,
    	}
    
    	VALID_PUT_OPTIONS = validOptions{
    		"prevValue": reflect.String,
    		"prevIndex": reflect.Uint64,
    		"prevExist": reflect.Bool,
    		"dir":       reflect.Bool,
    	}
    
    	VALID_POST_OPTIONS = validOptions{}
    
    	VALID_DELETE_OPTIONS = validOptions{
    		"recursive": reflect.Bool,
    		"dir":       reflect.Bool,
    		"prevValue": reflect.String,
    		"prevIndex": reflect.Uint64,
    	}
    )

      Valid options for GET, PUT, POST, DELETE Using CAPITALIZED_UNDERSCORE to emphasize that these values are meant to be used as constants.

      View Source
      var (
      	ErrWatchStoppedByUser = errors.New("Watch stopped by the user via stop channel")
      )

        Errors introduced by the Watch command.

        Functions

        func SetLogger

        func SetLogger(log Logger)

        Types

        type Client

        type Client struct {
        	// contains filtered or unexported fields
        }

        func NewClient

        func NewClient(machines []string) *Client

          NewClient create a basic client that is configured to be used with the given machine list.

          func NewClientFromFile

          func NewClientFromFile(fpath string) (*Client, error)

            NewClientFromFile creates a client from a given file path. The given file is expected to use the JSON format.

            func NewClientFromReader

            func NewClientFromReader(reader io.Reader) (*Client, error)

              NewClientFromReader creates a Client configured from a given reader. The configuration is expected to use the JSON format.

              func NewTLSClient

              func NewTLSClient(machines []string, cert, key, caCert string) (*Client, error)

                NewTLSClient create a basic client with TLS configuration

                func (*Client) AddChild

                func (c *Client) AddChild(key string, value string, ttl uint64) (*Response, error)

                  Add a new file with a random etcd-generated key under the given path.

                  func (*Client) AddChildDir

                  func (c *Client) AddChildDir(key string, ttl uint64) (*Response, error)

                    Add a new directory with a random etcd-generated key under the given path.

                    func (*Client) AddRootCA

                    func (c *Client) AddRootCA(caCert string) error

                      AddRootCA adds a root CA cert for the etcd client

                      func (*Client) CloseCURL

                      func (c *Client) CloseCURL()

                      func (*Client) CompareAndDelete

                      func (c *Client) CompareAndDelete(key string, prevValue string, prevIndex uint64) (*Response, error)

                      func (*Client) CompareAndSwap

                      func (c *Client) CompareAndSwap(key string, value string, ttl uint64,
                      	prevValue string, prevIndex uint64) (*Response, error)

                      func (*Client) Create

                      func (c *Client) Create(key string, value string, ttl uint64) (*Response, error)

                        Create creates a file with the given value under the given key. It succeeds only if the given key does not yet exist.

                        func (*Client) CreateDir

                        func (c *Client) CreateDir(key string, ttl uint64) (*Response, error)

                          CreateDir creates a directory. It succeeds only if the given key does not yet exist.

                          func (*Client) Delete

                          func (c *Client) Delete(key string, recursive bool) (*Response, error)

                            Delete deletes the given key.

                            When recursive set to false, if the key points to a directory the method will fail.

                            When recursive set to true, if the key points to a file, the file will be deleted; if the key points to a directory, then everything under the directory (including all child directories) will be deleted.

                            func (*Client) DeleteDir

                            func (c *Client) DeleteDir(key string) (*Response, error)

                              DeleteDir deletes an empty directory or a key value pair

                              func (*Client) Get

                              func (c *Client) Get(key string, sort, recursive bool) (*Response, error)

                                Get gets the file or directory associated with the given key. If the key points to a directory, files and directories under it will be returned in sorted or unsorted order, depending on the sort flag. If recursive is set to false, contents under child directories will not be returned. If recursive is set to true, all the contents will be returned.

                                func (*Client) GetCluster

                                func (c *Client) GetCluster() []string

                                func (*Client) MarshalJSON

                                func (c *Client) MarshalJSON() ([]byte, error)

                                  MarshalJSON implements the Marshaller interface as defined by the standard JSON package.

                                  func (*Client) OpenCURL

                                  func (c *Client) OpenCURL()

                                  func (*Client) RawCompareAndDelete

                                  func (c *Client) RawCompareAndDelete(key string, prevValue string, prevIndex uint64) (*RawResponse, error)

                                  func (*Client) RawCompareAndSwap

                                  func (c *Client) RawCompareAndSwap(key string, value string, ttl uint64,
                                  	prevValue string, prevIndex uint64) (*RawResponse, error)

                                  func (*Client) RawCreate

                                  func (c *Client) RawCreate(key string, value string, ttl uint64) (*RawResponse, error)

                                  func (*Client) RawCreateDir

                                  func (c *Client) RawCreateDir(key string, ttl uint64) (*RawResponse, error)

                                  func (*Client) RawDelete

                                  func (c *Client) RawDelete(key string, recursive bool, dir bool) (*RawResponse, error)

                                  func (*Client) RawGet

                                  func (c *Client) RawGet(key string, sort, recursive bool) (*RawResponse, error)

                                  func (*Client) RawSet

                                  func (c *Client) RawSet(key string, value string, ttl uint64) (*RawResponse, error)

                                  func (*Client) RawSetDir

                                  func (c *Client) RawSetDir(key string, ttl uint64) (*RawResponse, error)

                                  func (*Client) RawUpdate

                                  func (c *Client) RawUpdate(key string, value string, ttl uint64) (*RawResponse, error)

                                  func (*Client) RawUpdateDir

                                  func (c *Client) RawUpdateDir(key string, ttl uint64) (*RawResponse, error)

                                  func (*Client) RawWatch

                                  func (c *Client) RawWatch(prefix string, waitIndex uint64, recursive bool,
                                  	receiver chan *RawResponse, stop chan bool) (*RawResponse, error)

                                  func (*Client) RecvCURL

                                  func (c *Client) RecvCURL() string

                                  func (*Client) Set

                                  func (c *Client) Set(key string, value string, ttl uint64) (*Response, error)

                                    Set sets the given key to the given value. It will create a new key value pair or replace the old one. It will not replace a existing directory.

                                    func (*Client) SetCluster

                                    func (c *Client) SetCluster(machines []string) bool

                                      SetCluster updates cluster information using the given machine list.

                                      func (*Client) SetConsistency

                                      func (c *Client) SetConsistency(consistency string) error

                                        SetConsistency changes the consistency level of the client.

                                        When consistency is set to STRONG_CONSISTENCY, all requests, including GET, are sent to the leader. This means that, assuming the absence of leader failures, GET requests are guaranteed to see the changes made by previous requests.

                                        When consistency is set to WEAK_CONSISTENCY, other requests are still sent to the leader, but GET requests are sent to a random server from the server pool. This reduces the read load on the leader, but it's not guaranteed that the GET requests will see changes made by previous requests (they might have not yet been committed on non-leader servers).

                                        func (*Client) SetDir

                                        func (c *Client) SetDir(key string, ttl uint64) (*Response, error)

                                          Set sets the given key to a directory. It will create a new directory or replace the old key value pair by a directory. It will not replace a existing directory.

                                          func (*Client) SetKeyPrefix

                                          func (c *Client) SetKeyPrefix(prefix string)

                                            SetKeyPrefix changes the key prefix from the default `/v2/keys` to whatever is set.

                                            func (*Client) SetPersistence

                                            func (c *Client) SetPersistence(writer io.Writer)

                                              SetPersistence sets a writer to which the config will be written every time it's changed.

                                              func (*Client) SetTransport

                                              func (c *Client) SetTransport(tr *http.Transport)

                                                Override the Client's HTTP Transport object

                                                func (*Client) SyncCluster

                                                func (c *Client) SyncCluster() bool

                                                  SyncCluster updates the cluster information using the internal machine list.

                                                  func (*Client) UnmarshalJSON

                                                  func (c *Client) UnmarshalJSON(b []byte) error

                                                    UnmarshalJSON implements the Unmarshaller interface as defined by the standard JSON package.

                                                    func (*Client) Update

                                                    func (c *Client) Update(key string, value string, ttl uint64) (*Response, error)

                                                      Update updates the given key to the given value. It succeeds only if the given key already exists.

                                                      func (*Client) UpdateDir

                                                      func (c *Client) UpdateDir(key string, ttl uint64) (*Response, error)

                                                        UpdateDir updates the given directory. It succeeds only if the given key already exists.

                                                        func (*Client) Watch

                                                        func (c *Client) Watch(prefix string, waitIndex uint64, recursive bool,
                                                        	receiver chan *Response, stop chan bool) (*Response, error)

                                                          If recursive is set to true the watch returns the first change under the given prefix since the given index.

                                                          If recursive is set to false the watch returns the first change to the given key since the given index.

                                                          To watch for the latest change, set waitIndex = 0.

                                                          If a receiver channel is given, it will be a long-term watch. Watch will block at the channel. After someone receives the channel, it will go on to watch that prefix. If a stop channel is given, the client can close long-term watch using the stop channel.

                                                          type Cluster

                                                          type Cluster struct {
                                                          	Leader   string   `json:"leader"`
                                                          	Machines []string `json:"machines"`
                                                          }

                                                          func NewCluster

                                                          func NewCluster(machines []string) *Cluster

                                                          type Config

                                                          type Config struct {
                                                          	CertFile    string        `json:"certFile"`
                                                          	KeyFile     string        `json:"keyFile"`
                                                          	CaCertFile  []string      `json:"caCertFiles"`
                                                          	Timeout     time.Duration `json:"timeout"`
                                                          	Consistency string        `json: "consistency"`
                                                          }

                                                          type EtcdError

                                                          type EtcdError struct {
                                                          	ErrorCode int    `json:"errorCode"`
                                                          	Message   string `json:"message"`
                                                          	Cause     string `json:"cause,omitempty"`
                                                          	Index     uint64 `json:"index"`
                                                          }

                                                          func (EtcdError) Error

                                                          func (e EtcdError) Error() string

                                                          type Logger

                                                          type Logger interface {
                                                          	Debug(args ...interface{})
                                                          	Debugf(fmt string, args ...interface{})
                                                          	Warning(args ...interface{})
                                                          	Warningf(fmt string, args ...interface{})
                                                          }

                                                          func GetLogger

                                                          func GetLogger() Logger

                                                          type Node

                                                          type Node struct {
                                                          	Key           string     `json:"key, omitempty"`
                                                          	Value         string     `json:"value,omitempty"`
                                                          	Dir           bool       `json:"dir,omitempty"`
                                                          	Expiration    *time.Time `json:"expiration,omitempty"`
                                                          	TTL           int64      `json:"ttl,omitempty"`
                                                          	Nodes         Nodes      `json:"nodes,omitempty"`
                                                          	ModifiedIndex uint64     `json:"modifiedIndex,omitempty"`
                                                          	CreatedIndex  uint64     `json:"createdIndex,omitempty"`
                                                          }

                                                          type Nodes

                                                          type Nodes []Node

                                                          func (Nodes) Len

                                                          func (ns Nodes) Len() int

                                                            interfaces for sorting

                                                            func (Nodes) Less

                                                            func (ns Nodes) Less(i, j int) bool

                                                            func (Nodes) Swap

                                                            func (ns Nodes) Swap(i, j int)

                                                            type RawResponse

                                                            type RawResponse struct {
                                                            	StatusCode int
                                                            	Body       []byte
                                                            	Header     http.Header
                                                            }

                                                            type Response

                                                            type Response struct {
                                                            	Action    string `json:"action"`
                                                            	Node      *Node  `json:"node"`
                                                            	PrevNode  *Node  `json:"prevNode,omitempty"`
                                                            	EtcdIndex uint64 `json:"etcdIndex"`
                                                            	RaftIndex uint64 `json:"raftIndex"`
                                                            	RaftTerm  uint64 `json:"raftTerm"`
                                                            }