RFC-0034 · Protocol Server Bindings
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
RFC-0033 defines what a module exposes — the api declaration, which is protocol-agnostic. This RFC defines how a module exposes it — the serve declaration and the adapter protocol by which protocol modules (gnomon.io.http, gnomon.io.grpc, etc.) register the per-operation binding slots that populate a serve.
The design mirrors the client-side model from RFC-0024. Where RFC-0024 defined the client + operation primitive and a manifest extension protocol that allowed gnomon.io.http and others to add protocol-specific slots, this RFC defines the symmetric server-side primitive:
| Client side (RFC-0024) | Server side (this RFC) |
|---|---|
client declaration | serve declaration |
operation {} block | serve-operation {} block |
gnomon.io.http extends operation {} | gnomon.io.http extends serve-operation {} |
| Compiler generates typed call stubs | Compiler generates typed handler stubs |
| Protocol adapter reads incoming spec | Protocol adapter emits outgoing route table |
2. Definitions
servedeclaration: A named binding that attaches one wire protocol to oneapideclaration. Oneserveper protocol per API.serve-operationblock: A per-operation binding block inside aservedeclaration. Extended by protocol adapter modules with protocol-specific slots — exactly asoperation {}blocks are extended on the client side.- handler stub: The compiler-generated typed entry point for a single exposed operation. Receives a deserialized input, enforces auth per
api.auth, invokes the domain operation, and serializes the output or error response. - route table: The compiled set of all protocol-level routes produced by a
servebinding (e.g., HTTP method + path pairs, gRPC service/method names). Included in the compiled bundle (RFC-0002). - completeness: A
servebinding is complete when every operation in the referencedapi.exposeshas aserve-operationblock or is covered by the protocol adapter’s default mapping rule.
3. The serve Primitive
3.1 Syntax
serve-decl ::=
[epistemic-modifier]
"serve" IDENT "{" serve-body "}"
epistemic-modifier ::= "draft" | "experimental" | "stable"
serve-body ::=
"api" ":" IDENT
"protocol" ":" protocol-ref
[protocol-slot*]
serve-operation-block*
protocol-ref ::= "http" | "grpc" | "graphql" | "trpc"
serve-operation-block ::=
IDENT "{" slot* "}"
api:MUST reference anapideclaration in the same module. Binding another module’sapiin this module’sserveis not permitted and MUST produce error M34002.protocol:MUST be one of the recognized values. Unrecognized values or values for which the corresponding adapter module is not imported MUST produce error M34007.protocol-slot*— protocol-level slots registered by the adapter module’s manifest (e.g.,base:for HTTP,package:for gRPC). These are not per-operation; they apply to theserveas a whole.serve-operation-block— per-operation binding. TheIDENTMUST name an operation listed in the referencedapi.exposes. Naming an unlisted operation MUST produce error M34003.
3.2 Invariants
- A
serveMUST reference a resolvedapiin the same module. Cross-module serve bindings MUST produce error M34002. - Two
servedeclarations in the same module MUST NOT bind the sameapito the sameprotocol. Duplicate protocol bindings MUST produce error M34005. - Every operation in the referenced
api.exposesMUST be covered — either by an explicitserve-operationblock or by the protocol adapter’s default mapping. Missing coverage MUST produce error M34001. - A
serve-operationblock MUST NOT name an operation absent fromapi.exposes. Such a block MUST produce error M34003. - A
serve-operationblock MUST NOT produce a route that conflicts with anotherserve-operationblock in the sameserve. Route conflicts MUST produce error M34004. - A
stableservethat references adraftapiMUST produce error M33008.
4. Adapter Protocol
The adapter protocol for server bindings follows the same manifest-extension pattern as RFC-0024 §6. Protocol modules declare their server-side slot extensions in their module manifest, alongside the existing client-side extensions.
4.1 Module Manifest Form
module gnomon.io.http {
extends {
// Existing: client-side operation slot extensions (RFC-0025)
operation {
method: HTTPMethod required
path: Text required
body: Text optional
query: List<Text> optional
headers: Map<Text, Text> optional
responseAs: ResponseEncoding optional default(json)
timeout: Integer optional default(30000)
}
// New: server-side serve-level slots
serve {
base: Text optional default("/")
cors: CORSPolicy optional
timeout: Integer optional default(30000)
}
// New: server-side per-operation slots
serve-operation {
method: HTTPMethod required
path: Text required
body: Text optional
query: List<Text> optional
statusCode: Integer optional default(200)
}
}
}
The compiler loads the adapter module’s manifest before parsing any serve declaration with the matching protocol: value. The serve {} block and each serve-operation {} block within that serve may then use the registered slots.
4.2 Default Mapping
A protocol adapter MAY declare a default-mapping rule that automatically derives serve-operation bindings from the operation’s kind and name, without requiring an explicit per-operation block. If a default mapping is declared and an operation has no explicit serve-operation block, the default mapping is applied.
Default mapping rules (normative for HTTP):
queryoperations →GET /<operationName>actionandprocedureoperations →POST /<operationName>
When a default mapping is applied, the compiler MUST emit informational diagnostic M34010 identifying the derived route, so authors can audit what was generated.
A serve that relies entirely on default mappings (no explicit serve-operation blocks) is valid provided the default mapping covers every exposed operation. If any operation falls outside the default mapping’s scope, M34001 is emitted.
5. Handler Stub Generation
For each serve-operation binding, the compiler generates a typed handler stub. The stub enforces the following pipeline at runtime:
- Deserialize input — parse the inbound request body or parameters into the operation’s declared
input {}schema using the per-field binding modifiers or the protocol adapter’s default parameter location rules (§5.1). Malformed input MUST be rejected with a protocol-appropriate error response before the handler body runs. - Null coercion at boundary — any inbound JSON field whose value is
nullis handled according to the null-at-boundary policy (§5.2) before the deserialized value is passed to the operation. The Gnomon type system does not permit null; this step coerces or rejects nulls before they enter the domain model. - Authenticate — enforce
api.authrequirements. Unauthenticated requests MUST be rejected before the handler body runs. - Authorize — evaluate any
policydeclarations applicable to the operation. Unauthorized requests MUST be rejected. - Invoke — call the domain operation with the deserialized, null-coerced input.
- Inject common errors — the
api.errors.commontypes are merged into the error taxonomy available to the serialization step. - Serialize output — marshal the operation’s return value (or error) into the protocol-appropriate response form.
Handler stubs are a compile-time output. They are included in the compiled module bundle (RFC-0002) and are not generated at runtime. The runtime loads the bundle and dispatches incoming requests to the pre-compiled stubs.
5.1 Per-Field Binding Modifiers on input {} Fields
The input {} fields of exposed operations support per-field binding modifiers (RFC-0024 §3, RFC-0008 §6.3a). These modifiers declare how the handler stub extracts each field from the inbound request, taking precedence over the serve-operation-level path:, query:, and body: slots and over the protocol adapter’s default parameter location algorithm.
Supported binding modifiers for HTTP serve-operation input {} fields:
| Modifier | Extraction source |
|---|---|
path | Extracted from the URL path segment matching {fieldName} |
query | Extracted from the URL query parameter with the same name |
body | Extracted from (or populated from) the request body |
header | Extracted from the X-<FieldName> request header |
header("X-Custom-Name") | Extracted from the named request header |
A field that carries a binding modifier AND is also referenced by a serve-operation-level slot (e.g., appears in path: or body:) MUST produce error M34023 (conflicting inbound binding).
5.2 Null-at-Boundary Policy
The Gnomon type system prohibits null as a value (RFC-0006 §4.A invariant 7). Inbound requests — particularly JSON — may contain explicit null values. The handler stub applies the following policy at the inbound boundary, before any values enter the domain model:
| Inbound field value | Field modifier | Policy | Diagnostic |
|---|---|---|---|
null | required | Reject request — return protocol-appropriate 400/invalid-argument | M34024 |
null | optional with default(v) | Treat null as field-absent, then apply v | — |
null | optional without default | Treat null as field-absent; do not manufacture a zero value | M34025 (info — emitted with --verbose-serve) |
null for a field absent from the input {} schema | — | Silently discard | — |
This policy implements the normative null handling defined in RFC-0006 §4.D for inbound serialization boundaries. The handler stub’s null coercion step (pipeline step 2) is the sole location where null enters and is resolved; null MUST NOT propagate past the handler stub into the domain operation.
For outbound serialization (step 7), the handler stub MUST NOT emit null for any field. Optional fields absent from the response are omitted from the JSON object entirely rather than serialized as null.
6. Multi-Protocol Exposure
A single api MAY be bound to multiple protocols by declaring multiple serve declarations, each with the same api: reference and a different protocol:. Each serve is independent — its route table, default mapping, and per-operation slots are evaluated separately.
// modules/selectsmart/benefits/serve.gnm
import "gnomon.io.http"
import "gnomon.io.grpc"
serve BenefitsHTTP {
api: BenefitsAPI
protocol: http
base: "/api/v1"
enrollInPlan { method: POST, path: "/enrollments" }
getEnrollmentStatus { method: GET, path: "/enrollments/{enrollmentId}" }
listAvailablePlans { method: GET, path: "/plans" }
getHouseholdSummary { method: GET, path: "/households/{householdId}/summary" }
changeElection { method: PATCH, path: "/enrollments/{enrollmentId}/election" }
terminateCoverage { method: DELETE, path: "/enrollments/{enrollmentId}" }
submitEnrollment { method: POST, path: "/enrollments/submit" }
amendElection { method: POST, path: "/enrollments/{enrollmentId}/amend" }
}
serve BenefitsGRPC {
api: BenefitsAPI
protocol: grpc
package: "benefits.v1"
service: "BenefitsService"
enrollInPlan { rpc: "Enroll" }
getEnrollmentStatus { rpc: "GetStatus" }
listAvailablePlans { rpc: "ListPlans" }
getHouseholdSummary { rpc: "GetHouseholdSummary" }
changeElection { rpc: "ChangeElection" }
terminateCoverage { rpc: "Terminate" }
submitEnrollment { rpc: "Submit" }
amendElection { rpc: "Amend" }
}
7. IO RFC Extensions (Normative)
Each IO protocol RFC that supports server-side exposure gains a new normative section defining the serve-operation slots registered by that protocol’s adapter. These sections are normative extensions to the existing RFCs and are governed by those RFCs’ authoring teams.
7.1 HTTP (RFC-0025 §8 — to be authored)
gnomon.io.http registers the following serve-operation slots:
| Slot | Type | Required | Default | Description |
|---|---|---|---|---|
method: | HTTPMethod | Yes | — | HTTP method to handle: GET, POST, PUT, PATCH, DELETE |
path: | Text | Yes | — | URL path template. Tokens {fieldName} bind to input {} fields. |
body: | Text | No | — | Name of the input {} field populated from the request body. |
query: | List<Text> | No | [] | Names of input {} fields populated from query parameters. |
statusCode: | Integer | No | 200 | HTTP status code on success. |
Route conflict rule: Two serve-operation blocks within the same serve that resolve to the same HTTP method + path template MUST produce error M34004.
7.2 gRPC (RFC-0026 §8 — to be authored)
gnomon.io.grpc registers the following serve-operation slots:
| Slot | Type | Required | Default | Description |
|---|---|---|---|---|
rpc: | Text | Yes | — | The gRPC method name within the declared service. |
stream: | GRPCStreamMode | No | unary | unary | server-streaming | client-streaming | bidi-streaming. Must be consistent with the operation’s returns type (Stream<T> for streaming). |
deadline: | Integer | No | 30000 | Per-call deadline in milliseconds (mirrors RFC-0026 §2.3). |
The serve-level package: and service: slots are registered at the serve block level, not per operation.
7.3 GraphQL (RFC-0027 §8 — to be authored)
gnomon.io.graphql registers the following serve-operation slots:
| Slot | Type | Required | Default | Description |
|---|---|---|---|---|
operationType: | GraphQLOperationType | Yes | — | query | mutation | subscription. |
fieldName: | Text | No | operation name | The GraphQL field name in the root type. Defaults to the operation name. |
description: | Text | No | meaning field value | Populates the GraphQL schema description. |
GraphQL query operations map to the root Query type; action and procedure operations map to the root Mutation type; reactive operations MAY map to Subscription.
7.4 tRPC (RFC-0029 §10 — to be authored)
gnomon.io.trpc registers the following serve-operation slots:
| Slot | Type | Required | Default | Description |
|---|---|---|---|---|
procedure: | Text | No | operation name | The tRPC procedure name in the router. Defaults to the operation name. |
type: | tRPCProcedureType | Yes | — | query | mutation. Subscriptions are not supported in this revision. |
The serve-level slot router: names the exported router type. Defaults to AppRouter.
8. Declaration Class and File Naming
serve is an Operations-class declaration (RFC-0008 §3), alongside api, action, and query. It MUST be declared in a file named serve.gnm within a concept folder. Placing a serve declaration in any other file class MUST produce error M08701 (mixed declaration classes).
The serve.gnm predefined filename is added to RFC-0001’s predefined file table. The compiler auto-discovers serve.gnm under the folder convention.
Both api.gnm and serve.gnm naturally co-locate in the same concept folder (e.g., modules/selectsmart/benefits/api.gnm and modules/selectsmart/benefits/serve.gnm).
9. Relationship to RFC-0024 Lockfile
RFC-0024 §6.3 defines a lockfile that records the resolved schema hash for spec-backed client declarations. The serve declaration has no equivalent lockfile requirement — the server contract is entirely author-defined and does not resolve external specs. The compiled bundle’s route table (RFC-0002) serves as the authoritative record of what was emitted.
Linked References
The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.
11. Diagnostic Codes (M34xxx)
All diagnostics introduced by this RFC occupy the M34000–M34999 range.
M340x: Serve binding structure
- M34001:
servebinding is incomplete — one or more operations inapi.exposeshave noserve-operationblock and no applicable default mapping (error) - M34002:
serveapi:references anapideclared in another module — cross-module serve bindings are not permitted (error) - M34003:
serve-operationblock names an operation not listed in the referencedapi.exposes— add the operation to theapifirst (error) - M34004: Two
serve-operationblocks in the sameserveresolve to the same protocol route — routes MUST be distinct (error) - M34005: Two
servedeclarations in the same module bind the sameapito the sameprotocol— only oneserveper protocol per API (error) - M34006:
serveapi:reference is unresolved — noapideclaration with that name exists in scope (error) - M34007:
serveprotocol:value is unrecognized or the corresponding adapter module is not imported (error)
M341x: Default mapping and completeness
- M34010:
serve-operationbinding derived from protocol default mapping (informational — emitted with--verbose-serve) - M34011: Default-mapped operation name does not follow the convention required by the default mapping rule; route may be unexpected (warning)
M342x: Handler stub generation
- M34020: Handler stub for operation has an unreachable error path — a
errors.commontype from theapideclaration cannot be serialized by this protocol (warning) - M34021:
api.authscheme is not supported by the selected protocol adapter — the scheme will be silently ignored at runtime (error) - M34022:
serve-operationdeclares a streaming mode (stream: server-streamingetc.) but the referenced operation’sreturnstype is notStream<T>(error) - M34023:
input {}field carries a per-field binding modifier AND is referenced by aserve-operation-level slot — conflicting inbound binding assignments (error) - M34024: Inbound request contains
nullfor arequiredfield — request rejected at boundary (runtime error; emitted as diagnostic during stub static analysis when the field’s type excludes null) - M34025: Inbound
nullfor anoptionalfield without adefaultnormalized to field-absent (informational — emitted with--verbose-serve)