Skip to main content

Crate libtracer

Crate libtracer 

Source
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 :field selector — 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 opt field, 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. value holds the bit pattern as an i64 (absolute = the u64 reinterpreted) to round-trip the full range exactly.
Tlv
@brief A decoded TLV. For opaque TLVs (opt.PL=0) payload holds the bytes and children is empty; for structured TLVs (opt.PL=1) children holds the parsed sub-TLVs and payload is 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_t enum and the TS ERROR codes so the conformance harness can emit identical ERR:<reason> text.

Constants§

MAX_PATH_REF_ELEMENTS
@brief The PATH_REF element-count bound — 255 elements / 2040 body bytes (RFC-0024 §4.3).
PATH_REF_ELEMENT_BYTES
@brief The PATH_REF element 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 input into a TLV tree.
encode
@brief Encode a TLV tree back to wire bytes, recomputing the trailer CRC from the body (+ timestamp bytes) when opt.cr is set. Mirrors encode in frame.cpp.
is_path_ref_type
@brief True for 0x14 PATH_REF only — the one type whose body is a fixed-stride 8-byte element array rather than a self-describing payload (RFC-0024 §4.2). 0x15 carries a PATH body since RFC-0029 §7.1, so no shape rule applies to it here.