gnomonlearn

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 declarationserve declaration
operation {} blockserve-operation {} block
gnomon.io.http extends operation {}gnomon.io.http extends serve-operation {}
Compiler generates typed call stubsCompiler generates typed handler stubs
Protocol adapter reads incoming specProtocol adapter emits outgoing route table

2. Definitions

  • serve declaration: A named binding that attaches one wire protocol to one api declaration. One serve per protocol per API.
  • serve-operation block: A per-operation binding block inside a serve declaration. Extended by protocol adapter modules with protocol-specific slots — exactly as operation {} 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 serve binding (e.g., HTTP method + path pairs, gRPC service/method names). Included in the compiled bundle (RFC-0002).
  • completeness: A serve binding is complete when every operation in the referenced api.exposes has a serve-operation block 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 an api declaration in the same module. Binding another module’s api in this module’s serve is 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 the serve as a whole.
  • serve-operation-block — per-operation binding. The IDENT MUST name an operation listed in the referenced api.exposes. Naming an unlisted operation MUST produce error M34003.

3.2 Invariants

  1. A serve MUST reference a resolved api in the same module. Cross-module serve bindings MUST produce error M34002.
  2. Two serve declarations in the same module MUST NOT bind the same api to the same protocol. Duplicate protocol bindings MUST produce error M34005.
  3. Every operation in the referenced api.exposes MUST be covered — either by an explicit serve-operation block or by the protocol adapter’s default mapping. Missing coverage MUST produce error M34001.
  4. A serve-operation block MUST NOT name an operation absent from api.exposes. Such a block MUST produce error M34003.
  5. A serve-operation block MUST NOT produce a route that conflicts with another serve-operation block in the same serve. Route conflicts MUST produce error M34004.
  6. A stable serve that references a draft api MUST 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):

  • query operations → GET /<operationName>
  • action and procedure operations → 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:

  1. 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.
  2. Null coercion at boundary — any inbound JSON field whose value is null is 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.
  3. Authenticate — enforce api.auth requirements. Unauthenticated requests MUST be rejected before the handler body runs.
  4. Authorize — evaluate any policy declarations applicable to the operation. Unauthorized requests MUST be rejected.
  5. Invoke — call the domain operation with the deserialized, null-coerced input.
  6. Inject common errors — the api.errors.common types are merged into the error taxonomy available to the serialization step.
  7. 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:

ModifierExtraction source
pathExtracted from the URL path segment matching {fieldName}
queryExtracted from the URL query parameter with the same name
bodyExtracted from (or populated from) the request body
headerExtracted 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 valueField modifierPolicyDiagnostic
nullrequiredReject request — return protocol-appropriate 400/invalid-argumentM34024
nulloptional with default(v)Treat null as field-absent, then apply v—
nulloptional without defaultTreat null as field-absent; do not manufacture a zero valueM34025 (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:

SlotTypeRequiredDefaultDescription
method:HTTPMethodYes—HTTP method to handle: GET, POST, PUT, PATCH, DELETE
path:TextYes—URL path template. Tokens {fieldName} bind to input {} fields.
body:TextNo—Name of the input {} field populated from the request body.
query:List<Text>No[]Names of input {} fields populated from query parameters.
statusCode:IntegerNo200HTTP 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:

SlotTypeRequiredDefaultDescription
rpc:TextYes—The gRPC method name within the declared service.
stream:GRPCStreamModeNounaryunary | server-streaming | client-streaming | bidi-streaming. Must be consistent with the operation’s returns type (Stream<T> for streaming).
deadline:IntegerNo30000Per-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:

SlotTypeRequiredDefaultDescription
operationType:GraphQLOperationTypeYes—query | mutation | subscription.
fieldName:TextNooperation nameThe GraphQL field name in the root type. Defaults to the operation name.
description:TextNomeaning field valuePopulates 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:

SlotTypeRequiredDefaultDescription
procedure:TextNooperation nameThe tRPC procedure name in the router. Defaults to the operation name.
type:tRPCProcedureTypeYes—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: serve binding is incomplete — one or more operations in api.exposes have no serve-operation block and no applicable default mapping (error)
  • M34002: serve api: references an api declared in another module — cross-module serve bindings are not permitted (error)
  • M34003: serve-operation block names an operation not listed in the referenced api.exposes — add the operation to the api first (error)
  • M34004: Two serve-operation blocks in the same serve resolve to the same protocol route — routes MUST be distinct (error)
  • M34005: Two serve declarations in the same module bind the same api to the same protocol — only one serve per protocol per API (error)
  • M34006: serve api: reference is unresolved — no api declaration with that name exists in scope (error)
  • M34007: serve protocol: value is unrecognized or the corresponding adapter module is not imported (error)

M341x: Default mapping and completeness

  • M34010: serve-operation binding 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.common type from the api declaration cannot be serialized by this protocol (warning)
  • M34021: api.auth scheme is not supported by the selected protocol adapter — the scheme will be silently ignored at runtime (error)
  • M34022: serve-operation declares a streaming mode (stream: server-streaming etc.) but the referenced operation’s returns type is not Stream<T> (error)
  • M34023: input {} field carries a per-field binding modifier AND is referenced by a serve-operation-level slot — conflicting inbound binding assignments (error)
  • M34024: Inbound request contains null for a required field — request rejected at boundary (runtime error; emitted as diagnostic during stub static analysis when the field’s type excludes null)
  • M34025: Inbound null for an optional field without a default normalized to field-absent (informational — emitted with --verbose-serve)