Module wire_format

Expand description

State-migrations S4 (#2259): the call signature and the sweep route’s names, for bynk migrate sweep, which signs as the runtime verifies. #1969: the cross-context wire format, version 1, as a published surface.

The interop track’s D1 (design/archive/retired-tracks.md, interop track) makes the format a caller outside the project can speak a contract with its own version, apart from the compiler’s: the path, method and headers of a call; the order of the callee’s checks, with their status codes and error bodies; the JSON encoding of each boundary type; and the contract hash.

This module is the single source for the parts that are constants. The emitter builds the /_bynk/call/ dispatch from CallCheck and the header names below, and reference renders reference/wire-format.md from the same values plus [crate::wire]’s encoding model and [crate::contract]’s hash. bynkc/tests/wire_reference.rs holds the page, the emitted dispatch, the runtime’s callService and the generated codecs to it.

Stability (version 1). Additive only: a new status code, a new error kind or a new optional header may be added within the version. Changing an existing encoding, check, status or the hash’s normal form is a new wire version, which a callee accepts beside the old one for an overlap window (ACCEPTED_WIRE_VERSIONS). That includes the request signature (signing_input): its canonical input and its headers are part of the version, the keys are not.

Modules§

reference: #1969: renders reference/wire-format.md, the published reference for wire format version 1.

Structs§

Header: One header of a call request, as the reference documents it.

Enums§

CallCheck: One check the callee makes on a call, in the published order.

Constants§

ACCEPTED_WIRE_VERSIONS: The wire versions this compiler’s callees accept. A request without WIRE_HEADER is version 1.
CALLER_HEADER: The calling context’s qualified name.
CALL_CHECKS: The callee’s checks, in the order it makes them. The first that fails answers the request.
CALL_METHOD: The only method a call may use.
CALL_PATH_PREFIX: The path prefix a call is addressed to; the service name follows it.
CONTRACT_HEADER: The caller’s compiled hash of the callee’s contract.
EDGE_FROM_PREFIX: I2 (#1971): the secret a callee holds for the edge from one caller, edge_key_from.
EDGE_TO_PREFIX: I2 (#1971): the secret a caller holds for the edge to one callee, edge_key_to.
HEADERS: Every header a call carries, in the order the reference lists them.
MALFORMED_JSON_DETAILS: The details of a MalformedJson refusal. The HTTP routes use the same.
MAX_BODY_BYTES: I2 (#1971): the largest body a callee reads, in bytes. The body is read under this cap before it is hashed, so a sender without a key cannot make the callee buffer and hash an unbounded one.
MIGRATE_CALLER: State-migrations S4 (#2259): the caller name a sweep signs as. The route admits no other caller, so a context’s edge key cannot wake instances.
MIGRATE_KEY: State-migrations S4 (#2259): the secret a sweep’s key is set under for the sweep’s duration. Without it the route answers 404.
MIGRATE_PATH_PREFIX: State-migrations S4 (#2259 Decision D): the prefix of bynk migrate sweep’s wake route, /_bynk/migrate/<Class>. Not part of the published call wire format: only the toolchain calls it.
SIGNATURE_HEADER: I2 (#1971): the request’s signature, HMAC-SHA256 over signing_input under the edge’s key, as 64 lowercase hex digits.
SIGNATURE_WINDOW_SECONDS: I2 (#1971): how far, in seconds, a request’s timestamp may be from the callee’s clock, either way. A requirement, not a tuning knob (ADR per-edge-call-signature): it bounds how long a captured request can be replayed, and nothing else does.
SIGNING_SCHEME: I2 (#1971): the first line of signing_input, naming the scheme, so a signature over this input can never verify as one over another format’s.
TIMESTAMP_HEADER: I2 (#1971): when the caller signed the request, in whole seconds since the Unix epoch, as a decimal integer.
WIRE_HEADER: The wire version the caller speaks; absent means 1.
WIRE_VERSION: The wire version this compiler’s callers speak.

Functions§

edge_key_from: I2 (#1971): the secret the callee holds for calls from caller (BYNK_CALL_FROM_SHOP__ORDERS). The callee picks it by the request’s CALLER_HEADER, so an undeclared caller finds no key and is refused.
edge_key_to: I2 (#1971): the secret the caller holds for calls to callee (BYNK_CALL_TO_SHOP__PAYMENT). Same value as the callee’s edge_key_from for the same edge.
edge_suffix: I2 (#1971): the part of an edge key’s name that names the context at its other end: upper case, a dot written __ (shop.orders → SHOP__ORDERS). None for a name outside is_edge_name’s domain.
is_edge_name: I2 (#1971): whether context is a name an edge key can be derived from: dot-separated segments, each a lowercase letter, then lowercase letters and digits, with single underscores between runs of them (shop.orders, a_b.c2). On that domain edge_suffix is injective, which is what keeps one caller’s key from verifying another’s name.
signing_input: I2 (#1971): the bytes a request’s signature is computed over. One field per line, \n-separated, no trailing newline: