crossbank 0.1.2

Local, on-device key/value storage for Rust — one API on native (redb) and in the browser (IndexedDB). A Hive-shaped replacement, with no network, server, or sync.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
//! Per-locker limits and retention policy.
//!
//! # Commit × Durability
//!
//! Two independent knobs decide when a write is safe, and they answer
//! different questions. [`Commit`] decides **when a commit happens**;
//! [`Durability`] decides **how hard that commit works to reach the disk**.
//! All four combinations are legal and each is useful:
//!
//! | | `Durability::Immediate` (default) | `Durability::Eventual` |
//! |---|---|---|
//! | **`Commit::Immediate`** (default) | Safest, slowest. One fsync per `put`; when `put` returns, the data survives a power cut. | One commit per `put`, no fsync. Survives the process dying; a power cut may lose recent writes until `flush`. |
//! | **`Commit::Deferred { after }`** | One fsync per batch of `after` writes. Nothing is stored — at all — until the batch commits or you `flush`. | Cheapest. Neither the batch nor the fsync happens until it fills or you `flush`. |
//!
//! **`flush` covers both.** [`crate::Locker::flush`],
//! [`crate::LazyLocker::flush`] and [`crate::Bank::flush_all`] commit whatever
//! is staged *and*, on an `Eventual` locker, force the backend fsync. One call
//! from `pagehide` or a native stop hook is the whole contract.
//!
//! The web backend does not honour `Durability` at all: IndexedDB has no
//! fsync knob to turn, and its own durability is the browser's business. An
//! `Eventual` locker on IndexedDB behaves exactly like an `Immediate` one, so
//! the setting is portable rather than platform-specific — it just costs
//! nothing there.

/// What happens to a locker's contents when storage runs short.
///
/// ```no_run
/// use crossbank::{Bank, BankConfig, LazyLocker, LockerConfig, Policy};
///
/// # async fn demo() -> crossbank::Result<()> {
/// let bank = Bank::open(BankConfig::at("app.crossbank")).await?;
///
/// // Regenerable data, capped. Least-recently-used entries are shed to stay
/// // under the budget, which crossbank accounts for itself.
/// let cache: LazyLocker<Vec<u8>> = bank
///     .lazy_locker_with(
///         "thumbnails",
///         LockerConfig::default().with_policy(Policy::Evictable { max_bytes: 8 << 20 }),
///     )
///     .await?;
/// cache.put("a", &vec![0u8; 4096]).await?;
/// println!("{} bytes accounted for", cache.budget_used());
///
/// // Anything that cannot be regenerated stays `Precious`, which is the
/// // default and needs no `with_policy` call at all.
/// let vault: LazyLocker<Vec<u8>> = bank.lazy_locker("vault").await?;
/// # let _ = vault;
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Policy {
    /// Never shed anything. The right choice for data that cannot be
    /// regenerated — saved reports, user documents, vault contents.
    ///
    /// The default: silently losing data for anyone who did not think about
    /// retention would be the wrong way round. Opt in to loss, never out.
    #[default]
    Precious,

    /// Shed least-recently-used entries to stay under `max_bytes`.
    ///
    /// A byte budget crossbank actually owns and enforces, deliberately not a
    /// fraction of `navigator.storage.estimate()`. That figure is origin-wide,
    /// moves when other tabs write, and cannot be attributed to a single
    /// locker — so a policy expressed against it would be untestable natively
    /// and unenforceable anywhere.
    Evictable { max_bytes: u64 },
}

/// What opening a locker does when a stored record will not decode.
///
/// Corruption is rare but not impossible: a truncated file, a filter chain
/// swapped without changing its id, a bug in a consumer's own `Filter`. The
/// question this settles is whether one bad record is allowed to make the
/// whole locker unopenable.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum OnCorrupt {
    /// Refuse to open. The default, because silently hiding data loss is the
    /// wrong way round: a caller has to *ask* to carry on without it.
    #[default]
    Fail,

    /// Open anyway, skipping the bad records and listing their keys.
    ///
    /// Nothing is written and nothing is deleted — the stored bytes are left
    /// exactly as they are, so a later build with a fixed decoder can still
    /// read them. Use [`crate::Bank::quarantine`] to remove them deliberately.
    Skip,
}

