Skip to main content

durable/
lib.rs

1//! Pi Durable storage: typed records, the [`Storage`] contract, and [`MemoryStorage`].
2//!
3//! Port of `packages/durable/src/{types,errors}.ts` and `storage/memory-storage.ts` from earendil-works/pi (MIT); the
4//! pinned revision is recorded in `fixtures/storage-conformance.json`. Errors carry the upstream error name and
5//! message. Upstream's SQLite and JSONL file backends are not ported: the product keeps durable records in the
6//! session's format-4 journal (`session-core`'s `durable_store::open`: a MemoryStorage whose commits are
7//! journal records).
8//!
9//! Differences from upstream:
10//! - Storage is synchronous and takes no cancellation context; the Session (phase 3) owns scheduling and cancellation.
11//! - Records are typed, so malformed records fail to deserialize instead of reaching storage, and a
12//!   `document.create` whose content is a delta is rejected at commit (upstream's types forbid it).
13
14mod documents;
15mod memory;
16mod records;
17mod session;
18mod transaction;
19
20pub use documents::{CheckpointInfo, Doc, DocDefinition, DocSemantics, Owner};
21pub use memory::{CommitSink, MemoryStorage, PreparedCommit};
22pub use records::*;
23pub use session::{CommitChange, CommitPublication, Session, SessionEnd, SessionError, Subscription};
24pub use transaction::{
25    ConversationOwnership, EntryDraft, EntryHead, SubmissionCreate, SubmissionSettlement, TaskDefinition, TaskOptions,
26    TaskOwnership, Tx, TxScope,
27};
28
29use serde_json::{Value, json};
30use std::collections::HashMap;
31use std::fmt;
32
33/// A Storage failure. `Request` fails only that read (upstream `StorageRequestError`, no durable effect); every
34/// other error, and any error from `commit` or `mint_id`, is fatal to the Session.
35#[derive(Clone, Debug, PartialEq, Eq)]
36pub enum StorageError {
37    Request(String),
38    Failed(String),
39    /// Persisted durable state is invalid (upstream `JsonlCorruptionError`): a journal record that does not parse.
40    Corrupt(String),
41}
42
43impl StorageError {
44    /// The upstream error class name.
45    pub fn name(&self) -> &'static str {
46        match self {
47            StorageError::Request(_) => "StorageRequestError",
48            StorageError::Failed(_) => "Error",
49            StorageError::Corrupt(_) => "JsonlCorruptionError",
50        }
51    }
52
53    pub fn message(&self) -> &str {
54        match self {
55            StorageError::Request(message) | StorageError::Failed(message) | StorageError::Corrupt(message) => message,
56        }
57    }
58}
59
60impl fmt::Display for StorageError {
61    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
62        f.write_str(self.message())
63    }
64}
65
66impl std::error::Error for StorageError {}
67
68pub type Result<T> = std::result::Result<T, StorageError>;
69
70pub(crate) fn failed<T>(message: impl Into<String>) -> Result<T> {
71    Err(StorageError::Failed(message.into()))
72}
73
74pub(crate) fn request<T>(message: impl Into<String>) -> Result<T> {
75    Err(StorageError::Request(message.into()))
76}
77
78/// Atomic persistence boundary for Session records.
79///
80/// Storage trusts the owning Session for semantically valid records, references, ancestry, and transitions. It
81/// enforces atomicity, the global ID namespace, immutable conversation/entry creation, and document record
82/// consistency; the Session serializes commits. A scan returns at most `limit` items and a cursor when more remain.
83pub trait Storage {
84    /// Atomically persist one batch and return its sequence; later reads observe it.
85    fn commit(&mut self, writes: Vec<StorageWrite>) -> Result<Seq>;
86    /// A fresh ID from the Session-global namespace, greater than every ID minted or stored before, across reopen.
87    fn mint_id(&mut self) -> Result<u64>;
88    fn conversation(&self, id: ConversationId) -> Result<Option<ConversationRecord>>;
89    fn scan_conversations(
90        &self,
91        query: &ConversationQuery,
92        limit: usize,
93        cursor: Option<&Cursor>,
94    ) -> Result<Page<ConversationRecord>>;
95    fn entry(&self, id: EntryId) -> Result<Option<StoredEntry>>;
96    /// One entry only when it is visible through the conversation's fork ancestry.
97    fn visible_entry(&self, conversation_id: ConversationId, id: EntryId) -> Result<Option<StoredEntry>>;
98    /// The newest visible entry with a `head` at or below the optional inclusive cutoff.
99    fn find_latest_head_marker(
100        &self,
101        conversation_id: ConversationId,
102        at_or_before: Option<EntryId>,
103    ) -> Result<Option<EntryRecord>>;
104    fn scan_entries(&self, query: &EntryQuery, limit: usize, cursor: Option<&Cursor>) -> Result<Page<EntryRecord>>;
105    fn task(&self, id: TaskId) -> Result<Option<TaskRecord>>;
106    fn scan_tasks(&self, query: &TaskQuery, limit: usize, cursor: Option<&Cursor>) -> Result<Page<TaskRecord>>;
107    fn submission(&self, id: SubmissionId) -> Result<Option<SubmissionRecord>>;
108    fn scan_submissions(
109        &self,
110        query: &SubmissionQuery,
111        limit: usize,
112        cursor: Option<&Cursor>,
113    ) -> Result<Page<SubmissionRecord>>;
114    fn submission_by_request(
115        &self,
116        conversation_id: ConversationId,
117        request_id: &str,
118    ) -> Result<Option<SubmissionRecord>>;
119    /// The incarnation occupying one exact logical address at the point.
120    fn find_document(&self, address: &DocumentAddress, at: DocumentPoint) -> Result<Option<DocumentRecord>>;
121    /// Materialize one incarnation by ID at the point, without following a replacement at its address.
122    fn document(&self, id: DocumentId, at: DocumentPoint) -> Result<Option<StoredDocument>>;
123    fn scan_documents(
124        &self,
125        query: &DocumentQuery,
126        limit: usize,
127        cursor: Option<&Cursor>,
128    ) -> Result<Page<DocumentRecord>>;
129    /// Release resources; every later operation fails.
130    fn close(&mut self) -> Result<()>;
131}
132
133/// Where a scan starts: its order and the last ID a previous page returned.
134#[derive(Clone, Copy, Debug)]
135pub(crate) struct ScanStart {
136    pub order: ScanOrder,
137    pub after: Option<i64>,
138}
139
140/// A cursor's `after`, which must be a JavaScript safe integer.
141pub(crate) fn cursor_after(cursor: &Cursor) -> Result<Option<i64>> {
142    match cursor.get("after") {
143        None => Ok(None),
144        Some(after) => match after.as_i64() {
145            Some(after) if after.unsigned_abs() <= MAX_SAFE_ID => Ok(Some(after)),
146            _ => request("Invalid storage cursor"),
147        },
148    }
149}
150
151/// Resolve a scan's order and position. A cursor continues in the order it was created with; a different requested
152/// order fails. A cursor without an order continues in the scan's default order.
153pub(crate) fn scan_start(
154    requested: Option<ScanOrder>,
155    cursor: Option<&Cursor>,
156    fallback: ScanOrder,
157) -> Result<ScanStart> {
158    let Some(cursor) = cursor else {
159        return Ok(ScanStart {
160            order: requested.unwrap_or(fallback),
161            after: None,
162        });
163    };
164    let Some(after) = cursor_after(cursor)? else {
165        return request("Invalid storage cursor");
166    };
167    let order = match cursor.get("order") {
168        None => fallback,
169        Some(value) => match serde_json::from_value::<ScanOrder>(value.clone()) {
170            Ok(order) => order,
171            Err(_) => return request("Invalid storage cursor"),
172        },
173    };
174    if let Some(requested) = requested
175        && requested != order
176    {
177        return request(format!(
178            "The cursor continues a {} scan; the query asks for {}",
179            order.as_str(),
180            requested.as_str()
181        ));
182    }
183    Ok(ScanStart {
184        order,
185        after: Some(after),
186    })
187}
188
189/// The continuation of a scan whose last returned item has `id`.
190pub(crate) fn next_cursor(id: u64, order: ScanOrder) -> Cursor {
191    match json!({ "after": id, "order": order.as_str() }) {
192        Value::Object(cursor) => cursor,
193        _ => unreachable!("json! object literal"),
194    }
195}
196
197/// The table that owns an ID in the Session-global namespace.
198#[derive(Clone, Copy, Debug, PartialEq, Eq)]
199pub(crate) enum Table {
200    Conversation,
201    Entry,
202    Task,
203    Submission,
204    Document,
205}
206
207impl Table {
208    pub(crate) fn as_str(self) -> &'static str {
209        match self {
210            Table::Conversation => "conversation",
211            Table::Entry => "entry",
212            Table::Task => "task",
213            Table::Submission => "submission",
214            Table::Document => "document",
215        }
216    }
217}
218
219impl fmt::Display for Table {
220    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
221        f.write_str(self.as_str())
222    }
223}
224
225/// Conversations, entries and documents are created once; tasks and submissions are replaced whole, but never
226/// change table. `existing` looks up the table already owning an ID.
227pub(crate) fn check_global_ids(
228    writes: &[StorageWrite],
229    mut existing: impl FnMut(u64) -> Result<Option<Table>>,
230) -> Result<()> {
231    let mut claimed: HashMap<u64, Table> = HashMap::new();
232    for write in writes {
233        let (table, id) = match write {
234            StorageWrite::Conversation { value } => (Table::Conversation, value.id.0),
235            StorageWrite::Entry { value } => (Table::Entry, value.id.0),
236            StorageWrite::Task { value } => (Table::Task, value.id.0),
237            StorageWrite::Submission { value } => (Table::Submission, value.id.0),
238            StorageWrite::DocumentCreate { record, .. } | StorageWrite::DocumentCopy { record, .. } => {
239                (Table::Document, record.id.0)
240            }
241            StorageWrite::DocumentChange { .. } | StorageWrite::DocumentRetire { .. } => continue,
242        };
243        let existing = existing(id)?;
244        let earlier = claimed.get(&id).copied();
245        if matches!(table, Table::Conversation | Table::Entry | Table::Document) {
246            if let Some(existing) = existing {
247                return failed(format!("ID {id} already belongs to {existing}"));
248            }
249            if earlier.is_some() {
250                return failed(format!("ID {id} is written more than once"));
251            }
252        } else {
253            if let Some(existing) = existing.filter(|existing| *existing != table) {
254                return failed(format!("ID {id} already belongs to {existing}"));
255            }
256            if earlier.is_some_and(|earlier| earlier != table) {
257                return failed(format!("ID {id} is written as two record types"));
258            }
259        }
260        claimed.insert(id, table);
261    }
262    Ok(())
263}
264
265/// Every document command of one commit for one incarnation.
266#[derive(Default)]
267pub(crate) struct DocumentAction {
268    pub create: Option<DocumentCreate>,
269    pub copy: Option<DocumentCopySource>,
270    pub content: Option<DocumentContent>,
271    pub retire: bool,
272}
273
274/// Group document writes by incarnation, in first-write order.
275pub(crate) fn document_actions(writes: &[StorageWrite]) -> Result<Vec<(u64, DocumentAction)>> {
276    let mut actions: Vec<(u64, DocumentAction)> = Vec::new();
277    for write in writes {
278        let id = match write {
279            StorageWrite::DocumentCreate { record, .. } | StorageWrite::DocumentCopy { record, .. } => record.id.0,
280            StorageWrite::DocumentChange { id, .. } | StorageWrite::DocumentRetire { id } => id.0,
281            _ => continue,
282        };
283        let index = match actions.iter().position(|(existing, _)| *existing == id) {
284            Some(index) => index,
285            None => {
286                actions.push((id, DocumentAction::default()));
287                actions.len() - 1
288            }
289        };
290        let action = &mut actions[index].1;
291        let more_than_one = || failed(format!("Document {id} has more than one content command"));
292        match write {
293            StorageWrite::DocumentCreate { record, content } => {
294                if action.create.is_some() || action.content.is_some() || action.copy.is_some() {
295                    return more_than_one();
296                }
297                action.create = Some(record.clone());
298                action.content = Some(content.clone());
299            }
300            StorageWrite::DocumentCopy { record, source } => {
301                if action.create.is_some() || action.content.is_some() || action.copy.is_some() {
302                    return more_than_one();
303                }
304                action.create = Some(record.clone());
305                action.copy = Some(*source);
306            }
307            StorageWrite::DocumentChange { content, .. } => {
308                if action.content.is_some() || action.copy.is_some() {
309                    return more_than_one();
310                }
311                action.content = Some(content.clone());
312            }
313            StorageWrite::DocumentRetire { .. } => {
314                if action.retire {
315                    return failed(format!("Document {id} is retired more than once"));
316                }
317                action.retire = true;
318            }
319            _ => unreachable!("filtered above"),
320        }
321    }
322    Ok(actions)
323}
324
325/// At most `limit` items, and a cursor after the last one when more matched.
326pub(crate) fn page<T>(mut values: Vec<T>, limit: usize, order: ScanOrder, id: impl Fn(&T) -> u64) -> Page<T> {
327    if values.len() <= limit {
328        return Page {
329            items: values,
330            next: None,
331        };
332    }
333    values.truncate(limit);
334    let next = values.last().map(|last| next_cursor(id(last), order));
335    Page { items: values, next }
336}