Preview of the proposed up-rust native-frame-model branch (up-rust b6b99c6d, up-spec f0e9b17) — not released documentation. branch · write-up
up_rust::frame

Module codec

Source
Expand description

Canonical byte codec for native frame metadata: the UFrame metadata field block, version 1.

This is the language-neutral serialization of UFrameMetadata used by the canonical selected-wire metadata codec and the native whole-frame envelope. Transports place these bytes wherever their physical layout wants them (a Zenoh attachment, the variable metadata prefix behind iceoryx2’s placement header, the metadata block behind LoLa’s ULOL header, …); the block itself is deliberately variable-length and presence-driven so that absent fields cost zero bytes.

Layout (all multi-byte integers little-endian):

u8   block_version        = 1
u8   kind                 FrameMessageKind wire code (1..=4)
u8   priority             0 = absent, 1..=7 = CS0..=CS6
u8   reserved             = 0
u32  presence             FIELD_* bitmask; unknown bits MUST be zero
u64  id.msb
u64  id.lsb
[FIELD_REQID]             u64 msb, u64 lsb
[FIELD_TTL]               u64 ttl in nanoseconds
[FIELD_COMM_STATUS]       i32 UCode value
[FIELD_PERMISSION_LEVEL]  u32
source UUri block         u32 ue_id, u16 resource_id, u8 ue_version_major,
                          u8 authority_len, authority bytes (UTF-8)
[FIELD_SINK]              UUri block
[FIELD_TOKEN]             u16 len, token bytes (UTF-8)
[FIELD_TRACEPARENT]       u8 len, traceparent bytes (UTF-8)
[FIELD_PAYLOAD_ENCODING]  u8 component bitmask (ENCODING_HAS_*), then in order:
                          [u32 registry_id] [u16 len + literal id bytes]
                          [u16 len + content type bytes]

Values that do not fit a length field are rejected at encode time — encoding never truncates.

§Walkthrough

  1. Construct and validate semantic UFrameMetadata.
  2. Call encode_frame_metadata_fields once; transports carry the returned block as opaque bytes in their binding-specific placement.
  3. On receive, call decode_frame_metadata_fields. Version, reserved bits, lengths, UTF-8, payload identity, and metadata invariants are checked before a semantic frame is exposed.
  4. Pin changes with round trips, malformed/truncated inputs, unknown-bit rejection, and golden vectors in wire_metadata_conformance and wire_metadata_golden.

This is a metadata profile, not a whole-frame envelope and not an application payload codec. up-spec/basics/uframe.adoc defines the profile registry; up-spec/up-l1/transport_families.adoc defines selected-wire identity and rejection behavior.

Enums§

UFrameFieldsError
Errors returned by the frame metadata field block codec.

Constants§

FIELD_COMM_STATUS
Presence bit: the frame has a communication status.
FIELD_MASK_V1
All presence bits defined by field block version 1.
FIELD_PAYLOAD_ENCODING
Presence bit: the frame has a payload encoding.
FIELD_PERMISSION_LEVEL
Presence bit: the frame has a permission level.
FIELD_REQID
Presence bit: the frame has a correlated request id.
FIELD_SINK
Presence bit: the frame has a sink URI.
FIELD_TOKEN
Presence bit: the frame has an access token.
FIELD_TRACEPARENT
Presence bit: the frame has a W3C traceparent.
FIELD_TTL
Presence bit: the frame has a time-to-live.
FRAME_FIELDS_VERSION
Version of the field block emitted by encode_frame_metadata_fields.

Functions§

decode_frame_metadata_fields
Decodes and validates frame metadata from its canonical field block bytes.
encode_frame_metadata_fields
Encodes validated frame metadata into its canonical field block bytes.