Skip to main content

durable/
session.rs

1//! The Session: one serialized mutation line over a [`Storage`], the loaded-document cache, and committed
2//! publication.
3//!
4//! Port of `packages/durable/src/session/session.ts` and the Session errors of `errors.ts`.
5//!
6//! Differences from upstream:
7//! - Synchronous. Commits, cold reads and close run on a FIFO ticket line, so they settle in admission order exactly
8//!   as upstream's promise chain does; a cached snapshot is served off the line. A Session is `Send + Sync` and
9//!   clones share it.
10//! - No `Context`: there are no context values to carry to listeners and no abort signals; a commit admitted to the
11//!   line always runs.
12//! - No document watches or document states (`watch`, `documentState`): commit listeners see every change.
13//! - Commit callbacks are synchronous, so a callback cannot settle with Tx operations still pending and the Tx
14//!   cannot be used after it settles (the borrow ends); escaped drafts are revoked.
15//! - Storage writes own copies of document values; published values are shared (`Arc`) with snapshots.
16
17use crate::documents::{
18    Doc, DocDefinition, Owner, check_record_scope, check_record_version, materialize_document, resolve_address,
19};
20use crate::transaction::{Tx, TxScope};
21use crate::{
22    ConversationId, DocumentAddress, DocumentCopySource, DocumentPoint, DocumentRecord, Seq, Storage, StorageError,
23    StorageWrite,
24};
25use chord_delta::{DeltaError, Op, Tracker};
26use serde_json::Value;
27use std::collections::HashMap;
28use std::fmt;
29use std::sync::{Arc, Condvar, Mutex, MutexGuard};
30
31/// A Session operation failure. `name()` is the upstream error class name.
32#[derive(Clone, Debug, PartialEq)]
33pub enum SessionError {
34    /// The Session failed, so nothing runs or commits any more; holds the first error (upstream `SessionFailed`).
35    Failed(Box<SessionError>),
36    /// A transaction read a table after its first table write; holds the `Tx` method name.
37    ReadAfterWrite(&'static str),
38    /// A submission reached a busy conversation and was not admitted.
39    Busy(ConversationId),
40    /// The Session is closing or closed.
41    Closed,
42    Storage(StorageError),
43    Delta(DeltaError),
44    /// Upstream `TypeError`.
45    Type(String),
46    /// Upstream plain `Error`, also what a commit callback returns for its own failures.
47    Error(String),
48}
49
50impl SessionError {
51    pub fn name(&self) -> &'static str {
52        match self {
53            SessionError::Failed(_) => "SessionFailed",
54            SessionError::ReadAfterWrite(_) => "ReadAfterWrite",
55            SessionError::Busy(_) => "ConversationBusy",
56            SessionError::Closed | SessionError::Error(_) => "Error",
57            SessionError::Storage(error) => error.name(),
58            SessionError::Delta(error) => error.name(),
59            SessionError::Type(_) => "TypeError",
60        }
61    }
62}
63
64impl fmt::Display for SessionError {
65    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
66        match self {
67            SessionError::Failed(_) => f.write_str("Session failed after a storage error; close and reopen it"),
68            SessionError::ReadAfterWrite(method) => {
69                write!(f, "Tx.{method}() cannot read tables after the first table write")
70            }
71            SessionError::Busy(id) => write!(f, "Conversation {} is busy", id.0),
72            SessionError::Closed => f.write_str("Session is closed"),
73            SessionError::Storage(error) => error.fmt(f),
74            SessionError::Delta(error) => error.fmt(f),
75            SessionError::Type(message) | SessionError::Error(message) => f.write_str(message),
76        }
77    }
78}
79
80impl std::error::Error for SessionError {}
81
82impl From<StorageError> for SessionError {
83    fn from(error: StorageError) -> Self {
84        SessionError::Storage(error)
85    }
86}
87
88impl From<DeltaError> for SessionError {
89    fn from(error: DeltaError) -> Self {
90        SessionError::Delta(error)
91    }
92}
93
94pub type Result<T> = std::result::Result<T, SessionError>;
95
96/// Why a Session ended: `close()`, or a failed Storage call, whose error it carries.
97#[derive(Clone, Debug, PartialEq)]
98pub enum SessionEnd {
99    Closed,
100    Failed(SessionError),
101}
102
103/// One change of a successful commit.
104#[derive(Clone, Debug, PartialEq)]
105#[allow(
106    clippy::large_enum_variant,
107    reason = "short-lived publication value; boxing would only complicate matching"
108)]
109pub enum CommitChange {
110    /// A complete conversation, entry, task, or submission record, as written.
111    Table(StorageWrite),
112    /// A created, changed, or retired incarnation; `value` is `None` and `ops` empty when this commit retired it.
113    Document {
114        record: DocumentRecord,
115        /// Owning conversation; task documents derive it from their task. `None` only for Session documents.
116        conversation_id: Option<ConversationId>,
117        version: Option<u64>,
118        /// `None` once this commit retired it.
119        value: Option<Arc<Value>>,
120        /// Exact operations of an ordinary update; empty for creation and retirement.
121        ops: Vec<Op>,
122    },
123    /// A definition-free fork copy; consumers hydrate through reads or watches.
124    DocumentCopy {
125        record: DocumentRecord,
126        conversation_id: ConversationId,
127        source: DocumentCopySource,
128    },
129}
130
131/// Every change of one successful commit.
132#[derive(Clone, Debug, PartialEq)]
133pub struct CommitPublication {
134    pub seq: Seq,
135    pub changes: Vec<CommitChange>,
136}
137
138/// One committed incarnation in the tracker cache.
139pub(crate) struct LoadedDocument {
140    pub record: DocumentRecord,
141    /// Persisted definition version; older while the tracked value is migrated only in memory.
142    pub stored_version: u64,
143    /// Definition version whose shape the tracked value has; access with another version reloads.
144    pub value_version: u64,
145    /// Stored deltas after the newest base; advanced by adoption.
146    pub deltas_since_base: usize,
147    pub tracker: Tracker,
148}
149
150pub(crate) type Loaded = Arc<Mutex<LoadedDocument>>;
151
152pub(crate) use jsrt::sync::lock;
153
154/// What the line guards: the backend and whether it has been closed.
155pub(crate) struct LineState {
156    storage: Box<dyn Storage + Send>,
157    storage_closed: bool,
158}
159
160/// FIFO mutation line: jobs run one at a time in the order they were admitted.
161struct Line {
162    turn: Mutex<(u64, u64)>,
163    advanced: Condvar,
164    state: Mutex<LineState>,
165}
166
167pub(crate) struct LineGuard<'a> {
168    line: &'a Line,
169    state: Option<MutexGuard<'a, LineState>>,
170}
171
172impl Line {
173    fn enter(&self) -> LineGuard<'_> {
174        let mut turn = lock(&self.turn);
175        let ticket = turn.0;
176        turn.0 += 1;
177        while turn.1 != ticket {
178            turn = self
179                .advanced
180                .wait(turn)
181                .unwrap_or_else(|poisoned| poisoned.into_inner());
182        }
183        drop(turn);
184        LineGuard {
185            line: self,
186            state: Some(lock(&self.state)),
187        }
188    }
189}
190
191impl Drop for LineGuard<'_> {
192    fn drop(&mut self) {
193        self.state.take();
194        lock(&self.line.turn).1 += 1;
195        self.line.advanced.notify_all();
196    }
197}
198
199impl std::ops::Deref for LineGuard<'_> {
200    type Target = LineState;
201    fn deref(&self) -> &LineState {
202        self.state.as_ref().expect("held")
203    }
204}
205
206impl std::ops::DerefMut for LineGuard<'_> {
207    fn deref_mut(&mut self) -> &mut LineState {
208        self.state.as_mut().expect("held")
209    }
210}
211
212type CommitListener = Arc<dyn Fn(&CommitPublication) + Send + Sync>;
213type CloseListener = Arc<dyn Fn() + Send + Sync>;
214
215#[derive(Default)]
216struct Listeners {
217    next: u64,
218    commits: Vec<(u64, CommitListener)>,
219    closes: Vec<(u64, CloseListener)>,
220}
221
222#[derive(Default)]
223struct Status {
224    closing: bool,
225    failure: Option<SessionError>,
226    end: Option<SessionEnd>,
227}
228
229pub(crate) struct Inner {
230    line: Line,
231    pub(crate) documents: Mutex<HashMap<String, Loaded>>,
232    listeners: Mutex<Listeners>,
233    status: Mutex<Status>,
234    ended: Condvar,
235    pub(crate) now: Box<dyn Fn() -> u64 + Send + Sync>,
236}
237
238/// Owner of one mutation line, its records, and its tracked documents.
239#[derive(Clone)]
240pub struct Session {
241    inner: Arc<Inner>,
242}
243
244/// Removes a listener when called; dropping it keeps the listener.
245pub struct Subscription {
246    inner: Arc<Inner>,
247    id: u64,
248}
249
250impl Subscription {
251    pub fn unsubscribe(self) {
252        let mut listeners = lock(&self.inner.listeners);
253        listeners.commits.retain(|(id, _)| *id != self.id);
254        listeners.closes.retain(|(id, _)| *id != self.id);
255    }
256}
257
258fn wall_clock() -> u64 {
259    jsrt::date::now_ms() as u64
260}
261
262impl Session {
263    /// Open a Session over one storage backend. The first error a Storage call returns, other than a
264    /// [`StorageError::Request`] from a read, fails the Session.
265    pub fn new(storage: impl Storage + Send + 'static) -> Session {
266        Session::with_clock(storage, wall_clock)
267    }
268
269    /// `now` is the wall clock (milliseconds) stamped on task lifecycle times.
270    pub fn with_clock(
271        storage: impl Storage + Send + 'static,
272        now: impl Fn() -> u64 + Send + Sync + 'static,
273    ) -> Session {
274        Session {
275            inner: Arc::new(Inner {
276                line: Line {
277                    turn: Mutex::new((0, 0)),
278                    advanced: Condvar::new(),
279                    state: Mutex::new(LineState {
280                        storage: Box::new(storage),
281                        storage_closed: false,
282                    }),
283                },
284                documents: Mutex::new(HashMap::new()),
285                listeners: Mutex::new(Listeners::default()),
286                status: Mutex::new(Status::default()),
287                ended: Condvar::new(),
288                now: Box::new(now),
289            }),
290        }
291    }
292
293    /// Run one atomic transaction on the mutation line. Its changes publish only after Storage acknowledges them.
294    pub fn commit<T>(&self, change: impl FnOnce(&mut Tx<'_>) -> Result<T>) -> Result<T> {
295        self.commit_with(TxScope::default(), change)
296    }
297
298    /// `commit` with defaults: the conversation of `Tx::create_task` and the task stamped on appended entries.
299    pub fn commit_with<T>(&self, scope: TxScope, change: impl FnOnce(&mut Tx<'_>) -> Result<T>) -> Result<T> {
300        self.inner.assert_usable()?;
301        let mut line = self.inner.line.enter();
302        self.inner.assert_healthy()?;
303        let mut tx = Tx::new(&self.inner, &mut line, scope);
304        let result = match change(&mut tx) {
305            Ok(result) => result,
306            Err(error) => {
307                tx.discard();
308                return Err(error);
309            }
310        };
311        // A callback that caught a failed read must not commit, nor succeed as if it had.
312        if let Err(error) = self.inner.assert_healthy() {
313            tx.discard();
314            return Err(error);
315        }
316        let (writes, plans) = tx.settle()?;
317        if writes.is_empty() {
318            return Ok(result);
319        }
320        let tables: Vec<StorageWrite> = writes
321            .iter()
322            .filter(|write| {
323                matches!(
324                    write,
325                    StorageWrite::Conversation { .. }
326                        | StorageWrite::Entry { .. }
327                        | StorageWrite::Task { .. }
328                        | StorageWrite::Submission { .. }
329                )
330            })
331            .cloned()
332            .collect();
333        let seq = self.inner.guard(&mut line, false, |storage| storage.commit(writes))?;
334        let documents = match crate::transaction::adopt(&self.inner, plans, seq) {
335            Ok(documents) => documents,
336            Err(error) => {
337                // Storage already committed; a failed adoption leaves memory behind durable state.
338                self.inner.fail(&mut line, error.clone());
339                return Err(error);
340            }
341        };
342        let mut changes: Vec<CommitChange> = tables.into_iter().map(CommitChange::Table).collect();
343        changes.extend(documents);
344        self.inner.publish(&CommitPublication { seq, changes });
345        Ok(result)
346    }
347
348    /// The committed value of a document; never creates one.
349    pub fn snapshot(&self, doc: &Doc, owner: Owner) -> Result<Option<Arc<Value>>> {
350        self.inner.assert_usable()?;
351        let definition = doc.definition();
352        let resolved = resolve_address(definition, owner)?;
353        let cached = lock(&self.inner.documents).get(&resolved.id).cloned();
354        let loaded = match cached.filter(|loaded| lock(loaded).value_version == definition.version) {
355            Some(loaded) => Some(loaded),
356            None => {
357                let mut line = self.inner.line.enter();
358                self.inner.assert_healthy()?;
359                self.inner
360                    .load(&mut line, definition, &resolved.id, &resolved.address)?
361            }
362        };
363        let Some(loaded) = loaded else { return Ok(None) };
364        let loaded = lock(&loaded);
365        check_record_scope(definition, &loaded.record.identity)?;
366        check_record_version(definition, &loaded.record.identity, loaded.stored_version)?;
367        Ok(Some(loaded.tracker.value().clone()))
368    }
369
370    /// Fail the Session with `error`, the first failure wins: admission ends, close listeners run, every watch ends,
371    /// and Storage closes. Must not be called on the mutation line (from a commit callback or listener).
372    pub fn fail(&self, error: SessionError) {
373        let mut line = self.inner.line.enter();
374        self.inner.fail(&mut line, error);
375    }
376
377    /// Observe complete commits synchronously after adoption, on the committing thread. The listener must not block
378    /// or call Session APIs.
379    pub fn subscribe_commits(
380        &self,
381        listener: impl Fn(&CommitPublication) + Send + Sync + 'static,
382    ) -> Result<Subscription> {
383        self.inner.assert_usable()?;
384        let mut listeners = lock(&self.inner.listeners);
385        listeners.next += 1;
386        let id = listeners.next;
387        listeners.commits.push((id, Arc::new(listener)));
388        Ok(Subscription {
389            inner: self.inner.clone(),
390            id,
391        })
392    }
393
394    /// Observe close synchronously when it begins, also when a failed Storage call closes the Session.
395    pub fn subscribe_close(&self, listener: impl Fn() + Send + Sync + 'static) -> Result<Subscription> {
396        self.inner.assert_usable()?;
397        let mut listeners = lock(&self.inner.listeners);
398        listeners.next += 1;
399        let id = listeners.next;
400        listeners.closes.push((id, Arc::new(listener)));
401        Ok(Subscription {
402            inner: self.inner.clone(),
403            id,
404        })
405    }
406
407    /// Seal admission, settle commits already admitted, then close Storage. Later calls wait for the first.
408    pub fn close(&self) -> Result<()> {
409        let first = {
410            let mut status = lock(&self.inner.status);
411            !std::mem::replace(&mut status.closing, true)
412        };
413        if !first {
414            self.wait_closed();
415            return Ok(());
416        }
417        self.inner.notify_close();
418        let mut line = self.inner.line.enter();
419        lock(&self.inner.listeners).commits.clear();
420        lock(&self.inner.documents).clear();
421        let result = if line.storage_closed {
422            Ok(())
423        } else {
424            line.storage_closed = true;
425            line.storage.close()
426        };
427        let mut status = lock(&self.inner.status);
428        if let Err(error) = &result
429            && status.failure.is_none()
430        {
431            status.failure = Some(SessionError::Storage(error.clone()));
432        }
433        status.end = Some(match &status.failure {
434            None => SessionEnd::Closed,
435            Some(failure) => SessionEnd::Failed(failure.clone()),
436        });
437        self.inner.ended.notify_all();
438        result.map_err(SessionError::Storage)
439    }
440
441    /// Wait until the Session has closed, Storage included: after `close()`, or after the first failed Storage call.
442    pub fn wait_closed(&self) -> SessionEnd {
443        let status = lock(&self.inner.status);
444        let status = self
445            .inner
446            .ended
447            .wait_while(status, |status| status.end.is_none())
448            .unwrap_or_else(|poisoned| poisoned.into_inner());
449        status.end.clone().expect("ended")
450    }
451
452    pub fn failure(&self) -> Option<SessionError> {
453        lock(&self.inner.status).failure.clone()
454    }
455
456    /// Jobs admitted to the mutation line and not yet finished, the running one included. Lets a caller (a test)
457    /// know that a commit or close has queued behind another, instead of guessing with a sleep.
458    pub fn line_len(&self) -> u64 {
459        let turn = lock(&self.inner.line.turn);
460        turn.0 - turn.1
461    }
462}
463
464impl Inner {
465    pub(crate) fn assert_healthy(&self) -> Result<()> {
466        match &lock(&self.status).failure {
467            Some(failure) => Err(SessionError::Failed(Box::new(failure.clone()))),
468            None => Ok(()),
469        }
470    }
471
472    fn assert_usable(&self) -> Result<()> {
473        let status = lock(&self.status);
474        if let Some(failure) = &status.failure {
475            return Err(SessionError::Failed(Box::new(failure.clone())));
476        }
477        if status.closing {
478            return Err(SessionError::Closed);
479        }
480        Ok(())
481    }
482
483    /// Run one backend call under the failure guard. A failed Session refuses the call; an error fails the Session
484    /// unless it is a [`StorageError::Request`] from a read (`read`), which fails only that call.
485    pub(crate) fn guard<T>(
486        &self,
487        line: &mut LineState,
488        read: bool,
489        call: impl FnOnce(&mut dyn Storage) -> crate::Result<T>,
490    ) -> Result<T> {
491        self.assert_healthy()?;
492        if line.storage_closed {
493            return Err(SessionError::Closed);
494        }
495        match call(line.storage.as_mut()) {
496            Ok(value) => Ok(value),
497            Err(error) => {
498                let exempt = read && matches!(error, StorageError::Request(_));
499                if !exempt {
500                    self.fail(line, SessionError::Storage(error.clone()));
501                }
502                Err(SessionError::Storage(error))
503            }
504        }
505    }
506
507    /// Fail the Session with `error`, the first wins: seal admission, run close listeners, end every watch, and close
508    /// Storage. Nothing retries; reopening recovers from what was committed.
509    pub(crate) fn fail(&self, line: &mut LineState, error: SessionError) {
510        {
511            let mut status = lock(&self.status);
512            if status.failure.is_some() {
513                return;
514            }
515            status.failure = Some(error.clone());
516            status.closing = true;
517        }
518        self.notify_close();
519        lock(&self.listeners).commits.clear();
520        lock(&self.documents).clear();
521        if !line.storage_closed {
522            line.storage_closed = true;
523            // A failing backend close is nobody's to see here; the first error stays the cause.
524            let _ = line.storage.close();
525        }
526        lock(&self.status).end = Some(SessionEnd::Failed(error));
527        self.ended.notify_all();
528    }
529
530    /// Run the close listeners once.
531    fn notify_close(&self) {
532        let closes = std::mem::take(&mut lock(&self.listeners).closes);
533        for (_, listener) in closes {
534            listener();
535        }
536    }
537
538    fn publish(&self, publication: &CommitPublication) {
539        let commits = lock(&self.listeners).commits.clone();
540        for (_, listener) in commits {
541            listener(publication);
542        }
543    }
544
545    /// The cached current incarnation, cold-loading and migrating it for this definition version when necessary.
546    pub(crate) fn load(
547        &self,
548        line: &mut LineState,
549        definition: &DocDefinition,
550        address_id: &str,
551        address: &DocumentAddress,
552    ) -> Result<Option<Loaded>> {
553        let cached = lock(&self.documents).get(address_id).cloned();
554        if let Some(cached) = cached {
555            // A tracker serves only definitions of the version its value was materialized for; others reload.
556            if lock(&cached).value_version == definition.version {
557                return Ok(Some(cached));
558            }
559            lock(&self.documents).remove(address_id);
560        }
561        let Some(record) = self.guard(line, true, |storage| {
562            storage.find_document(address, DocumentPoint::Current)
563        })?
564        else {
565            return Ok(None);
566        };
567        let id = record.identity.id;
568        let Some(stored) = self.guard(line, true, |storage| storage.document(id, DocumentPoint::Current))? else {
569            return Err(SessionError::Error(format!(
570                "Current document {} ({}) cannot be read",
571                id.0, record.identity.kind
572            )));
573        };
574        let value = materialize_document(definition, &stored)?;
575        let loaded = Arc::new(Mutex::new(LoadedDocument {
576            record: stored.record,
577            stored_version: stored.version,
578            value_version: definition.version,
579            deltas_since_base: stored.deltas_since_base,
580            tracker: Tracker::new(value),
581        }));
582        lock(&self.documents).insert(address_id.to_owned(), loaded.clone());
583        Ok(Some(loaded))
584    }
585}