Module storage 

luci-storage — block-based storage engine for Luci.

This crate implements the [[single-file-format]] that backs every Luci index. It manages disk space as fixed-size blocks, tracks free space with extent-based free lists, and provides atomic commit via a two-root-pointer technique.

See [[architecture-storage-format]] for the full design.

Modules

lock

Five-state file locking protocol for cross-process coordination.

Structs

BlockAllocator

Block allocator with extent-based free-list tracking.

BlockId

Identifies a block by its zero-based index within the data region.

Extent

A contiguous range of blocks: [start, start + count).

FileHeader

The 4 KB file header for a .luci index file.

MetadataSnapshot

Point-in-time snapshot of all index metadata, stored in the metadata root block referenced by a root pointer.

RootPointer

A root pointer in the file header.

SegmentEntry

An entry in the segment directory mapping a segment to its block location.

SingleFileDirectory

Production storage backend: all data in a single .luci file using the block allocator and two-root-pointer atomic commit.

VectorIndexEntry

An entry in the vector-index directory mapping a dense_vector field to the file extent holding its serialized search index (HNSW graph today; other algorithms in the future).

Wal

Write-ahead log for buffering document operations between commits.

Enums

ActiveRoot

Identifies which root pointer is active.

DurabilityMode

Durability mode controlling when WAL writes are fsynced to disk.

WalRecord

A single WAL record: either a document put or delete.

Constants

BLOCK_SIZE

Block size in bytes: 256 KB.

FORMAT_VERSION

Current format version. Incremented on breaking format changes.

HEADER_SIZE

Size of the file header in bytes: 4 KB.

MAGIC

Magic bytes identifying a Luci index file.

Traits

Storage

Trait abstracting over storage backends.

Functions

replay_wal

Replay a WAL file, returning all valid records.

xxh3_checksum

Compute the xxHash (XXH3-64) checksum of a metadata root block.