client

The official Go client. Source: client/v3/ plus the support module client/pkg/.

Purpose

go.etcd.io/etcd/client/v3 is the Go SDK most consumers (Kubernetes, the etcdctl CLI, hundreds of operators) use to talk to an etcd cluster. client/pkg factors out non-gRPC helpers — TLS, file IO, type aliases, logging — that are also useful to non-client code (e.g. the server's own integration tests).

Directory layout

client/
├── pkg/                       # client/pkg/v3 module
│   ├── fileutil/              # file locking, pre-allocation, fsync
│   ├── logutil/               # zap helpers
│   ├── srv/                   # DNS SRV-based discovery
│   ├── testutil/              # leak-detector, recordingTransport, ...
│   ├── tlsutil/               # cipher suites, TLS version helpers
│   ├── transport/             # *http.Transport / TLS configuration helpers
│   ├── types/                 # ID, URLs, slice helpers
│   └── verify/                # debug-build invariants
└── v3/                        # client/v3 module — the actual SDK
    ├── client.go              # Client struct
    ├── kv.go, lease.go, watch.go, auth.go, cluster.go, maintenance.go
    ├── txn.go, op.go, compare.go, options.go
    ├── retry.go, retry_interceptor.go
    ├── credentials/           # gRPC credentials wrapper
    ├── concurrency/           # Mutex, Election, STM (transactional KV)
    ├── leasing/               # Caching client that holds short-lived leases
    ├── mirror/                # KV mirroring helper
    ├── namespace/             # Prefix-namespacing wrapper
    ├── naming/                # gRPC naming.Resolver implementations
    ├── ordering/              # Linearizable read ordering helpers
    ├── snapshot/              # Snapshot save helpers
    ├── kubernetes/            # Kubernetes-tailored helpers
    ├── clientv3util/          # Common transaction shorthand (KeyExists, KeyMissing)
    └── internal/              # Private endpoint resolver and gRPC plumbing

Key abstractions

Symbol	File	Description
Client	client/v3/client.go	Top-level client, embeds Cluster, KV, Lease, Watcher, Auth, Maintenance
Config	client/v3/config.go	Endpoints, dial timeout, credentials, keepalive, retry policy
KV interface	client/v3/kv.go	Put, Get, Delete, Compact, Do, Txn
Lease interface	client/v3/lease.go	Grant, Revoke, KeepAlive, KeepAliveOnce, TimeToLive, Leases
Watcher interface	client/v3/watch.go	Watch, RequestProgress, Close
Auth, Cluster, Maintenance	same package	Their RPC services
concurrency.Mutex, concurrency.Election, concurrency.NewSTM	client/v3/concurrency/	Distributed primitives built on top of leases + transactions
retryInterceptor	client/v3/retry_interceptor.go	gRPC interceptor that retries idempotent calls on transient errors

How it works

Every Client owns:

• A *grpc.ClientConn connected to one or more endpoints.
• A Cluster view that periodically refreshes membership.
• Per-service handles (kv, lease, watcher, auth, maintenance) implemented as thin wrappers around the generated gRPC stubs.

The unary retry policy lives in retry.go and retry_interceptor.go; the stream retry policy (for Watch) is implemented in watch.go. Both honor Client.Ctx() for cancellation.

Lease.KeepAlive runs a goroutine per lease ID that streams LeaseKeepAliveRequests and surfaces failures as a closed channel, letting callers fail fast.

Examples

The client/v3 test files at the top of the directory (e.g. example_kv_test.go) are symlinks into tests/integration/clientv3/examples/. This keeps godoc-style examples close to the package they document while letting them run as real integration tests.

Integration points

• Imports api/ for protobuf types.
• Uses client/pkg/transport for TLS and client/pkg/srv for DNS-based endpoint resolution.
• Built on top of google.golang.org/grpc.
• Exposed through:
  • etcdctl (every CLI command),
  • cache/ (the watch-fan-out shard imports clientv3.Client directly),
  • tests/integration/cache_test.go, tests/integration/clientv3/...,
  • etcdutl/snapshot/ for snapshot save.

Entry points for modification

• New high-level helper → client/v3/clientv3util/ for tiny utilities, otherwise a new file at the package root.
• New retry behavior → client/v3/retry.go.
• New gRPC dial option → client/v3/config.go (then propagate via Config.DialOptions).
• Concurrency primitives → client/v3/concurrency/.