@lossless.org/client 1.23.2 → 2.0.0

package/dist_ts/objectstorage/plugins.d.ts

@@ -1,7 +1,8 @@
 import * as crypto from 'node:crypto';
 import * as path from 'node:path';
 import * as stream from 'node:stream';
-export { crypto, path, stream };
+import * as nodeUtil from 'node:util';
+export { crypto, nodeUtil, path, stream };
 import * as smartmime from '@push.rocks/smartmime';
 import * as smartpath from '@push.rocks/smartpath';
 import * as smartpromise from '@push.rocks/smartpromise';

package/dist_ts/objectstorage/plugins.js

@@ -3,7 +3,8 @@
 import * as crypto from 'node:crypto';
 import * as path from 'node:path';
 import * as stream from 'node:stream';
-export { crypto, path, stream };
+import * as nodeUtil from 'node:util';
+export { crypto, nodeUtil, path, stream };
 // @push.rocks scope
 import * as smartmime from '@push.rocks/smartmime';
 import * as smartpath from '@push.rocks/smartpath';
@@ -20,4 +21,4 @@ export { tsclass, };
 import * as s3 from '@aws-sdk/client-s3';
 import { Minimatch } from 'minimatch';
 export { s3, Minimatch, };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL29iamVjdHN0b3JhZ2UvcGx1Z2lucy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxhQUFhO0FBRWIsY0FBYztBQUNkLE9BQU8sS0FBSyxNQUFNLE1BQU0sYUFBYSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxJQUFJLE1BQU0sV0FBVyxDQUFDO0FBQ2xDLE9BQU8sS0FBSyxNQUFNLE1BQU0sYUFBYSxDQUFDO0FBRXRDLE9BQU8sRUFBRSxNQUFNLEVBQUUsSUFBSSxFQUFFLE1BQU0sRUFBRSxDQUFDO0FBRWhDLG9CQUFvQjtBQUNwQixPQUFPLEtBQUssU0FBUyxNQUFNLHVCQUF1QixDQUFDO0FBQ25ELE9BQU8sS0FBSyxTQUFTLE1BQU0sdUJBQXVCLENBQUM7QUFDbkQsT0FBTyxLQUFLLFlBQVksTUFBTSwwQkFBMEIsQ0FBQztBQUN6RCxPQUFPLEtBQUssT0FBTyxNQUFNLHFCQUFxQixDQUFDO0FBQy9DLE9BQU8sS0FBSyxXQUFXLE1BQU0seUJBQXlCLENBQUM7QUFDdkQsT0FBTyxLQUFLLFdBQVcsTUFBTSx5QkFBeUIsQ0FBQztBQUN2RCxPQUFPLEtBQUssV0FBVyxNQUFNLHlCQUF5QixDQUFDO0FBRXZELE9BQU8sRUFBRSxTQUFTLEVBQUUsU0FBUyxFQUFFLFlBQVksRUFBRSxPQUFPLEVBQUUsV0FBVyxFQUFFLFdBQVcsRUFBRSxXQUFXLEVBQUUsQ0FBQztBQUU5RixXQUFXO0FBQ1gsT0FBTyxLQUFLLE9BQU8sTUFBTSxrQkFBa0IsQ0FBQztBQUU1QyxPQUFPLEVBQ0wsT0FBTyxHQUNSLENBQUE7QUFFRCxvQkFBb0I7QUFDcEIsT0FBTyxLQUFLLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUN6QyxPQUFPLEVBQUUsU0FBUyxFQUFFLE1BQU0sV0FBVyxDQUFDO0FBRXRDLE9BQU8sRUFDTCxFQUFFLEVBQ0YsU0FBUyxHQUNWLENBQUEifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL29iamVjdHN0b3JhZ2UvcGx1Z2lucy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxhQUFhO0FBRWIsY0FBYztBQUNkLE9BQU8sS0FBSyxNQUFNLE1BQU0sYUFBYSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxJQUFJLE1BQU0sV0FBVyxDQUFDO0FBQ2xDLE9BQU8sS0FBSyxNQUFNLE1BQU0sYUFBYSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxRQUFRLE1BQU0sV0FBVyxDQUFDO0FBRXRDLE9BQU8sRUFBRSxNQUFNLEVBQUUsUUFBUSxFQUFFLElBQUksRUFBRSxNQUFNLEVBQUUsQ0FBQztBQUUxQyxvQkFBb0I7QUFDcEIsT0FBTyxLQUFLLFNBQVMsTUFBTSx1QkFBdUIsQ0FBQztBQUNuRCxPQUFPLEtBQUssU0FBUyxNQUFNLHVCQUF1QixDQUFDO0FBQ25ELE9BQU8sS0FBSyxZQUFZLE1BQU0sMEJBQTBCLENBQUM7QUFDekQsT0FBTyxLQUFLLE9BQU8sTUFBTSxxQkFBcUIsQ0FBQztBQUMvQyxPQUFPLEtBQUssV0FBVyxNQUFNLHlCQUF5QixDQUFDO0FBQ3ZELE9BQU8sS0FBSyxXQUFXLE1BQU0seUJBQXlCLENBQUM7QUFDdkQsT0FBTyxLQUFLLFdBQVcsTUFBTSx5QkFBeUIsQ0FBQztBQUV2RCxPQUFPLEVBQUUsU0FBUyxFQUFFLFNBQVMsRUFBRSxZQUFZLEVBQUUsT0FBTyxFQUFFLFdBQVcsRUFBRSxXQUFXLEVBQUUsV0FBVyxFQUFFLENBQUM7QUFFOUYsV0FBVztBQUNYLE9BQU8sS0FBSyxPQUFPLE1BQU0sa0JBQWtCLENBQUM7QUFFNUMsT0FBTyxFQUNMLE9BQU8sR0FDUixDQUFBO0FBRUQsb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxFQUFFLE1BQU0sb0JBQW9CLENBQUM7QUFDekMsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLFdBQVcsQ0FBQztBQUV0QyxPQUFPLEVBQ0wsRUFBRSxFQUNGLFNBQVMsR0FDVixDQUFBIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lossless.org/client",
