@lossless.org/client 1.22.1 → 1.23.0

package/ts/nosqldb/classes.session.ts

@@ -21,9 +21,11 @@ import {
   captureSmartdataWrite,
   hasSmartdataWriteObservers,
   type ISmartdataWrite,
+  type ISmartdataWriteReport,
   type TSmartdataWriteKind,
 } from './classes.writeobserver.js';
 import {
+  accountSmartdataOwnWriteRevisions,
   captureSmartdataCollectionChange,
   captureSmartdataReadChange,
   hasSmartdataReadScope,
@@ -35,12 +37,22 @@ import {
   type ISmartdataReadSpec,
 } from './classes.readtracker.js';
 import {
+  beginSmartdataWriteRevisionCommit,
   flushSmartdataWriteRevisions,
   isSmartdataWriteRevisionsActive,
+  noteSmartdataWriteRevisionEntries,
   readPreviousRevisionIds,
   sharedRevisionId,
   writeRevisionsPartitionField,
 } from './classes.writerevisions.js';
+import {
+  deliverSmartdataWriteLogCommit,
+  flushSmartdataWriteLog,
+  isSmartdataWriteLogActive,
+  requiresSmartdataWriteTransactions,
+  writeLogReportOf,
+  type ISmartdataWriteLogCommit,
+} from './classes.writelog.js';
 
 interface ISmartdataSessionBinding {
   session: SmartdataSession;
@@ -70,6 +82,10 @@ interface ISmartdataSessionBinding {
   transactionWrites: ISmartdataTransactionWrite[];
   /** The write-revision counters the current attempt's writes bump right before its commit. */
   revisionBumps: Set<string>;
+  /** The reports of the current attempt's writes, which its write-log entry carries. */
+  logReports: ISmartdataWriteReport[];
+  /** Collections the current attempt changed in ways no report describes. */
+  logUnplaced: Set<string>;
   operationSettled?: Promise<void>;
   resolveOperationSettled?: () => void;
   invalidated: boolean;
@@ -361,7 +377,15 @@ export class SmartdataSession {
     let attemptInterruption: { error: unknown } | undefined;
     /** The session-ended rejection the last attempt failed with, and how far that transaction had got. */
     let sessionEnded: { error: SmartdataPersistenceError; end: TSmartdataTransactionEnd } | undefined;
+    let finishRevisionCommit: (() => void) | undefined;
+    /** The last attempt's write-log entry until the transaction's outcome is known. */
+    let logCommit: ISmartdataWriteLogCommit | undefined;
     const runAttempt = async () => {
+      finishRevisionCommit?.();
+      finishRevisionCommit = undefined;
+      // The driver starts another attempt only once the last one was aborted.
+      logCommit?.settle();
+      logCommit = undefined;
       const attempt = Symbol('smartdataTransactionAttempt');
       binding.transactionAttempt = attempt;
       binding.transactionCallbackOpen = true;
@@ -370,6 +394,8 @@ export class SmartdataSession {
       binding.transactionCommitReached = false;
       binding.transactionWrites = [];
       binding.revisionBumps = new Set();
+      binding.logReports = [];
+      binding.logUnplaced = new Set();
       callbackError = undefined;
       attemptInterruption = undefined;
       try {
@@ -421,16 +447,22 @@ export class SmartdataSession {
         }
         // An abort that arrived while the callback ran rolls the attempt back.
         signal?.throwIfAborted();
-        // The writes' revisions commit with them. A failure fails the attempt
-        // before its commit, and a transient one is retried with it.
+        // The writes' revisions and write-log entry commit with them. A
+        // failure fails the attempt before its commit, and a transient one is
+        // retried with it.
+        const mongoDb = binding.client.db(binding.owner.smartdataOptions.mongoDbName);
         if (binding.revisionBumps.size > 0) {
-          await flushSmartdataWriteRevisions(
-            binding.client.db(binding.owner.smartdataOptions.mongoDbName),
-            binding.rawSession,
-            binding.revisionBumps,
-            signal,
-          );
+          finishRevisionCommit = beginSmartdataWriteRevisionCommit(binding.owner, binding.revisionBumps);
+          await flushSmartdataWriteRevisions(mongoDb, binding.rawSession, binding.revisionBumps, signal);
         }
+        logCommit = await flushSmartdataWriteLog(
+          binding.owner,
+          mongoDb,
+          binding.rawSession,
+          binding.logReports,
+          binding.logUnplaced,
+          signal,
+        );
         // The driver commits next; a deadline that expires or a session that
         // ends from here on leaves the commit outcome unknown.
         binding.transactionCommitReached = true;
@@ -509,17 +541,25 @@ export class SmartdataSession {
     let result: TResult | undefined;
     let transactionEnded: TSmartdataTransactionEnd | undefined;
     let committedWrites: ISmartdataTransactionWrite[] = [];
+    let committedRevisionBumps: ReadonlySet<string> = new Set();
+    let returnedFromCommit = false;
     try {
       result = timeoutMS === undefined
         ? await binding.rawSession.withTransaction(runAttempt)
         : await binding.rawSession.withTransaction(runAttempt, { timeoutMS });
       transactionEnded = binding.transactionEnded;
       committedWrites = binding.transactionWrites;
+      committedRevisionBumps = binding.revisionBumps;
+      returnedFromCommit = true;
     } catch (errorArg) {
       const { error, outcome } = settleTransactionRejection(errorArg);
       if (outcome === 'unknown') changeReadsOfTransaction(binding.transactionWrites);
       throw rejectTransaction(error, outcome);
     } finally {
+      if (!returnedFromCommit) {
+        finishRevisionCommit?.();
+        logCommit?.settle();
+      }
       binding.transactionActive = false;
       binding.transactionTimeoutMS = undefined;
       binding.transactionSignal = undefined;
@@ -529,15 +569,33 @@ export class SmartdataSession {
       binding.transactionEnded = undefined;
       binding.transactionWrites = [];
       binding.revisionBumps = new Set();
+      binding.logReports = [];
+      binding.logUnplaced = new Set();
     }
-    if (transactionEnded) {
-      const outcome = commitOutcomeOfTransactionEnd(transactionEnded);
-      if (outcome === 'unknown') changeReadsOfTransaction(committedWrites);
-      throw rejectTransaction(createTransactionSessionEndedError(transactionEnded), outcome);
-    }
-    changeReadsOfTransaction(committedWrites);
-    for (const write of committedWrites) {
-      write.deliver?.();
+    try {
+      if (transactionEnded) {
+        const outcome = commitOutcomeOfTransactionEnd(transactionEnded);
+        try {
+          if (outcome === 'unknown') changeReadsOfTransaction(committedWrites);
+        } finally {
+          finishRevisionCommit?.();
+        }
+        throw rejectTransaction(createTransactionSessionEndedError(transactionEnded), outcome);
+      }
+      try {
+        changeReadsOfTransaction(committedWrites);
+        accountSmartdataOwnWriteRevisions(binding.owner, committedRevisionBumps);
+      } finally {
+        finishRevisionCommit?.();
+      }
+      noteSmartdataWriteRevisionEntries(binding.owner, committedRevisionBumps);
+      for (const write of committedWrites) {
+        write.deliver?.();
+      }
+      // Followers hear of the commit before they may read it from the journal.
+      if (logCommit) deliverSmartdataWriteLogCommit(binding.owner, logCommit);
+    } finally {
+      logCommit?.settle();
     }
     return result;
   }
@@ -578,6 +636,8 @@ export const createSmartdataSession = (ownerArg: SmartdataDb): SmartdataSession
     transactionCommitReached: false,
     transactionWrites: [],
     revisionBumps: new Set(),
+    logReports: [],
+    logUnplaced: new Set(),
     invalidated: false,
   };
   bindings.set(session, binding);
@@ -834,18 +894,19 @@ const revisionTransactionSessionOf = (ownerArg: SmartdataDb): SmartdataSession |
 
 /**
  * Whether a write must start a transaction of its own to carry its write
- * revisions: the database keeps them and the write runs outside an owned
- * transaction. A raw driver session cannot carry them and is refused.
+ * revisions and write-log entry: the database keeps either and the write runs
+ * outside an owned transaction. A raw driver session cannot carry them and is
+ * refused.
  */
-export const needsSmartdataRevisionTransaction = (
+export const needsSmartdataWriteTransaction = (
   sessionArg: TSmartdataOrdinarySession | undefined,
   ownerArg: SmartdataDb,
 ): boolean => {
-  if (!isSmartdataWriteRevisionsActive(ownerArg)) return false;
+  if (!requiresSmartdataWriteTransactions(ownerArg)) return false;
   if (sessionArg !== undefined && !isSmartdataSession(sessionArg)) {
     throw new SmartdataPersistenceError(
       'unsupported_operation',
-      'Writes of a database with write revisions run on sessions of db.createSession(), not raw driver sessions.',
+      'Writes of a database with write revisions or a write log run on sessions of db.createSession(), not raw driver sessions.',
     );
   }
   return sessionArg === undefined || !resolveBinding(sessionArg, ownerArg).transactionActive;
@@ -860,13 +921,13 @@ const transactionOptionsOf = (
 });
 
 /**
- * Runs one write of a database with write revisions in a transaction, so its
- * revisions commit with it: on the caller's owned session, or on a session of
+ * Runs one write of a database with write revisions or a write log in a
+ * transaction, so its revisions and entry commit with it: on the caller's owned session, or on a session of
  * its own that ends with the call. The call's deadline and signal bound the
  * whole transaction; the collection is prepared before it starts, since its
  * DDL cannot run inside.
  */
-export const runSmartdataRevisionTransaction = async <TResult>(
+export const runSmartdataWriteTransaction = async <TResult>(
   sessionArg: SmartdataSession | undefined,
   ownerArg: SmartdataDb,
   optionsArg: Pick<
@@ -916,8 +977,8 @@ export const runWithOrdinarySmartdataSession = async <TResult>(
   ) => Promise<TResult>,
 ): Promise<TResult> => {
   optionsArg.signal?.throwIfAborted();
-  if (optionsArg.ordinaryWrite && needsSmartdataRevisionTransaction(sessionArg, ownerArg)) {
-    return runSmartdataRevisionTransaction(
+  if (optionsArg.ordinaryWrite && needsSmartdataWriteTransaction(sessionArg, ownerArg)) {
+    return runSmartdataWriteTransaction(
       sessionArg as SmartdataSession | undefined,
       ownerArg,
       optionsArg,
@@ -965,6 +1026,21 @@ const bufferTransactionWrite = (
   }
 };
 
+/**
+ * Adds a write's report, or a collection no report describes, to the
+ * write-log entry of an owned transaction's current attempt. A write that
+ * settles after its attempt ended rolls back with that attempt.
+ */
+const logTransactionWrite = (
+  bindingArg: ISmartdataSessionBinding,
+  writeArg: { report: ISmartdataWriteReport } | { unplaced: string },
+): void => {
+  const attempt = transactionContext.getStore()?.attempt;
+  if (attempt === undefined || attempt !== bindingArg.transactionAttempt) return;
+  if ('report' in writeArg) bindingArg.logReports.push(writeArg.report);
+  else bindingArg.logUnplaced.add(writeArg.unplaced);
+};
+
 /**
  * Adds write-revision counters to the current attempt of an owned transaction.
  * A write that settles after its attempt ended rolls back with that attempt.
@@ -1026,6 +1102,8 @@ export const reportSmartdataWrite = (
     if (field !== undefined && isSmartdataWriteRevisionsActive(ownerArg)) {
       bumpTransactionRevisions(binding, writeRevisionIdsOfWrite(writeArg, field));
     }
+    const report = writeLogReportOf(ownerArg, writeArg);
+    if (report) logTransactionWrite(binding, { report });
   }
   const changeReads = captureSmartdataReadChange(ownerArg, writeArg, buffered);
   const deliver = captureSmartdataWrite(ownerArg, writeArg);
@@ -1054,6 +1132,9 @@ export const reportSmartdataWriteFailure = (
   if (binding && buffered && isSmartdataWriteRevisionsActive(ownerArg)) {
     bumpTransactionRevisions(binding, [sharedRevisionId(collectionNameArg)]);
   }
+  if (binding && buffered && isSmartdataWriteLogActive(ownerArg)) {
+    logTransactionWrite(binding, { unplaced: collectionNameArg });
+  }
   const changeReads = captureSmartdataCollectionChange(ownerArg, collectionNameArg, buffered);
   if (!changeReads) return;
   if (binding && buffered) {