v3 RPC

Source: server/etcdserver/api/v3rpc/.

Purpose

v3rpc exposes the gRPC services declared in api/etcdserverpb/rpc.proto: KV, Watch, Lease, Auth, Cluster, Maintenance. It also implements health.HealthServer for gRPC health probes and registers all interceptors (auth, metrics, logging).

Directory layout

server/etcdserver/api/v3rpc/
├── grpc.go              # Server() factory: builds *grpc.Server with all options
├── interceptor.go       # Unary + stream interceptors (auth, recovery, throttle)
├── codec.go             # Custom protobuf codec
├── header.go            # Cluster/member id headers on every response
├── health.go            # gRPC HealthServer
├── key.go               # KV service
├── watch.go             # Watch service (streaming)
├── lease.go             # Lease service (mix of unary + streaming)
├── auth.go              # Auth service
├── member.go            # Cluster service
├── maintenance.go       # Maintenance service (snapshot, defrag, hash, alarm)
├── quota.go             # Backend-quota guard
├── util.go              # Error translation, header helpers
├── metrics.go
└── *_test.go, validationfuzz_test.go

Key abstractions

Symbol	File	Description
Server	server/etcdserver/api/v3rpc/grpc.go	Builds the gRPC server with TLS, tracing, interceptors, services
kvServer, watchServer, leaseServer, authServer, clusterServer, maintenanceServer	corresponding .go files	Each implements the generated *Server interface
quotaKVServer	server/etcdserver/api/v3rpc/quota.go	Wraps kvServer to reject puts/txns that would exceed --quota-backend-bytes
serverInterceptor / streamInterceptor	server/etcdserver/api/v3rpc/interceptor.go	Unary + stream interceptor chains
togRPCError	server/etcdserver/api/v3rpc/util.go	Maps internal errors to gRPC codes via api/v3/v3rpc/rpctypes

Interceptor chain

graph TD
    req[Incoming gRPC] --> recov[recovery interceptor]
    recov --> auth[AuthInterceptor]
    auth --> tracing[tracing interceptor]
    tracing --> metrics[metrics interceptor]
    metrics --> handler[service handler]
    handler --> resp[response]

The interceptors are wired in interceptor.go::newUnaryInterceptor / newStreamInterceptor.

Watch service shape

Watch is the most complex service. The server holds a per-stream serverWatchStream that owns:

• A receive loop reading client WatchRequests.
• A send loop pulling events from mvcc.WatchStream and writing WatchResponses.
• A control channel for cancellations and progress notifications.

watch.go is 18 KB; many of the trickier behaviors — fragmented events, progress-on-quiet-keys, prev_kv, watch-id reuse — live there.

Health endpoint

server/etcdserver/api/v3rpc/health.go exposes a gRPC HealthCheck. Combined with etcdhttp/health.go (HTTP), it is what Kubernetes probes use to declare an etcd pod ready.

Integration points

• EtcdServer (server/etcdserver/v3_server.go) provides the actual KV / lease / auth / maintenance methods this package wraps.
• AuthStore is reached through the auth interceptor.
• Backend quota — quota.go consults mvcc.Store.Quota.
• Tracing — propagated via OpenTelemetry interceptors when distributed tracing is enabled.

Entry points for modification

• New service → add to rpc.proto, regenerate, implement here, register in grpc.go.
• New interceptor → interceptor.go plus the chain construction in grpc.go.
• New error translation → util.go::togRPCError and api/v3/v3rpc/rpctypes/error.go.
• Validation hardening → validationfuzz_test.go is the fuzz harness; consider extending it for new request shapes.