client

package
v0.11.0 Latest Latest
Warning

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

 Go to latest Published: Dec 4, 2024 License: Apache-2.0 Imports: 24 Imported by: 3

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ErrorIsRetryable added in v0.6.0 

func ErrorIsRetryable(err error) bool

Returns whether an error returned by etcd is probably transient and the operation should be retried

func KeyIsPresent added in v0.5.0 

func KeyIsPresent(key string, presence bool) clientv3.Cmp

func KeyValueIsCmp added in v0.5.0 

func KeyValueIsCmp(key string, cmp string, value string) clientv3.Cmp

func KeyVersionIsCmp added in v0.5.0 

func KeyVersionIsCmp(key string, cmp string, value int64) clientv3.Cmp

Types

type AcquireLockOptions 

type AcquireLockOptions struct {
	Key             string
	Ttl             int64
	Timeout         time.Duration
	RetryInterval   time.Duration
	ExtraConditions []clientv3.Cmp
}

type ChunkedKeyInfo added in v0.5.0 

type ChunkedKeyInfo struct {
	Size    int64
	Count   int64
	Version int64
}

type ChunkedKeyPayload added in v0.5.0 

type ChunkedKeyPayload struct {
	Key   string
	Value io.ReadCloser
	Size  int64
}

func (*ChunkedKeyPayload) Close added in v0.5.0 

func (p *ChunkedKeyPayload) Close() error

func (*ChunkedKeyPayload) Read added in v0.5.0 

func (p *ChunkedKeyPayload) Read(r []byte) (n int, err error)

type ChunkedKeySnapshot added in v0.5.0 

type ChunkedKeySnapshot struct {
	Info     ChunkedKeyInfo
	Revision int64
}

type ChunksReader 

type ChunksReader struct {
	Client   *EtcdClient
	Key      string
	Index    int64
	Buffer   *bytes.Buffer
	Snapshot ChunkedKeySnapshot
}

func (*ChunksReader) Close 

func (r *ChunksReader) Close() error

func (*ChunksReader) Read 

func (r *ChunksReader) Read(p []byte) (n int, err error)

type EtcdClient 

type EtcdClient struct {
	Client         *clientv3.Client
	Retries        uint64
	RetryInterval  time.Duration
	RequestTimeout time.Duration
	Context        context.Context
	// contains filtered or unexported fields
}

Etcd client with simple interface for retries and timeouts. It should be instanciated with the Connect function.

func Connect 

func Connect(ctx context.Context, opts EtcdClientOptions) (*EtcdClient, error)

Entrypoint function to try connect to the etcd cluster and return a client.

func (*EtcdClient) AcquireLock 

func (cli *EtcdClient) AcquireLock(opts AcquireLockOptions) (*Lock, bool, error)

func (*EtcdClient) ApplyDiffToPrefix 

func (cli *EtcdClient) ApplyDiffToPrefix(prefix string, diff KeyDiff) error

Applies the operation predicated by KeyDiff argument on all the keys prefixed with a given value. Note that all the keys referenced in the KeyDiff structure are assumed to be relative keys without the prefix. As such, the prefix will be prepended to all the keys in the Keydiff before applying the operations. Also note that all the operations in the KeyDiff are applied atomically in a single transaction.

func (*EtcdClient) ChangeLeader added in v0.6.0 

func (cli *EtcdClient) ChangeLeader() error

Forces a change of leader in the etcd cluster.

func (*EtcdClient) ChangeUserPassword added in v0.2.0 

func (cli *EtcdClient) ChangeUserPassword(username string, password string) error

func (*EtcdClient) Close 

func (cli *EtcdClient) Close()

Close the underlying connection to the etcd cluster that the client as.

func (*EtcdClient) DeleteChunkedKey 

func (cli *EtcdClient) DeleteChunkedKey(key string) error

func (*EtcdClient) DeleteKey 

