Expand description
@brief libtracer core wire codec — a from-scratch, native Rust port of the C++
reference codec in core/src/frame.cpp and the TypeScript core in
bindings/typescript/src/codec.mjs. It must match both byte-for-byte;
correctness is gated by the SHARED conformance vectors under
tests/conformance/vectors/v1/ and the cross-core differential fuzzer
(tests/conformance/diff_fuzz.py).
The wire format is documented in docs/reference/01-data-format.md and pinned
normatively by docs/spec/v1.md:
header (4 or 6 bytes) + payload + optional trailer (timestamp then CRC).
This is a third, fully independent implementation (no FFI over C++,
per ADR-0028) — it compiles #![no_std] (it only needs alloc for the owned
TLV tree) so it can target WASM and bare-metal MCUs.
Re-exports§
pub use error_registry::error_code;pub use error_registry::error_raw_code;pub use error_registry::error_string;pub use error_registry::parse_error;pub use error_registry::status_errors;pub use error_registry::status_ok;pub use error_registry::status_with_errors;pub use error_registry::Disposition;pub use error_registry::ErrCode;pub use error_registry::ErrorId;pub use error_registry::ParsedError;pub use error_registry::Severity;pub use field::encode_field;pub use field::field_tlv;pub use field::parse_field;pub use field::parse_field_tlv;pub use field::FieldLevel;pub use field::FieldMode;pub use field::MAX_FIELD_DEPTH;pub use fwd::decode_fwd;pub use fwd::encode_fwd;pub use fwd::encode_fwd_bytes;pub use fwd::parse_fwd_tlv;pub use fwd::reply_error_code;pub use fwd::reply_error_path;pub use fwd::FieldSel;pub use fwd::FwdRequest;pub use fwd::ParsedFwd;pub use tlv_builders::name;pub use tlv_builders::path_ref;pub use tlv_builders::path_ref_element;pub use tlv_builders::subscriber;pub use tlv_builders::text_name;pub use tlv_builders::validate_segment;pub use tlv_builders::value;pub use tlv_builders::value_opts;pub use tlv_builders::value_u16;pub use tlv_builders::value_u32;pub use tlv_builders::value_u64;pub use tlv_builders::value_u8;pub use tlv_builders::BuildError;pub use tlv_builders::PathRefElement;pub use tlv_builders::ValueOptions;pub use tlv_builders::MAX_PATH_BYTES;pub use tlv_builders::MAX_SEGMENTS;pub use tlv_builders::MAX_SEGMENT_BYTES;
Modules§
- error_
registry - @brief Protocol ERROR registry + STATUS (Unit 3).
- field
- @brief
:fieldselector — FIELD TLV (0x10) build/parse (Unit 5). - fwd
- @brief FWD remote-operation envelope — FWD TLV (
0x0F) build/parse (Unit 4). - path
- @brief PATH string ⇄ TLV conversion + validation (Unit 2).
- structured
- @brief Structured-TLV typed accessors + builders (Unit 6).
- tlv_
builders - @brief Typed TLV builders and child-lookup accessors (Unit 1).
- type_
code - @brief Core type-code registry (0x01-0x10). 0x05 is retired (was LIST, ADR-0003). The codec treats every nonzero type generically, so these constants are a convenience, not an exhaustive set — with one exception: 0x14 PATH_REF (RFC-0024 §4) carries a bare fixed-stride 8-byte record array rather than a self-describing body, so the decoder checks its shape by type.
Structs§
- Crc
- @brief A decoded CRC. 16-bit values are zero-extended into
value. - Opt
- @brief The 1-byte
optfield, unpacked. Bits MSB->LSB: R | PL | TS | CR | LL | CW | TF | R. - Timestamp
- @brief A decoded wire timestamp. Absolute form is a u64 ns count since the Unix epoch;
relative form is a signed i32 ns offset.
valueholds the bit pattern as ani64(absolute = the u64 reinterpreted) to round-trip the full range exactly. - Tlv
- @brief A decoded TLV. For opaque TLVs (opt.PL=0)
payloadholds the bytes andchildrenis empty; for structured TLVs (opt.PL=1)childrenholds the parsed sub-TLVs andpayloadis empty. - Trailer
- @brief A decoded trailer: an optional timestamp followed by an optional CRC.
Enums§
- CrcWidth
- @brief The trailer CRC width.
- Error
- @brief A decode failure. Names mirror the C++
tr::wire::error_tenum and the TSERRORcodes so the conformance harness can emit identicalERR:<reason>text.
Constants§
- MAX_
PATH_ REF_ ELEMENTS - @brief The
PATH_REFelement-count bound — 255 elements / 2040 body bytes (RFC-0024 §4.3). - PATH_
REF_ ELEMENT_ BYTES - @brief The
PATH_REFelement stride — 8 bytes,(u32 index, u32 generation)LE (RFC-0024 §4.4).
Functions§
- crc16_
ccitt - @brief CRC-16-CCITT (FALSE): poly 0x1021, MSB-first, init 0xFFFF, no final xor.
- crc32c
- @brief CRC-32C (Castagnoli): reflected poly 0x82F63B78, init/xor 0xFFFFFFFF.
- decode
- @brief Decode exactly one TLV that fills
inputinto a TLV tree. - encode
- @brief Encode a TLV tree back to wire bytes, recomputing the trailer CRC from the body
(+ timestamp bytes) when
opt.cris set. Mirrorsencodeinframe.cpp. - is_
path_ ref_ type - @brief True for
0x14 PATH_REFonly — the one type whose body is a fixed-stride 8-byte element array rather than a self-describing payload (RFC-0024 §4.2).0x15carries aPATHbody since RFC-0029 §7.1, so no shape rule applies to it here.