gnomonlearn

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 {} by gnomon.io.http (§2)
  • How each auth: value on the enclosing client maps 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 returns schema (§5)
  • How the baseUrl: from the enclosing client is combined with the operation’s path: (§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).

SlotTypeRequiredDefaultDescription
method:HTTPMethodYes—HTTP method: GET, POST, PUT, PATCH, DELETE, or HEAD
path:TextYes—URL path template. Tokens of the form {fieldName} are interpolated from input {} fields.
body:TextNo—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:ResponseEncodingNojsonHow to decode the response body: json | text | binary.
timeout:IntegerNo30000Per-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:

ModifierEffect
pathField is a path parameter. Interpolated into the path: template as {fieldName}.
queryField is appended to the URL as a query parameter.
bodyField is serialized as (or into) the request body.
headerField 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: valueHTTP header(s) emittedCredential store key
bearer-tokenAuthorization: Bearer <token><ClientName>.token
api-keyX-Api-Key: <key><ClientName>.apiKey
basicAuthorization: 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:

  1. Per-environment secret binding declared in the module’s deployment manifest
  2. Process environment variable matching the credential store key (uppercased, dots replaced with underscores — e.g. GITHUB_TOKEN for GitHub.token)
  3. 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:

  1. Path parameters — a field whose name appears as a {fieldName} token in path: is a path parameter. The runtime URL-encodes the field value and interpolates it into the path at call time.

  2. 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).

  3. Body — the field named by body: is serialized as the request body. By default, serialization is JSON (Content-Type: application/json). If responseAs: binary is set on the operation, body serialization is application/octet-stream.

  4. 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:DecodingBound as
json (default)JSON.parse of UTF-8 bodyGnomon record matching returns schema
textUTF-8 stringText scalar
binaryRaw bytesBytes 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 terminal entry is found, the operation fails immediately with that error classification.
  • If a matching ignore entry is found, the error is swallowed and the operation returns a zero-value for its returns schema.
  • 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 a timeout selector, 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.

CodeSeverityDescription
M25510ErrorInput field not placed by any binding modifier, path template token, query: list, or body: slot. The field will not be sent.
M25511ErrorHTTP 4xx or 5xx response with no matching selector in the errors {} block.
M25512ErrorHTTP request timed out with no timeout selector in the errors {} block.
M25513Errormethod: slot missing from an HTTP operation in a client that imports gnomon.io.http.
M25514ErrorField 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.
M25515InfoField 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

CodeDescriptionSeverity
M25510Unplaced input fieldError
M25511Unhandled HTTP error responseError
M25512Unhandled timeoutError
M25513method: slot missingError
M25514Conflicting field binding: per-field modifier and operation-level slot both claim the same fieldError
M25515path modifier auto-synthesizes path tokenInfo

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