func (cli *EtcdClient) DeleteKey(key string) error

Delete a key.

func (*EtcdClient) DeleteKeyRange 

func (cli *EtcdClient) DeleteKeyRange(key string, rangeEnd string) error

Delete all the keys within a certain range of values. If you want to delete all the keys prefixed by a certain value, consider using the DeletePrefix method instead.

func (*EtcdClient) DeletePrefix 

func (cli *EtcdClient) DeletePrefix(prefix string) error

Delete all the keys that are prefixed by a given value

func (*EtcdClient) DeleteRole added in v0.2.0 

func (cli *EtcdClient) DeleteRole(name string) error

func (*EtcdClient) DeleteUser added in v0.2.0 

func (cli *EtcdClient) DeleteUser(username string) error

func (*EtcdClient) DiffBetweenPrefixes 

func (cli *EtcdClient) DiffBetweenPrefixes(srcPrefix string, dstPrefix string) (KeyDiff, error)

Convenience method that returns a KeyDiff structure containing all the operations that would need to be applied on the destination prefix to make it like the source prefix. Note that for comparative purpose, a relative representation of both keyspaces without their respective prefixes is assumed.

func (*EtcdClient) GetAuthStatus added in v0.5.0 

func (cli *EtcdClient) GetAuthStatus() (bool, error)

Retrieves the authentication status (enabled or not) of the etcd cluster.

func (*EtcdClient) GetChunkedKey 

func (cli *EtcdClient) GetChunkedKey(key string) (*ChunkedKeyPayload, error)

func (*EtcdClient) GetGroupMembers added in v0.9.0 

func (cli *EtcdClient) GetGroupMembers(groupPrefix string) (map[string]string, int64, error)

Get a list of group members of a group represented by groupPrefix First return value are a map of members, with its keys being member ids and values being the passed member contents. Second return value is the etcd revision at the time the result was obtained

func (*EtcdClient) GetKey 

func (cli *EtcdClient) GetKey(key string, opts GetKeyOptions) (KeyInfo, error)

Get information on the given key including the value.

func (*EtcdClient) GetKeyRange 

func (cli *EtcdClient) GetKeyRange(key string, rangeEnd string) (KeyRangeInfo, error)

Get all the keys within a certain range of values. If you want to get all the keys prefixed by a certain value, consider using the GetPrefix method instead.

func (*EtcdClient) GetMembers added in v0.6.0 

func (cli *EtcdClient) GetMembers(statusInfo bool) (EtcdMembers, error)

Get members info in the cluster. If statusInfo is true, additional status info will be fetched from each node in the cluster

func (*EtcdClient) GetPrefix added in v0.2.0 

func (cli *EtcdClient) GetPrefix(prefix string) (KeyRangeInfo, error)

Get all the keys that are prefixed by a given value

func (*EtcdClient) GetRolePermissions added in v0.2.0 

func (cli *EtcdClient) GetRolePermissions(name string) ([]EtcdRolePermission, bool, error)

func (*EtcdClient) GetUserRoles added in v0.2.0 

func (cli *EtcdClient) GetUserRoles(username string) ([]string, bool, error)

func (*EtcdClient) GrantRolePermission added in v0.2.0 

func (cli *EtcdClient) GrantRolePermission(name string, permission EtcdRolePermission) error

func (*EtcdClient) GrantUserRole added in v0.2.0 

func (cli *EtcdClient) GrantUserRole(username string, role string) error

func (*EtcdClient) InsertEmptyRole added in v0.2.0 

func (cli *EtcdClient) InsertEmptyRole(name string) error

func (*EtcdClient) InsertEmptyUser added in v0.2.0 

func (cli *EtcdClient) InsertEmptyUser(username string, password string) error

func (*EtcdClient) InsertRole added in v0.2.0 

func (cli *EtcdClient) InsertRole(role EtcdRole) error

func (*EtcdClient) InsertUser added in v0.2.0 

