zerodds_foundation/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2026 ZeroDDS Contributors
3//! Crate `zerodds-foundation`. Safety classification: **SAFE**.
4//!
5//! Foundation-layer primitives for the ZeroDDS stack: hot-path
6//! buffer pools, wire-integrity hashes (CRC-32C / CRC-64-XZ / MD5),
7//! observability event language + sinks, tracing spans + histograms,
8//! and a lock-free-read RCU cell container.
9//!
10//! `no_std`-capable, `forbid(unsafe_code)`. Pure Rust without external
11//! crates — the foundation-pillar idea "the frame does not stay hollow".
12//!
13//! ## Layer position
14//!
15//! Layer 0 (Foundation). Has **no** dependencies on other
16//! ZeroDDS crates. Used by layer 1 (primitives: cdr, qos, types)
17//! and all higher layers.
18//!
19//! Architecture reference: `docs/architecture/02_architecture.md §3`
20//! and `docs/architecture/04_safety_by_architecture.md §2`.
21//!
22//! ## Public API
23//!
24//! - **Stack buffer** ([`PoolBuffer`], [`PoolBufferError`]): fixed-capacity
25//!   buffer for hot-path allocations, on-stack with a `CAP` generic.
26//!   Append operations are O(1) without touching the heap; overflow is
27//!   signalled as a Result instead of panicking.
28//! - **CRC + MD5** ([`crc32c`], [`crc64_xz`], [`md5`]): wire-integrity
29//!   hashes; pure Rust with standard lookup tables.
30//! - **Observability** ([`Event`], [`Sink`], [`Level`], [`Component`],
31//!   [`NullSink`], [`StderrJsonSink`], [`VecSink`]): structured
32//!   DDS events; a Sink trait for arbitrary consumers.
33//! - **Tracing** ([`Span`], [`SpanContext`], [`TraceId`], [`SpanId`],
34//!   [`SpanKind`], [`SpanStatus`], [`Histogram`]): spans + histograms
35//!   for coarse-grained tracing; OTLP export in the
36//!   `zerodds-observability-otlp` crate.
37//! - **RCU** ([`RcuCell`]): copy-on-write container for low-write/
38//!   high-read patterns without `unsafe`.
39//!
40//! ## Feature flags
41//!
42//! | Feature | Default | Purpose |
43//! |---------|---------|-------|
44//! | `std` | ✅ | Enables `BufferPool`, `RcuCell`, `StderrJsonSink`, `VecSink`. Implies `alloc`. |
45//! | `alloc` | ✅ (via `std`) | Enables `observability` + `tracing` + MD5 with Vec padding. |
46//! | `safety` | ❌ | Reserved for future safety build constraints. |
47//!
48//! Without features (`default-features = false`): only `PoolBuffer`,
49//! `crc32c`, `crc64_xz`, `md5` (the no_std MD5 path is limited to 56
50//! bytes of input).
51//!
52//! ## Example
53//!
54//! ```rust
55//! use zerodds_foundation::{crc32c, PoolBuffer, PoolBufferError};
56//!
57//! // CRC-32C over an RTPS datagram.
58//! let payload = b"\x52\x54\x50\x53\x02\x05\x01\x0F";
59//! let checksum = crc32c(payload);
60//! assert_eq!(checksum & 0xFFFF_FFFF, checksum);
61//!
62//! // Hot-path buffer with fixed capacity.
63//! let mut buf: PoolBuffer<256> = PoolBuffer::new();
64//! buf.extend_from_slice(payload).unwrap();
65//! assert_eq!(buf.as_slice(), payload);
66//!
67//! // Overflow is explicit, no panic.
68//! let mut tiny: PoolBuffer<4> = PoolBuffer::new();
69//! assert_eq!(
70//!     tiny.extend_from_slice(payload),
71//!     Err(PoolBufferError::Overflow)
72//! );
73//! ```
74
75#![no_std]
76#![forbid(unsafe_code)]
77#![warn(missing_docs)]
78
79#[cfg(feature = "alloc")]
80extern crate alloc;
81
82#[cfg(feature = "std")]
83extern crate std;
84
85pub mod buffer;
86pub mod crc;
87#[cfg(feature = "alloc")]
88pub mod observability;
89#[cfg(feature = "std")]
90pub mod rcu;
91#[cfg(feature = "alloc")]
92pub mod tracing;
93
94pub use buffer::{PoolBuffer, PoolBufferError};
95pub use crc::{crc32c, crc64_xz, md5};
96#[cfg(feature = "alloc")]
97pub use observability::{Component, Event, Level, NullSink, SharedSink, Sink, null_sink};
98#[cfg(feature = "std")]
99pub use observability::{StderrJsonSink, VecSink};
100#[cfg(feature = "std")]
101pub use rcu::RcuCell;
102#[cfg(feature = "alloc")]
103pub use tracing::{Histogram, Span, SpanContext, SpanId, SpanKind, SpanStatus, TraceId};
104
105#[cfg(test)]
106mod tests {
107    #[test]
108    fn crate_compiles() {
109        // Smoke test: the crate compiles and the test harness runs.
110    }
111}
zerodds_foundation/lib.rs

zerodds_foundation/
lib.rs