/// When a write reaches storage.
///
/// The default is [`Commit::Immediate`] and it is never chosen for you.
///
/// ```no_run
/// use crossbank::{Bank, BankConfig, Commit, LazyLocker, LockerConfig};
///
/// # async fn demo() -> crossbank::Result<()> {
/// let bank = Bank::open(BankConfig::at("app.crossbank")).await?;
/// let locker: LazyLocker<Vec<u8>> = bank
///     .lazy_locker_with(
///         "ingest",
///         LockerConfig::default().with_commit(Commit::Deferred { after: 64 }),
///     )
///     .await?;
///
/// locker.put("a", &vec![1u8; 16]).await?;
/// assert_eq!(locker.pending(), 1); // staged, not stored
///
/// // NOTHING flushes this for you — no timer, no task, no destructor.
/// // Call it from your stop hook, or from `pagehide` on the web.
/// locker.flush().await?;
/// assert_eq!(locker.pending(), 0);
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Commit {
    /// Every write is its own commit, and `put` returns once it has landed.
    ///
    /// The safe answer, and the default: when `put` returns, the data is
    /// stored.
    #[default]
    Immediate,

    /// Stage writes in memory and commit them in batches of `after`.
    ///
    /// **Only one handle per name may use it.** Two handles on one locker each
    /// keep their own staging buffer, so whichever flushed last would win and
    /// the other's writes would be silently overwritten. [`crate::Bank`]
    /// refuses the second open with [`crate::Error::InvalidConfig`] rather
    /// than let that happen — see [`crate::Bank::locker_with`].
    ///
    /// # You must call `flush` yourself
    ///
    /// **crossbank spawns nothing.** There is no timer, no background task and
    /// no destructor that will flush for you — a `Drop` implementation cannot
    /// await, and on the web a closing tab does not run one anyway. Staged
    /// writes that are never flushed are lost, and that is the whole cost of
    /// this mode.
    ///
    /// So a consumer choosing `Deferred` **must** call
    /// [`crate::LazyLocker::flush`], [`crate::Locker::flush`] or
    /// [`crate::Bank::flush_all`]:
    ///
    /// * on the web, from `pagehide` and from `visibilitychange` when the
    ///   document becomes hidden — **not** `beforeunload`, which mobile
    ///   browsers frequently never fire;
    /// * natively, from whatever the application uses as its stop hook.
    ///
    /// `examples/flush_on_pagehide.rs` shows both.
    ///
    /// # What is visible before a flush
    ///
    /// Everything, to this handle: an eager locker updates its resident value
    /// immediately, and a lazy locker sees staged writes through `get`,
    /// `contains_key`, `len` and the key listings. Change events are raised
    /// when the write is staged, because that is when it becomes visible —
    /// which does mean an event can precede a commit that later fails.
    ///
    /// Nothing is visible to another handle, another tab or another process
    /// until it is committed.
    Deferred {
        /// Commit once this many writes are staged. Zero and one both mean
        /// "commit on the next write", which is [`Commit::Immediate`] with
        /// extra steps.
        after: usize,
    },
}

pub use crate::backend::api::Durability;

