1use 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#[derive(Clone, Debug, PartialEq)]
33pub enum SessionError {
34 Failed(Box<SessionError>),
36 ReadAfterWrite(&'static str),
38 Busy(ConversationId),
40 Closed,
42 Storage(StorageError),
43 Delta(DeltaError),
44 Type(String),
46 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#[derive(Clone, Debug, PartialEq)]
98pub enum SessionEnd {
99 Closed,
100 Failed(SessionError),
101}
102
103#[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 Table(StorageWrite),
112 Document {
114 record: DocumentRecord,
115 conversation_id: Option<ConversationId>,
117 version: Option<u64>,
118 value: Option<Arc<Value>>,
120 ops: Vec<Op>,
122 },
123 DocumentCopy {
125 record: DocumentRecord,
126 conversation_id: ConversationId,
127 source: DocumentCopySource,
128 },
129}
130
131#[derive(Clone, Debug, PartialEq)]
133pub struct CommitPublication {
134 pub seq: Seq,
135 pub changes: Vec<CommitChange>,
136}
137
138pub(crate) struct LoadedDocument {
140 pub record: DocumentRecord,
141 pub stored_version: u64,
143 pub value_version: u64,
145 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
154pub(crate) struct LineState {
156 storage: Box<dyn Storage + Send>,
157 storage_closed: bool,
158}
159
160struct 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#[derive(Clone)]
240pub struct Session {
241 inner: Arc<Inner>,
242}
243
244pub 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 pub fn new(storage: impl Storage + Send + 'static) -> Session {
266 Session::with_clock(storage, wall_clock)
267 }
268
269 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 pub fn commit<T>(&self, change: impl FnOnce(&mut Tx<'_>) -> Result<T>) -> Result<T> {
295 self.commit_with(TxScope::default(), change)
296 }
297
298 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 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 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 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 pub fn fail(&self, error: SessionError) {
373 let mut line = self.inner.line.enter();
374 self.inner.fail(&mut line, error);
375 }
376
377 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 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 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 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 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 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 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 let _ = line.storage.close();
525 }
526 lock(&self.status).end = Some(SessionEnd::Failed(error));
527 self.ended.notify_all();
528 }
529
530 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 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 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}