Skip to main content

Crate crossbank

Crate crossbank 

Source
Expand description

crossbank — local, on-device key/value storage for Rust, and a direct replacement for Flutter’s Hive (hive_ce).

It saves an application’s data on the machine it is running on: a redb file on Linux, macOS, Windows, Android and iOS, and real IndexedDB in the browser, behind one API. There is no network code, no server, no sync and no cloud anywhere in it — crossbank never talks to anything. Modelled on Hive’s architecture and ergonomics, deliberately not its file format, and Hive’s own data is not migrated.

See the README for the Hive-to-crossbank mapping, and PLAN.md in the repository for the design and its rationale. The plan is inward-facing working notes and deliberately does not ship inside the published crate.

§Status

0.1.x — the API may still change before 1.0. M0–M6 are complete: data persists natively (redb) and in real browsers (IndexedDB), large lazy values are chunked with streaming Writer/Reader access, and storage pressure is answered by Bank::persist / Bank::is_persisted / Bank::usage plus a byte-budget LRU on Policy::Evictable lockers. Two facilities are opt-in and never chosen for you: cross-tab coherence (BankConfig::with_coherence, web only) and write coalescing (Commit::Deferred, whose flush you own — crossbank spawns nothing).

Values are sealed through a FilterChain, set per bank or per locker (LockerConfig::with_chain). crossbank ships LZ4 and CRC32 and no cipher at all: implement Filter to add one, so key handling and its audit burden stay with the application that owns the keys.

Web storage has rules a filesystem does not; the README’s “Web caveats” section covers persistence, Safari’s seven-day eviction, and what coherence changes about an eager get().

Keys are bytes. Every &str method has a _by twin taking &[u8] (Locker::get_by, Locker::put_by, LazyLocker::range_by, …), a &str key is stored as exactly its UTF-8 bytes, and the &str listings (Locker::keys, LazyLocker::to_map) skip what they cannot spell rather than failing — Locker::has_non_utf8_keys and Locker::keys_bytes cover the rest.

Bulk work goes through Locker::put_all / Locker::delete_all, each one atomic commit, and change notification through Locker::watch, Locker::watch_key and Locker::watch_keys. BankHandle carries the same bulk shapes over its channel (BankHandle::put_all, BankHandle::delete_all, BankHandle::get_many, BankHandle::entries) plus the bank-level questions, which is what a Hive-shaped shim in front of it needs.

Damaged data is survivable rather than fatal: OnCorrupt::Skip opens a locker without its unreadable records and lists them via Locker::corrupt_keys, Bank::verify surveys a locker without changing it, and Bank::quarantine is the only thing that deletes a record for being corrupt.

§Shape

  Bank / Locker / LazyLocker / Transaction / Writer / Reader / BankHandle
─────────────────────────────────────────────────────────────  public API
  codec · filters · chunking · RAM index · watch · eviction
─────────────────────────────────────────────────────────────  engine (portable)
                       trait Backend
─────────────────────────────────────────────────────────────
  memory (all)      redb (native)      IndexedDB (wasm32)

Everything above the Backend trait is portable Rust with no cfg in it. Backends stay deliberately dumb — no chunking, no codecs, no eviction — so that a single conformance suite can grade all of them against one spec.

Re-exports§

pub use backend::RedbBackend;
pub use backend::Backend;
pub use backend::MemoryBackend;
pub use backend::Usage;
pub use bank::delete_bank;
pub use bank::Bank;
pub use bank::BankConfig;
pub use bank::Location;
pub use codec::Filter;
pub use codec::FilterChain;
pub use error::Error;
pub use error::Result;
pub use handle::BankHandle;
pub use locker::Commit;
pub use locker::Durability;
pub use locker::LazyLocker;
pub use locker::Locker;
pub use locker::LockerConfig;
pub use locker::OnCorrupt;
pub use locker::Policy;
pub use locker::Reader;
pub use locker::Transaction;
pub use locker::Writer;
pub use watch::Event;
pub use watch::EventStream;
pub use handle::BankHandle as RemoteBank;

Modules§

backend
Storage backends.
bank
The bank: the root handle, and the registry that maps locker names to ids.
codec
Value encoding: the envelope, its filter chain, and the serde layer.
error
crossbank’s error type.
handle
A Send + Sync handle onto a bank that is not itself Send.
key
Key encoding.
locker
Lockers: the two containers a bank hands out.
watch
Change notification.

Constants§

NAME
The crate name, useful in diagnostics.