/// Limits applied to one locker.
///
/// Cloneable rather than `Copy`: a locker may carry its own filter chain, and
/// a chain is a `dyn Filter` list behind an `Arc`.
///
/// Every field has a safe default and none of them is ever chosen for you.
/// Build with the `with_*` methods:
///
/// ```no_run
/// use std::sync::Arc;
/// use crossbank::codec::{FilterChain, Lz4};
/// use crossbank::{Bank, BankConfig, Commit, Durability, LazyLocker, LockerConfig, Policy};
///
/// # async fn demo() -> crossbank::Result<()> {
/// let bank = Bank::open(BankConfig::at("app.crossbank")).await?;
///
/// let config = LockerConfig::default()
///     // Shed the least recently used entries to stay under a budget
///     // crossbank enforces itself.
///     .with_policy(Policy::Evictable { max_bytes: 64 << 20 })
///     // Stage writes and commit them in batches. YOU own the flush.
///     .with_commit(Commit::Deferred { after: 32 })
///     // Skip the per-commit fsync until `flush`.
///     .with_durability(Durability::Eventual)
///     .with_chunk_size(256 * 1024)
///     // This locker compresses; the rest of the bank need not.
///     .with_chain(Arc::new(FilterChain::new(7, vec![Box::new(Lz4)])));
///
/// let cache: LazyLocker<Vec<u8>> = bank.lazy_locker_with("candles", config).await?;
/// cache.put("BTCUSDT", &vec![0u8; 4096]).await?;
///
/// // Nothing above stores anything until this.
/// cache.flush().await?;
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct LockerConfig {
    /// Largest value an eager locker will accept.
    ///
    /// Eager lockers answer `get()` synchronously and infallibly, so they can
    /// never await a chunk fetch. Anything past this belongs in a lazy locker.
    pub max_inline: usize,

    /// Largest total an eager locker will load at open.
    ///
    /// The guardrail against typing `locker()` where `lazy_locker()` was meant
    /// and quietly pulling hundreds of megabytes into memory. Failing loudly at
    /// open beats discovering it as an out-of-memory abort later.
    pub eager_budget: u64,

    pub policy: Policy,

    /// When writes reach storage. See [`Commit`].
    pub commit: Commit,

    /// How hard each commit works to reach the disk. See [`Durability`] and
    /// the table in the module docs.
    pub durability: Durability,

    /// What to do about a record that will not decode. See [`OnCorrupt`].
    pub on_corrupt: OnCorrupt,

    /// Size of one chunk for a lazy value that does not fit inline.
    ///
    /// Peak memory on the streaming path is a small multiple of this, not of
    /// the value. 256 KiB is the starting default; benches may move it.
    pub chunk_size: usize,

    /// The filter chain this locker's values are sealed with.
    ///
    /// `None` — the default — means the bank's chain. Set it to give one
    /// locker a different one: LZ4 on a candle series next to a raw chain on
    /// settings, in the same bank.
    ///
    /// The choice is **persistent**, not a runtime option. The chain id is
    /// recorded in `meta` the first time the locker is opened, and every later
    /// open under a different id is refused with [`crate::Error::SchemaMismatch`]
    /// rather than handing stored bytes to the wrong inverse transform. Chunks
    /// are sealed piece by piece with the same chain, and so is anything a
    /// coherence message carries inline.
    pub chain: Option<std::sync::Arc<crate::codec::FilterChain>>,
}

/// Two configs are equal when they would behave identically. A filter chain
/// compares by its id, which is exactly the thing that gates format
/// compatibility — see [`crate::codec::FilterChain`].
impl PartialEq for LockerConfig {
    fn eq(&self, other: &Self) -> bool {
        self.max_inline == other.max_inline
            && self.eager_budget == other.eager_budget
            && self.policy == other.policy
            && self.commit == other.commit
            && self.durability == other.durability
            && self.on_corrupt == other.on_corrupt
            && self.chunk_size == other.chunk_size
            && self.chain_id() == other.chain_id()
    }
}

impl Eq for LockerConfig {}

impl Default for LockerConfig {
    fn default() -> Self {
        Self {
            max_inline: 256 * 1024,
            eager_budget: 32 * 1024 * 1024,
            policy: Policy::Precious,
            commit: Commit::Immediate,
            durability: Durability::Immediate,
            on_corrupt: OnCorrupt::Fail,
            chunk_size: 256 * 1024,
            chain: None,
        }
    }
}

impl LockerConfig {
    pub fn with_max_inline(mut self, bytes: usize) -> Self {
        self.max_inline = bytes;
        self
    }

    pub fn with_eager_budget(mut self, bytes: u64) -> Self {
        self.eager_budget = bytes;
        self
    }

    pub fn with_policy(mut self, policy: Policy) -> Self {
        self.policy = policy;
        self
    }

    /// See [`Commit`]. Deferred writes are never the default, and the caller
    /// takes on the duty of flushing them.
    pub fn with_commit(mut self, commit: Commit) -> Self {
        self.commit = commit;
        self
    }

    /// See [`Durability`]. `Eventual` trades power-cut safety for speed and
    /// hands the caller the duty of calling `flush`.
    pub fn with_durability(mut self, durability: Durability) -> Self {
        self.durability = durability;
        self
    }

    /// Whether this locker's commits skip the per-commit fsync.
    pub(crate) fn is_eventual(&self) -> bool {
        matches!(self.durability, Durability::Eventual)
    }

