salamander/view/
mod.rs

1//! docs/phase-1.5.md §3 — the query layer.
2//!
3//! The core idea (§3): **an index is just another deterministic fold over
4//! the log.** Instead of constructing a projection on demand and handing
5//! back a snapshot (Phase 1's model), the DB *owns* registered **views**
6//! and fans every appended event out to them synchronously, so a query
7//! never sees a stale view (INV-2). Because a view is a fold, it inherits
8//! every guarantee the log already has: INV-1 and the crash harness cover
9//! it, and `log/` still interprets nothing.
10//!
11//! This module defines the object-safe [`View`] trait the registry drives,
12//! and [`IndexedView`] — the batteries-included queryable view with
13//! secondary indexes (`get`/`range`/`prefix`/`by`). The registry itself
14//! (`register`/`deregister`/`view`/fan-out) lives on [`crate::Salamander`].
15
16use std::any::Any;
17
18use crate::event::{Body, Event};
19use crate::log::Log;
20use crate::projection::decode_stored_event;
21use crate::Result;
22
23pub mod indexed;
24
25pub use indexed::{Change, IndexedView};
26
27/// The universal secondary-index key type (query-layer design OQ-Q1). One
28/// byte-vector key type per view keeps the generics ergonomic and is the
29/// natural serialized form once Phase 2 snapshots indexes to disk.
30pub type IndexKey = Vec<u8>;
31
32/// A live view the DB drives **type-erased**, as `dyn View<B>`.
33///
34/// Deliberately **object-safe** — no associated types, no `Self`-returning
35/// methods — which is exactly why it is *not* `: Projection`. `Projection`
36/// has `type State` and `state(&self) -> &Self::State`, and an associated
37/// type makes `dyn Projection` impossible. A `View` carries only what the
38/// registry needs to *drive* it (`apply`/`cursor`) and *downcast* it
39/// (`as_any`); the query methods live on the concrete type, reached after
40/// downcast via [`crate::Salamander::view`].
41///
42/// `IndexedView` implements **both** `View` (so the registry can store it
43/// as `dyn View`) and `Projection` (so `replay_into`/`view_at` still build
44/// it on demand for time-travel). A concrete type implementing two traits
45/// is fine; only the *stored* form is erased.
46pub trait View<B>: Any {
47    /// Fold one event into the view. Same determinism contract as
48    /// `Projection::apply` (query-layer design §6, INV-2).
49    fn apply(&mut self, event: &Event<B>);
50
51    /// All events with offset < cursor have been applied.
52    fn cursor(&self) -> u64;
53
54    /// Upcast to `dyn Any` so the registry can downcast to the concrete
55    /// view type on query. (`Box<dyn View<B>>` is not automatically
56    /// `dyn Any`; this is the standard bridge.)
57    fn as_any(&self) -> &dyn Any;
58}
59
60/// Fold `log[view.cursor(), upto)` into a type-erased view — the
61/// object-safe sibling of `replay_into` (which needs the non-object-safe
62/// `Projection`). Both walk the same loop; they differ only in what they
63/// can be called on. Used by `register` to catch a freshly-registered view
64/// up to head before it starts receiving live fan-out.
65pub(crate) fn catch_up<B: Body>(view: &mut dyn View<B>, log: &Log, upto: u64) -> Result<()> {
66    for item in log.records_from(view.cursor()) {
67        let record = item?;
68        if record.position >= upto {
69            break;
70        }
71        let event = decode_stored_event::<B>(&record)?;
72        view.apply(&event);
73    }
74    Ok(())
75}
salamander/view/mod.rs

salamander/view/
mod.rs
