RFC-0026 · gRPC Protocol Binding
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.
1. Purpose
This RFC defines gnomon.io.grpc — the gRPC protocol binding module for client operations. It specifies the slot extensions that gnomon.io.grpc registers on operation {} blocks, allowing authors to hand-author gRPC operations inline in a client.operations {} block without relying on a schema adapter.
gnomon.io.grpc is a protocol binding, not a schema adapter. It does not parse .proto files or generate operations from Protobuf definitions. For spec-backed gRPC clients driven by a .proto file or descriptor set, see RFC-0030 (Protobuf adapter), which generates operations in the form defined by this RFC.
This RFC defines:
- The slot extensions registered on
operation {}bygnomon.io.grpc(§2) - The four gRPC call modes and their gnomon operation semantics (§3)
- How gRPC status codes map to the gnomon error taxonomy (§4)
- How
auth:on the enclosingclientmaps to gRPC metadata (§5) - TLS configuration and the production guard against unencrypted connections (§6)
- Diagnostic codes in the M26xxx range (§7)
2. Slot Extensions
When gnomon.io.grpc is imported, it registers the following slots on operation {} blocks within any client that uses it. These slots are parsed by the compiler after loading gnomon.io.grpc’s module manifest (per RFC-0024 §6.2).
Operation slot extensions (applied to every operation {} block within a client that uses gnomon.io.grpc):
| Slot | Type | Required | Default | Description |
|---|---|---|---|---|
service: | Text | Yes | — | Fully-qualified gRPC service name (e.g. workos.directory.DirectoryService). |
rpc: | Text | Yes | — | RPC method name within the service (e.g. ListDirectories). |
mode: | CallMode | No | unary | Call mode: unary | server-streaming | client-streaming | bidi-streaming. |
package: | Text | No | — | Proto package name for fully-qualified type resolution. When provided, the runtime uses this to resolve message types in the proto registry rather than relying on reflection. |
deadline: | Integer | No | 30000 | Maximum time in milliseconds the runtime will wait for the call to complete before cancelling it. See §2.3. |
Client slot extensions (applied to each client {} block that uses gnomon.io.grpc):
| Slot | Type | Required | Default | Description |
|---|---|---|---|---|
tls: | TLSMode | No | system | TLS mode for the connection: none | system | custom. none disables TLS (development only; triggers M26614 in production). system uses the host system certificate store. custom uses a user-supplied certificate bundle (implementation-defined). |
2.1 Module Manifest (Normative)
module gnomon.io.grpc {
extends {
operation {
service: Text required
rpc: Text required
mode: CallMode optional default(unary)
package: Text optional
deadline: Integer optional default(30000) // milliseconds
}
client {
tls: TLSMode optional default(system)
// TLSMode: none | system | custom
// none — plaintext; development only (see §6.1)
// system — TLS using the system certificate store (default)
// custom — TLS using a user-supplied certificate bundle (implementation-defined)
}
}
}
2.2 Example
imports {
gnomon.io.grpc: "^1.0.0"
}
client WorkOSDirectory {
meaning: "WorkOS Directory Sync gRPC API."
baseUrl: "grpc.workos.com:443"
auth: bearer-token
tls: system -- use system certificate store (default; shown for clarity)
errors {
UNAVAILABLE: transient
DEADLINE_EXCEEDED: transient
UNAUTHENTICATED: terminal
}
operations {
listDirectories {
meaning: "List all directories for the current organization."
input {
organizationId: Text required
pageSize: Integer optional
pageToken: Text optional
}
returns: ListDirectoriesResponse
errors {
NOT_FOUND: terminal
}
service: "workos.directory.DirectoryService"
rpc: "ListDirectories"
mode: unary
package: "workos.directory"
deadline: 10000 -- 10 s; overrides the 30 s default for this operation
}
watchDirectoryEvents {
meaning: "Stream real-time directory events."
input {
organizationId: Text required
}
returns: Stream<DirectoryEvent>
errors {}
service: "workos.directory.DirectoryService"
rpc: "WatchEvents"
mode: server-streaming
package: "workos.directory"
}
}
}
2.3 Deadline Semantics (Normative)
If deadline: is not specified on an operation, the default deadline is 30,000 ms (30 seconds). A gRPC call that exceeds its deadline MUST be cancelled by the runtime immediately upon expiry. The cancelled call MUST produce error M26616 and MUST be reported to the caller as a DEADLINE_EXCEEDED status, subject to the operation’s errors {} classification.
Implementations MUST propagate the deadline as a gRPC deadline on the outgoing call (via the context.WithDeadline mechanism in the underlying gRPC transport), not merely as a client-side timer, so that the server is also notified.
3. Call Mode Semantics
gRPC supports four call modes. The mode: slot selects among them. The mode determines the required shape of the operation’s input {} fields and returns: type.
3.1 unary
A single request message is sent; a single response message is received. The operation blocks until the response arrives or the deadline is exceeded.
- Input: any
input {}schema; all fields are serialized into one request message. - Returns: any non-streaming return type.
- Gnomon call site:
execute {}block in anactionor asagastep.
3.2 server-streaming
A single request message is sent; the server responds with a stream of zero or more messages, followed by a terminal status.
- Input: any
input {}schema. - Returns: MUST be
Stream<T>whereTis the per-message type. The compiler emits M26615 if the declaredreturnstype is notStream<T>. - Gnomon call site: integrates with RFC-0020 reactive subscriptions. The returned
Stream<T>handle follows the RFC-0020 subscription lifecycle (open, pause, close).
3.3 client-streaming
The client sends a stream of request messages; the server responds with a single message after the client closes the stream.
- Input: MUST contain exactly one field of type
Stream<T>whereTis the per-message type. The compiler emits M26615 if no such field is declared. - Returns: any non-streaming return type.
- Gnomon call site:
execute {}block; theStream<T>input field is bound to a reactive source (RFC-0020).
3.4 bidi-streaming
The client and server exchange streams of messages concurrently.
- Input: MUST contain exactly one field of type
Stream<T>. - Returns: MUST be
Stream<U>. - Gnomon call site:
execute {}block with both input and return bound to RFC-0020 stream handles.
3.5 Mode Constraint Summary
mode: | Input constraint | Returns constraint |
|---|---|---|
unary | Any | Non-streaming |
server-streaming | Any | Stream<T> |
client-streaming | One field: Stream<T> | Non-streaming |
bidi-streaming | One field: Stream<T> | Stream<U> |
Violation of any constraint causes M26615 (error).
4. gRPC Status Code Taxonomy
gRPC calls terminate with a status code. The runtime maps gRPC status codes to the gnomon error taxonomy as follows.
4.1 Success
| gRPC status | Meaning | Action |
|---|---|---|
OK | Call succeeded | Deserialize response; bind to returns schema. |
4.2 Transient Errors
These errors indicate conditions that may resolve on retry.
| gRPC status | Default class | Notes |
|---|---|---|
UNAVAILABLE | transient | Server temporarily unavailable or shedding load. |
DEADLINE_EXCEEDED | transient | Call exceeded its deadline. |
If the operation’s errors {} block (or the client-level block) classifies either of these as transient, the runtime applies the configured retry policy (exponential backoff with jitter; defaults: 3 retries, initial delay 500 ms, max delay 10 s). If no matching selector is found, the runtime raises M26610.
4.3 Non-Retryable Auth Errors
| gRPC status | Action |
|---|---|
UNAUTHENTICATED | Non-retryable. If a matching selector is declared, apply its classification. Otherwise raise M26611. |
PERMISSION_DENIED | Non-retryable. If a matching selector is declared, apply its classification. Otherwise raise M26611. |
4.4 Not-Found
| gRPC status | Action |
|---|---|
NOT_FOUND | Non-retryable. If a matching selector is declared, apply its classification. Otherwise raise M26612. |
4.5 All Other Status Codes
Any gRPC status code not listed above is non-retryable. If a matching selector is declared in the errors {} block, apply it. Otherwise raise M26613.
gRPC status codes not listed in the selector table and not matched by any errors {} selector MUST be treated as non-retryable errors and MUST be reported to the caller as M26613 (unclassified status code).
4.6 Selector Matching
gRPC status code names (e.g. UNAVAILABLE, NOT_FOUND) are valid error-selector tokens when gnomon.io.grpc is in scope. They follow the same specificity rules as numeric HTTP selectors (RFC-0024 §3): an exact status code name beats a wildcard *.
5. Auth
gRPC transports authentication via call metadata (equivalent to HTTP headers at the protocol level). The auth: slot on the enclosing client maps to metadata entries as follows.
auth: value | gRPC metadata entry | Credential store key |
|---|---|---|
bearer-token | authorization: Bearer <token> | <ClientName>.token |
none | (none) | — |
api-key and basic auth schemes are not natively defined for gRPC in this RFC. Authors requiring those patterns MUST use none auth and inject credentials via the operation-level or client-level metadata using a custom interceptor (implementation-defined). A future RFC may standardize additional gRPC auth schemes.
Credential resolution follows the same precedence order as RFC-0025 §3.1 (deployment manifest → environment variable → runtime secret vault).
6. TLS Configuration
gRPC connections default to TLS. This is the normative default and requires no explicit configuration.
6.1 Disabling TLS
Setting tls: none on the client declaration disables TLS for development and testing against local servers (e.g. localhost:50051):
client LocalService {
baseUrl: "localhost:50051"
auth: none
tls: none -- plaintext; development only
operations { ... }
}
The compiler emits a warning when tls: none is present, advising authors that this configuration must not reach a production environment.
6.2 Production Guard
The runtime MUST detect the active environment at startup. If the environment is classified as production (determined by the deployment manifest or the GNOMON_ENV environment variable being set to production), the runtime MUST reject any client with tls: none and raise M26614 as a startup-time error, refusing to start. This guard cannot be bypassed at runtime; it can only be resolved by changing tls: to system or custom, or by operating in a non-production environment.
7. Diagnostic Codes
All codes in the M26xxx range are owned by this RFC.
| Code | Severity | Description |
|---|---|---|
| M26610 | Error | gRPC transient status code (UNAVAILABLE or DEADLINE_EXCEEDED) received with no matching transient selector in the errors {} block. |
| M26611 | Error | gRPC auth error (UNAUTHENTICATED or PERMISSION_DENIED) received with no matching selector in the errors {} block. |
| M26612 | Error | gRPC NOT_FOUND status received with no matching selector in the errors {} block. |
| M26613 | Error | gRPC status code not covered by any of the above special cases received with no matching selector in the errors {} block. |
| M26614 | Error | tls: none is set on a client in a production environment. Startup is aborted. |
| M26615 | Error | service: or rpc: slot missing from a gRPC operation; or streaming mode constraints violated (incorrect input or returns shape for the declared mode:). |
| M26616 | Error | A gRPC call exceeded its deadline: and was cancelled by the runtime. The call is reported to the caller as DEADLINE_EXCEEDED. |
7.1 Failure Mode Summary
| Code | Description | Severity |
|---|---|---|
| M26610 | Unhandled transient gRPC error | Error |
| M26611 | Unhandled gRPC auth error | Error |
| M26612 | Unhandled gRPC not-found | Error |
| M26613 | Unhandled gRPC status code | Error |
| M26614 | tls: none in production | Error |
| M26615 | Missing required slot or mode constraint violation | Error |
| M26616 | gRPC call deadline exceeded; call cancelled | Error |
8. What This RFC Does NOT Define
- Protobuf
.protofile parsing and operation generation → RFC-0030 - Channel pooling, load balancing, and service mesh integration — implementation concerns; not specified here
- gRPC-Web transport (browser compatibility) — deferred to a future RFC
- Interceptor API for custom metadata injection — implementation-defined
- OAuth2 token refresh for gRPC — deferred to a future authentication RFC