Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_o3db_sync/src/lane.rs

25.8 KiB, 1 run

created by r1870400018:74441, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1//! A sequence lane: a bounded log under one key prefix in any [`Database`], each entry at its own
2//! rising sequence number, read in pages above a cursor, trimmed from the bottom, with lazy expiry
3//! and per-reader cursors whose least live value is the lane's `stable` point.
4//!
5//! Every method runs while the caller holds THAT LANE's lock, and [`Lane::new`] takes the
6//! [`LaneGuard`] that proves it, obtainable only from [`LaneLocks::lock`]: the head, the floor and
7//! the reader table are read, changed and written back, and two unserialised callers on one lane
8//! would lose an update. `read_after` writes too, since it deletes the expired entries it meets.
9//! The lane's prefix is the guard's, so a guard for one lane cannot open another. Only the lane
10//! is serialised, not the store: the database is shared (`&DB`, its `insert`, `get` and `delete`
11//! being `&self` and thread-safe), so lanes of different accounts and scopes run side by side
12//! and a lane section never holds up the rest of the store. Every key a lane touches is under
13//! its own prefix, so two lanes never write the same key.
14//!
15//! Each request's hold on its lane is bounded by the caller's doors: an append batch by its
16//! record count (the caller's), and a page by both bytes and `max_steps`, the slots (entries,
17//! holes and expired entries alike) one [`Lane::read_after`] may visit before it answers `more`.
18//! The lane reads values throughout and never relies on a key-only presence answer.
19//!
20//! A replay whose entry has gone (trimmed, removed or expired) appends anew; refusing a replayed
21//! ephemeral record after its expiry is the caller's (Daimond's C8), not the lane's.
22//!
23//! TRIMS. [`Lane::trim_through`] raises the floor in one write and deletes nothing: a durable
24//! entry at or below the floor reads absent at once, and an ephemeral one (with an expiry) stays
25//! at its own sequence and reads to every reader below it until it expires, so a reader behind a
26//! trim still gets a live Stop or consent. [`Lane::sweep_trimmed`] then deletes the trimmed
27//! slots a bounded number at a time, so the caller can release the lane's lock between steps;
28//! the ephemerals it meets are listed (`p/k`) so a reader below the floor reaches them without
29//! walking the holes. [`Lane::trim_pending`] says whether a step has work.
30//!
31//! Keys, under the caller's prefix `p`:
32//!
33//! | key | holds |
34//! |---|---|
35//! | `p/m` | `[head, floor, swept, due]`: the last sequence handed out, the highest trimmed, how far the trim's deletion has reached (≤ floor), and the earliest expiry in `p/k` (0 for none) |
36//! | `p/e/<seq>` | `[exp_ms, id, value]`, `exp_ms` 0 for never, `id` empty for none |
37//! | `p/i/<hex id>` | the sequence the entry with that id was appended at |
38//! | `p/r` | the reader table, `{name: [cursor, live]}`, one value, bounded by the caller's readers |
39//! | `p/k` | the ephemerals at or below `swept` kept by the sweep, `[[seq, exp_ms]…]` in sequence order; bound: the lane's ephemerals still in their life; shed: each is dropped by the sweep once it expires |
40//!
41//! Built for Daimond's sync carrier (design (2), 16 Oct 2026, §7; the U2 delta of 10 Oct, §3.1,
42//! row G1). Steel's paced outbox keeps the same shape by hand.
43//!
44//! [Written with AI entirely](https://need2know.ai/entirely-ai/code)\
45//! Anthropic Claude
46
47use oxedyne_fe2o3_core::prelude::*;
48use oxedyne_fe2o3_iop_crypto::enc::Encrypter;
49use oxedyne_fe2o3_iop_db::api::Database;
50use oxedyne_fe2o3_iop_hash::api::Hasher;
51use oxedyne_fe2o3_jdat::{
52 prelude::*,
53 id::NumIdDat,
54};
55
56use std::{
57 collections::hash_map::RandomState,
58 hash::BuildHasher,
59 marker::PhantomData,
60 sync::{
61 Mutex,
62 MutexGuard,
63 },
64};
65
66
67/// The per-lane locks: a fixed set of mutexes (stripes), each lane taking the one its prefix
68/// hashes to under a per-process random key, so the set is bounded whatever the number of lanes
69/// and nobody outside can aim two lanes at one stripe. Two lanes on one stripe only take turns.
70///
71/// Hold at most one [`LaneGuard`] per thread: two lanes on one stripe would wait on each other.
72#[derive(Debug)]
73pub struct LaneLocks {
74 stripes: Box<[Mutex<()>]>,
75 hasher: RandomState,
76}
77
78impl Default for LaneLocks {
79 fn default() -> Self {
80 Self::new(Self::DEFAULT_STRIPES)
81 }
82}
83
84impl LaneLocks {
85 /// Enough stripes that unrelated lanes rarely meet, at one mutex each.
86 pub const DEFAULT_STRIPES: usize = 256;
87
88 /// `stripes` mutexes, at least one.
89 pub fn new(stripes: usize) -> Self {
90 let n = stripes.max(1);
91 let mut v = Vec::with_capacity(n);
92 for _ in 0..n {
93 v.push(Mutex::new(()));
94 }
95 Self {
96 stripes: v.into_boxed_slice(),
97 hasher: RandomState::new(),
98 }
99 }
100
101 /// Takes the lock of the lane under `prefix`, waiting while another holds it, and answers the
102 /// guard [`Lane::new`] takes. A poisoned stripe is taken as it is: a lane writes each entry
103 /// before the head that counts it, so a section cut short by a panic leaves a lane that reads
104 /// whole.
105 pub fn lock<S: Into<String>>(&self, prefix: S) -> LaneGuard<'_> {
106 let prefix = prefix.into();
107 let i = self.stripe(&prefix);
108 let held = match self.stripes[i].lock() {
109 Ok(g) => g,
110 Err(p) => p.into_inner(),
111 };
112 LaneGuard { _held: held, prefix }
113 }
114
115 /// As [`lock`](Self::lock), but `None` rather than waiting when the lane's stripe is held.
116 pub fn try_lock<S: Into<String>>(&self, prefix: S) -> Option<LaneGuard<'_>> {
117 let prefix = prefix.into();
118 let i = self.stripe(&prefix);
119 let held = match self.stripes[i].try_lock() {
120 Ok(g) => g,
121 Err(std::sync::TryLockError::Poisoned(p)) => p.into_inner(),
122 Err(std::sync::TryLockError::WouldBlock) => return None,
123 };
124 Some(LaneGuard { _held: held, prefix })
125 }
126
127 fn stripe(&self, prefix: &str) -> usize {
128 (self.hasher.hash_one(prefix) % self.stripes.len() as u64) as usize
129 }
130}
131
132/// The proof that the holder has the lock of the lane under [`prefix`](Self::prefix), from
133/// [`LaneLocks::lock`] only; the lock is released when it drops.
134#[derive(Debug)]
135pub struct LaneGuard<'l> {
136 _held: MutexGuard<'l, ()>,
137 prefix: String,
138}
139
140impl LaneGuard<'_> {
141 /// The prefix of the lane this guard holds.
142 pub fn prefix(&self) -> &str {
143 &self.prefix
144 }
145}
146
147
148/// What [`Lane::append`] answers.
149#[derive(Clone, Copy, Debug, PartialEq, Eq)]
150pub struct Appended {
151 pub seq: u64,
152 pub replay: bool, // the id was already held, so nothing was written
153}
154
155/// One entry as read.
156#[derive(Clone, Debug, PartialEq)]
157pub struct Entry {
158 pub seq: u64,
159 pub exp_ms: Option<u64>,
160 pub val: Dat,
161}
162
163/// One answer of [`Lane::read_after`].
164#[derive(Clone, Debug, PartialEq)]
165pub struct Page {
166 pub entries: Vec<Entry>,
167 pub through: u64, // every sequence up to this one has been answered or is a hole
168 pub more: bool, // entries above `through` were left for the next page
169 pub floor: u64, // the highest sequence trimmed when the page was read
170 pub gap: bool, // `after` was below the floor, so trimmed entries were never answered
171 pub steps: usize, // the slots this read visited (kept ephemerals, entries, holes)
172 pub dropped: u64, // encoded bytes of the expired entries above the floor it deleted
173}
174
175/// The lane's head record as stored.
176#[derive(Clone, Copy, Debug, PartialEq, Eq)]
177struct Meta {
178 head: u64,
179 floor: u64,
180 swept: u64, // every durable entry at or below it is deleted; never above `floor`
181 due: u64, // the earliest expiry among the kept ephemerals, 0 for none
182}
183
184#[derive(Clone, Copy, Debug, PartialEq, Eq)]
185pub enum ReaderState {
186 Live,
187 Dormant, // kept, but out of `stable` until it acknowledges again
188}
189
190#[derive(Clone, Debug, PartialEq, Eq)]
191pub struct Reader {
192 pub name: String,
193 pub cursor: u64,
194 pub state: ReaderState,
195}
196
197/// A lane over a shared database, under its lane's lock. Made for one section and dropped with
198/// it; it holds nothing the store does not.
199#[derive(Debug)]
200pub struct Lane<
201 'a,
202 const UIDL: usize,
203 UID: NumIdDat<UIDL>,
204 ENC: Encrypter,
205 KH: Hasher,
206 DB: Database<UIDL, UID, ENC, KH>,
207> {
208 db: &'a DB,
209 user: UID,
210 prefix: &'a str,
211 phantom: PhantomData<(ENC, KH)>,
212}
213
214impl<
215 'a,
216 const UIDL: usize,
217 UID: NumIdDat<UIDL>,
218 ENC: Encrypter,
219 KH: Hasher,
220 DB: Database<UIDL, UID, ENC, KH>,
221>
222 Lane<'a, UIDL, UID, ENC, KH, DB>
223{
224 /// The guard is the proof of the lane's section, and names the lane: the lane keeps the borrow
225 /// for its life, so the lock outlives every call on it.
226 pub fn new(db: &'a DB, user: UID, guard: &'a LaneGuard<'_>) -> Self {
227 Self {
228 db,
229 user,
230 prefix: guard.prefix(),
231 phantom: PhantomData,
232 }
233 }
234
235 /// The last sequence handed out, 0 for a lane never appended to.
236 pub fn head(&self) -> Outcome<u64> {
237 Ok(res!(self.meta()).head)
238 }
239
240 /// The highest sequence trimmed; reads start above it.
241 pub fn floor(&self) -> Outcome<u64> {
242 Ok(res!(self.meta()).floor)
243 }
244
245 /// The sequences above the floor, entries and holes alike: an upper bound on the entries held.
246 pub fn depth(&self) -> Outcome<u64> {
247 let m = res!(self.meta());
248 Ok(m.head - m.floor)
249 }
250
251 /// Appends `val` at the next sequence. With an `id` the lane already holds, nothing is written
252 /// and the held entry's sequence is answered, so a replayed append does not double. Held means
253 /// the entry the id record names still carries that id: after a crash between the id write and
254 /// the head write, the next append takes that sequence, and the dangling record is not held. The
255 /// id is
256 /// forgotten with its entry, so an append replayed after its entry was trimmed, removed or
257 /// expired appends anew. `exp_ms` is the millisecond the entry stops reading, on whatever clock
258 /// the caller passes to [`read_after`](Self::read_after).
259 pub fn append(&self, val: Dat, id: Option<&[u8]>, exp_ms: Option<u64>) -> Outcome<Appended> {
260 if val.byte_len().is_none() {
261 return Err(err!(
262 "lane {}: a value whose encoded length cannot be measured (an arbitrary-precision \
263 number) cannot be paged by bytes.", self.prefix;
264 Invalid, Input));
265 }
266 if let Some(id) = id {
267 if let Some(seq) = res!(self.id_seq(id)) {
268 if let Some((_, Some(held), _)) = res!(self.entry_at(seq)) {
269 if held.as_slice() == id {
270 return Ok(Appended { seq, replay: true });
271 }
272 }
273 }
274 }
275 let mut m = res!(self.meta());
276 let seq = match m.head.checked_add(1) {
277 Some(s) => s,
278 None => return Err(err!("lane {}: the sequence is spent.", self.prefix; Overflow)),
279 };
280 let stored = Dat::List(vec![
281 Dat::U64(exp_ms.unwrap_or(0)),
282 match id {
283 Some(b) => Dat::bytdat(b.to_vec()),
284 None => Dat::Empty,
285 },
286 val,
287 ]);
288 // The entry before the head, so a reader never sees a head whose entry is not yet written.
289 res!(self.db.insert(self.entry_key(seq), stored, self.user, None));
290 if let Some(id) = id {
291 res!(self.db.insert(self.id_key(id), Dat::U64(seq), self.user, None));
292 }
293 m.head = seq;
294 res!(self.put_meta(&m));
295 Ok(Appended { seq, replay: false })
296 }
297
298 /// Entries above `after` in sequence order, stopping before the one that would carry the page
299 /// over `max_bytes` of encoded values (a first entry larger than that is still answered, so a
300 /// reader is never stuck), or once `max_steps` slots have been visited, holes and expired
301 /// entries counting as entries do; either way `more` is set and `through` is the last slot
302 /// visited, so the next page goes on from there. Holes are skipped. An entry whose `exp_ms` is at or before `now_ms`
303 /// reads absent and is deleted, for every reader, so `now_ms` must be the gateway's receipt
304 /// clock, the one `exp_ms` was set on, never a device's. A cursor below the floor is answered
305 /// the live ephemerals between it and the floor, then on above the floor, with `gap` set: the
306 /// durable entries between were trimmed and the reader must re-base.
307 pub fn read_after(
308 &self,
309 after: u64,
310 max_bytes: usize,
311 max_steps: usize,
312 now_ms: u64,
313 )
314 -> Outcome<Page>
315 {
316 self.read_after_measured(after, max_bytes, max_steps, now_ms, |v| v.byte_len())
317 }
318
319 /// As [`read_after`](Self::read_after), with each entry's size taken from `measure` rather
320 /// than its encoded length, so a caller can page by what it will send (a wire form) rather
321 /// than by what is stored. `None` from `measure` is an error.
322 ///
323 /// Below the floor only ephemerals read: first the kept ones above `after` (a step each),
324 /// then the slots the sweep has not reached, then on above the floor.
325 pub fn read_after_measured<F: Fn(&Dat) -> Option<usize>>(
326 &self,
327 after: u64,
328 max_bytes: usize,
329 max_steps: usize,
330 now_ms: u64,
331 measure: F,
332 )
333 -> Outcome<Page>
334 {
335 let m = res!(self.meta());
336 let mut through = after.min(m.head);
337 let mut entries = Vec::new();
338 let mut used = 0usize;
339 let mut more = false;
340 let mut steps = 0usize;
341 let mut dropped = 0u64;
342 // The kept ephemerals at or below `swept`: nothing else there is held.
343 if through < m.swept {
344 for (k, _) in res!(self.kept()) {
345 if k <= through {
346 continue;
347 }
348 if steps >= max_steps {
349 more = true;
350 break;
351 }
352 steps += 1;
353 if let Some((Some(exp), _, val)) = res!(self.entry_at(k)) {
354 // An expired one is left to the sweep, which drops it from the list.
355 if exp > now_ms {
356 let size = match measure(&val) {
357 Some(n) => n,
358 None => return Err(err!(
359 "lane {}: entry {} cannot be measured.", self.prefix, k;
360 Invalid, Input)),
361 };
362 if !entries.is_empty() && used.saturating_add(size) > max_bytes {
363 more = true;
364 break;
365 }
366 used = used.saturating_add(size);
367 entries.push(Entry { seq: k, exp_ms: Some(exp), val });
368 }
369 }
370 through = k;
371 }
372 if !more {
373 through = m.swept;
374 }
375 }
376 let mut seq = through;
377 while !more && seq < m.head {
378 if steps >= max_steps {
379 more = true;
380 break;
381 }
382 steps += 1;
383 seq += 1;
384 let (exp_ms, id, val) = match res!(self.entry_at(seq)) {
385 Some(e) => e,
386 None => {
387 through = seq;
388 continue;
389 },
390 };
391 match exp_ms {
392 // Trimmed: the sweep deletes it.
393 None if seq <= m.floor => {
394 through = seq;
395 continue;
396 },
397 Some(exp) if exp <= now_ms => {
398 if seq > m.floor {
399 dropped = dropped.saturating_add(val.byte_len().unwrap_or(0) as u64);
400 }
401 res!(self.drop_entry(seq, id.as_deref()));
402 through = seq;
403 continue;
404 },
405 _ => (),
406 }
407 let size = match measure(&val) {
408 Some(n) => n,
409 None => return Err(err!(
410 "lane {}: entry {} cannot be measured.", self.prefix, seq;
411 Invalid, Input)),
412 };
413 if !entries.is_empty() && used.saturating_add(size) > max_bytes {
414 more = true;
415 break;
416 }
417 used = used.saturating_add(size);
418 entries.push(Entry { seq, exp_ms, val });
419 through = seq;
420 }
421 Ok(Page { entries, through, more, floor: m.floor, gap: after < m.floor, steps, dropped })
422 }
423
424 /// Deletes the entry at `seq`, leaving a hole reads skip. Answers whether there was one.
425 pub fn remove(&self, seq: u64) -> Outcome<bool> {
426 match res!(self.entry_at(seq)) {
427 Some((_, id, _)) => {
428 res!(self.drop_entry(seq, id.as_deref()));
429 Ok(true)
430 },
431 None => Ok(false),
432 }
433 }
434
435 /// Raises the floor to `seq` (never above the head, never lower), in one write: every durable
436 /// entry up to it reads absent from now on, and every ephemeral one stays readable, at its own
437 /// sequence, until it expires. Deletes nothing; [`sweep_trimmed`](Self::sweep_trimmed) does,
438 /// in bounded steps. Answers the floor.
439 pub fn trim_through(&self, seq: u64) -> Outcome<u64> {
440 let mut m = res!(self.meta());
441 let to = seq.min(m.head);
442 if to <= m.floor {
443 return Ok(m.floor);
444 }
445 m.floor = to;
446 res!(self.put_meta(&m));
447 Ok(to)
448 }
449
450 /// Whether [`sweep_trimmed`](Self::sweep_trimmed) has work by `now_ms`: trimmed slots not yet
451 /// deleted, or a kept ephemeral past its expiry. One read.
452 pub fn trim_pending(&self, now_ms: u64) -> Outcome<bool> {
453 let m = res!(self.meta());
454 Ok(m.swept < m.floor || (m.due != 0 && m.due <= now_ms))
455 }
456
457 /// One bounded step of the trim's deletion: drops the kept ephemerals expired by `now_ms`,
458 /// then walks on from where the last step stopped towards the floor, deleting each durable
459 /// and expired entry and listing each live ephemeral, visiting at most `max_steps` slots in
460 /// all. Answers whether work is left ([`trim_pending`](Self::trim_pending)).
461 pub fn sweep_trimmed(&self, max_steps: usize, now_ms: u64) -> Outcome<bool> {
462 let mut m = res!(self.meta());
463 let expired = m.due != 0 && m.due <= now_ms;
464 if !expired && m.swept >= m.floor {
465 return Ok(false);
466 }
467 let was = m;
468 let mut steps = 0usize;
469 let mut kept = Vec::new();
470 let mut listed = false;
471 if expired {
472 let all = res!(self.kept());
473 let n = all.len();
474 for (k, exp) in all {
475 if exp <= now_ms && steps < max_steps {
476 steps += 1;
477 if let Some((_, id, _)) = res!(self.entry_at(k)) {
478 res!(self.drop_entry(k, id.as_deref()));
479 }
480 } else {
481 kept.push((k, exp));
482 }
483 }
484 listed = kept.len() != n;
485 } else {
486 kept = res!(self.kept());
487 }
488 while m.swept < m.floor && steps < max_steps {
489 steps += 1;
490 let s = m.swept + 1;
491 if let Some((exp, id, _)) = res!(self.entry_at(s)) {
492 match exp {
493 Some(e) if e > now_ms => {
494 kept.push((s, e));
495 listed = true;
496 },
497 _ => res!(self.drop_entry(s, id.as_deref())),
498 }
499 }
500 m.swept = s;
501 }
502 m.due = kept.iter().map(|(_, e)| *e).min().unwrap_or(0);
503 // The list before the head record that counts it, so a cut-short step leaves every
504 // kept ephemeral listed (one listed twice at worst, which reads skip).
505 if listed {
506 res!(self.put_kept(&kept));
507 }
508 if m != was {
509 res!(self.put_meta(&m));
510 }
511 Ok(m.swept < m.floor || (m.due != 0 && m.due <= now_ms))
512 }
513
514 /// Records that `name` has read through `cursor` (held at the head), and marks it live. A
515 /// cursor may move back, for a reader starting over. Writes only when the cursor or the state
516 /// changes, so a reader acknowledging where it already stands costs no write. Answers the
517 /// cursor kept.
518 pub fn ack(&self, name: &str, cursor: u64) -> Outcome<u64> {
519 let head = res!(self.head());
520 let cursor = cursor.min(head);
521 let mut rs = res!(self.readers());
522 match rs.iter_mut().find(|r| r.name == name) {
523 Some(r) => {
524 if r.cursor == cursor && r.state == ReaderState::Live {
525 return Ok(cursor);
526 }
527 r.cursor = cursor;
528 r.state = ReaderState::Live;
529 },
530 None => rs.push(Reader {
531 name: name.to_string(),
532 cursor,
533 state: ReaderState::Live,
534 }),
535 }
536 res!(self.put_readers(&rs));
537 Ok(cursor)
538 }
539
540 /// Takes `name` out of `stable` until it acknowledges again, keeping its cursor. Answers
541 /// whether the lane knew it.
542 pub fn set_dormant(&self, name: &str) -> Outcome<bool> {
543 let mut rs = res!(self.readers());
544 let found = match rs.iter_mut().find(|r| r.name == name) {
545 Some(r) => {
546 r.state = ReaderState::Dormant;
547 true
548 },
549 None => false,
550 };
551 if found {
552 res!(self.put_readers(&rs));
553 }
554 Ok(found)
555 }
556
557 /// Forgets `name` and its cursor. Answers whether the lane knew it.
558 pub fn forget(&self, name: &str) -> Outcome<bool> {
559 let mut rs = res!(self.readers());
560 let n = rs.len();
561 rs.retain(|r| r.name != name);
562 if rs.len() == n {
563 return Ok(false);
564 }
565 res!(self.put_readers(&rs));
566 Ok(true)
567 }
568
569 /// Every reader the lane knows, live and dormant, in name order.
570 pub fn readers(&self) -> Outcome<Vec<Reader>> {
571 let m = match res!(self.db.get(&self.readers_key(), None)) {
572 Some((Dat::Map(m), _)) => m,
573 Some((d, _)) => return Err(err!(
574 "lane {}: the reader table is a {:?}, not a map.", self.prefix, d.kind();
575 Invalid, Input, Mismatch)),
576 None => return Ok(Vec::new()),
577 };
578 let mut rs = Vec::with_capacity(m.len());
579 for (k, v) in m.iter() {
580 let name = match k {
581 Dat::Str(s) => s.clone(),
582 _ => return Err(err!(
583 "lane {}: a reader is named by a {:?}, not a string.", self.prefix, k.kind();
584 Invalid, Input, Mismatch)),
585 };
586 let (cursor, live) = match v {
587 Dat::List(l) if l.len() == 2 => match (number(&l[0]), &l[1]) {
588 (Some(c), Dat::Bool(b)) => (c, *b),
589 _ => return Err(err!(
590 "lane {}: reader '{}' holds {:?}.", self.prefix, name, v;
591 Invalid, Input, Mismatch)),
592 },
593 _ => return Err(err!(
594 "lane {}: reader '{}' holds {:?}.", self.prefix, name, v;
595 Invalid, Input, Mismatch)),
596 };
597 rs.push(Reader {
598 name,
599 cursor,
600 state: if live { ReaderState::Live } else { ReaderState::Dormant },
601 });
602 }
603 rs.sort_by(|a, b| a.name.cmp(&b.name));
604 Ok(rs)
605 }
606
607 /// The least cursor over live readers: every live reader has read through it. The head when no
608 /// reader is live. Never above the head.
609 pub fn stable(&self) -> Outcome<u64> {
610 let head = res!(self.head());
611 let least = res!(self.readers()).iter()
612 .filter(|r| r.state == ReaderState::Live)
613 .map(|r| r.cursor)
614 .min();
615 Ok(least.unwrap_or(head).min(head))
616 }
617
618 // ── Keys and stored forms ──────────────────────────────────────────────────
619
620 fn meta_key(&self) -> Dat { dat!(fmt!("{}/m", self.prefix)) }
621 fn readers_key(&self) -> Dat { dat!(fmt!("{}/r", self.prefix)) }
622 fn entry_key(&self, seq: u64) -> Dat { dat!(fmt!("{}/e/{}", self.prefix, seq)) }
623
624 fn id_key(&self, id: &[u8]) -> Dat {
625 let mut s = String::with_capacity(self.prefix.len() + 3 + 2 * id.len());
626 s.push_str(&self.prefix);
627 s.push_str("/i/");
628 for b in id {
629 s.push_str(&fmt!("{:02x}", b));
630 }
631 dat!(s)
632 }
633
634 fn kept_key(&self) -> Dat { dat!(fmt!("{}/k", self.prefix)) }
635
636 // `[head, floor]` is a lane no trim has swept since: swept at the floor, nothing kept.
637 fn meta(&self) -> Outcome<Meta> {
638 let bad = |d: &dyn std::fmt::Debug| err!("lane {}: the head record holds {:?}.", self.prefix, d;
639 Invalid, Input, Mismatch);
640 match res!(self.db.get(&self.meta_key(), None)) {
641 None => Ok(Meta { head: 0, floor: 0, swept: 0, due: 0 }),
642 Some((Dat::List(l), _)) => {
643 let n: Vec<Option<u64>> = l.iter().map(number).collect();
644 let m = match n.as_slice() {
645 [Some(h), Some(f)] => Meta { head: *h, floor: *f, swept: *f, due: 0 },
646 [Some(h), Some(f), Some(s), Some(d)] => Meta { head: *h, floor: *f, swept: *s, due: *d },
647 _ => return Err(bad(&l)),
648 };
649 if m.floor > m.head || m.swept > m.floor {
650 return Err(bad(&l));
651 }
652 Ok(m)
653 },
654 Some((d, _)) => Err(bad(&d)),
655 }
656 }
657
658 fn put_meta(&self, m: &Meta) -> Outcome<()> {
659 let v = Dat::List(vec![Dat::U64(m.head), Dat::U64(m.floor), Dat::U64(m.swept), Dat::U64(m.due)]);
660 res!(self.db.insert(self.meta_key(), v, self.user, None));
661 Ok(())
662 }
663
664 // The kept ephemerals, `(seq, exp_ms)` in sequence order.
665 fn kept(&self) -> Outcome<Vec<(u64, u64)>> {
666 let l = match res!(self.db.get(&self.kept_key(), None)) {
667 None => return Ok(Vec::new()),
668 Some((Dat::List(l), _)) => l,
669 Some((d, _)) => return Err(err!(
670 "lane {}: the kept list is a {:?}.", self.prefix, d.kind();
671 Invalid, Input, Mismatch)),
672 };
673 let mut out = Vec::with_capacity(l.len());
674 for d in &l {
675 match d {
676 Dat::List(p) if p.len() == 2 => match (number(&p[0]), number(&p[1])) {
677 (Some(k), Some(e)) => out.push((k, e)),
678 _ => return Err(err!(
679 "lane {}: a kept entry holds {:?}.", self.prefix, p;
680 Invalid, Input, Mismatch)),
681 },
682 _ => return Err(err!("lane {}: a kept entry holds {:?}.", self.prefix, d;
683 Invalid, Input, Mismatch)),
684 }
685 }
686 out.sort();
687 out.dedup();
688 Ok(out)
689 }
690
691 fn put_kept(&self, kept: &[(u64, u64)]) -> Outcome<()> {
692 if kept.is_empty() {
693 res!(self.db.delete(&self.kept_key(), self.user, None));
694 return Ok(());
695 }
696 let v = Dat::List(kept.iter()
697 .map(|(k, e)| Dat::List(vec![Dat::U64(*k), Dat::U64(*e)]))
698 .collect());
699 res!(self.db.insert(self.kept_key(), v, self.user, None));
700 Ok(())
701 }
702
703 fn put_readers(&self, rs: &[Reader]) -> Outcome<()> {
704 let mut m = DaticleMap::new();
705 for r in rs {
706 m.insert(
707 Dat::Str(r.name.clone()),
708 Dat::List(vec![Dat::U64(r.cursor), Dat::Bool(r.state == ReaderState::Live)]),
709 );
710 }
711 res!(self.db.insert(self.readers_key(), Dat::Map(m), self.user, None));
712 Ok(())
713 }
714
715 fn id_seq(&self, id: &[u8]) -> Outcome<Option<u64>> {
716 match res!(self.db.get(&self.id_key(id), None)) {
717 None => Ok(None),
718 Some((d, _)) => match number(&d) {
719 Some(n) => Ok(Some(n)),
720 None => Err(err!("lane {}: an id record holds {:?}.", self.prefix, d;
721 Invalid, Input, Mismatch)),
722 },
723 }
724 }
725
726 // The stored entry at `seq` as (expiry, id, value), or `None` for a hole.
727 fn entry_at(&self, seq: u64) -> Outcome<Option<(Option<u64>, Option<Vec<u8>>, Dat)>> {
728 let l = match res!(self.db.get(&self.entry_key(seq), None)) {
729 None => return Ok(None),
730 Some((Dat::List(l), _)) if l.len() == 3 => l,
731 Some((d, _)) => return Err(err!(
732 "lane {}: entry {} holds {:?}.", self.prefix, seq, d.kind();
733 Invalid, Input, Mismatch)),
734 };
735 let mut it = l.into_iter();
736 let (exp, id, val) = match (it.next(), it.next(), it.next()) {
737 (Some(e), Some(i), Some(v)) => (e, i, v),
738 _ => return Err(err!(
739 "lane {}: entry {} is short.", self.prefix, seq;
740 Invalid, Input, Mismatch)),
741 };
742 let exp = match number(&exp) {
743 Some(0) => None,
744 Some(n) => Some(n),
745 None => return Err(err!("lane {}: entry {} has expiry {:?}.", self.prefix, seq, exp;
746 Invalid, Input, Mismatch)),
747 };
748 let id = match id {
749 Dat::Empty => None,
750 Dat::BU8(b) |
751 Dat::BU16(b) |
752 Dat::BU32(b) |
753 Dat::BU64(b) |
754 Dat::BC64(b) => Some(b),
755 d => return Err(err!("lane {}: entry {} has id {:?}.", self.prefix, seq, d;
756 Invalid, Input, Mismatch)),
757 };
758 Ok(Some((exp, id, val)))
759 }
760
761 fn drop_entry(&self, seq: u64, id: Option<&[u8]>) -> Outcome<()> {
762 if let Some(id) = id {
763 // Only when it still names this entry; a later append may have taken the id.
764 if res!(self.id_seq(id)) == Some(seq) {
765 res!(self.db.delete(&self.id_key(id), self.user, None));
766 }
767 }
768 res!(self.db.delete(&self.entry_key(seq), self.user, None));
769 Ok(())
770 }
771}
772
773// A stored count, however narrowly the decoder typed it.
774fn number(d: &Dat) -> Option<u64> {
775 match d {
776 Dat::U64(x) => Some(*x),
777 Dat::U32(x) => Some(*x as u64),
778 Dat::U16(x) => Some(*x as u64),
779 Dat::U8(x) => Some(*x as u64),
780 Dat::C64(x) => Some(*x),
781 _ => None,
782 }
783}