-  "version": "1.23.2",
+  "version": "2.0.0",
   "private": false,
   "publishConfig": {
     "registry": "https://verdaccio.lossless.digital"
@@ -86,7 +86,7 @@
     "@git.zone/tsbuild": "6.0.2",
     "@git.zone/tsbundle": "3.2.1",
     "@git.zone/tsrun": "3.0.3",
-    "@git.zone/tstest": "7.2.0",
+    "@git.zone/tstest": "7.2.1",
     "@lossless.org/nosqldb": "8.0.2",
     "@lossless.org/nosqldb-qualified": "npm:@lossless.org/nosqldb@10.9.0",
     "@lossless.org/objectstorage": "10.3.1",

package/readme.md

@@ -137,6 +137,8 @@ Family imports preserve the established SmartData and SmartBucket names and cons
 | Bucket lookup for bucket-scoped credentials | `smartBucket.getBucketByName(name, { signal? })` and `smartBucket.bucketExists(name, { signal? })` send one HeadBucket; `createBucket(name, { signal? })` and `removeBucket(name, { signal? })` take the same options |
 | Byte-range downloads | `bucket.fastGetRangeStream({ path, range: { start, end? }, signal? }, typeArg?)` — one ranged GetObject resolving `{ stream, range, size }`; range failures reject with `ObjectRangeError` code `invalid_argument`, `range_not_satisfiable` or `invalid_response` |
 | Reads of objects that may be missing | `bucket.fastGetIfPresent({ path, signal? })` — one GetObject resolving the object's bytes, or `null` when the key does not exist |
+| Bounded requests | `new SmartBucket(config, { connectionTimeoutMs?, requestTimeoutMs?, maxAttempts? })` and the same options on `new ObjectStorageConnection({ ... })` — every request of the client a SmartBucket builds ends within `smartBucket.requestBounds.requestDeadlineMs`, retries included, or rejects with `ObjectStorageRequestDeadlineError` |
+| Signals on writes, moves and listings | `bucket.fastPut({ ..., signal? })`, `bucket.fastMove({ ..., signal? })`, `bucket.listObjectKeysPage({ ..., signal? })`, `bucket.listAllObjects(prefix?, { signal? })` and `bucket.listAllObjectsArray(prefix?, { signal? })`; `fastGet`, `fastPutStream`, `fastCopy` and `fastRemove` already took one |
 
 A bucket lookup sends one HeadBucket for the named bucket, never ListBuckets, so a credential scoped to its bucket can open it without the account-wide list permission, and a lookup does not depend on which buckets a listing returns. A missing bucket (404) keeps its answer: `getBucketByName()` rejects with `Bucket '<name>' not found.` and `bucketExists()` resolves `false`. A bucket the credentials may not access (403) rejects both with an error that names the denial and keeps the provider error as `cause`; S3 does not say whether such a bucket exists. Any other provider failure is rethrown unchanged. `signal` aborts the in-flight request and rejects with the signal's reason. Lookups, creations and removals run as lifecycle-managed operations: `SmartBucket.close()` aborts and awaits them, and the storage client cannot be replaced while one is active.
 
@@ -146,6 +148,10 @@ A bucket lookup sends one HeadBucket for the named bucket, never ListBuckets, so
 
 `fastGetIfPresent()` answers "read it, or tell me it is gone" with one GetObject, so an object removed between an existence check and a read can no longer turn into a failed read: a provider answer that the key does not exist — `NoSuchKey`, `NotFound` or any other HTTP 404 — resolves `null`. Every other failure rejects as `fastGet()` does, the provider error unchanged: a missing bucket (`NoSuchBucket`), a denied request, a failure while the body streams, and an abort through `signal` or `SmartBucket.close()`, which rejects with the abort reason even when the provider answers not-found after it. `fastExists()` and the create-only check of `fastPutStream()` classify a missing object the same way.
 
+Every request of the S3 client a `SmartBucket` builds is bounded. An attempt whose socket does not connect within `connectionTimeoutMs` (default 10 s, at most 60 s), or whose response headers do not arrive within `requestTimeoutMs` of its start (default 60 s, at most 1 h; the upload of the request body counts), fails with the SDK's `TimeoutError`; the SDK retries it up to `maxAttempts` attempts in all (default 3, at most 10, standard retry mode, `AWS_MAX_ATTEMPTS` and shared config files ignored). Each value must be a positive safe integer; anything else is refused with a `TypeError` before a client is built. `smartBucket.requestBounds` (and `connection.requestBounds`) reads the frozen bounds, including `requestDeadlineMs = maxAttempts × requestTimeoutMs + (maxAttempts − 1) × 20 000 ms + 1 000 ms` — the attempts, the longest wait the retry strategy takes before a retry (a provider's retry-after hint included), and a second for the client's own work. 221 000 ms with the defaults. A request still unsettled at that deadline, a stalled error body included, rejects with `ObjectStorageRequestDeadlineError`, its attempt in flight is destroyed and no further attempt of it starts, so a consumer can hold the client to an upper bound of its own (`requestDeadlineMs < bound`). The bound does not undo a request: a PutObject the provider received completely before the deadline or an abort may still take effect. It covers requests, not the time a caller takes to read a download it received: a response body streams at the caller's pace until it is consumed, the caller's signal aborts or the SmartBucket closes. While a client assigned through `storageClient` or `replaceStorageClient()` is in use, `requestBounds` is `undefined` and that client's own configuration applies. A single-request upload (`fastPut`, `fastPutStream`) must finish sending its body within `requestTimeoutMs`; for large objects raise it or use `fastPutStreamExact()`, whose parts are separate requests of 5 MiB each.
+
+A `signal` aborts the request in flight, stops its retries and rejects with the signal's reason; an already aborted signal sends nothing. A signal of a bucket read, write, copy, move, removal, existence check or listing that is not an `AbortSignal`, a `Proxy` of one included, is refused with a `TypeError` before any request. A per-call time limit is a signal as well, `AbortSignal.timeout(ms)` or an own `AbortController`.
+
 ### Document APIs that need a MongoDB backend
 
 The document model runs on both NoSQLDB and MongoDB, but several APIs do not mean the same thing on both. The NoSQLDB engine is qualified at 8.0.2 and 10.9.0 (see [Verification](#verification)); the two releases part on the grouped-totals and guarded-`$expr` rows below — 10.9.0 groups composite keys exactly and evaluates the guard, 8.0.2 does neither — on whether a migration can create a partial index or a collection validator at all, on when a transaction learns of a write conflict, and on whether `$elemMatch` applies query operators to scalar array elements.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@lossless.org/client',
-  version: '1.23.2',
+  version: '2.0.0',
   description: 'One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.'
 }

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.directory.ts

@@ -243,6 +243,14 @@ export class Directory {
 
 
     const getDirectory = async (directoryArg: Directory, dirNameToSearch: string, isFinalDirectory: boolean) => {
+      // A listed directory and a new one of the same name are the same handle. Only whether the
+      // final directory exists decides anything, and only when it is created with an initializer
+      // file; otherwise a caller that accepts an empty directory needs no listing, which walks every
+      // key below the prefix and costs a large bucket seconds per level.
+      const createsInitializer = isFinalDirectory && optionsArg.createWithInitializerFile;
+      if ((optionsArg.getEmptyDirectory || optionsArg.createWithInitializerFile) && !createsInitializer) {
+        return new Directory(this.bucketRef, directoryArg, dirNameToSearch);
+      }
       const directories = await directoryArg.listDirectories();
       let returnDirectory = directories.find((directory) => {
         return directory.name === dirNameToSearch;

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 = (