func (cli *EtcdClient) InsertUser(user EtcdUser) error

func (*EtcdClient) JoinGroup added in v0.9.0 

func (cli *EtcdClient) JoinGroup(groupPrefix string, memberId string, memberContent string) error

Join a group as represented by groupPrefix. A member with id memberId and content memberContent will be added.

func (*EtcdClient) LeaveGroup added in v0.9.0 

func (cli *EtcdClient) LeaveGroup(groupPrefix string, memberId string) error

Leave a group as represented by groupPrefix. A member with id memberId will be removed.

func (*EtcdClient) ListRoles added in v0.2.0 

func (cli *EtcdClient) ListRoles() ([]string, error)

func (*EtcdClient) ListUsers added in v0.2.0 

func (cli *EtcdClient) ListUsers() ([]string, error)

func (*EtcdClient) PutChunkedKey 

func (cli *EtcdClient) PutChunkedKey(key *ChunkedKeyPayload) error

func (*EtcdClient) PutKey 

func (cli *EtcdClient) PutKey(key string, val string) (int64, error)

Upsert the given value in the key. Returns the revision of the store right after the key was upserted.

func (*EtcdClient) ReadLock 

func (cli *EtcdClient) ReadLock(key string) (*Lock, error)

func (*EtcdClient) ReleaseLock 

func (cli *EtcdClient) ReleaseLock(key string) error

func (*EtcdClient) RevokeRolePermission added in v0.2.0 

func (cli *EtcdClient) RevokeRolePermission(name string, key string, rangeEnd string) error

func (*EtcdClient) RevokeUserRole added in v0.2.0 

func (cli *EtcdClient) RevokeUserRole(username string, role string) error

func (*EtcdClient) SetAuthStatus added in v0.5.0 

func (cli *EtcdClient) SetAuthStatus(enable bool) error

Sets the authentication status (enabled or not) of the etcd cluster.

func (*EtcdClient) SetContext added in v0.5.0 

func (cli *EtcdClient) SetContext(ctx context.Context) *EtcdClient

Returns a copy of the EtcdClient instance with a different Golang context. Note that the underlying client connection to the etcd cluster is reused though. Thus, a call to the Close method would impact both the original client and its copy.

func (*EtcdClient) SetEndpoints added in v0.6.0 

func (cli *EtcdClient) SetEndpoints(endpoints []string) (*EtcdClient, error)

Returns a copy of the EtcdClient instance with a different underlying connection. The endpoints of the new connection can be set in the argument. Note however that the context is reused. To change it as well, a call to the SetContext can be made.

func (*EtcdClient) SetLeaderStatus added in v0.6.0 

func (cli *EtcdClient) SetLeaderStatus(name string, isLeader bool) error

Sets the leader status on the node with the given name. If isLeader is true, the node will be elected leader if it isn't. If isLeader is false, the leadership will be transfered to another node.

func (*EtcdClient) Snapshot added in v0.10.0 

func (cli *EtcdClient) Snapshot(onLeader bool, path string, snapshotTimeout time.Duration) error

func (*EtcdClient) UpdateRole added in v0.2.0 

func (cli *EtcdClient) UpdateRole(role EtcdRole) error

func (*EtcdClient) UpdateUser added in v0.2.0 

func (cli *EtcdClient) UpdateUser(user EtcdUser) error

func (*EtcdClient) UpsertRole added in v0.2.0 

func (cli *EtcdClient) UpsertRole(role EtcdRole) error

func (*EtcdClient) UpsertUser added in v0.2.0 

func (cli *EtcdClient) UpsertUser(user EtcdUser) error

func (*EtcdClient) WaitGroupCountThreshold added in v0.9.0 

func (cli *EtcdClient) WaitGroupCountThreshold(groupPrefix string, threshold int64, doneCh <-chan struct{}) <-chan error

