Documentation
¶
Overview ¶
Package clientv3 implements the official Go etcd client for v3.
Create client using `clientv3.New`:
// expect dial time-out on ipv4 blackhole _, err := clientv3.New(clientv3.Config{ Endpoints: []string{"http://254.0.0.1:12345"}, DialTimeout: 2 * time.Second, }) // etcd clientv3 >= v3.2.10, grpc/grpc-go >= v1.7.3 if err == context.DeadlineExceeded { // handle errors } // etcd clientv3 <= v3.2.9, grpc/grpc-go <= v1.2.1 if err == grpc.ErrClientConnTimeout { // handle errors } cli, err := clientv3.New(clientv3.Config{ Endpoints: []string{"localhost:2379", "localhost:22379", "localhost:32379"}, DialTimeout: 5 * time.Second, }) if err != nil { // handle error! } defer cli.Close()
Make sure to close the client after using it. If the client is not closed, the connection will have leaky goroutines.
To specify a client request timeout, wrap the context with context.WithTimeout:
ctx, cancel := context.WithTimeout(context.Background(), timeout) resp, err := kvc.Put(ctx, "sample_key", "sample_value") cancel() if err != nil { // handle error! } // use the response
The Client has internal state (watchers and leases), so Clients should be reused instead of created as needed. Clients are safe for concurrent use by multiple goroutines.
etcd client returns 3 types of errors:
- context error: canceled or deadline exceeded.
- gRPC status error: e.g. when clock drifts in server-side before client's context deadline exceeded.
- gRPC error: see https://github.com/etcd-io/etcd/blob/master/etcdserver/api/v3rpc/rpctypes/error.go
Here is the example code to handle client errors:
resp, err := kvc.Put(ctx, "", "") if err != nil { if err == context.Canceled { // ctx is canceled by another routine } else if err == context.DeadlineExceeded { // ctx is attached with a deadline and it exceeded } else if err == rpctypes.ErrEmptyKey { // client-side error: key is not provided } else if ev, ok := status.FromError(err); ok { code := ev.Code() if code == codes.DeadlineExceeded { // server-side context might have timed-out first (due to clock skew) // while original client-side context is not timed-out yet } } else { // bad cluster endpoints, which are not etcd servers } } go func() { cli.Close() }() _, err := kvc.Get(ctx, "a") if err != nil { // with etcd clientv3 <= v3.3 if err == context.Canceled { // grpc balancer calls 'Get' with an inflight client.Close } else if err == grpc.ErrClientConnClosing { // <= gRCP v1.7.x // grpc balancer calls 'Get' after client.Close. } // with etcd clientv3 >= v3.4 if clientv3.IsConnCanceled(err) { // gRPC client connection is closed } }
The grpc load balancer is registered statically and is shared across etcd clients. To enable detailed load balancer logging, set the ETCD_CLIENT_DEBUG environment variable. E.g. "ETCD_CLIENT_DEBUG=1".
Index ¶
- Constants
- Variables
- func GetLogger() logutil.Logger
- func GetPrefixRangeEnd(prefix string) string
- func IsConnCanceled(err error) bool
- func NewLogger(gl grpclog.LoggerV2) logutil.Logger
- func RetryAuthClient(c *Client) pb.AuthClient
- func RetryClusterClient(c *Client) pb.ClusterClient
- func RetryKVClient(c *Client) pb.KVClient
- func RetryLeaseClient(c *Client) pb.LeaseClient
- func RetryMaintenanceClient(c *Client, conn *grpc.ClientConn) pb.MaintenanceClient
- func SetLogger(l grpclog.LoggerV2)
- func WithRequireLeader(ctx context.Context) context.Context
- type AlarmMember
- type AlarmResponse
- type Auth
- type AuthDisableResponse
- type AuthEnableResponse
- type AuthRoleAddResponse
- type AuthRoleDeleteResponse
- type AuthRoleGetResponse
- type AuthRoleGrantPermissionResponse
- type AuthRoleListResponse
- type AuthRoleRevokePermissionResponse
- type AuthUserAddResponse
- type AuthUserChangePasswordResponse
- type AuthUserDeleteResponse
- type AuthUserGetResponse
- type AuthUserGrantRoleResponse
- type AuthUserListResponse
- type AuthUserRevokeRoleResponse
- type AuthenticateResponse
- type Client
- func (c *Client) ActiveConnection() *grpc.ClientConn
- func (c *Client) Close() error
- func (c *Client) Ctx() context.Context
- func (c *Client) Dial(ep string) (*grpc.ClientConn, error)
- func (c *Client) Endpoints() []string
- func (c *Client) SetEndpoints(eps ...string)
- func (c *Client) Sync(ctx context.Context) error
- type Cluster
- type Cmp
- type CompactOp
- type CompactOption
- type CompactResponse
- type CompareResult
- type CompareTarget
- type Config
- type DefragmentResponse
- type DeleteResponse
- type ErrKeepAliveHalted
- type Event
- type GetResponse
- type HashKVResponse
- type KV
- type Lease
- type LeaseGrantResponse
- type LeaseID
- type LeaseKeepAliveResponse
- type LeaseLeasesResponse
- type LeaseOp
- type LeaseOption
- type LeaseRevokeResponse
- type LeaseStatus
- type LeaseTimeToLiveResponse
- type Maintenance
- type Member
- type MemberAddResponse
- type MemberListResponse
- type MemberPromoteResponse
- type MemberRemoveResponse
- type MemberUpdateResponse
- type MoveLeaderResponse
- type Op
- func (op Op) IsCountOnly() bool
- func (op Op) IsDelete() bool
- func (op Op) IsGet() bool
- func (op Op) IsKeysOnly() bool
- func (op Op) IsPut() bool
- func (op Op) IsSerializable() bool
- func (op Op) IsTxn() bool
- func (op Op) KeyBytes() []byte
- func (op Op) MaxCreateRev() int64
- func (op Op) MaxModRev() int64
- func (op Op) MinCreateRev() int64
- func (op Op) MinModRev() int64
- func (op Op) RangeBytes() []byte
- func (op Op) Rev() int64
- func (op Op) Txn() ([]Cmp, []Op, []Op)
- func (op Op) ValueBytes() []byte
- func (op *Op) WithKeyBytes(key []byte)
- func (op *Op) WithRangeBytes(end []byte)
- func (op *Op) WithValueBytes(v []byte)
- type OpOption
- func WithCountOnly() OpOption
- func WithCreatedNotify() OpOption
- func WithFilterDelete() OpOption
- func WithFilterPut() OpOption
- func WithFirstCreate() []OpOption
- func WithFirstKey() []OpOption
- func WithFirstRev() []OpOption
- func WithFragment() OpOption
- func WithFromKey() OpOption
- func WithIgnoreLease() OpOption
- func WithIgnoreValue() OpOption
- func WithKeysOnly() OpOption
- func WithLastCreate() []OpOption
- func WithLastKey() []OpOption
- func WithLastRev() []OpOption
- func WithLease(leaseID LeaseID) OpOption
- func WithLimit(n int64) OpOption
- func WithMaxCreateRev(rev int64) OpOption
- func WithMaxModRev(rev int64) OpOption
- func WithMinCreateRev(rev int64) OpOption
- func WithMinModRev(rev int64) OpOption
- func WithPrefix() OpOption
- func WithPrevKV() OpOption
- func WithProgressNotify() OpOption
- func WithRange(endKey string) OpOption
- func WithRev(rev int64) OpOption
- func WithSerializable() OpOption
- func WithSort(target SortTarget, order SortOrder) OpOption
- type OpResponse
- type Permission
- type PermissionType
- type PutResponse
- type SortOption
- type SortOrder
- type SortTarget
- type StatusResponse
- type TransportCredentialsWithDialer
- type Txn
- type TxnResponse
- type UserAddOptions
- type WatchChan
- type WatchResponse
- type Watcher
Constants ¶
const ( PermRead = authpb.READ PermWrite = authpb.WRITE PermReadWrite = authpb.READWRITE )
const MaxLeaseTTL = 9000000000
MaxLeaseTTL is the maximum lease TTL value
Variables ¶
var ( ErrNoAvailableEndpoints = errors.New("etcdclient: no available endpoints") ErrOldCluster = errors.New("etcdclient: old cluster version") )
var LeaseResponseChSize = 16
LeaseResponseChSize is the size of buffer to store unsent lease responses. WARNING: DO NOT UPDATE. Only for testing purposes.
Functions ¶
func GetPrefixRangeEnd ¶
GetPrefixRangeEnd gets the range end of the prefix. 'Get(foo, WithPrefix())' is equal to 'Get(foo, WithRange(GetPrefixRangeEnd(foo))'.
func IsConnCanceled ¶
IsConnCanceled returns true, if error is from a closed gRPC connection. ref. https://github.com/grpc/grpc-go/pull/1854
func NewLogger ¶
NewLogger returns a new Logger with logutil.Logger.
func RetryAuthClient ¶
func RetryAuthClient(c *Client) pb.AuthClient
RetryAuthClient implements a AuthClient.
func RetryClusterClient ¶
func RetryClusterClient(c *Client) pb.ClusterClient
RetryClusterClient implements a ClusterClient.
func RetryLeaseClient ¶
func RetryLeaseClient(c *Client) pb.LeaseClient
RetryLeaseClient implements a LeaseClient.
func RetryMaintenanceClient ¶
func RetryMaintenanceClient(c *Client, conn *grpc.ClientConn) pb.MaintenanceClient
RetryMaintenanceClient implements a Maintenance.
Types ¶
type AlarmMember ¶
type AlarmMember pb.AlarmMember
type AlarmResponse ¶
type AlarmResponse pb.AlarmResponse
type Auth ¶
type Auth interface { // AuthEnable enables auth of an etcd cluster. AuthEnable(ctx context.Context) (*AuthEnableResponse, error) // AuthDisable disables auth of an etcd cluster. AuthDisable(ctx context.Context) (*AuthDisableResponse, error) // UserAdd adds a new user to an etcd cluster. UserAdd(ctx context.Context, name string, password string) (*AuthUserAddResponse, error) // UserAddWithOptions adds a new user to an etcd cluster with some options. UserAddWithOptions(ctx context.Context, name string, password string, opt *UserAddOptions) (*AuthUserAddResponse, error) // UserDelete deletes a user from an etcd cluster. UserDelete(ctx context.Context, name string) (*AuthUserDeleteResponse, error) // UserChangePassword changes a password of a user. UserChangePassword(ctx context.Context, name string, password string) (*AuthUserChangePasswordResponse, error) // UserGrantRole grants a role to a user. UserGrantRole(ctx context.Context, user string, role string) (*AuthUserGrantRoleResponse, error) // UserGet gets a detailed information of a user. UserGet(ctx context.Context, name string) (*AuthUserGetResponse, error) // UserList gets a list of all users. UserList(ctx context.Context) (*AuthUserListResponse, error) // UserRevokeRole revokes a role of a user. UserRevokeRole(ctx context.Context, name string, role string) (*AuthUserRevokeRoleResponse, error) // RoleAdd adds a new role to an etcd cluster. RoleAdd(ctx context.Context, name string) (*AuthRoleAddResponse, error) // RoleGrantPermission grants a permission to a role. RoleGrantPermission(ctx context.Context, name string, key, rangeEnd string, permType PermissionType) (*AuthRoleGrantPermissionResponse, error) // RoleGet gets a detailed information of a role. RoleGet(ctx context.Context, role string) (*AuthRoleGetResponse, error) // RoleList gets a list of all roles. RoleList(ctx context.Context) (*AuthRoleListResponse, error) // RoleRevokePermission revokes a permission from a role. RoleRevokePermission(ctx context.Context, role string, key, rangeEnd string) (*AuthRoleRevokePermissionResponse, error) // RoleDelete deletes a role. RoleDelete(ctx context.Context, role string) (*AuthRoleDeleteResponse, error) }
type AuthDisableResponse ¶
type AuthDisableResponse pb.AuthDisableResponse
type AuthEnableResponse ¶
type AuthEnableResponse pb.AuthEnableResponse
type AuthRoleAddResponse ¶
type AuthRoleAddResponse pb.AuthRoleAddResponse
type AuthRoleDeleteResponse ¶
type AuthRoleDeleteResponse pb.AuthRoleDeleteResponse
type AuthRoleGetResponse ¶
type AuthRoleGetResponse pb.AuthRoleGetResponse
type AuthRoleGrantPermissionResponse ¶
type AuthRoleGrantPermissionResponse pb.AuthRoleGrantPermissionResponse
type AuthRoleListResponse ¶
type AuthRoleListResponse pb.AuthRoleListResponse
type AuthRoleRevokePermissionResponse ¶
type AuthRoleRevokePermissionResponse pb.AuthRoleRevokePermissionResponse
type AuthUserAddResponse ¶
type AuthUserAddResponse pb.AuthUserAddResponse
type AuthUserChangePasswordResponse ¶
type AuthUserChangePasswordResponse pb.AuthUserChangePasswordResponse
type AuthUserDeleteResponse ¶
type AuthUserDeleteResponse pb.AuthUserDeleteResponse
type AuthUserGetResponse ¶
type AuthUserGetResponse pb.AuthUserGetResponse
type AuthUserGrantRoleResponse ¶
type AuthUserGrantRoleResponse pb.AuthUserGrantRoleResponse
type AuthUserListResponse ¶
type AuthUserListResponse pb.AuthUserListResponse
type AuthUserRevokeRoleResponse ¶
type AuthUserRevokeRoleResponse pb.AuthUserRevokeRoleResponse
type AuthenticateResponse ¶
type AuthenticateResponse pb.AuthenticateResponse
type Client ¶
type Client struct { Cluster KV Lease Watcher Auth Maintenance // Username is a user name for authentication. Username string // Password is a password for authentication. Password string // contains filtered or unexported fields }
Client provides and manages an etcd v3 client session.
func New ¶
New creates a new etcdv3 client from a given configuration.
func NewCtxClient ¶
NewCtxClient creates a client with a context but no underlying grpc connection. This is useful for embedded cases that override the service interface implementations and do not need connection management.
func NewFromURL ¶
NewFromURL creates a new etcdv3 client from a URL.
func NewFromURLs ¶
NewFromURLs creates a new etcdv3 client from URLs.
func (*Client) ActiveConnection ¶
func (c *Client) ActiveConnection() *grpc.ClientConn
ActiveConnection returns the current in-use connection
func (*Client) Close ¶
Close shuts down the client's etcd connections.
func (*Client) Ctx ¶
Ctx is a context for "out of band" messages (e.g., for sending "clean up" message when another context is canceled). It is canceled on client Close().
func (*Client) Dial ¶
func (c *Client) Dial(ep string) (*grpc.ClientConn, error)
Dial connects to a single endpoint using the client's config.
func (*Client) Endpoints ¶
Endpoints lists the registered endpoints for the client.
func (*Client) SetEndpoints ¶
SetEndpoints updates client's endpoints.
type Cluster ¶
type Cluster interface { // MemberList lists the current cluster membership. MemberList(ctx context.Context) (*MemberListResponse, error) // MemberAdd adds a new member into the cluster. MemberAdd(ctx context.Context, peerAddrs []string) (*MemberAddResponse, error) // MemberAddAsLearner adds a new learner member into the cluster. MemberAddAsLearner(ctx context.Context, peerAddrs []string) (*MemberAddResponse, error) // MemberRemove removes an existing member from the cluster. MemberRemove(ctx context.Context, id uint64) (*MemberRemoveResponse, error) // MemberUpdate updates the peer addresses of the member. MemberUpdate(ctx context.Context, id uint64, peerAddrs []string) (*MemberUpdateResponse, error) // MemberPromote promotes a member from raft learner (non-voting) to raft voting member. MemberPromote(ctx context.Context, id uint64) (*MemberPromoteResponse, error) }
func NewClusterFromClusterClient ¶
func NewClusterFromClusterClient(remote pb.ClusterClient, c *Client) Cluster
type Cmp ¶
func LeaseValue ¶
LeaseValue compares a key's LeaseID to a value of your choosing. The empty LeaseID is 0, otherwise known as `NoLease`.
func (*Cmp) KeyBytes ¶
KeyBytes returns the byte slice holding with the comparison key.
func (*Cmp) ValueBytes ¶
ValueBytes returns the byte slice holding the comparison value, if any.
func (*Cmp) WithKeyBytes ¶
WithKeyBytes sets the byte slice for the comparison key.
func (Cmp) WithPrefix ¶
WithPrefix sets the comparison to scan all keys prefixed by the key.
func (Cmp) WithRange ¶
WithRange sets the comparison to scan the range [key, end).
type CompactOp ¶
type CompactOp struct {
// contains filtered or unexported fields
}
CompactOp represents a compact operation.
func OpCompact ¶
func OpCompact(rev int64, opts ...CompactOption) CompactOp
OpCompact wraps slice CompactOption to create a CompactOp.
type CompactOption ¶
type CompactOption func(*CompactOp)
CompactOption configures compact operation.
func WithCompactPhysical ¶
func WithCompactPhysical() CompactOption
WithCompactPhysical makes Compact wait until all compacted entries are removed from the etcd server's storage.
type CompactResponse ¶
type CompactResponse pb.CompactionResponse
type CompareTarget ¶
type CompareTarget int
const ( CompareVersion CompareTarget = iota CompareCreated CompareModified CompareValue )
type Config ¶
type Config struct { // Endpoints is a list of URLs. Endpoints []string `json:"endpoints"` // AutoSyncInterval is the interval to update endpoints with its latest members. // 0 disables auto-sync. By default auto-sync is disabled. AutoSyncInterval time.Duration `json:"auto-sync-interval"` // DialTimeout is the timeout for failing to establish a connection. DialTimeout time.Duration `json:"dial-timeout"` // DialKeepAliveTime is the time after which client pings the server to see if // transport is alive. DialKeepAliveTime time.Duration `json:"dial-keep-alive-time"` // DialKeepAliveTimeout is the time that the client waits for a response for the // keep-alive probe. If the response is not received in this time, the connection is closed. DialKeepAliveTimeout time.Duration `json:"dial-keep-alive-timeout"` // MaxCallSendMsgSize is the client-side request send limit in bytes. // If 0, it defaults to 2.0 MiB (2 * 1024 * 1024). // Make sure that "MaxCallSendMsgSize" < server-side default send/recv limit. // ("--max-request-bytes" flag to etcd or "embed.Config.MaxRequestBytes"). MaxCallSendMsgSize int // MaxCallRecvMsgSize is the client-side response receive limit. // If 0, it defaults to "math.MaxInt32", because range response can // easily exceed request send limits. // Make sure that "MaxCallRecvMsgSize" >= server-side default send/recv limit. // ("--max-request-bytes" flag to etcd or "embed.Config.MaxRequestBytes"). MaxCallRecvMsgSize int // TLS holds the client secure credentials, if any. TLS *tls.Config // Username is a user name for authentication. Username string `json:"username"` // Password is a password for authentication. Password string `json:"password"` // RejectOldCluster when set will refuse to create a client against an outdated cluster. RejectOldCluster bool `json:"reject-old-cluster"` // DialOptions is a list of dial options for the grpc client (e.g., for interceptors). // For example, pass "grpc.WithBlock()" to block until the underlying connection is up. // Without this, Dial returns immediately and connecting the server happens in background. DialOptions []grpc.DialOption // Context is the default client context; it can be used to cancel grpc dial out and // other operations that do not have an explicit context. Context context.Context // LogConfig configures client-side logger. // If nil, use the default logger. // TODO: configure gRPC logger LogConfig *zap.Config // PermitWithoutStream when set will allow client to send keepalive pings to server without any active streams(RPCs). PermitWithoutStream bool `json:"permit-without-stream"` }
type DefragmentResponse ¶
type DefragmentResponse pb.DefragmentResponse
type DeleteResponse ¶
type DeleteResponse pb.DeleteRangeResponse
func (*DeleteResponse) OpResponse ¶
func (resp *DeleteResponse) OpResponse() OpResponse
type ErrKeepAliveHalted ¶
type ErrKeepAliveHalted struct {
Reason error
}
ErrKeepAliveHalted is returned if client keep alive loop halts with an unexpected error.
This usually means that automatic lease renewal via KeepAlive is broken, but KeepAliveOnce will still work as expected.
func (ErrKeepAliveHalted) Error ¶
func (e ErrKeepAliveHalted) Error() string
type Event ¶
func (*Event) IsCreate ¶
IsCreate returns true if the event tells that the key is newly created.
type GetResponse ¶
type GetResponse pb.RangeResponse
func (*GetResponse) OpResponse ¶
func (resp *GetResponse) OpResponse() OpResponse
type HashKVResponse ¶
type HashKVResponse pb.HashKVResponse
type KV ¶
type KV interface { // Put puts a key-value pair into etcd. // Note that key,value can be plain bytes array and string is // an immutable representation of that bytes array. // To get a string of bytes, do string([]byte{0x10, 0x20}). Put(ctx context.Context, key, val string, opts ...OpOption) (*PutResponse, error) // Get retrieves keys. // By default, Get will return the value for "key", if any. // When passed WithRange(end), Get will return the keys in the range [key, end). // When passed WithFromKey(), Get returns keys greater than or equal to key. // When passed WithRev(rev) with rev > 0, Get retrieves keys at the given revision; // if the required revision is compacted, the request will fail with ErrCompacted . // When passed WithLimit(limit), the number of returned keys is bounded by limit. // When passed WithSort(), the keys will be sorted. Get(ctx context.Context, key string, opts ...OpOption) (*GetResponse, error) // Delete deletes a key, or optionally using WithRange(end), [key, end). Delete(ctx context.Context, key string, opts ...OpOption) (*DeleteResponse, error) // Compact compacts etcd KV history before the given rev. Compact(ctx context.Context, rev int64, opts ...CompactOption) (*CompactResponse, error) // Do applies a single Op on KV without a transaction. // Do is useful when creating arbitrary operations to be issued at a // later time; the user can range over the operations, calling Do to // execute them. Get/Put/Delete, on the other hand, are best suited // for when the operation should be issued at the time of declaration. Do(ctx context.Context, op Op) (OpResponse, error) // Txn creates a transaction. Txn(ctx context.Context) Txn }
type Lease ¶
type Lease interface { // Grant creates a new lease. Grant(ctx context.Context, ttl int64) (*LeaseGrantResponse, error) // Revoke revokes the given lease. Revoke(ctx context.Context, id LeaseID) (*LeaseRevokeResponse, error) // TimeToLive retrieves the lease information of the given lease ID. TimeToLive(ctx context.Context, id LeaseID, opts ...LeaseOption) (*LeaseTimeToLiveResponse, error) // Leases retrieves all leases. Leases(ctx context.Context) (*LeaseLeasesResponse, error) // KeepAlive attempts to keep the given lease alive forever. If the keepalive responses posted // to the channel are not consumed promptly the channel may become full. When full, the lease // client will continue sending keep alive requests to the etcd server, but will drop responses // until there is capacity on the channel to send more responses. // // If client keep alive loop halts with an unexpected error (e.g. "etcdserver: no leader") or // canceled by the caller (e.g. context.Canceled), KeepAlive returns a ErrKeepAliveHalted error // containing the error reason. // // The returned "LeaseKeepAliveResponse" channel closes if underlying keep // alive stream is interrupted in some way the client cannot handle itself; // given context "ctx" is canceled or timed out. // // TODO(v4.0): post errors to last keep alive message before closing // (see https://github.com/etcd-io/etcd/pull/7866) KeepAlive(ctx context.Context, id LeaseID) (<-chan *LeaseKeepAliveResponse, error) // KeepAliveOnce renews the lease once. The response corresponds to the // first message from calling KeepAlive. If the response has a recoverable // error, KeepAliveOnce will retry the RPC with a new keep alive message. // // In most of the cases, Keepalive should be used instead of KeepAliveOnce. KeepAliveOnce(ctx context.Context, id LeaseID) (*LeaseKeepAliveResponse, error) // Close releases all resources Lease keeps for efficient communication // with the etcd server. Close() error }
type LeaseGrantResponse ¶
type LeaseGrantResponse struct { *pb.ResponseHeader ID LeaseID TTL int64 Error string }
LeaseGrantResponse wraps the protobuf message LeaseGrantResponse.
type LeaseID ¶
type LeaseID int64
const ( // NoLease is a lease ID for the absence of a lease. NoLease LeaseID = 0 )
type LeaseKeepAliveResponse ¶
type LeaseKeepAliveResponse struct { *pb.ResponseHeader ID LeaseID TTL int64 }
LeaseKeepAliveResponse wraps the protobuf message LeaseKeepAliveResponse.
type LeaseLeasesResponse ¶
type LeaseLeasesResponse struct { *pb.ResponseHeader Leases []LeaseStatus `json:"leases"` }
LeaseLeasesResponse wraps the protobuf message LeaseLeasesResponse.
type LeaseOp ¶
type LeaseOp struct {
// contains filtered or unexported fields
}
LeaseOp represents an Operation that lease can execute.
type LeaseOption ¶
type LeaseOption func(*LeaseOp)
LeaseOption configures lease operations.
func WithAttachedKeys ¶
func WithAttachedKeys() LeaseOption
WithAttachedKeys makes TimeToLive list the keys attached to the given lease ID.
type LeaseRevokeResponse ¶
type LeaseRevokeResponse pb.LeaseRevokeResponse
type LeaseStatus ¶
type LeaseStatus struct {
ID LeaseID `json:"id"`
}
LeaseStatus represents a lease status.
type LeaseTimeToLiveResponse ¶
type LeaseTimeToLiveResponse struct { *pb.ResponseHeader ID LeaseID `json:"id"` // TTL is the remaining TTL in seconds for the lease; the lease will expire in under TTL+1 seconds. Expired lease will return -1. TTL int64 `json:"ttl"` // GrantedTTL is the initial granted time in seconds upon lease creation/renewal. GrantedTTL int64 `json:"granted-ttl"` // Keys is the list of keys attached to this lease. Keys [][]byte `json:"keys"` }
LeaseTimeToLiveResponse wraps the protobuf message LeaseTimeToLiveResponse.
type Maintenance ¶
type Maintenance interface { // AlarmList gets all active alarms. AlarmList(ctx context.Context) (*AlarmResponse, error) // AlarmDisarm disarms a given alarm. AlarmDisarm(ctx context.Context, m *AlarmMember) (*AlarmResponse, error) // Defragment releases wasted space from internal fragmentation on a given etcd member. // Defragment is only needed when deleting a large number of keys and want to reclaim // the resources. // Defragment is an expensive operation. User should avoid defragmenting multiple members // at the same time. // To defragment multiple members in the cluster, user need to call defragment multiple // times with different endpoints. Defragment(ctx context.Context, endpoint string) (*DefragmentResponse, error) // Status gets the status of the endpoint. Status(ctx context.Context, endpoint string) (*StatusResponse, error) // HashKV returns a hash of the KV state at the time of the RPC. // If revision is zero, the hash is computed on all keys. If the revision // is non-zero, the hash is computed on all keys at or below the given revision. HashKV(ctx context.Context, endpoint string, rev int64) (*HashKVResponse, error) // Snapshot provides a reader for a point-in-time snapshot of etcd. // If the context "ctx" is canceled or timed out, reading from returned // "io.ReadCloser" would error out (e.g. context.Canceled, context.DeadlineExceeded). Snapshot(ctx context.Context) (io.ReadCloser, error) // MoveLeader requests current leader to transfer its leadership to the transferee. // Request must be made to the leader. MoveLeader(ctx context.Context, transfereeID uint64) (*MoveLeaderResponse, error) }
func NewMaintenance ¶
func NewMaintenance(c *Client) Maintenance
func NewMaintenanceFromMaintenanceClient ¶
func NewMaintenanceFromMaintenanceClient(remote pb.MaintenanceClient, c *Client) Maintenance
type MemberAddResponse ¶
type MemberAddResponse pb.MemberAddResponse
type MemberListResponse ¶
type MemberListResponse pb.MemberListResponse
type MemberPromoteResponse ¶
type MemberPromoteResponse pb.MemberPromoteResponse
type MemberRemoveResponse ¶
type MemberRemoveResponse pb.MemberRemoveResponse
type MemberUpdateResponse ¶
type MemberUpdateResponse pb.MemberUpdateResponse
type MoveLeaderResponse ¶
type MoveLeaderResponse pb.MoveLeaderResponse
type Op ¶
type Op struct {
// contains filtered or unexported fields
}
Op represents an Operation that kv can execute.
func OpDelete ¶
OpDelete returns "delete" operation based on given key and operation options.
func OpGet ¶
OpGet returns "get" operation based on given key and operation options.
func OpPut ¶
OpPut returns "put" operation based on given key-value and operation options.
func OpTxn ¶
OpTxn returns "txn" operation based on given transaction conditions.
func (Op) IsCountOnly ¶
IsCountOnly returns whether countOnly is set.
func (Op) IsDelete ¶
IsDelete returns true iff the operation is a Delete.
func (Op) IsSerializable ¶
IsSerializable returns true if the serializable field is true.
func (Op) KeyBytes ¶
KeyBytes returns the byte slice holding the Op's key.
func (Op) MaxCreateRev ¶
MaxCreateRev returns the operation's maximum create revision.
func (Op) MaxModRev ¶
MaxModRev returns the operation's maximum modify revision.
func (Op) MinCreateRev ¶
MinCreateRev returns the operation's minimum create revision.
func (Op) MinModRev ¶
MinModRev returns the operation's minimum modify revision.
func (Op) RangeBytes ¶
RangeBytes returns the byte slice holding with the Op's range end, if any.
func (Op) Txn ¶
Txn returns the comparison(if) operations, "then" operations, and "else" operations.
func (Op) ValueBytes ¶
ValueBytes returns the byte slice holding the Op's value, if any.
func (*Op) WithKeyBytes ¶
WithKeyBytes sets the byte slice for the Op's key.
func (*Op) WithRangeBytes ¶
WithRangeBytes sets the byte slice for the Op's range end.
type OpOption ¶
type OpOption func(*Op)
OpOption configures Operations like Get, Put, Delete.
func WithCountOnly ¶
func WithCountOnly() OpOption
WithCountOnly makes the 'Get' request return only the count of keys.
func WithCreatedNotify ¶
func WithCreatedNotify() OpOption
WithCreatedNotify makes watch server sends the created event.
func WithFilterDelete ¶
func WithFilterDelete() OpOption
WithFilterDelete discards DELETE events from the watcher.
func WithFilterPut ¶
func WithFilterPut() OpOption
WithFilterPut discards PUT events from the watcher.
func WithFirstCreate ¶
func WithFirstCreate() []OpOption
WithFirstCreate gets the key with the oldest creation revision in the request range.
func WithFirstKey ¶
func WithFirstKey() []OpOption
WithFirstKey gets the lexically first key in the request range.
func WithFirstRev ¶
func WithFirstRev() []OpOption
WithFirstRev gets the key with the oldest modification revision in the request range.
func WithFragment ¶
func WithFragment() OpOption
WithFragment to receive raw watch response with fragmentation. Fragmentation is disabled by default. If fragmentation is enabled, etcd watch server will split watch response before sending to clients when the total size of watch events exceed server-side request limit. The default server-side request limit is 1.5 MiB, which can be configured as "--max-request-bytes" flag value + gRPC-overhead 512 bytes. See "etcdserver/api/v3rpc/watch.go" for more details.
func WithFromKey ¶
func WithFromKey() OpOption
WithFromKey specifies the range of 'Get', 'Delete', 'Watch' requests to be equal or greater than the key in the argument.
func WithIgnoreLease ¶
func WithIgnoreLease() OpOption
WithIgnoreLease updates the key using its current lease. This option can not be combined with WithLease. Returns an error if the key does not exist.
func WithIgnoreValue ¶
func WithIgnoreValue() OpOption
WithIgnoreValue updates the key using its current value. This option can not be combined with non-empty values. Returns an error if the key does not exist.
func WithKeysOnly ¶
func WithKeysOnly() OpOption
WithKeysOnly makes the 'Get' request return only the keys and the corresponding values will be omitted.
func WithLastCreate ¶
func WithLastCreate() []OpOption
WithLastCreate gets the key with the latest creation revision in the request range.
func WithLastKey ¶
func WithLastKey() []OpOption
WithLastKey gets the lexically last key in the request range.
func WithLastRev ¶
func WithLastRev() []OpOption
WithLastRev gets the key with the latest modification revision in the request range.
func WithLease ¶
WithLease attaches a lease ID to a key in 'Put' request.
func WithLimit ¶
WithLimit limits the number of results to return from 'Get' request. If WithLimit is given a 0 limit, it is treated as no limit.
func WithMaxCreateRev ¶
WithMaxCreateRev filters out keys for Get with creation revisions greater than the given revision.
func WithMaxModRev ¶
WithMaxModRev filters out keys for Get with modification revisions greater than the given revision.
func WithMinCreateRev ¶
WithMinCreateRev filters out keys for Get with creation revisions less than the given revision.
func WithMinModRev ¶
WithMinModRev filters out keys for Get with modification revisions less than the given revision.
func WithPrefix ¶
func WithPrefix() OpOption
WithPrefix enables 'Get', 'Delete', or 'Watch' requests to operate on the keys with matching prefix. For example, 'Get(foo, WithPrefix())' can return 'foo1', 'foo2', and so on.
func WithPrevKV ¶
func WithPrevKV() OpOption
WithPrevKV gets the previous key-value pair before the event happens. If the previous KV is already compacted, nothing will be returned.
func WithProgressNotify ¶
func WithProgressNotify() OpOption
WithProgressNotify makes watch server send periodic progress updates every 10 minutes when there is no incoming events. Progress updates have zero events in WatchResponse.
func WithRange ¶
WithRange specifies the range of 'Get', 'Delete', 'Watch' requests. For example, 'Get' requests with 'WithRange(end)' returns the keys in the range [key, end). endKey must be lexicographically greater than start key.
func WithRev ¶
WithRev specifies the store revision for 'Get' request. Or the start revision of 'Watch' request.
func WithSerializable ¶
func WithSerializable() OpOption
WithSerializable makes 'Get' request serializable. By default, it's linearizable. Serializable requests are better for lower latency requirement.
func WithSort ¶
func WithSort(target SortTarget, order SortOrder) OpOption
WithSort specifies the ordering in 'Get' request. It requires 'WithRange' and/or 'WithPrefix' to be specified too. 'target' specifies the target to sort by: key, version, revisions, value. 'order' can be either 'SortNone', 'SortAscend', 'SortDescend'.
type OpResponse ¶
type OpResponse struct {
// contains filtered or unexported fields
}
func (OpResponse) Del ¶
func (op OpResponse) Del() *DeleteResponse
func (OpResponse) Get ¶
func (op OpResponse) Get() *GetResponse
func (OpResponse) Put ¶
func (op OpResponse) Put() *PutResponse
func (OpResponse) Txn ¶
func (op OpResponse) Txn() *TxnResponse
type Permission ¶
type Permission authpb.Permission
type PermissionType ¶
type PermissionType authpb.Permission_Type
func StrToPermissionType ¶
func StrToPermissionType(s string) (PermissionType, error)
type PutResponse ¶
type PutResponse pb.PutResponse
func (*PutResponse) OpResponse ¶
func (resp *PutResponse) OpResponse() OpResponse
type SortOption ¶
type SortOption struct { Target SortTarget Order SortOrder }
type SortTarget ¶
type SortTarget int
const ( SortByKey SortTarget = iota SortByVersion SortByCreateRevision SortByModRevision SortByValue )
type StatusResponse ¶
type StatusResponse pb.StatusResponse
type TransportCredentialsWithDialer ¶
type TransportCredentialsWithDialer interface { grpccredentials.TransportCredentials Dialer(ctx context.Context, dialEp string) (net.Conn, error) }
TransportCredentialsWithDialer is for a gRPC load balancer workaround. See credentials.transportCredential for details.
type Txn ¶
type Txn interface { // If takes a list of comparison. If all comparisons passed in succeed, // the operations passed into Then() will be executed. Or the operations // passed into Else() will be executed. If(cs ...Cmp) Txn // Then takes a list of operations. The Ops list will be executed, if the // comparisons passed in If() succeed. Then(ops ...Op) Txn // Else takes a list of operations. The Ops list will be executed, if the // comparisons passed in If() fail. Else(ops ...Op) Txn // Commit tries to commit the transaction. Commit() (*TxnResponse, error) }
Txn is the interface that wraps mini-transactions.
Txn(context.TODO()).If( Compare(Value(k1), ">", v1), Compare(Version(k1), "=", 2) ).Then( OpPut(k2,v2), OpPut(k3,v3) ).Else( OpPut(k4,v4), OpPut(k5,v5) ).Commit()
type TxnResponse ¶
type TxnResponse pb.TxnResponse
func (*TxnResponse) OpResponse ¶
func (resp *TxnResponse) OpResponse() OpResponse
type UserAddOptions ¶
type UserAddOptions authpb.UserAddOptions
type WatchChan ¶
type WatchChan <-chan WatchResponse
type WatchResponse ¶
type WatchResponse struct { Header pb.ResponseHeader Events []*Event // CompactRevision is the minimum revision the watcher may receive. CompactRevision int64 // Canceled is used to indicate watch failure. // If the watch failed and the stream was about to close, before the channel is closed, // the channel sends a final response that has Canceled set to true with a non-nil Err(). Canceled bool // Created is used to indicate the creation of the watcher. Created bool // contains filtered or unexported fields }
func (*WatchResponse) Err ¶
func (wr *WatchResponse) Err() error
Err is the error value if this WatchResponse holds an error.
func (*WatchResponse) IsProgressNotify ¶
func (wr *WatchResponse) IsProgressNotify() bool
IsProgressNotify returns true if the WatchResponse is progress notification.
type Watcher ¶
type Watcher interface { // Watch watches on a key or prefix. The watched events will be returned // through the returned channel. If revisions waiting to be sent over the // watch are compacted, then the watch will be canceled by the server, the // client will post a compacted error watch response, and the channel will close. // If the context "ctx" is canceled or timed out, returned "WatchChan" is closed, // and "WatchResponse" from this closed channel has zero events and nil "Err()". // The context "ctx" MUST be canceled, as soon as watcher is no longer being used, // to release the associated resources. // // If the context is "context.Background/TODO", returned "WatchChan" will // not be closed and block until event is triggered, except when server // returns a non-recoverable error (e.g. ErrCompacted). // For example, when context passed with "WithRequireLeader" and the // connected server has no leader (e.g. due to network partition), // error "etcdserver: no leader" (ErrNoLeader) will be returned, // and then "WatchChan" is closed with non-nil "Err()". // In order to prevent a watch stream being stuck in a partitioned node, // make sure to wrap context with "WithRequireLeader". // // Otherwise, as long as the context has not been canceled or timed out, // watch will retry on other recoverable errors forever until reconnected. // // TODO: explicitly set context error in the last "WatchResponse" message and close channel? // Currently, client contexts are overwritten with "valCtx" that never closes. // TODO(v3.4): configure watch retry policy, limit maximum retry number // (see https://github.com/etcd-io/etcd/issues/8980) Watch(ctx context.Context, key string, opts ...OpOption) WatchChan // RequestProgress requests a progress notify response be sent in all watch channels. RequestProgress(ctx context.Context) error // Close closes the watcher and cancels all watch requests. Close() error }
func NewWatchFromWatchClient ¶
func NewWatchFromWatchClient(wc pb.WatchClient, c *Client) Watcher
Source Files
¶
Directories
¶
Path | Synopsis |
---|---|
Package balancer implements client balancer.
|
Package balancer implements client balancer. |
connectivity
Package connectivity implements client connectivity operations.
|
Package connectivity implements client connectivity operations. |
picker
Package picker defines/implements client balancer picker policy.
|
Package picker defines/implements client balancer picker policy. |
resolver/endpoint
Package endpoint resolves etcd entpoints using grpc targets of the form 'endpoint://<id>/<endpoint>'.
|
Package endpoint resolves etcd entpoints using grpc targets of the form 'endpoint://<id>/<endpoint>'. |
Package credentials implements gRPC credential interface with etcd specific logic.
|
Package credentials implements gRPC credential interface with etcd specific logic. |