kithara-storage

Storage primitives for kithara. Provides a unified StorageResource enum (Mmap | Mem) with random-access read_at/write_at, blocking wait_range, and convenience read_into/write_all. MmapResource is file-backed via mmap-io; MemResource is fully in-memory. OpenMode controls file access for mmap: Auto (default), ReadWrite, or ReadOnly.

Usage

use kithara_storage::{MmapResource, MmapOptions, OpenMode, StorageResource};

// File-backed (mmap)
let mmap = MmapResource::open(cancel_token, MmapOptions {
    path: path.into(),
    initial_len: None,
    mode: OpenMode::Auto,
})?;
let resource = StorageResource::from(mmap);
resource.write_at(0, &data)?;
let outcome = resource.wait_range(0..1024)?;

Blocking coordination

sequenceDiagram
    participant DL as Downloader (async)
    participant W as Writer
    participant SR as StorageResource
    participant RS as RangeSet
    participant CV as Condvar
    participant R as Reader (sync)

    Note over DL,R: Async downloader and sync reader share StorageResource

    DL->>W: poll next chunk from network
    W->>SR: write_at(offset, bytes)
    SR->>RS: insert(offset..offset+len)
    SR->>CV: notify_all()

    R->>SR: wait_range(pos..pos+len)
    SR->>RS: check coverage
    alt Range not ready
        SR->>CV: wait(50ms timeout)
        Note over SR,CV: Loop until ready, EOF, or cancelled
        CV-->>SR: woken by notify_all
        SR->>RS: re-check coverage
    end
    SR-->>R: WaitOutcome::Ready

    R->>SR: read_at(pos, buf)
    SR-->>R: bytes read

wait_range blocks the calling thread via parking_lot::Condvar until the requested byte range is fully written, or the resource reaches EOF/error/cancellation.

Key Types

Mmap vs Mem

Synchronization

Range tracking uses RangeSet<u64> (from rangemap) to record which byte ranges have been written. wait_range blocks via parking_lot::Condvar with a 50 ms timeout loop until the requested range is fully covered, returns Eof when the resource is committed and the range starts beyond the final length, and returns Interrupted when a seek/flush wakes the waiter. CancellationToken is checked at operation entry and during wait loops.

Integration

Foundation layer for kithara-assets. Higher-level concerns (trees of resources, eviction, leases) are handled by kithara-assets.

Notes on the `redundant_reexport` audit warning

just audit kithara-storage flags two redundant_reexport warnings — MemOptions and MmapOptions are surfaced both via pub use from lib.rs and via the <Driver>::Options associated type. The duplication is intentional and documented here per AGENTS.md ("if you must suppress, document why in the owning crate README.md"):

MmapOptions / MemOptions are the canonical user-facing constructor types — every caller writes MmapOptions { path, initial_len, mode } reachable via kithara_storage::MmapOptions.
The Driver::Options associated type is the binding that lets the generic Resource::<D>::open(token, opts: D::Options) constructor pick the right driver from the option struct's type alone (via type inference at the call site). Removing Options would force every caller to pre-qualify with the driver type alias (MmapResource::open / MemResource::open) — a wider API ripple than the duplicated path is worth.
Dropping the pub use (the audit's literal suggested fix) would break ~15 external callers that rely on kithara_storage::{MmapOptions, MemOptions}.

The two warnings are stable across releases; no other audit warnings should appear.

kithara-storage 0.0.1-alpha2