@lossless.org/client 1.11.0 → 1.13.0

package/ts/nosqldb/classes.session.ts

@@ -11,6 +11,7 @@ import {
   SmartdataPersistenceError,
   createSmartdataTimeoutError,
   isMongoDeadlineError,
+  isMongoTransientTransactionError,
   normalizeDeadlineError,
   normalizeOrdinaryPersistenceError,
 } from './classes.persistence.js';
@@ -31,12 +32,75 @@ interface ISmartdataSessionBinding {
   transactionSignal?: AbortSignal;
   transactionAttempt?: symbol;
   transactionFailure?: { error: unknown };
+  /** Set once the current attempt's callback returned and the driver moves on to commit. */
+  transactionCommitReached: boolean;
+  /** Set when the session ended while a transaction ran, stating how far the transaction had got. */
+  transactionEnded?: TSmartdataTransactionEnd;
   operationSettled?: Promise<void>;
   resolveOperationSettled?: () => void;
   invalidated: boolean;
   closing?: Promise<void>;
 }
 
+/** How far a transaction had got when its session ended outside the callback's control. */
+type TSmartdataTransactionEnd = 'before_commit' | 'during_commit';
+
+/**
+ * Whether a transaction that `SmartdataSession.withTransaction()` rejected
+ * could have committed:
+ *
+ * - `not_committed`: nothing of the transaction was committed. The call failed
+ *   before the driver sent a commit, or the database answered the commit with
+ *   an error that states the transaction was aborted.
+ * - `unknown`: a commit was sent and its outcome was never confirmed; it may
+ *   have applied.
+ */
+export type TSmartdataTransactionCommitOutcome = 'not_committed' | 'unknown';
+
+/** The commit outcome of every value a `withTransaction()` call rejected with. */
+const transactionCommitOutcomes = new WeakMap<object, TSmartdataTransactionCommitOutcome>();
+
+/**
+ * Records what `errorArg`, the rejection of a `withTransaction()` call, means
+ * for the commit, and returns it for the throw. A value several transactions
+ * rejected with keeps `unknown` once any of them may have committed. A
+ * primitive cannot be recorded.
+ */
+const rejectTransaction = (
+  errorArg: unknown,
+  outcomeArg: TSmartdataTransactionCommitOutcome,
+): unknown => {
+  if (
+    ((typeof errorArg === 'object' && errorArg !== null) || typeof errorArg === 'function')
+    && transactionCommitOutcomes.get(errorArg) !== 'unknown'
+  ) {
+    transactionCommitOutcomes.set(errorArg, outcomeArg);
+  }
+  return errorArg;
+};
+
+const commitOutcomeOfTransactionEnd = (
+  endArg: TSmartdataTransactionEnd,
+): TSmartdataTransactionCommitOutcome =>
+  endArg === 'during_commit' ? 'unknown' : 'not_committed';
+
+/**
+ * The session of a transaction ended while it ran, for example through the
+ * database's `close()`. The driver then returns the callback's result without
+ * committing, so the call must reject instead.
+ */
+const createTransactionSessionEndedError = (
+  endArg: TSmartdataTransactionEnd,
+  causeArg?: unknown,
+): SmartdataPersistenceError =>
+  new SmartdataPersistenceError(
+    'unsupported_operation',
+    endArg === 'during_commit'
+      ? 'SmartData transaction session ended during commit; the commit outcome is unknown.'
+      : 'SmartData transaction session ended before commit; nothing was committed.',
+    causeArg === undefined ? undefined : { cause: causeArg },
+  );
+
 const bindings = new WeakMap<SmartdataSession, ISmartdataSessionBinding>();
 const bindingsByOwner = new WeakMap<SmartdataDb, Set<ISmartdataSessionBinding>>();
 const smartdataSessionInvalidationAggregateBrand = Symbol(
@@ -130,6 +194,30 @@ const normalizeTransactionOptions = (
   };
 };
 
