RFC-0025 · HTTP 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.http — the HTTP/1.1 and HTTP/2 protocol binding module for client operations. It specifies the slot extensions that gnomon.io.http registers on operation {} blocks, allowing authors to hand-author HTTP operations inline in a client.operations {} block without relying on a schema adapter.
gnomon.io.http is a protocol binding, not a schema adapter. It does not parse or generate operations from external specifications. For spec-backed HTTP clients driven by an OpenAPI document, see RFC-0028 (OpenAPI adapter), which generates operations in the form defined by this RFC.
This RFC defines:
- The slot extensions registered on
operation {}bygnomon.io.http(§2) - How each
auth:value on the enclosingclientmaps to outbound HTTP headers (§3) - The rules for distributing
input {}fields across path parameters, query parameters, and request body (§4) - How HTTP responses are deserialized and bound to the operation’s
returnsschema (§5) - How the
baseUrl:from the enclosingclientis combined with the operation’spath:(§6) - Diagnostic codes in the M25xxx range (§7)
2. Slot Extensions
When gnomon.io.http 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.http’s module manifest (per RFC-0024 §6.2).
| Slot | Type | Required | Default | Description |
|---|---|---|---|---|
method: | HTTPMethod | Yes | — | HTTP method: GET, POST, PUT, PATCH, DELETE, or HEAD |
path: | Text | Yes | — | URL path template. Tokens of the form {fieldName} are interpolated from input {} fields. |
body: | Text | No | — | Name of the input {} field to serialize as the request body. Serialized as JSON unless overridden. |
query: | List<Text> | No | [] | Names of input {} fields to append as URL query parameters. |
headers: | Map<Text, Text> | No | {} | Static header name → value pairs added to every request. Merged with client-level headers {}, with operation-level entries winning on conflict. |
responseAs: | ResponseEncoding | No | json | How to decode the response body: json | text | binary. |
timeout: | Integer | No | 30000 | Per-request timeout in milliseconds. Overrides any client-level default. |
2.1 Module Manifest (Normative)
The slot extensions above are declared in gnomon.io.http’s module manifest as follows:
module gnomon.io.http {
extends {
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)
}
}
}
The compiler loads this manifest before parsing any client declaration that imports gnomon.io.http. Operations in that client’s operations {} block may then use these slots in addition to the primitive slots (input, returns, errors) defined in RFC-0024 §3.
2.2 Per-Field Binding Modifiers
gnomon.io.http supports per-field binding modifiers on input {} fields (RFC-0024 §3, RFC-0008 §6.3a). When a field carries a binding modifier, that modifier takes precedence over the operation-level path:, query:, and body: slots and over the distribution fallback algorithm (§4).
Supported binding modifiers on HTTP operation input {} fields:
| Modifier | Effect |
|---|---|
path | Field is a path parameter. Interpolated into the path: template as {fieldName}. |
query | Field is appended to the URL as a query parameter. |
body | Field is serialized as (or into) the request body. |
header | Field is sent as the X-<FieldName> request header. |
header("X-Custom-Name") | Field is sent as the named request header. |
A field MUST NOT carry more than one binding modifier. A field that carries a binding modifier AND appears in the operation-level path: template, query: list, or body: slot is a conflict and MUST produce error M25514.
When per-field modifiers are present, any input {} field without a binding modifier falls through to the distribution fallback (§4). This means per-field modifiers and operation-level slots can coexist; the per-field modifiers simply claim their fields first.
2.3 Example
The example below shows the same createIssue operation written two ways — first using operation-level slots (the existing form), then using per-field modifiers (the preferred form for explicitness).
imports {
gnomon.io.http: "^1.0.0"
}
client GitHub {
meaning: "GitHub REST API v3."
baseUrl: "https://api.github.com"
auth: bearer-token
headers {
"Accept": "application/vnd.github+json"
"X-GitHub-Api-Version": "2022-11-28"
}
errors {
5xx: transient
4xx: terminal
}
operations {
// Operation-level slot form (§4 fallback still applies for unplaced fields)
getRepository {
meaning: "Fetch metadata for a single repository."
input {
owner: Text required
repo: Text required
}
returns: Repository
errors {
404: terminal
}
method: GET
path: "/repos/{owner}/{repo}"
}
// Per-field binding modifier form — explicit, no ambiguity
createIssue {
meaning: "Open a new issue on a repository."
input {
owner: Text required path
repo: Text required path
title: Text required body
bodyText: Text optional body
apiToken: Text optional header("X-Request-Token")
}
returns: Issue
errors {
422: terminal
}
method: POST
path: "/repos/{owner}/{repo}/issues"
}
}
}
When both owner and repo carry path modifiers they are interpolated into path: without being listed in {tokens} — the compiler synthesizes path tokens from the modifier-declared fields. If a field carries path but its name does not appear as a {token} in path:, the compiler also emits informational M25515 (path token auto-synthesized).
3. Auth Scheme Implementations
The auth: slot on the enclosing client declaration (RFC-0024 §4) drives which HTTP headers gnomon.io.http attaches to every outbound request. Credential values are retrieved from the runtime credential store at call time; they are never embedded in the compiled bundle.
auth: value | HTTP header(s) emitted | Credential store key |
|---|---|---|
bearer-token | Authorization: Bearer <token> | <ClientName>.token |
api-key | X-Api-Key: <key> | <ClientName>.apiKey |
basic | Authorization: Basic <base64(user:pass)> | <ClientName>.username, <ClientName>.password |
none | (none) | — |
Auth headers are applied after static headers {} entries. If an auth scheme would produce a header whose name is already declared in the operation-level or client-level headers {} block, the explicit headers {} entry wins and the runtime MUST NOT override it.
3.1 Credential Store Resolution
The runtime resolves credentials in the following precedence order:
- Per-environment secret binding declared in the module’s deployment manifest
- Process environment variable matching the credential store key (uppercased, dots replaced with underscores — e.g.
GITHUB_TOKENforGitHub.token) - Runtime secret vault (if configured)
If a required credential is missing at call time, the runtime raises a non-retryable error before making the network request.
4. Parameter Location Rules (Fallback Algorithm)
The parameter location algorithm resolves where each input {} field is sent. It runs in two passes:
Pass 1 — Per-field binding modifiers (§2.2): Fields carrying a binding modifier (path, query, body, header, header("X-Name")) are assigned to their declared location. These fields are removed from consideration before Pass 2 runs.
Pass 2 — Operation-level slot fallback: The remaining fields (those without a binding modifier) are distributed by the following rules, applied in order:
-
Path parameters — a field whose name appears as a
{fieldName}token inpath:is a path parameter. The runtime URL-encodes the field value and interpolates it into the path at call time. -
Query parameters — a field whose name appears in the
query:list is appended to the URL as a query string entry (?name=value). List-valued fields are repeated (?tag=a&tag=b). -
Body — the field named by
body:is serialized as the request body. By default, serialization is JSON (Content-Type: application/json). IfresponseAs: binaryis set on the operation, body serialization isapplication/octet-stream. -
Unplaced — a field not resolved in Pass 1 or Pass 2 steps 1–3 is unplaced. The compiler emits M25510 for each unplaced field.
Fields MUST NOT be assigned to more than one location across both passes. A conflict (field has a binding modifier AND appears in an operation-level slot) MUST produce error M25514.
4.1 Default Body Behavior for Mutating Methods
For operations where method: is POST, PUT, or PATCH and no body: slot is declared and no field carries a body modifier, the compiler MAY apply a default: all input {} fields not consumed by Pass 1 or Pass 2 steps 1–2 are collected into an implicit body object. The compiler emits a warning (M25510 at warning severity) when this implicit collection is applied, advising authors to use per-field body modifiers or declare body: explicitly.
For GET, HEAD, and DELETE, there is no implicit body. Unplaced fields are M25510 errors unless claimed by a binding modifier or listed in query:.
5. Response Deserialization
The runtime deserializes the HTTP response and binds it to the operation’s returns schema according to the following rules.
5.1 Success (2xx)
The response body is decoded per the responseAs: slot:
responseAs: | Decoding | Bound as |
|---|---|---|
json (default) | JSON.parse of UTF-8 body | Gnomon record matching returns schema |
text | UTF-8 string | Text scalar |
binary | Raw bytes | Bytes scalar |
After decoding, the result is structurally validated against the operation’s returns schema. Fields present in the response but not declared in returns are silently discarded. Fields declared as required in returns but absent from the response cause a runtime type error (non-retryable).
5.2 Client Errors (4xx)
The runtime matches the response status code against the operation’s errors {} block (then the client-level errors {} block, per RFC-0024 §4). The most-specific matching selector wins.
- If a matching
terminalentry is found, the operation fails immediately with that error classification. - If a matching
ignoreentry is found, the error is swallowed and the operation returns a zero-value for itsreturnsschema. - If no matching selector is found, the runtime propagates the error as M25511.
5.3 Server Errors (5xx)
Server errors follow the same selector resolution as §5.2. If the matching entry is classified transient, the runtime applies the module’s configured retry policy (exponential backoff with jitter; defaults: 3 retries, initial delay 500 ms, max delay 10 s). If retries are exhausted, the error is re-raised as terminal.
If no matching selector is found, the runtime propagates as M25511 (with severity elevated to error).
5.4 Timeout
If the request does not complete within the timeout: interval (default 30 000 ms):
- If the
errors {}block declares atimeoutselector, that classification is applied. - Otherwise, the runtime raises M25512.
The timeout clock starts when the outbound request is dispatched. DNS resolution and TLS handshake are included in the timeout window.
6. baseUrl Resolution
The baseUrl: slot on the enclosing client is prepended to the operation’s path: to form the final request URL.
finalUrl = baseUrl + path (after path-parameter interpolation)
Exception: if path: begins with http:// or https://, it is treated as an absolute URL and baseUrl: is ignored entirely. The compiler emits a warning when an absolute path: is detected alongside a non-empty baseUrl:, because this is likely unintentional.
baseUrl: may contain an environment variable reference using the syntax $ENV_VAR_NAME. The runtime resolves these at startup; an unresolved variable that lacks a default causes a startup-time error rather than a per-call error.
Examples:
baseUrl: | path: | finalUrl |
|---|---|---|
"https://api.example.com/v2" | "/users/{id}" | https://api.example.com/v2/users/42 |
"https://api.example.com" | "https://other.example.com/x" | https://other.example.com/x (baseUrl ignored) |
"$API_BASE_URL" | "/ping" | resolved at runtime from API_BASE_URL env var |
7. Diagnostic Codes
All codes in the M25xxx range are owned by this RFC.
| Code | Severity | Description |
|---|---|---|
| M25510 | Error | Input field not placed by any binding modifier, path template token, query: list, or body: slot. The field will not be sent. |
| M25511 | Error | HTTP 4xx or 5xx response with no matching selector in the errors {} block. |
| M25512 | Error | HTTP request timed out with no timeout selector in the errors {} block. |
| M25513 | Error | method: slot missing from an HTTP operation in a client that imports gnomon.io.http. |
| M25514 | Error | Field carries a per-field binding modifier (§2.2) AND also appears in an operation-level path: template, query: list, or body: slot — conflicting location assignments. |
| M25515 | Info | Field carries path modifier but its name does not appear as a {token} in path: — compiler auto-synthesizes the path token from the field name. |
7.1 Failure Mode Summary
| Code | Description | Severity |
|---|---|---|
| M25510 | Unplaced input field | Error |
| M25511 | Unhandled HTTP error response | Error |
| M25512 | Unhandled timeout | Error |
| M25513 | method: slot missing | Error |
| M25514 | Conflicting field binding: per-field modifier and operation-level slot both claim the same field | Error |
| M25515 | path modifier auto-synthesizes path token | Info |
8. What This RFC Does NOT Define
- OpenAPI spec parsing and operation generation → RFC-0028
- OAuth2 flow mechanics (token refresh, PKCE) — deferred to a future authentication RFC
- Multipart form body encoding — deferred
- Response streaming (chunked transfer, SSE) — deferred; see RFC-0020 for the reactive model these will integrate with