@lossless.org/client 1.23.3 → 2.1.0

package/ts/nosqldb/classes.session.ts

@@ -11,6 +11,7 @@ import {
 import { assertDataOptions } from './classes.operationbudget.js';
 import {
   SmartdataPersistenceError,
+  SmartdataTransactionConflictError,
   createSmartdataTimeoutError,
   isMongoDeadlineError,
   isMongoTransientTransactionError,
@@ -355,6 +356,14 @@ export class SmartdataSession {
    * committed, afterwards the commit outcome is unknown. The callback's
    * error, if it threw, is the `cause`.
    *
+   * The driver re-runs an attempt the database aborted as transient — a
+   * write conflict or another error labelled `TransientTransactionError` —
+   * until its retry window of 120 seconds closes. When every attempt was
+   * aborted that way, the call rejects with `SmartdataTransactionConflictError`
+   * (code `transaction_conflict`): nothing was committed and the transaction
+   * is safe to re-run. With `timeoutMS` the deadline is the window, and the
+   * call rejects with `timeout` instead.
+   *
    * Every rejection states whether the transaction could have committed:
    * `SmartdataSession.getCommitOutcome(error)` returns `not_committed` or
    * `unknown` for the value the call rejected with.
@@ -370,6 +379,9 @@ export class SmartdataSession {
       throw rejectTransaction(errorArg, 'not_committed');
     }
     const { binding, timeoutMS, signal } = admitted;
+    const startedAt = performance.now();
+    /** How many times the driver started the callback. */
+    let attempts = 0;
     binding.transactionActive = true;
     binding.transactionTimeoutMS = timeoutMS;
     binding.transactionSignal = signal;
@@ -385,6 +397,7 @@ export class SmartdataSession {
     const runAttempt = async () => {
       // The last attempt's slots end after this one starts, so it bumps others.
       const attemptStartedAt = performance.now();
+      attempts++;
       revisionAttempt?.finish(false);
       revisionAttempt = beginSmartdataWriteRevisionAttempt(binding.owner, attemptStartedAt);
       // The driver starts another attempt only once the last one was aborted.
@@ -511,6 +524,19 @@ export class SmartdataSession {
           outcome: commitOutcomeOfTransactionEnd(binding.transactionEnded),
         };
       }
+      // The driver re-runs every attempt aborted as transient until its retry
+      // window closes, so such an error that still reaches here exhausted it.
+      // With `timeoutMS` the driver raises a deadline error in its place.
+      if (isMongoTransientTransactionError(errorArg) && !isMongoDeadlineError(errorArg)) {
+        return {
+          error: new SmartdataTransactionConflictError({
+            attempts,
+            elapsedMS: Math.round(performance.now() - startedAt),
+            cause: errorArg,
+          }),
+          outcome: 'not_committed',
+        };
+      }
       if (errorArg === callbackError) {
         return { error: normalizeDeadlineError(errorArg), outcome: 'not_committed' };
       }

package/ts/nosqldb/index.ts

@@ -48,7 +48,7 @@ export type {
 export type {
   ISmartdataQueryPlanOptions, ISmartdataQueryPlan, ISmartdataQueryPlanStage,
 } from './classes.queryplaninspection.js';
-export { SmartdataPersistenceError } from './classes.persistence.js';
+export { SmartdataPersistenceError, SmartdataTransactionConflictError } from './classes.persistence.js';
 export type { TSmartdataPersistenceErrorCode } from './classes.persistence.js';
 export * from './classes.exactpersistence.js';
 export * from './classes.easystore.js';

package/ts/objectstorage/classes.bucket.ts

@@ -30,6 +30,8 @@ export interface IListObjectKeysPageOptions {
   prefix?: string;
   limit: number;
   startAfter?: string;
+  /** Optional caller-owned cancellation signal */
+  signal?: AbortSignal;
 }
 
 export interface IListObjectKeysPageResult {
@@ -37,10 +39,7 @@ export interface IListObjectKeysPageResult {
   nextStartAfter?: string;
 }
 
-export interface IListObjectEntriesPageOptions extends IListObjectKeysPageOptions {
-  /** Optional caller-owned cancellation signal */
-  signal?: AbortSignal;
-}
+export interface IListObjectEntriesPageOptions extends IListObjectKeysPageOptions {}
 
 /**
  * One object as ListObjectsV2 reported it when the page was listed.
@@ -429,17 +428,15 @@ export class Bucket {
   // ===============
 
   /**
-   * store file
+   * Stores an object with one PutObject request; without `overwrite: true`
+   * a HeadObject request first refuses an existing object. `signal` aborts
+   * the request in flight and rejects with its reason.
    */
-  public async fastPut(
-    optionsArg: interfaces.IPathDecriptor & {
-      contents: string | Buffer;
-      overwrite?: boolean;
-    }
-  ): Promise<File> {
+  public async fastPut(optionsArg: interfaces.IFastPutOptions): Promise<File> {
+    const signal = helpers.requireOptionalAbortSignal(optionsArg.signal, 'fastPut signal');
     const reducedPath = await helpers.reducePathDescriptorToPath(optionsArg);
     if (optionsArg.overwrite !== true) {
-      const exists = await this.fastExists({ path: reducedPath });
+      const exists = await this.fastExists({ path: reducedPath, signal });
 
       if (exists) {
         throw new Error(
@@ -449,12 +446,19 @@ export class Bucket {
       }
     }
 
-    const command = new plugins.s3.PutObjectCommand({
-      Bucket: this.name,
-      Key: reducedPath,
-      Body: optionsArg.contents,
-    });
-    await this.smartbucketRef.storageClient.send(command);
+    const operation = beginBasicBucketOperation(this, signal);
+    try {
+      const command = new plugins.s3.PutObjectCommand({
+        Bucket: operation.bucketName,
+        Key: reducedPath,
+        Body: optionsArg.contents,
+      });
+      await operation.runProvider(
+        () => operation.client.send(command, { abortSignal: operation.signal }),
+      );
+    } finally {
+      operation.finish();
+    }
 
     const parsedPath = plugins.path.parse(reducedPath);
     return new File({
@@ -469,7 +473,7 @@ export class Bucket {
   /**
    * get file
    */
-  public async fastGet(optionsArg: { path: string }): Promise<Buffer> {
+  public async fastGet(optionsArg: interfaces.IFastGetStreamOptions): Promise<Buffer> {
     return await readObjectBody(await this.fastGetStream(optionsArg));
   }
 
@@ -502,9 +506,9 @@ export class Bucket {
    * @param optionsArg
    * @returns
    */
-  public async fastGetReplaySubject(optionsArg: {
-    path: string;
-  }): Promise<plugins.smartrx.rxjs.ReplaySubject<Buffer>> {
+  public async fastGetReplaySubject(
+    optionsArg: interfaces.IFastGetStreamOptions,
+  ): Promise<plugins.smartrx.rxjs.ReplaySubject<Buffer>> {
     const source = await this.fastGetStream(optionsArg);
     const replaySubject = new plugins.smartrx.rxjs.ReplaySubject<Buffer>();
     void (async () => {
@@ -965,15 +969,12 @@ export class Bucket {
   /**
    * Move object from one path to another within the same bucket or to another bucket
    */
-  public async fastMove(optionsArg: {
-    sourcePath: string;
-    destinationPath: string;
-    targetBucket?: Bucket;
-    overwrite?: boolean;
-  }): Promise<void> {
+  public async fastMove(optionsArg: interfaces.IFastMoveOptions): Promise<void> {
+    const signal = helpers.requireOptionalAbortSignal(optionsArg.signal, 'fastMove signal');
     const destinationBucket = optionsArg.targetBucket || this;
     const exists = await destinationBucket.fastExists({
       path: optionsArg.destinationPath,
+      signal,
     });
 
     if (exists && !optionsArg.overwrite) {
@@ -984,7 +985,7 @@ export class Bucket {
     }
 
     await this.fastCopy(optionsArg);
-    await this.fastRemove({ path: optionsArg.sourcePath });
+    await this.fastRemove({ path: optionsArg.sourcePath, signal });
   }
 
   /**
@@ -1120,17 +1121,30 @@ export class Bucket {
    * }
    * ```
    */
-  public async *listAllObjects(prefix: string = ''): AsyncIterableIterator<string> {
+  public async *listAllObjects(
+    prefix: string = '',
+    optionsArg: interfaces.IListAllObjectsOptions = {},
+  ): AsyncIterableIterator<string> {
+    const signal = helpers.requireOptionalAbortSignal(optionsArg.signal, 'listAllObjects signal');
     let continuationToken: string | undefined;
 
     do {
-      const command = new plugins.s3.ListObjectsV2Command({
-        Bucket: this.name,
-        Prefix: prefix,
-        ContinuationToken: continuationToken,
-      });
-
-      const response = await this.smartbucketRef.storageClient.send(command);
+      const operation = beginBasicBucketOperation(this, signal);
+      let response: plugins.s3.ListObjectsV2CommandOutput;
+      try {
+        operation.assertCurrent();
+        const command = new plugins.s3.ListObjectsV2Command({
+          Bucket: operation.bucketName,
+          Prefix: prefix,
+          ContinuationToken: continuationToken,
+        });
+        response = await operation.runProvider(
+          () => operation.client.send(command, { abortSignal: operation.signal }),
+        );
+        operation.assertCurrent();
+      } finally {
+        operation.finish();
+      }
 
       for (const obj of response.Contents || []) {
         if (obj.Key) yield obj.Key;
@@ -1210,19 +1224,28 @@ export class Bucket {
     optionsArg: IListObjectKeysPageOptions,
   ): Promise<IListObjectKeysPageResult> {
     const prefix = assertListingPageOptions(optionsArg, 'Object key page');
-    const response = await this.smartbucketRef.storageClient.send(
-      createListingPageCommand(this.name, prefix, optionsArg),
-    );
-    const { keys, nextStartAfter } = readListingPageContents(
-      response,
-      prefix,
-      optionsArg,
-      'key page',
-    );
-    return {
-      keys,
-      ...(nextStartAfter !== undefined ? { nextStartAfter } : {}),
-    };
+    const signal = helpers.requireOptionalAbortSignal(optionsArg.signal, 'Object key page signal');
+    const operation = beginBasicBucketOperation(this, signal);
+    try {
+      operation.assertCurrent();
+      const command = createListingPageCommand(operation.bucketName, prefix, optionsArg);
+      const response = await operation.runProvider(
+        () => operation.client.send(command, { abortSignal: operation.signal }),
+      );
+      operation.assertCurrent();
+      const { keys, nextStartAfter } = readListingPageContents(
+        response,
+        prefix,
+        optionsArg,
+        'key page',
+      );
+      return {
+        keys,
+        ...(nextStartAfter !== undefined ? { nextStartAfter } : {}),
+      };
+    } finally {
+      operation.finish();
+    }
   }
 
   /**
@@ -1238,10 +1261,8 @@ export class Bucket {
     optionsArg: IListObjectEntriesPageOptions,
   ): Promise<IListObjectEntriesPageResult> {
     const prefix = assertListingPageOptions(optionsArg, 'Object entry page');
-    if (optionsArg.signal !== undefined && !(optionsArg.signal instanceof AbortSignal)) {
-      throw new TypeError('Object entry page signal must be an AbortSignal');
-    }
-    const operation = beginBasicBucketOperation(this, optionsArg.signal);
+    const signal = helpers.requireOptionalAbortSignal(optionsArg.signal, 'Object entry page signal');
+    const operation = beginBasicBucketOperation(this, signal);
     try {
       operation.assertCurrent();
       const command = createListingPageCommand(operation.bucketName, prefix, optionsArg);
@@ -1345,9 +1366,12 @@ export class Bucket {
    * console.log(`Found ${allKeys.length} objects`);
    * ```
    */
-  public async listAllObjectsArray(prefix: string = ''): Promise<string[]> {
+  public async listAllObjectsArray(
+    prefix: string = '',
+    optionsArg: interfaces.IListAllObjectsOptions = {},
+  ): Promise<string[]> {
     const keys: string[] = [];
-    for await (const key of this.listAllObjects(prefix)) {
+    for await (const key of this.listAllObjects(prefix, optionsArg)) {
       keys.push(key);
     }
     return keys;

package/ts/objectstorage/classes.connection.ts

@@ -1,7 +1,8 @@
 import { SmartBucket } from './classes.smartbucket.js';
 import type { ICapabilities, IOperationOptions, IReadiness } from '../core/interfaces.js';
+import type { IObjectStorageRequestOptions } from './interfaces.js';
 
-export interface IObjectStorageConnectionOptions {
+export interface IObjectStorageConnectionOptions extends IObjectStorageRequestOptions {
   backend: 'objectstorage' | 's3';
   endpoint: string;
   region?: string;
@@ -23,7 +24,8 @@ export class ObjectStorageConnection extends SmartBucket {
     super({ endpoint: endpoint.hostname, port: Number(endpoint.port || (endpoint.protocol === 'https:' ? 443 : 80)),
       useSsl: endpoint.protocol === 'https:', accessKey: options.credentials.accessKeyId,
       accessSecret: options.credentials.secretAccessKey, region: options.region ?? 'us-east-1' },
-      { forcePathStyle: options.forcePathStyle });
+      { forcePathStyle: options.forcePathStyle, connectionTimeoutMs: options.connectionTimeoutMs,
+        requestTimeoutMs: options.requestTimeoutMs, maxAttempts: options.maxAttempts });
     this.backend = options.backend;
     this.capabilities = Object.freeze({ backend: this.backend, transactions: 'unsupported', changeStreams: 'unsupported',
       compositeGrouping: 'unsupported', objectMetrics: 'unsupported', diskResidentScans: 'unknown' });

package/ts/objectstorage/classes.requestdeadlineerror.ts

@@ -0,0 +1,16 @@
+/**
+ * The rejection of a request that reached the request deadline of the
+ * storage client a SmartBucket built (`SmartBucket.requestBounds`). The
+ * attempt in flight was destroyed and no further attempt starts. A request
+ * the provider had received completely before the deadline may still take
+ * effect.
+ */
+export class ObjectStorageRequestDeadlineError extends Error {
+  public readonly deadlineMs: number;
+
+  constructor(deadlineMsArg: number) {
+    super(`The object storage request exceeded its deadline of ${deadlineMsArg} ms.`);
+    this.name = 'ObjectStorageRequestDeadlineError';
+    this.deadlineMs = deadlineMsArg;
+  }
+}

package/ts/objectstorage/classes.smartbucket.ts

@@ -4,6 +4,11 @@ import * as plugins from './plugins.js';
 import { Bucket } from './classes.bucket.js';
 import { normalizeStorageDescriptor } from './helpers.js';
 import { headBucketExists } from './internal.bucketrequests.js';
+import {
+  bindRequestDeadline,
+  createBoundedClientConfig,
+  resolveRequestBounds,
+} from './internal.requestbounds.js';
 import {
   beginOperationLifecycleClose,
   commitOperationLifecycleClient,
@@ -14,6 +19,8 @@ import {
 } from './internal.exactupload.capability.js';
 import type {
   IBucketRequestOptions,
+  IObjectStorageRequestBounds,
+  IObjectStorageRequestOptions,
   ISmartBucketReadinessOptions,
   TSmartBucketReadinessFailureReason,
   TSmartBucketReadinessResult,
@@ -31,6 +38,8 @@ export class SmartBucket {
 
   private currentStorageClient: plugins.s3.S3Client;
   private ownedStorageClient: plugins.s3.S3Client;
+  private readonly boundedStorageClient: plugins.s3.S3Client;
+  private readonly boundedStorageClientBounds: IObjectStorageRequestBounds;
   private lifecycleState: TSmartBucketLifecycleState = 'open';
   private lifecycleEpoch = 0;
   private activeReadinessControllers = new Set<AbortController>();
@@ -85,6 +94,18 @@ export class SmartBucket {
     }
   }
 
+  /**
+   * The bounds every request of the storage client this SmartBucket built
+   * runs within, or `undefined` while a client assigned through
+   * `storageClient` or `replaceStorageClient()` is in use: its requests are
+   * bounded only by its own configuration.
+   */
+  public get requestBounds(): IObjectStorageRequestBounds | undefined {
+    return this.currentStorageClient === this.boundedStorageClient
+      ? this.boundedStorageClientBounds
+      : undefined;
+  }
+
   /** @deprecated Use storageClient instead */
   public get s3Client(): plugins.s3.S3Client {
     return this.currentStorageClient;
@@ -93,18 +114,26 @@ export class SmartBucket {
   /**
    * the constructor of SmartBucket
    */
-  constructor(configArg: plugins.tsclass.storage.IStorageDescriptor, clientOptions: { forcePathStyle?: boolean } = {}) {
+  constructor(
+    configArg: plugins.tsclass.storage.IStorageDescriptor,
+    clientOptions: { forcePathStyle?: boolean } & IObjectStorageRequestOptions = {},
+  ) {
     this.config = configArg;
 
     // Use the normalizer to handle various endpoint formats
     const { normalized } = normalizeStorageDescriptor(configArg);
+    const requestBounds = resolveRequestBounds(clientOptions);
 
     this.currentStorageClient = new plugins.s3.S3Client({
       endpoint: normalized.endpointUrl,
       region: normalized.region,
       credentials: normalized.credentials,
       forcePathStyle: clientOptions.forcePathStyle ?? normalized.forcePathStyle,
+      ...createBoundedClientConfig(requestBounds),
     });
+    bindRequestDeadline(this.currentStorageClient, requestBounds);
+    this.boundedStorageClient = this.currentStorageClient;
+    this.boundedStorageClientBounds = requestBounds;
     this.ownedStorageClient = this.currentStorageClient;
     registerOperationLifecycle(this, this.currentStorageClient);
   }

package/ts/objectstorage/helpers.ts

@@ -21,6 +21,22 @@ export const reducePathDescriptorToPath = async (pathDescriptorArg: interfaces.I
   return returnPath;
 }
 
+/**
+ * Validates a caller's cancellation signal: a genuine `AbortSignal`.
+ */
+export const requireOptionalAbortSignal = (
+  valueArg: unknown,
+  labelArg: string,
+): AbortSignal | undefined => {
+  if (valueArg === undefined) {
+    return undefined;
+  }
+  if (plugins.nodeUtil.types.isProxy(valueArg) || !(valueArg instanceof AbortSignal)) {
+    throw new TypeError(`${labelArg} must be an AbortSignal.`);
+  }
+  return valueArg;
+};
+
 // Storage Descriptor Normalization
 export interface IStorageWarning {
   code: string;

package/ts/objectstorage/index.ts

@@ -3,6 +3,7 @@ export * from './classes.bucket.js';
 export * from './classes.exactuploaderror.js';
 export * from './classes.exactpathpurgeerror.js';
 export * from './classes.objectrangeerror.js';
+export * from './classes.requestdeadlineerror.js';
 export * from './classes.directory.js';
 export * from './classes.file.js';
 export * from './classes.listcursor.js';

package/ts/objectstorage/interfaces.ts

@@ -87,6 +87,25 @@ export interface IFastStatOptions extends IPathDecriptor {
   signal?: AbortSignal;
 }
 
+export interface IFastPutOptions extends IPathDecriptor {
+  contents: string | Buffer;
+  overwrite?: boolean;
+  signal?: AbortSignal;
+}
+
+export interface IFastMoveOptions {
+  sourcePath: string;
+  destinationPath: string;
+  targetBucket?: Bucket;
+  overwrite?: boolean;
+  signal?: AbortSignal;
+}
+
+export interface IListAllObjectsOptions {
+  /** Optional caller-owned cancellation signal */
+  signal?: AbortSignal;
+}
+
 export interface IDirectoryFastPutStreamOptions {
   path: string;
   stream: Readable;
@@ -103,6 +122,45 @@ export interface IBucketRequestOptions {
   signal?: AbortSignal;
 }
 
+// ================================
+// Request Bound Interfaces
+// ================================
+
+/**
+ * Bounds of every request sent by the storage client a SmartBucket builds.
+ * Each is a positive safe integer; an omitted one takes its default.
+ */
+export interface IObjectStorageRequestOptions {
+  /** Time one attempt may take to connect its socket in milliseconds (default: 10000, maximum: 60000) */
+  connectionTimeoutMs?: number;
+  /**
+   * Time from the start of one attempt to its response headers in
+   * milliseconds, connecting and uploading the request body included
+   * (default: 60000, maximum: 3600000)
+   */
+  requestTimeoutMs?: number;
+  /** Attempts of one request, the first one included (default: 3, maximum: 10) */
+  maxAttempts?: number;
+}
+
+/**
+ * The effective bounds of the storage client a SmartBucket built.
+ */
+export interface IObjectStorageRequestBounds {
+  readonly connectionTimeoutMs: number;
+  readonly requestTimeoutMs: number;
+  readonly maxAttempts: number;
+  /** The longest wait of the SDK before a retry */
+  readonly maxRetryDelayMs: number;
+  /**
+   * `maxAttempts * requestTimeoutMs + (maxAttempts - 1) * maxRetryDelayMs`
+   * plus 1000 ms for the client's own work around the attempts: the client
+   * destroys a request still unsettled after this time, retries included,
+   * and starts no further attempt of it
+   */
+  readonly requestDeadlineMs: number;
+}
+
 // ================================
 // SmartBucket Readiness Interfaces
 // ================================

package/ts/objectstorage/internal.exactupload.capability.ts

@@ -1,4 +1,5 @@
 import * as plugins from './plugins.js';
+import { requireOptionalAbortSignal } from './helpers.js';
 import type {
   IExactPathPurgeCapability,
   IExactUploadCapability,
@@ -541,6 +542,7 @@ export const beginBasicBucketOperation = (
   bucketRefArg: IBucketCapabilityRef,
   callerSignalArg?: AbortSignal,
 ): IBasicBucketOperation => {
+  const callerSignal = requireOptionalAbortSignal(callerSignalArg, 'Object storage request signal');
   const smartbucketRef = bucketRefArg.smartbucketRef;
   const lifecycleRecord = getLifecycleRecord(smartbucketRef);
   const binding: IExactCapabilityBinding = {
@@ -550,7 +552,7 @@ export const beginBasicBucketOperation = (
     storageClient: lifecycleRecord.storageClient,
     lifecycleGeneration: lifecycleRecord.generation,
   };
-  return beginOperation(binding, callerSignalArg);
+  return beginOperation(binding, callerSignal);
 };
 
 export const beginExactUploadProbeOperation = (