Crate subc_protocol

Expand description

subc wire contract.

This crate is the single source of truth for the subc <-> module wire, shared by subc-core and AFT. It defines the envelope (the fixed 17-byte routing header subc splices on), the canonical subc-generated body schemas such as ErrorBody, and the capability manifest. JSON-RPC request and response bodies remain module-owned opaque payloads to subc.

§The envelope (locked — see docs/subc-core-architecture.md §4.8)

 offset  size  field     type    purpose
   0      4    len       u32     # of BODY bytes after this 17-byte header
   4      1    ver       u8      envelope version
   5      1    type      u8      frame kind (see FrameType)
   6      1    flags     u8      bit0 BINARY · bits1-2 PRIORITY · bit3 LAST · 4-7 reserved
   7      2    channel   u16     route = (component, session); 0 = subc itself
   9      8    corr      u64     correlation id; CANCEL carries the target call's corr
  17 -> body

Little-endian (same-machine, native, no byte-swap on the hot path).

Frozen prefix (the versioning invariant): len (u32 @ 0) and ver (u8 @ 4) keep fixed meaning + position in every future version. A reader of any version can therefore always read the first 5 bytes, learn ver, look up that version’s header length, read the rest, and splice len body bytes. decode_header enforces this discipline.

Re-exports§

pub use frame::Frame;
pub use frame::FrameBuildError;

Modules§

frame: The complete wire frame: the decoded envelope header plus its opaque body.
manifest: Capability manifest schema for subc modules.
session: Session route control wire contract.

Structs§

BindIdentity: Per-route bind identity shared by client-facing and module-facing control.
EnvelopeHeader: A decoded envelope header. The body is the len bytes that follow it.
ErrorBody: Canonical JSON body for all subc-generated ERROR frames.
Flags: The flags byte (offset 6): bit0 BINARY · bits1-2 PRIORITY · bit3 LAST.
ModuleHelloAckBody: subc-to-module HELLO_ACK body used during module registration.
ModuleHelloBody: Module-to-subc HELLO body used during module registration.

Enums§

DecodeError: Why a header could not be decoded.
FrameType: Frame kind (type byte at offset 5).
Priority: Scheduling priority carried in flags bits 1-2. subc schedules on this without parsing the body.
RouteTarget: Explicit target for a route open/bind operation.

Constants§

FROZEN_PREFIX_LEN: Bytes of the frozen prefix (len u32 + ver u8) that are stable across every envelope version. A reader needs only these to learn the version and thus the full header length.
HEADER_LEN: Fixed header length for PROTOCOL_VERSION 1.
MAX_FRAME_BODY_LEN: Maximum v1 frame body accepted before allocation.
PROTOCOL_VERSION: Envelope protocol version this build speaks.
SUBC_LAUNCH_NONCE_ENV: Env var subc sets, on each spawn of a reserved module only, to a fresh one-time launch nonce. The child echoes it in ModuleHelloBody::launch_nonce; subc accepts a reserved module_id’s HELLO only when the nonce matches the one it last injected for that id. Non-reserved modules never receive it.
SUBC_MODULE_ID_ENV: Env var subc sets on each supervised child telling it the module_id it is supervised under, so it can register under that id.

Functions§

decode_header: Decode an envelope header from the front of bytes, following the frozen-prefix discipline: