The contract between a grpcd server and the services and clients that talk to
it: three RPCs, defined in protos/grpcd/, and the rules an implementation of
either side honors. Beside them, the admission contract a grpcd gateway
consults services with, defined in protos/admission/.
go get github.com/grpcd/protosThe generated Go lives at the module root, package grpcd, with the Connect
handlers and clients in grpcdconnect and the admission messages in
admission.
Every method name on the wire is gRPC wire format: a leading slash, the fully qualified service name, a slash, and the method name.
Valid:
/Service/Method/package.Service/Method/deeply.nested.package.Service/Method
Invalid:
package.Service.Method(no slashes)/package.Service/Method/(trailing slash)package.Service/Method(no leading slash)//package.Service/Method(consecutive slashes)/package.Service/Get Method(whitespace)
This is the form that appears as the HTTP/2 :path, so a client discovering a
method holds the string it will send. The server rejects anything else with
INVALID_ARGUMENT.
An address is host:port. The server composes it: the IP comes from the peer
of the Register connection, the port from the request. Neither party holds
both halves. A containerized service does not know its reachable IP, and the
server sees only the ephemeral source port of the connection. Reading the IP
off the connection also means a service can register only the address it
actually connected from.
A method maps to a set of addresses. Replicas of one service serve the same methods and each registers its own address, so removing one leaves the others.
rpc Register(RegisterRequest) returns (stream RegisterResponse);The request carries the service's name, its method list, and its listening
port. The server writes one row per method, sends one empty RegisterResponse,
and holds the stream. The stream then carries nothing.
The registration is the stream. When it ends, by clean shutdown, crash, or transport failure, the server removes every row the request named. There is no refresh, no expiry, and no deregistration RPC; a service that crashes and one that exits cleanly take the same path.
server_name names the service, not the instance. Replicas share it; the
address identifies the instance.
A Register naming no methods, or a port outside 1–65535, is rejected with
INVALID_ARGUMENT.
rpc Discover(stream DiscoverRequest) returns (stream DiscoverResponse);The client's first message is method_name. The server answers with one
candidate address, drawn at random from the method's set, so clients
discovering the same method spread across its replicas.
The client reaches the candidate. If it can, it closes the stream. If it
cannot, it sends dead_address naming the candidate; the server removes that
address from the method and answers with the next.
When the set is empty the server holds the stream and answers with the next
address registered for the method as it arrives. The client blocks on its
receive rather than asking again. A first message with no_wait set asks for
NOT_FOUND instead of the hold: a client resolving a single request, a
gateway forwarding one, has nothing to wait for, while a client that will hold
the address waits.
A client holds the address it took until the transport to it drops. It then
opens a new Discover, reports the address dead, and takes the next candidate.
rpc Watch(WatchRequest) returns (stream WatchResponse);The request names a method and the address the client holds for it. The server holds the stream.
When a new address registers for the method, the server sends it to a share of
the clients holding other addresses: each holder is chosen with probability
1/N, N being the method's address count after the addition. The rest hear
nothing. The expected share of clients moving is the new replica's fair share,
so a new replica takes its part of existing connections without every client
reconnecting.
A client sent an address probes it. Reachable: it moves, opens a new Watch
naming the new address, and closes the old one. Unreachable: it stays and
reports nothing.
A client opens Watch before closing the Discover that gave it the address,
and opens the new Watch before closing the old one, so no registration falls
between the two.
The server pushes to a client only on a stream that client opened and holds: a
Discover waiting for a registration, or a Watch naming an address it holds.
When the Watch stream breaks, the client opens a new one naming the same
address.
A client reporting an address dead may be wrong; its own network can be at
fault while the service is healthy. The server treats the open Register
stream as proof the service is up and writes the row back. A client with a
persistent local fault drives a remove-and-restore cycle rather than losing the
row for everyone.
A gateway routing through grpcd consults admission services before forwarding
a request. The contract is two messages, AdmissionRequest and
AdmissionResponse, with no shared service: each admission service declares
its own unary RPC taking the one and returning the other, and the gateway is
configured with that RPC's procedure name. Method discovery keys on the
procedure, so two admission services never share one.
AdmissionRequest carries the target procedure, every header as received, and
the peer (remote address and, over TLS, the client certificate). The body is
never sent. AdmissionResponse names headers to remove and headers to set on
the forwarded request, remove applied before set, and may name a different
procedure to forward to. A refusal is the error the RPC returns, which the
gateway answers to the client without forwarding.
service Authenticator {
rpc Authenticate(admission.AdmissionRequest) returns (admission.AdmissionResponse);
}