Wait until a group as represented by groupPrefix has reached a threshold number of members Last argument is a done channel that can be closed to halt the wait. Return argument is a channel that will received an error if there is an issue or otherwise will be closed when the wait condition is fulfilled

func (*EtcdClient) Watch added in v0.6.0 

func (cli *EtcdClient) Watch(wKey string, opts WatchOptions) <-chan WatchNotification

Watch the keys of a given prefix for changes and returns a channel that notifies of any changes

type EtcdClientOptions 

type EtcdClientOptions struct {
	//If tls is enabled and certificate authentication is used, path to the client certificate file
	ClientCertPath string
	//If tls is enabled and certificate authentication is used, path to the client private key file
	ClientKeyPath string
	//If tls is enabled and certificate authentication is used, alternate argument to provide a path to a file containing the client cert and the client key concatenanted after
	ClientCertKeyPath string
	//If tls is enabled, path to the CA certificate used to sign etcd's server certificates.
	CaCertPath string
	//If password authentication is used, name of the user.
	Username string
	//If password authentication is used, password of the user.
	Password string
	//Endpoints of the etcd cluster. Each entry should be of the format 'address:port'
	EtcdEndpoints []string
	//Timeout for the initial connection attempt to the etcd cluster
	ConnectionTimeout time.Duration
	//Timeout for individual requests to the etcd cluster
	RequestTimeout time.Duration
	//Interval of time to wait before retrying when requests to the etcd cluster fail
	RetryInterval time.Duration
	//Number of retries to attempt before returning an error when requests to the etcd cluster fail
	Retries uint64
	//If set to true, connection to the etcd cluster will be attempted in plaintext without encryption
	SkipTLS bool
}

Etcd connection options for the client.

type EtcdMember added in v0.6.0 

type EtcdMember struct {
	Id         uint64
	Name       string
	PeerUrls   []string
	ClientUrls []string
	IsLearner  bool
	Status     *EtcdMemberStatus
}

type EtcdMemberStatus added in v0.6.0 

type EtcdMemberStatus struct {
	IsLeader         bool
	IsResponsive     bool
	ResponseError    error
	ProtocolVersion  string
	DbSize           int64
	DbSizeInUse      int64
	RaftIndex        uint64
	RaftTerm         uint64
	RaftAppliedIndex uint64
}

type EtcdMembers added in v0.6.0 

type EtcdMembers struct {
	ClusterId    uint64
	RespId       uint64
	RespRevision int64
	RespRaftTerm uint64
	Members      []EtcdMember
}

type EtcdRole added in v0.2.0 

type EtcdRole struct {
	Name        string
	Permissions []EtcdRolePermission
}

type EtcdRolePermission added in v0.2.0 

type EtcdRolePermission struct {
	Permission string
	Key        string
	RangeEnd   string
}

type EtcdUser added in v0.2.0 

type EtcdUser struct {
	Username string
	Password string
	Roles    []string
}

type GetKeyOptions added in v0.6.0 

type GetKeyOptions struct {
	//Specifies that the value of the key at a given store revision is wanted.
	//Can be left at the default 0 value if the latest version of the key is desired.
	Revision int64
}

Options that get passed to GetKey method.

type KeyDiff added in v0.6.0 

type KeyDiff struct {
	//List of keys to insert with the insert value to make it like the source
	Inserts map[string]string
	//List of keys to update with the update value to make it like the source
	Updates map[string]string
	//List of keys to delete in the target to make it like the source
	Deletions []string
}

Differential between two key spaces

func GetKeyDiff added in v0.6.0 

func GetKeyDiff(src map[string]string, dst map[string]string) KeyDiff

Given a desired source keyspace and a destination keyspace that should be modified to be like the source, it returns the modifications to do on the destination to make it so.

func (*KeyDiff) FilterKeys added in v0.7.0 

func (diff *KeyDiff) FilterKeys(fn KeyDiffFilter) *KeyDiff

