@lossless.org/client 1.6.0 → 1.8.0

package/ts/nosqldb/classes.session.ts

@@ -1,8 +1,17 @@
 import * as plugins from './plugins.js';
 
 import type { SmartdataDb } from './classes.db.js';
+import {
+  SmartdataOperationDeadline,
+  requireOperationSignal,
+  requireOperationTimeoutMS,
+} from './classes.operationdeadline.js';
+import { assertDataOptions } from './classes.operationbudget.js';
 import {
   SmartdataPersistenceError,
+  createSmartdataTimeoutError,
+  isMongoDeadlineError,
+  normalizeDeadlineError,
   normalizeOrdinaryPersistenceError,
 } from './classes.persistence.js';
 
@@ -16,6 +25,10 @@ interface ISmartdataSessionBinding {
   transactionActive: boolean;
   transactionCallbackOpen: boolean;
   transactionUsesOrdinaryWrite: boolean;
+  /** Set while a transaction with a client deadline runs; it bounds every operation inside. */
+  transactionTimeoutMS?: number;
+  /** Set while a transaction with a signal runs; every operation inside observes it. */
+  transactionSignal?: AbortSignal;
   transactionAttempt?: symbol;
   transactionFailure?: { error: unknown };
   operationSettled?: Promise<void>;
@@ -47,6 +60,28 @@ interface IOrdinarySessionOperationOptions {
   prepared?: boolean;
   /** Names the collection whose preparation a refusal must ask for. */
   collectionName?: string;
+  /** The caller's validated client deadline for the call's database work. */
+  timeoutMS?: number;
+  /** The API's own default deadline; a transaction deadline replaces it. */
+  defaultTimeoutMS?: number;
+  /** The caller's validated cancellation signal for the call's database work. */
+  signal?: AbortSignal;
+}
+
+export interface ISmartdataTransactionOptions {
+  /**
+   * Client deadline for the whole transaction (1..120000 ms): every attempt,
+   * the operations the callback runs on the session, the driver's retries and
+   * the commit. Operations inside take no `timeoutMS` of their own.
+   */
+  timeoutMS?: number;
+  /**
+   * Cancels the transaction. Every operation the callback runs on the session
+   * observes it: the one in flight is interrupted and every later one is
+   * refused with the abort reason. An aborted transaction is rolled back and
+   * never committed; a commit already sent runs to its own outcome.
+   */
+  signal?: AbortSignal;
 }
 
 const transactionContext = new plugins.nodeAsyncHooks.AsyncLocalStorage<
@@ -82,6 +117,19 @@ const resolveBinding = (
   return binding;
 };
 
+const normalizeTransactionOptions = (
+  optionsArg: ISmartdataTransactionOptions | undefined,
+): { timeoutMS?: number; signal?: AbortSignal } => {
+  if (optionsArg === undefined) {
+    return {};
+  }
+  const { timeoutMS, signal } = assertDataOptions(optionsArg, ['timeoutMS', 'signal']);
+  return {
+    timeoutMS: requireOperationTimeoutMS(timeoutMS, 'SmartData transaction timeoutMS'),
+    signal: requireOperationSignal(signal, 'SmartData transaction signal'),
+  };
+};
+
 const assertTransactionSucceeded = (bindingArg: ISmartdataSessionBinding): void => {
   if (bindingArg.transactionFailure) {
     throw bindingArg.transactionFailure.error;
@@ -89,8 +137,35 @@ const assertTransactionSucceeded = (bindingArg: ISmartdataSessionBinding): void
 };
 
 export class SmartdataSession {
+  /**
+   * Runs `callbackArg` in a transaction, retrying it as the driver decides.
+   *
+   * `timeoutMS` bounds the whole transaction through the driver's client-side
+   * operation timeout. When it expires the call rejects with a
+   * `SmartdataPersistenceError` of code `timeout`: before the commit was sent
+   * nothing was committed, during the commit the outcome is unknown. When the
+   * deadline expires inside the callback, the driver's closing
+   * `abortTransaction` runs on a fresh deadline of the same length, so a
+   * stalled database settles the call within about twice `timeoutMS`.
+   *
+   * `signal` cancels the transaction. An abort before the call rejects with
+   * the abort reason at once. An abort while the callback runs interrupts the
+   * operation in flight on the session and refuses every later one with the
+   * reason; once the callback has settled, the driver's `abortTransaction`
+   * rolls the attempt back and the call rejects with the reason, even when
+   * the callback caught it, and no further attempt starts. The driver cannot
+   * cancel a commit in flight, so an abort that arrives after the commit was
+   * sent leaves the commit to its own outcome: the call returns the result
+   * when it committed, and rejects with `timeout` ("the commit outcome is
+   * unknown") when the deadline expired during it.
+   *
+   * 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.
+   */
   public async withTransaction<TResult>(
     callbackArg: (sessionArg: SmartdataSession) => Promise<TResult>,
+    optionsArg?: ISmartdataTransactionOptions,
   ): Promise<TResult | undefined> {
     if (typeof callbackArg !== 'function') {
       throw new SmartdataPersistenceError(
@@ -98,6 +173,7 @@ export class SmartdataSession {
         'SmartData transaction callback must be a function.',
       );
     }
+    const { timeoutMS, signal } = normalizeTransactionOptions(optionsArg);
     const binding = resolveBinding(this);
     if (binding.operationActive || binding.transactionActive) {
       throw new SmartdataPersistenceError(
@@ -105,52 +181,76 @@ export class SmartdataSession {
         'Parallel or nested SmartData session operations are not supported.',
       );
     }
+    signal?.throwIfAborted();
     binding.transactionActive = true;
+    binding.transactionTimeoutMS = timeoutMS;
+    binding.transactionSignal = signal;
     let callbackError: unknown;
-    try {
-      return await binding.rawSession.withTransaction(async () => {
-        const attempt = Symbol('smartdataTransactionAttempt');
-        binding.transactionAttempt = attempt;
-        binding.transactionCallbackOpen = true;
-        binding.transactionUsesOrdinaryWrite = false;
-        binding.transactionFailure = undefined;
-        callbackError = undefined;
+    let commitReached = false;
+    const runAttempt = async () => {
+      const attempt = Symbol('smartdataTransactionAttempt');
+      binding.transactionAttempt = attempt;
+      binding.transactionCallbackOpen = true;
+      binding.transactionUsesOrdinaryWrite = false;
+      binding.transactionFailure = undefined;
+      callbackError = undefined;
+      commitReached = false;
+      try {
+        let result: TResult;
+        let callbackReturned = false;
         try {
-          let callbackReturned = false;
-          try {
-            const result = await transactionContext.run(
-              { contextToken: binding.contextToken, attempt },
-              async () => callbackArg(this),
+          // A retry the driver starts after an abort ends before the callback.
+          signal?.throwIfAborted();
+          result = await transactionContext.run(
+            { contextToken: binding.contextToken, attempt },
+            async () => callbackArg(this),
+          );
+          callbackReturned = true;
+        } finally {
+          const activeOperation = binding.operationActive
+            ? binding.operationSettled
+            : undefined;
+          binding.transactionCallbackOpen = false;
+          if (binding.transactionAttempt === attempt) {
+            binding.transactionAttempt = undefined;
+          }
+          if (activeOperation) {
+            await activeOperation;
+          }
+          assertTransactionSucceeded(binding);
+          if (callbackReturned && activeOperation) {
+            throw new SmartdataPersistenceError(
+              'unsupported_operation',
+              'A SmartData transaction callback returned with an operation still active.',
             );
-            callbackReturned = true;
-            return result;
-          } finally {
-            const activeOperation = binding.operationActive
-              ? binding.operationSettled
-              : undefined;
-            binding.transactionCallbackOpen = false;
-            if (binding.transactionAttempt === attempt) {
-              binding.transactionAttempt = undefined;
-            }
-            if (activeOperation) {
-              await activeOperation;
-            }
-            assertTransactionSucceeded(binding);
-            if (callbackReturned && activeOperation) {
-              throw new SmartdataPersistenceError(
-                'unsupported_operation',
-                'A SmartData transaction callback returned with an operation still active.',
-              );
-            }
           }
-        } catch (errorArg) {
-          callbackError = errorArg;
-          throw errorArg;
         }
-      });
+        // 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;
+        return result;
+      } catch (errorArg) {
+        callbackError = errorArg;
+        throw errorArg;
+      }
+    };
+    try {
+      return timeoutMS === undefined
+        ? await binding.rawSession.withTransaction(runAttempt)
+        : await binding.rawSession.withTransaction(runAttempt, { timeoutMS });
     } catch (errorArg) {
       if (errorArg === callbackError) {
-        throw errorArg;
+        throw normalizeDeadlineError(errorArg);
+      }
+      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,
+        );
       }
       if (binding.transactionUsesOrdinaryWrite) {
         return normalizeOrdinaryPersistenceError(
@@ -161,6 +261,8 @@ export class SmartdataSession {
       throw errorArg;
     } finally {
       binding.transactionActive = false;
+      binding.transactionTimeoutMS = undefined;
+      binding.transactionSignal = undefined;
       binding.transactionUsesOrdinaryWrite = false;
       binding.transactionFailure = undefined;
     }
@@ -220,6 +322,15 @@ export const acquireSmartdataSession = (
   release: () => void;
 } => {
   const binding = resolveBinding(sessionArg, ownerArg);
+  if (
+    binding.transactionActive
+    && binding.transactionSignal?.aborted
+    && transactionContext.getStore()?.contextToken === binding.contextToken
+  ) {
+    // The transaction was cancelled: the attempt fails with the abort reason.
+    binding.transactionFailure ??= { error: binding.transactionSignal.reason };
+    throw binding.transactionSignal.reason;
+  }
   if (binding.transactionFailure) {
     throw new SmartdataPersistenceError(
       'unsupported_operation',
@@ -361,17 +472,88 @@ export const leaseOrdinarySmartdataSession = (
   });
 };
 
+/**
+ * The deadline and signal one operation runs under. Inside an owned
+ * transaction with a deadline, the transaction's deadline bounds the
+ * operation through the session, and the driver refuses a second one on the
+ * same session, so an explicit operation deadline is refused and a default
+ * one is dropped. Inside an owned transaction with a signal, the operation
+ * observes that signal beside its own.
+ */
+export const resolveSmartdataOperationDeadline = (
+  sessionArg: TSmartdataOrdinarySession | undefined,
+  optionsArg: Pick<IOrdinarySessionOperationOptions, 'timeoutMS' | 'defaultTimeoutMS' | 'signal'>,
+): SmartdataOperationDeadline => {
+  const binding = isSmartdataSession(sessionArg) ? bindings.get(sessionArg) : undefined;
+  const transactionSignal = binding?.transactionActive ? binding.transactionSignal : undefined;
+  const signals = [optionsArg.signal, transactionSignal].filter(
+    (signalArg): signalArg is AbortSignal => signalArg !== undefined,
+  );
+  const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
+  if (binding?.transactionTimeoutMS !== undefined) {
+    if (optionsArg.timeoutMS !== undefined) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        'The SmartData transaction deadline bounds every operation inside it; omit the operation timeoutMS.',
+      );
+    }
+    return signal === undefined
+      ? SmartdataOperationDeadline.unbounded
+      : new SmartdataOperationDeadline(undefined, signal);
+  }
+  const timeoutMS = optionsArg.timeoutMS ?? optionsArg.defaultTimeoutMS;
+  return timeoutMS === undefined && signal === undefined
+    ? SmartdataOperationDeadline.unbounded
+    : new SmartdataOperationDeadline(timeoutMS, signal);
+};
+
+/**
+ * The error one operation on the session boundary rejects with: an expired
+ * driver deadline becomes the `timeout` persistence error, everything else
+ * passes through. An operation its deadline or signal interrupted inside an
+ * owned transaction also fails the transaction attempt, so `withTransaction`
+ * rolls it back and rejects with that error even when the callback caught it:
+ * whatever the interrupted command did inside the transaction is unknown.
+ */
+export const settleSmartdataOperationError = (
+  sessionArg: TSmartdataOrdinarySession | undefined,
+  deadlineArg: SmartdataOperationDeadline,
+  errorArg: unknown,
+): unknown => {
+  const error = normalizeDeadlineError(errorArg);
+  const binding = isSmartdataSession(sessionArg) ? bindings.get(sessionArg) : undefined;
+  const aborted = deadlineArg.signal?.aborted === true && errorArg === deadlineArg.signal.reason;
+  const expired = error instanceof SmartdataPersistenceError && error.code === 'timeout';
+  if (binding?.transactionActive && (aborted || expired)) {
+    binding.transactionFailure ??= { error };
+  }
+  return error;
+};
+
+/**
+ * Runs one model operation on the ordinary session boundary: the owned
+ * session lease, the operation's client deadline and signal, and the mapping
+ * of an expired driver deadline to the `timeout` persistence error.
+ */
 export const runWithOrdinarySmartdataSession = async <TResult>(
   sessionArg: TSmartdataOrdinarySession | undefined,
   ownerArg: SmartdataDb,
   optionsArg: IOrdinarySessionOperationOptions,
   operationArg: (
     rawSessionArg: plugins.mongodb.ClientSession | undefined,
+    deadlineArg: SmartdataOperationDeadline,
   ) => Promise<TResult>,
 ): Promise<TResult> => {
+  optionsArg.signal?.throwIfAborted();
   const lease = leaseOrdinarySmartdataSession(sessionArg, ownerArg, optionsArg);
+  let deadline: SmartdataOperationDeadline | undefined;
   try {
-    return await operationArg(lease.rawSession);
+    deadline = resolveSmartdataOperationDeadline(sessionArg, optionsArg);
+    return await operationArg(lease.rawSession, deadline);
+  } catch (errorArg) {
+    throw deadline
+      ? settleSmartdataOperationError(sessionArg, deadline, errorArg)
+      : normalizeDeadlineError(errorArg);
   } finally {
     lease.release();
   }