lnmp_envelope/lib.rs
1#![warn(missing_docs)]
2#![warn(clippy::all)]
3
4//! # lnmp-envelope
5//!
6//! Operational metadata envelope for LNMP records.
7//!
8//! This crate provides a way to attach operational context (timestamp, source,
9//! trace ID, sequence) to LNMP records without affecting their deterministic
10//! properties or semantic checksums.
11//!
12//! ## Alignment with Industry Standards
13//!
14//! LNMP Envelope aligns with:
15//! - **CloudEvents**: Similar context attributes (time, source, id)
16//! - **Kafka Headers**: Record-level metadata separate from payload
17//! - **W3C Trace Context**: Compatible trace ID format for distributed tracing
18//! - **OpenTelemetry**: Seamless integration with telemetry spans
19//!
20//! ## Core Principles
21//!
22//! 1. **Determinism Preserved**: Envelope metadata does NOT affect `SemanticChecksum`
23//! 2. **Zero Overhead**: Unused envelope features have no performance cost
24//! 3. **Transport Agnostic**: Defined independently, bindings provided separately
25//! 4. **Future Proof**: Extensible via labels, unknown fields skipped gracefully
26//!
27//! ## Quick Start
28//!
29//! ```
30//! use lnmp_core::{LnmpRecord, LnmpField, LnmpValue};
31//! use lnmp_envelope::EnvelopeBuilder;
32//!
33//! // Create a record
34//! let mut record = LnmpRecord::new();
35//! record.add_field(LnmpField { fid: 12, value: LnmpValue::Int(14532) });
36//!
37//! // Wrap with envelope
38//! let envelope = EnvelopeBuilder::new(record)
39//! .timestamp(1732373147000)
40//! .source("auth-service")
41//! .trace_id("abc-123-xyz")
42//! .sequence(42)
43//! .build();
44//!
45//! assert!(envelope.has_metadata());
46//! ```
47//!
48//! ## Encoding Formats
49//!
50//! ### Binary (TLV)
51//!
52//! Envelope metadata is encoded as Type-Length-Value entries in the LNMP
53//! container metadata extension block:
54//!
55//! ```text
56//! Type: 0x10 (Timestamp) | Length: 8 | Value: u64 BE
57//! Type: 0x11 (Source) | Length: N | Value: UTF-8 string
58//! Type: 0x12 (TraceID) | Length: M | Value: UTF-8 string
59//! Type: 0x13 (Sequence) | Length: 8 | Value: u64 BE
60//! ```
61//!
62//! ### Text (Header Comment)
63//!
64//! ```text
65//! #ENVELOPE timestamp=1732373147000 source=auth-service trace_id="abc-123"
66//! F12=14532
67//! F7=1
68//! ```
69//!
70//! ## Transport Bindings
71//!
72//! ### HTTP
73//!
74//! ```text
75//! X-LNMP-Timestamp: 1732373147000
76//! X-LNMP-Source: auth-service
77//! X-LNMP-Trace-ID: abc-123-xyz
78//! X-LNMP-Sequence: 42
79//! ```
80//!
81//! ### Kafka
82//!
83//! ```text
84//! Record headers:
85//! lnmp.timestamp: "1732373147000"
86//! lnmp.source: "auth-service"
87//! lnmp.trace_id: "abc-123-xyz"
88//! lnmp.sequence: "42"
89//! ```
90//!
91//! ## Features
92//!
93//! - `serde`: Enable serde serialization support (optional)
94
95pub mod binary_codec;
96mod envelope;
97mod error;
98mod metadata;
99pub mod text_codec;
100
101pub use envelope::{EnvelopeBuilder, LnmpEnvelope};
102pub use error::{EnvelopeError, Result};
103pub use metadata::EnvelopeMetadata;
104
105// Re-export for convenience
106pub use lnmp_core::{LnmpField, LnmpRecord, LnmpValue};