Filter the keys of a KeyDiff structure by applying a function on each key and only keeping the keys for which the function returns true. The result of the filter is returned into a separate structure.

func (*KeyDiff) IsEmpty added in v0.6.0 

func (diff *KeyDiff) IsEmpty() bool

Returns true if a KeyDiff Structure indicates not modifications to the destination

func (*KeyDiff) TransformKeys added in v0.7.0 

func (diff *KeyDiff) TransformKeys(fn KeyDiffTransform) *KeyDiff

Change the keys of a KeyDiff structure by applying a function on each key. The result of the filter is returned into a separate structure.

type KeyDiffFilter added in v0.7.0 

type KeyDiffFilter func(key string) bool

type KeyDiffTransform added in v0.7.0 

type KeyDiffTransform func(key string) string

type KeyInfo added in v0.5.0 

type KeyInfo struct {
	//Key
	Key string
	//Value stored at the key
	Value string
	//Etcd version of the key, which is incremented when a key changes and reset to 0 when it is deleted
	Version int64
	//Revision of the etcd store when the key was created
	CreateRevision int64
	//Revision of the etcd store when the key was last modified
	ModRevision int64
	//Id of the lease that created the key if the key was created with a lease
	Lease int64
}

Structure holding information returned on a specific key

func (*KeyInfo) Found added in v0.6.0 

func (info *KeyInfo) Found() bool

Returns whether the KeyInfo structure stores a key that was found. If the key is not found, an empty KeyInfo structure will be returned which will be detected by this method.

type KeyInfoMap added in v0.6.0 

type KeyInfoMap map[string]KeyInfo

A map of KeyInfo values with each key in the map being the KeyInfo's key. This is used as a separate type mostly for convenience methods

func (*KeyInfoMap) ToValueMap added in v0.6.0 

func (info *KeyInfoMap) ToValueMap(prefixTrim string) map[string]string

Flatten a KeyInfoMap structure to a simple map of key/value pairs. The method accepts a prefix argument that will be trimmed from the beginning of the keys.

type KeyRangeInfo added in v0.6.0 

type KeyRangeInfo struct {
	Keys     KeyInfoMap
	Revision int64
}

Result from a key range query. It returns a KeyInfoMap structure containing the result. It also contains a revision indication the revision of the etcd store at the moment the results were returned.

type Lock added in v0.5.0 

type Lock struct {
	Lease     clientv3.LeaseID
	Ttl       int64
	Timestamp time.Time
	Revision  int64
}

type WatchInfo added in v0.5.0 

type WatchInfo struct {
	//Inserted or updated keys. The map keys are the keys that were upserted.
	Upserts map[string]WatchKeyInfo
	//List of keys that were deleted
	Deletions []string
}

Reported changes to key(s) of interest by the watch function

func (*WatchInfo) ApplyOn added in v0.9.0 

func (info *WatchInfo) ApplyOn(dest map[string]string)

Apply the changes of a WatchInfo structure to a map of strings

type WatchKeyInfo added in v0.6.0 

type WatchKeyInfo struct {
	Value          string
	Version        int64
	CreateRevision int64
	ModRevision    int64
	Lease          int64
}

Information on key that got upserted as reported by the watch function

type WatchNotification added in v0.6.0 

type WatchNotification struct {
	//Changes that are reported if it is not an error
	Changes WatchInfo
	//Error that is reported if it is an error
	Error error
}

Events returned by the watch function. It can report either a change or an error.

type WatchOptions added in v0.6.0 

type WatchOptions struct {
	//If non-zero, will watch from the given etcd store revision. Useful for retroactively watching past changes.
	Revision int64
	//If true, it will assume the key argument is a prefix and will watch for all changes affecting keys with that prefix
	IsPrefix bool
	//If true, it will trim the prefix value from all the keys in the reported changes. Useful if you are interested only in relative keys.
	TrimPrefix bool
}

Options for the watch method

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.