Crate oxgraph_snapshot 

Topology-agnostic byte-level snapshot container.

oxgraph-snapshot defines a sectioned, zero-copy checkpoint format that can validate, package, and read immutable topology snapshots without knowing whether their contents are graphs, hypergraphs, or anything else. Section semantics belong to upper layers (oxgraph-csr, oxgraph-graph, oxgraph-hyper); the container only validates and exposes byte-aligned section payloads.

Format overview

Every snapshot consists of a fixed HEADER_SIZE-byte header, a SECTION_ENTRY_SIZE-byte entry per section, and a payload region whose offsets and lengths are recorded in the entries. All multi-byte integer fields are little-endian and stored unaligned, so snapshots can be borrowed from any byte slice — Vec<u8>, mmap’d files, sub-slices — without an alignment requirement on the base pointer.

Section payloads are exposed as byte slices via Section::bytes; the Section::try_as_slice helper checks the actual payload pointer’s alignment against align_of::<T>() so consumers can reinterpret &[u8] as &[T] only when it is safe to do so.

Cargo features

• default: reader-only API; no_std, no allocation.
• alloc: enables [SnapshotBuilder], an owning builder that returns an encoded Vec<u8>.
• std: reserved for future mmap helpers; no effect in v1 beyond activating alloc.

Stability

v1.0 is the first topology-agnostic format major; the bytes are intentionally not yet promised as a stable ABI. Format minor bumps will preserve backward read compatibility once they ship.

Structs

HeaderOnlySnapshot

Header-only handle to a snapshot’s bytes.

PendingSection

Description of one section to include in a snapshot.

Section

Borrowed view of one validated section in a snapshot.

SectionIter

Iterator over a snapshot’s validated sections.

Snapshot

Validated, borrowed handle to a snapshot’s bytes and section table.

SnapshotPlan

Validated plan that can compute its encoded length and write itself.

Enums

PlanError

Error returned by snapshot writers.

SectionViewError

Error returned when borrowing a section payload as a typed slice fails.

SnapshotError

Snapshot container validation error.

ValidationLevel

Validation depth applied at snapshot open time.

Constants

FORMAT_MAGIC

Magic bytes identifying the topology snapshot container format.

FORMAT_MAJOR

Format major version this library reads and writes.

FORMAT_MINOR

Format minor version written by this library’s builder.

HEADER_SIZE

Size of the snapshot header in bytes.

MAX_ALIGNMENT_LOG2

Maximum permitted alignment_log2 value (2^12 = 4 KiB, page-friendly).

MAX_SECTION_COUNT

Maximum permitted section count for v1 snapshots.

MAX_SUPPORTED_MINOR

Highest format minor version this library can read.

SECTION_ENTRY_SIZE

Size of one section table entry in bytes.