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 fuer den ZeroDDS-Stack: Hot-Path-
6//! Buffer-Pools, Wire-Integritaets-Hashes (CRC-32C / CRC-64-XZ / MD5),
7//! Observability-Event-Sprache + Sinks, Tracing-Spans + Histogramme,
8//! und ein Lock-Free-Read RCU-Cell-Container.
9//!
10//! `no_std`-tauglich, `forbid(unsafe_code)`. Pure-Rust ohne externe
11//! Crates — die Foundation-Pillar-Idee „Frame bleibt nicht hohl".
12//!
13//! ## Schichten-Position
14//!
15//! Layer 0 (Foundation). Hat **keine** Dependencies auf andere
16//! ZeroDDS-Crates. Wird von Layer 1 (Primitives: cdr, qos, types)
17//! und allen hoeheren Schichten verwendet.
18//!
19//! Architektur-Referenz: `docs/architecture/02_architecture.md §3`
20//! und `docs/architecture/04_safety_by_architecture.md §2`.
21//!
22//! ## Public API
23//!
24//! - **Stack-Buffer** ([`PoolBuffer`], [`PoolBufferError`]): fixed-capacity
25//!   Buffer fuer Hot-Path-Allokationen, on-stack mit `CAP`-Generic.
26//!   Append-Operationen sind O(1) ohne Heap-Touch; Overflow wird als
27//!   Result signalisiert statt zu panicen.
28//! - **CRC + MD5** ([`crc32c`], [`crc64_xz`], [`md5`]): Wire-Integritaets-
29//!   Hashes; pure-Rust mit Standard-Lookup-Tables.
30//! - **Observability** ([`Event`], [`Sink`], [`Level`], [`Component`],
31//!   [`NullSink`], [`StderrJsonSink`], [`VecSink`]): strukturierte
32//!   DDS-Events; Sink-Trait fuer beliebige Konsumenten.
33//! - **Tracing** ([`Span`], [`SpanContext`], [`TraceId`], [`SpanId`],
34//!   [`SpanKind`], [`SpanStatus`], [`Histogram`]): Spans + Histogramme
35//!   fuer grobgranulares Tracing; OTLP-Export im
36//!   `zerodds-observability-otlp`-Crate.
37//! - **RCU** ([`RcuCell`]): Copy-on-Write-Container fuer wenig-Schreib/
38//!   viel-Lese-Patterns ohne `unsafe`.
39//!
40//! ## Feature-Flags
41//!
42//! | Feature | Default | Zweck |
43//! |---------|---------|-------|
44//! | `std` | ✅ | Aktiviert `BufferPool`, `RcuCell`, `StderrJsonSink`, `VecSink`. Implies `alloc`. |
45//! | `alloc` | ✅ (via `std`) | Aktiviert `observability` + `tracing` + MD5 mit Vec-Padding. |
46//! | `safety` | ❌ | Reserviert fuer zukuenftige Safety-Build-Constraints. |
47//!
48//! Ohne Features (`default-features = false`): nur `PoolBuffer`,
49//! `crc32c`, `crc64_xz`, `md5` (no_std-MD5-Pfad ist auf 56 Byte
50//! Eingabe limitiert).
51//!
52//! ## Beispiel
53//!
54//! ```rust
55//! use zerodds_foundation::{crc32c, PoolBuffer, PoolBufferError};
56//!
57//! // CRC-32C ueber ein RTPS-Datagramm.
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 mit fester Kapazitaet.
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 ist explizit, kein 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: Crate kompiliert und Testharness laeuft.
110    }
111}
zerodds_foundation/lib.rs

zerodds_foundation/
lib.rs