+/** Everything `withTransaction()` refuses before a transaction starts. */
+const admitTransaction = (
+  sessionArg: SmartdataSession,
+  callbackArg: unknown,
+  optionsArg: ISmartdataTransactionOptions | undefined,
+): { binding: ISmartdataSessionBinding; timeoutMS?: number; signal?: AbortSignal } => {
+  if (typeof callbackArg !== 'function') {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      'SmartData transaction callback must be a function.',
+    );
+  }
+  const { timeoutMS, signal } = normalizeTransactionOptions(optionsArg);
+  const binding = resolveBinding(sessionArg);
+  if (binding.operationActive || binding.transactionActive) {
+    throw new SmartdataPersistenceError(
+      'unsupported_operation',
+      'Parallel or nested SmartData session operations are not supported.',
+    );
+  }
+  signal?.throwIfAborted();
+  return { binding, timeoutMS, signal };
+};
+
 const assertTransactionSucceeded = (bindingArg: ISmartdataSessionBinding): void => {
   if (bindingArg.transactionFailure) {
     throw bindingArg.transactionFailure.error;
@@ -137,6 +225,25 @@ const assertTransactionSucceeded = (bindingArg: ISmartdataSessionBinding): void
 };
 
 export class SmartdataSession {
+  /**
+   * Whether the transaction whose `withTransaction()` call rejected with
+   * `errorArg` could have committed: `not_committed` when nothing of it was
+   * committed, `unknown` when a commit was sent and never confirmed, so it may
+   * have applied. Every rejection of `withTransaction()` carries one, whatever
+   * it is: the client's own errors, the callback's error, the abort reason or
+   * a driver error, which all keep their identity. A value several calls
+   * rejected with reads `unknown` once any of them may have committed.
+   *
+   * Returns `undefined` for any other value, and for a primitive rejection —
+   * a callback that throws a string, or a string abort reason — which cannot
+   * carry the outcome; treat `undefined` as `unknown`.
+   */
+  public static getCommitOutcome(errorArg: unknown): TSmartdataTransactionCommitOutcome | undefined {
+    return (typeof errorArg === 'object' && errorArg !== null) || typeof errorArg === 'function'
+      ? transactionCommitOutcomes.get(errorArg)
+      : undefined;
+  }
+
   /**
    * Runs `callbackArg` in a transaction, retrying it as the driver decides.
    *
@@ -162,42 +269,50 @@ export class SmartdataSession {
    * Any operation on the session that its deadline or a signal interrupts
    * fails the attempt: the call rolls it back and rejects with that
    * operation's error even when the callback caught it.
+   *
+   * When the session ends while the call runs — the database's `close()`
+   * ends every session — the call never reports a commit. It rejects with
+   * `unsupported_operation`: before the callback returned nothing was
+   * committed, afterwards the commit outcome is unknown. The callback's
+   * error, if it threw, is the `cause`.
+   *
+   * Every rejection states whether the transaction could have committed:
+   * `SmartdataSession.getCommitOutcome(error)` returns `not_committed` or
+   * `unknown` for the value the call rejected with.
    */
   public async withTransaction<TResult>(
     callbackArg: (sessionArg: SmartdataSession) => Promise<TResult>,
     optionsArg?: ISmartdataTransactionOptions,
   ): Promise<TResult | undefined> {
-    if (typeof callbackArg !== 'function') {
-      throw new SmartdataPersistenceError(
-        'invalid_argument',
-        'SmartData transaction callback must be a function.',
-      );
-    }
-    const { timeoutMS, signal } = normalizeTransactionOptions(optionsArg);
-    const binding = resolveBinding(this);
-    if (binding.operationActive || binding.transactionActive) {
-      throw new SmartdataPersistenceError(
-        'unsupported_operation',
-        'Parallel or nested SmartData session operations are not supported.',
-      );
+    let admitted: ReturnType<typeof admitTransaction>;
+    try {
+      admitted = admitTransaction(this, callbackArg, optionsArg);
+    } catch (errorArg) {
+      throw rejectTransaction(errorArg, 'not_committed');
     }
-    signal?.throwIfAborted();
+    const { binding, timeoutMS, signal } = admitted;
     binding.transactionActive = true;
     binding.transactionTimeoutMS = timeoutMS;
     binding.transactionSignal = signal;
+    binding.transactionEnded = undefined;
     let callbackError: unknown;
-    let commitReached = false;
+    /** The signal or deadline interruption that failed the last attempt. */
+    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;
     const runAttempt = async () => {
       const attempt = Symbol('smartdataTransactionAttempt');
       binding.transactionAttempt = attempt;
       binding.transactionCallbackOpen = true;
       binding.transactionUsesOrdinaryWrite = false;
       binding.transactionFailure = undefined;
+      binding.transactionCommitReached = false;
       callbackError = undefined;
-      commitReached = false;
+      attemptInterruption = undefined;
       try {
         let result: TResult;
         let callbackReturned = false;
+        let callbackThrown: { error: unknown } | undefined;
         try {
           // A retry the driver starts after an abort ends before the callback.
           signal?.throwIfAborted();
@@ -206,6 +321,9 @@ export class SmartdataSession {
             async () => callbackArg(this),
           );
           callbackReturned = true;
+        } catch (errorArg) {
+          callbackThrown = { error: errorArg };
+          throw errorArg;
         } finally {
           const activeOperation = binding.operationActive
             ? binding.operationSettled
@@ -217,7 +335,20 @@ export class SmartdataSession {
           if (activeOperation) {
             await activeOperation;
           }
+          attemptInterruption = binding.transactionFailure;
           assertTransactionSucceeded(binding);
+          if (binding.transactionEnded) {
+            // The driver would commit or return the result on a session that is
+            // being ended; the attempt fails instead, keeping the callback's error.
+            sessionEnded = {
+              error: createTransactionSessionEndedError(
+                binding.transactionEnded,
+                callbackThrown?.error,
+              ),
+              end: binding.transactionEnded,
+            };
+            throw sessionEnded.error;
+          }
           if (callbackReturned && activeOperation) {
             throw new SmartdataPersistenceError(
               'unsupported_operation',
@@ -227,45 +358,107 @@ export class SmartdataSession {
         }
         // An abort that arrived while the callback ran rolls the attempt back.
         signal?.throwIfAborted();
-        // The driver commits next; a deadline that expires from here on
-        // leaves the commit outcome unknown.
-        commitReached = true;
+        // The driver commits next; a deadline that expires or a session that
+        // ends from here on leaves the commit outcome unknown.
+        binding.transactionCommitReached = true;
         return result;
       } catch (errorArg) {
         callbackError = errorArg;
+        if (signal?.aborted && errorArg === signal.reason) {
+          attemptInterruption ??= { error: errorArg };
+        }
         throw errorArg;
       }
     };
-    try {
-      return timeoutMS === undefined
-        ? await binding.rawSession.withTransaction(runAttempt)
-        : await binding.rawSession.withTransaction(runAttempt, { timeoutMS });
-    } catch (errorArg) {
+    /**
+     * What the call rejects with when the driver's `withTransaction()` rejected
+     * with `errorArg`, and whether the transaction could have committed. Once
+     * the last attempt's callback returned, the driver was committing: every
+     * error from there on leaves the commit outcome unknown, unless it states
+     * that the transaction was aborted. The driver starts another attempt only
+     * after such an error, so an earlier attempt never committed.
+     */
+    const settleTransactionRejection = (
+      errorArg: unknown,
+    ): { error: unknown; outcome: TSmartdataTransactionCommitOutcome } => {
+      // The driver's closing abort replaces the attempt's error when it finds
+      // the transaction already aborted, as a session that close() ended leaves
+      // it; the interruption that failed the attempt keeps its rejection.
+      if (attemptInterruption) {
+        return { error: normalizeDeadlineError(attemptInterruption.error), outcome: 'not_committed' };
+      }
+      if (sessionEnded) {
+        return { error: sessionEnded.error, outcome: commitOutcomeOfTransactionEnd(sessionEnded.end) };
+      }
+      if (
+        binding.transactionEnded
+        && errorArg !== signal?.reason
+        && !isMongoDeadlineError(errorArg)
+        && !(errorArg instanceof SmartdataPersistenceError && errorArg.code === 'timeout')
+      ) {
+        return {
+          error: createTransactionSessionEndedError(binding.transactionEnded, errorArg),
+          outcome: commitOutcomeOfTransactionEnd(binding.transactionEnded),
+        };
+      }
       if (errorArg === callbackError) {
-        throw normalizeDeadlineError(errorArg);
+        return { error: normalizeDeadlineError(errorArg), outcome: 'not_committed' };
       }
+      const outcome: TSmartdataTransactionCommitOutcome =
+        binding.transactionCommitReached && !isMongoTransientTransactionError(errorArg)
+          ? 'unknown'
+          : 'not_committed';
       if (isMongoDeadlineError(errorArg)) {
-        throw createSmartdataTimeoutError(
-          commitReached
-            ? 'SmartData transaction exceeded its client deadline during commit; the commit outcome is unknown.'
-            : 'SmartData transaction exceeded its client deadline before commit; nothing was committed.',
-          errorArg,
-        );
+        return {
+          error: createSmartdataTimeoutError(
+            outcome === 'unknown'
+              ? 'SmartData transaction exceeded its client deadline during commit; the commit outcome is unknown.'
+              : binding.transactionCommitReached
+                ? 'SmartData transaction exceeded its client deadline after the database aborted its commit; nothing was committed.'
+                : 'SmartData transaction exceeded its client deadline before commit; nothing was committed.',
+            errorArg,
+          ),
+          outcome,
+        };
       }
       if (binding.transactionUsesOrdinaryWrite) {
-        return normalizeOrdinaryPersistenceError(
-          errorArg,
-          'SmartData transaction conflicts with a unique index.',
-        );
+        try {
+          normalizeOrdinaryPersistenceError(
+            errorArg,
+            'SmartData transaction conflicts with a unique index.',
+          );
+        } catch (normalizedArg) {
+          return { error: normalizedArg, outcome };
+        }
       }
-      throw errorArg;
+      return { error: errorArg, outcome };
+    };
+    let result: TResult | undefined;
+    let transactionEnded: TSmartdataTransactionEnd | undefined;
+    try {
+      result = timeoutMS === undefined
+        ? await binding.rawSession.withTransaction(runAttempt)
+        : await binding.rawSession.withTransaction(runAttempt, { timeoutMS });
+      transactionEnded = binding.transactionEnded;
+    } catch (errorArg) {
+      const { error, outcome } = settleTransactionRejection(errorArg);
+      throw rejectTransaction(error, outcome);
     } finally {
       binding.transactionActive = false;
       binding.transactionTimeoutMS = undefined;
       binding.transactionSignal = undefined;
       binding.transactionUsesOrdinaryWrite = false;
       binding.transactionFailure = undefined;
+      binding.transactionCommitReached = false;
+      binding.transactionEnded = undefined;
     }
+    if (transactionEnded) {
+      throw rejectTransaction(
+        createTransactionSessionEndedError(transactionEnded),
+        commitOutcomeOfTransactionEnd(transactionEnded),
+      );
+    }
+    return result;
   }
 
   public async close(): Promise<void> {
@@ -301,6 +494,7 @@ export const createSmartdataSession = (ownerArg: SmartdataDb): SmartdataSession
     transactionActive: false,
     transactionCallbackOpen: false,
     transactionUsesOrdinaryWrite: false,
+    transactionCommitReached: false,
     invalidated: false,
   };
   bindings.set(session, binding);
@@ -559,8 +753,13 @@ export const runWithOrdinarySmartdataSession = async <TResult>(
   }
 };
 
+/**
+ * Ends every session of the owner. `endOptionsArg.timeoutMS` is the driver's
+ * deadline for aborting a transaction a session still holds.
+ */
 export const invalidateSmartdataSessions = async (
   ownerArg: SmartdataDb,
+  endOptionsArg?: Pick<plugins.mongodb.EndSessionOptions, 'timeoutMS'>,
 ): Promise<void> => {
   const ownerBindings = bindingsByOwner.get(ownerArg);
   if (!ownerBindings) {
@@ -568,11 +767,11 @@ export const invalidateSmartdataSessions = async (
   }
   const sessions = [...ownerBindings];
   for (const bindingArg of sessions) {
-    bindingArg.invalidated = true;
+    invalidateSessionBinding(bindingArg);
   }
   const results = await Promise.allSettled(
     sessions.map((bindingArg) =>
-      closeSessionBinding(bindingArg),
+      closeSessionBinding(bindingArg, endOptionsArg),
     ),
   );
   const errors = results.flatMap((resultArg) =>
@@ -589,12 +788,28 @@ export const invalidateSmartdataSessions = async (
   }
 };
 
+/**
+ * Refuses every later operation on the session. A transaction still running on
+ * it records how far it had got, so it rejects instead of reporting a commit.
+ */
+const invalidateSessionBinding = (bindingArg: ISmartdataSessionBinding): void => {
+  bindingArg.invalidated = true;
+  if (bindingArg.transactionActive) {
+    bindingArg.transactionEnded ??= bindingArg.transactionCommitReached
+      ? 'during_commit'
+      : 'before_commit';
+  }
+};
+
 /** Failed cleanup remains owned and invalidated until an explicit retry succeeds. */
-const closeSessionBinding = async (bindingArg: ISmartdataSessionBinding): Promise<void> => {
+const closeSessionBinding = async (
+  bindingArg: ISmartdataSessionBinding,
+  endOptionsArg?: Pick<plugins.mongodb.EndSessionOptions, 'timeoutMS'>,
+): Promise<void> => {
   if (bindingArg.closing) return bindingArg.closing;
-  bindingArg.invalidated = true;
+  invalidateSessionBinding(bindingArg);
   const closing = Promise.resolve().then(async () => {
-    await bindingArg.rawSession.endSession();
+    await bindingArg.rawSession.endSession(endOptionsArg);
     bindingsByOwner.get(bindingArg.owner)?.delete(bindingArg);
     bindings.delete(bindingArg.session);
   });