Camus · /kæmˈuː/
An embedded persistent buffer with at-least-once storage handoff.
Camus durably stages opaque records between application code and an external effect. It is purpose-built for local spools, embedded outboxes, upload staging, and durable write-behind workloads. Once an append succeeds, the record remains recoverable until its exact release is durable.
At a glance
- Small lifecycle:
append -> read -> release -> reclaim. - Logical multi-stream: any number of lightweight stream namespaces share efficient root-wide physical storage.
- Async readiness:
Stream::readwaits for work and returns a non-empty, owned, bounded snapshot; no callback or polling loop is required. - Durable progress: group commit amortizes syncs without weakening the recovery outcome of an individual append or release.
- Explicit pressure: capacity is unbounded or globally bounded with
BlockorRejectNew; pending data is never silently evicted. - Application-neutral bytes: metadata and payload remain opaque, and physical locations never enter the public API.
Camus deliberately stops at the durable-buffer boundary. It is not a general-purpose KV database or message broker and provides no arbitrary queries, mutable records, networking, consumer ownership, retry scheduling, or exactly-once effects. The embedding application owns delivery policy and downstream idempotency.
Compatibility commitment: starting with
1.0.0-rc.1, the public Rust API follows Semantic Versioning and format-v1 roots remain readable by later compatible releases. Incompatible persistent changes require a new explicit format version and migration design. Earlier unpublished development roots are outside this compatibility boundary.
Install
Camus is available as a stable 1.0 release:
[]
= "1.0.0"
The 1.0 production durability target is Linux on a validated local filesystem. macOS is supported as a development environment; see the deployment envelope before production use.
Quick start
The intended API composes directly in async application code:
use Bytes;
use ;
async
Runnable, compiled versions of this lifecycle are in examples.
Core contract
- A storage root contains any number of caller-selected logical streams.
StreamIdis a root-scopedu64; every value is valid and no stream is a reserved default.- A stream is a logical namespace, not a directory, shard, rollover unit, I/O lane, consumer, or subscription.
appendandappend_batchtransfer owned opaque metadata and payload bytes into one recoverable durability epoch.- Camus allocates a stable opaque 32-byte
RecordIdfor each record. Physical segment locations never enter the public API. Stream::readwaits asynchronously for pending work and returns a non-empty, owned, bounded snapshot. Observation does not claim or remove records.Stream::releasedurably removes an exact record subset from the shared pending set. It is idempotent for records already released or reclaimed.- Reclamation is automatic.
Log::reclaimlets an application explicitly request and await the same maintenance when useful. - Capacity is configured once for the complete root as either unbounded or
bounded with
BlockorRejectNew; Camus has no per-stream quota.
The safe application flow is:
append record
-> read pending record
-> make the downstream effect durable
-> release record
-> Camus reclaims its physical segment when eligible
If a process stops after the downstream effect but before release becomes durable, recovery returns the record again. Applications must make repeated effects safe when that matters.
API overview
Potentially blocking storage work is async. Methods that only construct a handle or copy reactor-maintained state are synchronous and never perform hidden filesystem I/O.
Log, Stream, and their clones are thread-safe clients of one root reactor.
A Stream keeps the root alive, so applications may retain only stream
handles after setup. Explicit shutdown closes the shared lifecycle; surviving
handles then return a closed error.
Record and PendingRecord own metadata and payload as immutable Bytes.
Moving a record across the reactor boundary does not cause an undocumented
deep copy. A pending record contains its RecordId, metadata, and payload, and
the snapshot can outlive the read Future.
RecordId implements copy, equality, and hashing and has a fixed 32-byte
serialization. It is useful for storage identity and release, not ordering,
physical addressing, or application deduplication. Applications put their own
idempotency keys in opaque metadata.
Configuration requires an explicit Capacity. Other operational limits have
documented, configurable defaults and may be tuned from benchmarks without
changing format-v1 semantics.
An absent max_segment_age disables age rollover. known_streams and stats
are concurrent in-memory snapshots; they do not imply a disk refresh. Root
stats separate storage, pressure, logical-operation, durability-group,
maintenance, and recovery state. Detailed pressure stats separate command
queue admission from reactor dispatch time and split finite filesystem jobs by
append, read, release, reclaim, and timer-driven rollover. Health is a separate
low-frequency lifecycle view.
Read and release semantics
ReadLimits contains a hard record-count limit and a hard payload-byte limit.
A read selects the longest fitting prefix of that stream's pending logical
sequence, skipping released gaps but never skipping the earliest pending
record to find smaller later work. Metadata bytes are returned but do not
count toward max_bytes; complete record size remains bounded by the root's
epoch limit.
If the earliest record alone exceeds max_bytes, read returns a typed error
containing its ID, required payload bytes, and configured bytes. It never
silently violates the limit. Before returning, Camus verifies both metadata
and payload checksums for every selected record. One mismatch fails the whole
read with no partial snapshot and poisons the open root.
When no record is pending, read waits outside reactor admission. After being woken it admits one bounded storage read. If another handle releases all of that work first, the operation waits again rather than returning an empty snapshot.
Multiple handles may read the same pending records concurrently. They do not represent independent consumers: one durable release removes a record from future snapshots for every handle on that stream. Applications that need claims, leases, per-subscriber copies, or ownership coordination build them above Camus.
One release call is an atomic ensure-not-pending operation for its currently
pending subset. Duplicate IDs and IDs already released or reclaimed are
successful no-ops. Scope errors and unknown future IDs are rejected before
admission. Every root has a configurable hard max_release_records; Camus
never silently splits a larger release into weaker atomic units.
Ordering and durability
Within one stream, records retain input order inside an append batch and the reactor's serialization order across batches. Released gaps are skipped without reordering the remainder. Camus exposes no cross-stream order and does not equate read order with consumer execution or completion order.
Each append request is one independent recovery epoch. Each release request's newly pending subset is one independent release unit. The reactor may group consecutive units of the same kind behind one storage sync, but group commit does not merge their atomic recovery outcomes.
Append success means the epoch's complete record bytes and commit marker were covered by a successful data durability barrier. Release success means its manifest frame was covered by a successful manifest durability barrier. Commands that arrive during a sync join a later group; Camus adds no fixed linger delay at low load.
Capacity, rollover, and reclamation
For a bounded root, Block waits asynchronously for admissible capacity while
leaving read, release, and maintenance able to run. RejectNew returns a typed
not-admitted error. A request that can never fit fails immediately under either
policy. Neither policy evicts pending data or reports false durable success.
Capacity charges exact encoded lengths of Camus format files, including framing, control metadata, released bytes not yet reclaimed, and transactional temporary files. It does not model filesystem allocation blocks or reserve the device's free space. Camus keeps non-configurable dynamic headroom for a checkpoint rewrite, the largest next manifest frame, and an active segment's seal footer so release and reclamation can still make progress.
Physical data uses one root-wide segment sequence shared by every logical stream. Segment size is a hard limit; a complete epoch never crosses a segment. Optional maximum segment age, disabled by default, is a reactor-driven soft rollover deadline, not a real-time or retention guarantee. The timer can seal an idle non-empty segment without an application callback. Camus creates no empty replacement; the next append creates a segment lazily.
A segment is physically removed only after every record it contains is released. Interleaving streams therefore means one slow stream may pin released bytes from another stream. This is an accepted initial tradeoff; future dynamic sharding or relocation may improve it without changing the logical API.
Reclamation runs automatically at low priority and is promoted when blocked
appends need capacity. Log::reclaim exists for explicit observability and
tests, not for correctness.
Runtime and performance contract
Camus starts one async reactor task per open root. The reactor owns admission, the bounded command queue, group selection, timers, and in-memory state. Each finite filesystem job runs through the runtime's blocking facility, with at most one storage job executing per root. Different roots may make progress in parallel.
When no runtime is supplied, Camus lazily creates one process-wide private
Tokio runtime and retains it until process exit. Applications that require
scheduler isolation may configure an Arc<dyn Runtime>. Tokio types do not
appear in storage-domain values or Futures.
Admitted foreground operations execute FIFO. Only consecutive same-kind commit units at the queue head may be grouped; a read or change of kind is a barrier. Automatic maintenance is lower priority unless capacity progress requires it.
Cancellation before operation admission is side-effect-free. After admission, the reactor owns the operation through completion; dropping its Future only abandons the result. A cancelled append or release may therefore be recovered as durable even though its caller observed no result.
Failure model
Expected pre-mutation errors do not poison a root. These include invalid configuration or input, lock contention, closure, capacity rejection, requests over configured limits, insufficient read limits, record-ID scope or existence errors, and exhausted identifiers.
An I/O error after admission, authoritative corruption, lazy body-checksum
failure, or runtime failure poisons the open root. The triggering operation
returns its precise error. A mutating operation reports that its durable
outcome is unknown; failure is not proof that the mutation is absent. Queued
and future storage operations return Poisoned, while in-memory stats and
shutdown remain available.
Recovery is close and reopen. The reopened root validates durable bytes and decides which complete operations survived. Camus has no in-place reset or continue-after-poison mode.
Observability boundary
Log::stats and Stream::stats are synchronous, in-memory snapshots. Root
counters are scoped to one successful open and saturate instead of wrapping.
Base gauges, counters, real wait durations, and recovery duration are always
available. Config::with_detailed_observability additionally measures
end-to-end logical calls and storage jobs; it is disabled by default to keep
the fast path lean.
Log::health reports Running, ShuttingDown, Poisoned, or Closed and
retains the first failed-closed cause. HealthWatch::changed provides prompt,
coalescing async notification without owning the root or backpressuring its
reactor. It is not a record-delivery event stream; Stream::read remains the
readiness Future.
Returned errors expose a stable low-cardinality ErrorKind. Camus does not
choose metric names, automatically label by stream ID, or depend on a logging,
tracing, metrics, or exporter framework. See the
observability guide for counter semantics and adapter
guidance.
Use cases and non-goals
Camus fits local spools, embedded outboxes, upload staging, and durable write-behind buffers where the application wants a small persistent handoff boundary.
Camus intentionally does not provide:
- application schemas, serialization, filtering, indexes, or mutable records;
- record-delivery callbacks or subscriptions, consumers, claims, leases, or retry scheduling;
- per-subscriber delivery or per-stream capacity fairness;
- exactly-once delivery, application deduplication, or distributed transactions;
- network protocols, HTTP handlers, service routing, clustering, or replication; or
- database redo/undo or an externally visible physical log sequence number.
Storage layout and compatibility
Logical streams do not have physical directories. Format v1 uses one root identity, one checkpoint/log pair, and one shared segment directory:
<root>/
ROOT
camus.lock
MANIFEST.chk
MANIFEST.log
segments/
segment-00000000000000000000.log
...
Every authoritative artifact carries the immutable random 128-bit root ID.
XXH3-64 checksums use the fixed format-v1 seed CAMUSV1!; they detect
accidental corruption and are not authentication.
The exact layouts and compatibility boundary are defined in docs/file-format.md. Filesystem ordering, recovery, release, and reclamation invariants are defined in docs/architecture.md. Unsupported or ambiguous authoritative data fails closed.
Release 1.0.0-rc.1 establishes format v1 as the published compatibility
boundary. Earlier unpublished development roots are not migration inputs.
Starting with this candidate, changing a magic, field, checksum range, codec,
or semantic interpretation requires an explicit new format version and
migration design.
Deployment envelope
Camus 1.0 targets Linux local filesystems that honor file data sync, directory sync, exclusive advisory locking, and atomic same-directory rename. macOS is a development environment, not part of the production durability support matrix or required CI and release qualification. A network, userspace, or layered filesystem is outside the durability envelope unless its behavior has been independently validated.
One process owner opens a root at a time. Back up a closed root or use an atomic filesystem snapshot; do not copy a live root file by file. Checksums do not protect against an attacker who can rewrite bytes and recompute them.
Documentation
- Architecture: execution, durability, recovery, release, and reclamation invariants.
- File format: normative format-v1 byte layouts and codecs.
- Usage guide: API composition, capacity, cancellation, and shutdown.
- Operations guide: supported deployment and failure response.
- Observability guide: snapshots, counter semantics, health transitions, and adapter guidance.
- Benchmark guide: reproducible durable-buffer workloads, comparison-engine mappings, and regression comparison.
- Long-running smoke guide: cyclic capacity pressure, latency telemetry, VictoriaMetrics reporting, and pass criteria.
- Release guide: RC qualification, compatibility gates, required repository settings, packaging, publication, and rollback.
- Runnable examples: replay, waiting reads, multi-stream use, maintenance, and observability.
Development
Before publishing, run:
RUSTDOCFLAGS="-D warnings"
Stable releases and release candidates additionally use the manual-only
Release qualification
workflow to validate candidate metadata, the applicable public-API baseline,
and tests executed from Cargo's extracted package source. The workflow never
publishes or tags a release.
License
Camus 1.0.0 and current development are licensed under the
MIT License. Published versions through 1.0.0-rc.2 remain
under the Apache License 2.0
included with those artifacts.