oxgraph_snapshot/lib.rs
1//! Topology-agnostic byte-level snapshot container.
2//!
3//! `oxgraph-snapshot` defines a sectioned, zero-copy checkpoint format that
4//! can validate, package, and read immutable topology snapshots without
5//! knowing whether their contents are graphs, hypergraphs, or anything
6//! else. Section semantics belong to upper layers (`oxgraph-csr`,
7//! `oxgraph-graph`, `oxgraph-hyper`); the container only validates and
8//! exposes byte-aligned section payloads.
9//!
10//! # Format overview
11//!
12//! Every snapshot consists of a fixed [`HEADER_SIZE`]-byte header, a
13//! [`SECTION_ENTRY_SIZE`]-byte entry per section, and a payload region
14//! whose offsets and lengths are recorded in the entries. All multi-byte
15//! integer fields are little-endian and stored unaligned, so snapshots can
16//! be borrowed from any byte slice — `Vec<u8>`, mmap'd files, sub-slices —
17//! without an alignment requirement on the base pointer.
18//!
19//! Section payloads are exposed as byte slices via [`Section::bytes`]; the
20//! [`Section::try_as_slice`] helper checks the actual payload pointer's
21//! alignment against `align_of::<T>()` so consumers can reinterpret
22//! `&[u8]` as `&[T]` only when it is safe to do so.
23//!
24//! # Cargo features
25//!
26//! - default: reader-only API; `no_std`, no allocation.
27//! - `alloc`: enables [`SnapshotBuilder`], an owning builder that returns an encoded `Vec<u8>`.
28//! - `std`: reserved for future mmap helpers; no effect in v1 beyond activating `alloc`.
29//!
30//! # Stability
31//!
32//! v1.0 is the first topology-agnostic format major; the bytes are
33//! intentionally not yet promised as a stable ABI. Format minor bumps
34//! will preserve backward read compatibility once they ship.
35#![no_std]
36
37#[cfg(kani)]
38extern crate kani;
39
40#[cfg(feature = "alloc")]
41extern crate alloc;
42
43mod container;
44mod container_error;
45
46#[cfg(kani)]
47mod proofs;
48
49#[cfg(feature = "alloc")]
50pub use crate::container::SnapshotBuilder;
51pub use crate::{
52 container::{
53 FORMAT_MAGIC, FORMAT_MAJOR, FORMAT_MINOR, HEADER_SIZE, HeaderOnlySnapshot,
54 MAX_ALIGNMENT_LOG2, MAX_SECTION_COUNT, MAX_SUPPORTED_MINOR, PendingSection,
55 SECTION_ENTRY_SIZE, Section, SectionIter, Snapshot, SnapshotPlan, ValidationLevel,
56 },
57 container_error::{PlanError, SectionViewError, SnapshotError},
58};