Module abi

Fixed-layout ABI profile of native frame metadata, version 1.

MAINTENANCE NOTE (dead-code audits): the consumers of this module are cross-language — C/C++ peers reading typed shared-memory headers and future polyglot bindings. Zero references from Rust repositories is the expected steady state and is NOT evidence this module is unused. Do not remove it on the basis of a Rust-side usage census.

UFrameMetadataAbiV1 is a derived representation of the semantic UFrameMetadata — not the canonical model, not the default wire form. It exists for the boundaries that genuinely need a fixed, directly readable C/C++/Rust struct: for example an iceoryx2 service whose peers want metadata as a typed user header instead of parsing the canonical field block, or deterministic byte-image test fixtures.

Most transports do not need this profile: the selected-wire layer carries variable metadata bytes produced by a metadata codec, and the shared-memory transports (iceoryx2, LoLa) already use a small fixed placement header plus that variable block. Use this profile only when both sides explicitly agree on it.

Layout rules (the shared-memory contract): #[repr(C)], self-contained (no pointers, no heap, no Drop), fixed size, explicit padding only, fixed-width integers and byte arrays only, little-endian in serialized form and native-endian in same-host shared memory. Compile-time assertions at the bottom of this file fail the build if the layout drifts.

Conversions to and from UFrameMetadata are fallible and never truncate: a value that exceeds a profile capacity is an error. The per-field capacities are profile policy (documented on each constant), not limits of the semantic model.

Cross-language reader checklist

1. Match UFRAME_ABI_TYPE_NAME, size, alignment, magic, and version before interpreting a header.
2. Mirror every field with fixed-width integer/byte-array types and C layout; never substitute native pointer, string, boolean, or enum layouts.
3. Check the presence mask before reading optional fields and reject unknown mask/flag bits.
4. Treat stored lengths as untrusted and verify each against its documented capacity before constructing a language-level string/view.
5. Use the fallible conversion/golden byte-image tests as the arbiter. A value too large for this profile remains valid semantic metadata; choose the canonical field block instead of truncating it.

The normative semantic model and metadata-profile registry live in up-spec/basics/uframe.adoc; this Rust struct is one derived ABI profile, not a language-specific conformance requirement.

Re-exports

pub use crate::frame::codec::FIELD_COMM_STATUS;

pub use crate::frame::codec::FIELD_MASK_V1;

pub use crate::frame::codec::FIELD_PAYLOAD_ENCODING;

pub use crate::frame::codec::FIELD_PERMISSION_LEVEL;

pub use crate::frame::codec::FIELD_REQID;

pub use crate::frame::codec::FIELD_SINK;

pub use crate::frame::codec::FIELD_TOKEN;

pub use crate::frame::codec::FIELD_TRACEPARENT;

pub use crate::frame::codec::FIELD_TTL;

Structs

UFrameMetadataAbiV1

Fixed-layout ABI profile v1 of native frame metadata.

UPayloadEncodingAbi

Fixed-capacity open payload encoding. size 172, align 4, no padding.

UTokenAbi

Fixed-capacity access token. size 512, align 2, no padding.

UTraceparentAbi

Fixed-capacity traceparent. size 64, align 1, no padding.

UUriAbi

Fixed-capacity UUri. size 136, align 4, no padding.

UUuidAbi

UUID as two 64-bit halves. size 16, align 8, no padding.

Enums

UFrameAbiError

Errors returned by ABI profile conversions.

Constants

UFRAME_ABI_ALIGN

Alignment of UFrameMetadataAbiV1 in bytes.

UFRAME_ABI_AUTHORITY_CAPACITY

Profile capacity for a UUri authority name (the UUri spec limit).

UFRAME_ABI_CONTENT_TYPE_CAPACITY

Profile capacity for a payload encoding content type.

UFRAME_ABI_ENCODING_HAS_REGISTRY_ID

Component flag: registry_id carries a value.

UFRAME_ABI_FLAG_LITTLE_ENDIAN

Flag bit: producer stored multi-byte integers little-endian. MUST be set in the serialized form of profile v1.

UFRAME_ABI_LITERAL_ID_CAPACITY

Profile capacity for a payload encoding literal id.

UFRAME_ABI_MAGIC

Magic bytes at offset 0 of every UFrameMetadataAbiV1: "UFA1".

UFRAME_ABI_SIZE

Total size of UFrameMetadataAbiV1 in bytes.

UFRAME_ABI_TOKEN_CAPACITY

Profile capacity for an access token. This is a policy limit of this profile only; conversions fail (never truncate) for larger tokens, which remain fully supported by the semantic model and the canonical field block.

UFRAME_ABI_TRACEPARENT_CAPACITY

Profile capacity for a W3C traceparent (version 00 uses 55 characters).

UFRAME_ABI_TYPE_NAME

Semantic type name for cross-language service matching (e.g. iceoryx2 #[type_name(...)] in Rust and IOX2_TYPE_NAME in C++).

UFRAME_ABI_VERSION

ABI profile version described by this module.