Skip to main content

wa_wire_recording/
lib.rs

1//! The wa-wire recording container: envelopes at rest.
2//!
3//! RFC-008 specifies one stanza crossing the boundary. This is a *sequence* of
4//! them in a file, plus the claims that decide whether two such files may be
5//! compared at all: which adapter, which spec, which dictionary, which traffic.
6//!
7//! A container without those claims does not make them absent. It makes them
8//! unverifiable, and a comparison runs and reports a verdict anyway.
9//!
10//! ```
11//! use wa_wire_recording::{ArtifactClass, Integrity, MetaBuilder, RecordingRef, RecordingWriter};
12//!
13//! let meta = MetaBuilder::new()
14//!     .adapter("zapo", "0.1.0", "1.7", 1, ["l0.inbound.tap"])?
15//!     .artifact_class(ArtifactClass::Synthetic)?;
16//!
17//! let mut writer = RecordingWriter::new(meta)?;
18//! writer.envelope(b"first")?;
19//! writer.mark(1_500, "stream:error")?;
20//! writer.envelope(b"second")?;
21//! let bytes = writer.finish();
22//!
23//! let recording = RecordingRef::decode(&bytes)?;
24//! assert_eq!(recording.integrity(), Integrity::Complete);
25//! assert_eq!(
26//!     recording.envelopes().collect::<Vec<_>>(),
27//!     [b"first".as_slice(), b"second"]
28//! );
29//! assert_eq!(recording.adapter().map(|a| a.id), Some("zapo"));
30//! # Ok::<(), Box<dyn core::error::Error>>(())
31//! ```
32//!
33//! # Truncation is a state, not a failure
34//!
35//! The record count lives in a trailer rather than the header, so a writer does
36//! not have to know its own length before the first byte — which is what lets a
37//! ring buffer be a writer at all. The consequence is that an interrupted
38//! recording has no trailer, and this reader treats that as
39//! [`Integrity::Truncated`]: every complete record is readable and the file is
40//! not comparable.
41//!
42//! That is deliberate. The artifact a crash recorder exists to produce is, by
43//! definition, the one that was interrupted, and a container that rejected it
44//! would fail its most important use while passing every test written against
45//! well-formed files.
46//!
47//! # What it does not do
48//!
49//! The trailer's checksum detects damage, not tampering: anything able to
50//! rewrite the records can rewrite the checksum, and nothing here is signed.
51//! Identity comes from [`input_digest`], which the container carries as opaque
52//! bytes and never computes — so the hash function stays the responsibility of
53//! whoever produced the traffic.
54//!
55//! [`input_digest`]: RecordingRef::input_digest
56
57#![no_std]
58#![cfg_attr(
59    test,
60    allow(
61        clippy::expect_used,
62        clippy::unwrap_used,
63        clippy::panic,
64        clippy::indexing_slicing,
65        clippy::arithmetic_side_effects,
66    )
67)]
68
69pub mod crc;
70pub mod error;
71pub mod meta;
72pub mod reader;
73pub mod record;
74#[cfg(feature = "alloc")]
75pub mod writer;
76
77pub use crc::{Crc32, crc32};
78pub use error::{ReadError, WriteError};
79pub use meta::{AdapterMeta, ArtifactClass, CapabilityNames, MetaEntry, Tag};
80pub use reader::{CONTAINER_VERSION, HEADER_LEN, Integrity, MAGIC, RecordingRef};
81pub use record::{Kind, Mark, Record};
82#[cfg(feature = "alloc")]
83pub use writer::{MetaBuilder, RecordingWriter};
84
85#[cfg(all(test, feature = "alloc"))]
86#[path = "lib_tests.rs"]
87mod tests;