gnomonlearn

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 {} by gnomon.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 enclosing client maps 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):

SlotTypeRequiredDefaultDescription
service:TextYes—Fully-qualified gRPC service name (e.g. workos.directory.DirectoryService).
rpc:TextYes—RPC method name within the service (e.g. ListDirectories).
mode:CallModeNounaryCall mode: unary | server-streaming | client-streaming | bidi-streaming.
package:TextNo—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:IntegerNo30000Maximum 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):

SlotTypeRequiredDefaultDescription
tls:TLSModeNosystemTLS 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 an action or a saga step.

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> where T is the per-message type. The compiler emits M26615 if the declared returns type is not Stream<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> where T is 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; the Stream<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 constraintReturns constraint
unaryAnyNon-streaming
server-streamingAnyStream<T>
client-streamingOne field: Stream<T>Non-streaming
bidi-streamingOne 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 statusMeaningAction
OKCall succeededDeserialize response; bind to returns schema.

4.2 Transient Errors

These errors indicate conditions that may resolve on retry.

gRPC statusDefault classNotes
UNAVAILABLEtransientServer temporarily unavailable or shedding load.
DEADLINE_EXCEEDEDtransientCall 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 statusAction
UNAUTHENTICATEDNon-retryable. If a matching selector is declared, apply its classification. Otherwise raise M26611.
PERMISSION_DENIEDNon-retryable. If a matching selector is declared, apply its classification. Otherwise raise M26611.

4.4 Not-Found

gRPC statusAction
NOT_FOUNDNon-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: valuegRPC metadata entryCredential store key
bearer-tokenauthorization: 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.

CodeSeverityDescription
M26610ErrorgRPC transient status code (UNAVAILABLE or DEADLINE_EXCEEDED) received with no matching transient selector in the errors {} block.
M26611ErrorgRPC auth error (UNAUTHENTICATED or PERMISSION_DENIED) received with no matching selector in the errors {} block.
M26612ErrorgRPC NOT_FOUND status received with no matching selector in the errors {} block.
M26613ErrorgRPC status code not covered by any of the above special cases received with no matching selector in the errors {} block.
M26614Errortls: none is set on a client in a production environment. Startup is aborted.
M26615Errorservice: or rpc: slot missing from a gRPC operation; or streaming mode constraints violated (incorrect input or returns shape for the declared mode:).
M26616ErrorA 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

CodeDescriptionSeverity
M26610Unhandled transient gRPC errorError
M26611Unhandled gRPC auth errorError
M26612Unhandled gRPC not-foundError
M26613Unhandled gRPC status codeError
M26614tls: none in productionError
M26615Missing required slot or mode constraint violationError
M26616gRPC call deadline exceeded; call cancelledError

8. What This RFC Does NOT Define

  • Protobuf .proto file 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