    pub fn with_on_corrupt(mut self, on_corrupt: OnCorrupt) -> Self {
        self.on_corrupt = on_corrupt;
        self
    }

    pub fn with_chunk_size(mut self, bytes: usize) -> Self {
        self.chunk_size = bytes.max(1);
        self
    }

    /// Give this locker its own filter chain instead of the bank's.
    ///
    /// Recorded in `meta` at first open and enforced on every later one. See
    /// [`LockerConfig::chain`].
    pub fn with_chain(mut self, chain: std::sync::Arc<crate::codec::FilterChain>) -> Self {
        self.chain = Some(chain);
        self
    }

    /// This locker's own chain id, if it has one.
    pub(crate) fn chain_id(&self) -> Option<u8> {
        self.chain.as_ref().map(|c| c.id())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn defaults_are_conservative() {
        let c = LockerConfig::default();
        assert_eq!(c.max_inline, 256 * 1024);
        assert_eq!(c.eager_budget, 32 * 1024 * 1024);
        assert_eq!(c.policy, Policy::Precious);
        assert_eq!(c.chunk_size, 256 * 1024);
        assert_eq!(c.commit, Commit::Immediate);
        assert_eq!(c.durability, Durability::Immediate);
    }

    #[test]
    fn durability_is_immediate_unless_asked_otherwise() {
        // The same rule as `commit`: nobody loses a write they did not ask to
        // risk. `Eventual` must be typed out.
        assert_eq!(Durability::default(), Durability::Immediate);
        assert!(!LockerConfig::default().is_eventual());
        let c = LockerConfig::default().with_durability(Durability::Eventual);
        assert_eq!(c.durability, Durability::Eventual);
        assert!(c.is_eventual());
    }

    #[test]
    fn writes_are_immediate_unless_asked_otherwise() {
        // Deferring by default would mean data silently lost for anyone who
        // never learned they had to flush. Opt in to the risk, never out.
        assert_eq!(Commit::default(), Commit::Immediate);
        let c = LockerConfig::default().with_commit(Commit::Deferred { after: 8 });
        assert_eq!(c.commit, Commit::Deferred { after: 8 });
    }

    #[test]
    fn failing_on_corruption_is_the_default() {
        // Opening over data we cannot read must be loud. Skipping silently
        // would turn data loss into a shrug.
        assert_eq!(OnCorrupt::default(), OnCorrupt::Fail);
        assert_eq!(LockerConfig::default().on_corrupt, OnCorrupt::Fail);
    }

    #[test]
    fn precious_is_the_default_policy() {
        // Defaulting to evictable would mean data silently disappearing for
        // anyone who did not think about it. Safe by default, opt in to loss.
        assert_eq!(Policy::default(), Policy::Precious);
    }

    #[test]
    fn builders_compose() {
        let c = LockerConfig::default()
            .with_max_inline(1024)
            .with_eager_budget(2048)
            .with_policy(Policy::Evictable { max_bytes: 4096 })
            .with_on_corrupt(OnCorrupt::Skip)
            .with_chunk_size(64)
            .with_durability(Durability::Eventual)
            .with_chain(std::sync::Arc::new(crate::codec::FilterChain::raw()));
        assert_eq!(c.on_corrupt, OnCorrupt::Skip);
        assert_eq!(c.durability, Durability::Eventual);
        assert_eq!(c.max_inline, 1024);
        assert_eq!(c.eager_budget, 2048);
        assert_eq!(c.policy, Policy::Evictable { max_bytes: 4096 });
        assert_eq!(c.chunk_size, 64);
        assert_eq!(c.chain_id(), Some(0));
    }

    /// A chain compares by the id that gates format compatibility, not by
    /// pointer identity — two `Arc`s over the same chain must not read as two
    /// different configs.
    #[test]
    fn configs_compare_a_chain_by_its_id() {
        use std::sync::Arc;
        let a = LockerConfig::default().with_chain(Arc::new(crate::codec::FilterChain::raw()));
        let b = LockerConfig::default().with_chain(Arc::new(crate::codec::FilterChain::raw()));
        assert_eq!(a, b);
        assert_ne!(a, LockerConfig::default());
    }
}