@lossless.org/client 1.23.3 → 2.0.0

package/ts/objectstorage/internal.requestbounds.ts

@@ -0,0 +1,192 @@
+import * as plugins from './plugins.js';
+import { ObjectStorageRequestDeadlineError } from './classes.requestdeadlineerror.js';
+import type {
+  IObjectStorageRequestBounds,
+  IObjectStorageRequestOptions,
+} from './interfaces.js';
+
+const requestOptionLimits = {
+  connectionTimeoutMs: { defaultValue: 10_000, maximum: 60_000 },
+  requestTimeoutMs: { defaultValue: 60_000, maximum: 3_600_000 },
+  maxAttempts: { defaultValue: 3, maximum: 10 },
+} as const;
+
+/**
+ * The longest wait of the SDK's standard retry strategy before a retry
+ * (`MAXIMUM_RETRY_DELAY` of `@smithy/core`, which caps a retry-after hint
+ * as well).
+ */
+const maxRetryDelayMs = 20_000;
+
+/**
+ * Time the deadline grants beyond the attempts and retry waits for the
+ * client's own work around them (serializing, signing, checksums), so an
+ * attempt's own timeout decides its failure and the deadline only ends a
+ * request the attempt bounds do not.
+ */
+const requestDeadlineAllowanceMs = 1_000;
+
+type TRequestOptionName = keyof typeof requestOptionLimits;
+
+const requireRequestOption = (
+  optionsArg: IObjectStorageRequestOptions,
+  nameArg: TRequestOptionName,
+): number => {
+  const value: unknown = optionsArg[nameArg];
+  const { defaultValue, maximum } = requestOptionLimits[nameArg];
+  if (value === undefined) {
+    return defaultValue;
+  }
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1 || value > maximum) {
+    throw new TypeError(
+      `Object storage ${nameArg} must be a positive safe integer no greater than ${maximum}.`,
+    );
+  }
+  return value;
+};
+
+/**
+ * Validates the request options of a storage client and derives its bounds.
+ */
+export const resolveRequestBounds = (
+  optionsArg: IObjectStorageRequestOptions,
+): IObjectStorageRequestBounds => {
+  const connectionTimeoutMs = requireRequestOption(optionsArg, 'connectionTimeoutMs');
+  const requestTimeoutMs = requireRequestOption(optionsArg, 'requestTimeoutMs');
+  const maxAttempts = requireRequestOption(optionsArg, 'maxAttempts');
+  return Object.freeze({
+    connectionTimeoutMs,
+    requestTimeoutMs,
+    maxAttempts,
+    maxRetryDelayMs,
+    requestDeadlineMs: maxAttempts * requestTimeoutMs
+      + (maxAttempts - 1) * maxRetryDelayMs
+      + requestDeadlineAllowanceMs,
+  });
+};
+
+/**
+ * The S3 client configuration that applies the bounds to every attempt:
+ * `@smithy/node-http-handler` destroys an attempt whose socket does not
+ * connect within `connectionTimeout` and, with `throwOnRequestTimeout`, one
+ * whose response headers did not arrive within `requestTimeout` of its start.
+ * `maxAttempts` and the standard retry mode are set explicitly, so
+ * `AWS_MAX_ATTEMPTS`, `AWS_RETRY_MODE` and shared config files cannot change
+ * them.
+ */
+export const createBoundedClientConfig = (boundsArg: IObjectStorageRequestBounds) => ({
+  maxAttempts: boundsArg.maxAttempts,
+  retryMode: 'standard',
+  requestHandler: {
+    connectionTimeout: boundsArg.connectionTimeoutMs,
+    requestTimeout: boundsArg.requestTimeoutMs,
+    throwOnRequestTimeout: true,
+  },
+}) satisfies Partial<plugins.s3.S3ClientConfig>;
+
+type TSendOptions = { abortSignal?: AbortSignal } & Record<string, unknown>;
+type TSendCallback = (errorArg: unknown, outputArg?: unknown) => void;
+type TUnboundedSend = (commandArg: unknown, optionsArg?: TSendOptions) => Promise<unknown>;
+
+const readStreamingBody = (outputArg: unknown): plugins.stream.Readable | undefined => {
+  if (typeof outputArg !== 'object' || outputArg === null) {
+    return undefined;
+  }
+  const body = (outputArg as { Body?: unknown }).Body;
+  return body instanceof plugins.stream.Readable ? body : undefined;
+};
+
+/**
+ * Bounds every `send()` of a storage client by `requestDeadlineMs`.
+ *
+ * Each request gets its own abort signal, which the caller's `abortSignal`
+ * and the deadline abort. The HTTP handler destroys the attempt in flight
+ * when it aborts, and refuses every later attempt of the request, so no
+ * attempt starts or sends after the deadline. The request rejects at the
+ * deadline with `ObjectStorageRequestDeadlineError`; the handler fails the
+ * aborted attempt with an `AbortError`, which the retry strategy never
+ * retries. A caller's abort still reaches a response body the request
+ * resolved with until that body closes.
+ */
+export const bindRequestDeadline = (
+  clientArg: plugins.s3.S3Client,
+  boundsArg: IObjectStorageRequestBounds,
+): void => {
+  const sendWithoutDeadline = clientArg.send.bind(clientArg) as unknown as TUnboundedSend;
+  const sendWithinDeadline = (
+    commandArg: unknown,
+    optionsArg: TSendOptions | undefined,
+  ): Promise<unknown> => new Promise((resolve, reject) => {
+    const callerSignal = optionsArg?.abortSignal;
+    const requestAbortController = new AbortController();
+    const forwardCallerAbort = (): void => {
+      requestAbortController.abort(callerSignal?.reason);
+    };
+    const releaseCallerSignal = (): void => {
+      callerSignal?.removeEventListener('abort', forwardCallerAbort);
+    };
+    if (callerSignal?.aborted) {
+      forwardCallerAbort();
+    } else {
+      callerSignal?.addEventListener('abort', forwardCallerAbort, { once: true });
+    }
+    let settled = false;
+    const deadlineTimer = setTimeout(() => {
+      settled = true;
+      const deadlineError = new ObjectStorageRequestDeadlineError(boundsArg.requestDeadlineMs);
+      requestAbortController.abort(deadlineError);
+      reject(deadlineError);
+    }, boundsArg.requestDeadlineMs);
+    sendWithoutDeadline(commandArg, {
+      ...optionsArg,
+      abortSignal: requestAbortController.signal,
+    }).then(
+      (outputArg) => {
+        clearTimeout(deadlineTimer);
+        const body = readStreamingBody(outputArg);
+        if (settled) {
+          releaseCallerSignal();
+          body?.destroy();
+          return;
+        }
+        settled = true;
+        if (body && !body.destroyed) {
+          body.once('close', releaseCallerSignal);
+        } else {
+          releaseCallerSignal();
+        }
+        resolve(outputArg);
+      },
+      (errorArg: unknown) => {
+        clearTimeout(deadlineTimer);
+        releaseCallerSignal();
+        if (settled) {
+          return;
+        }
+        settled = true;
+        reject(errorArg);
+      },
+    );
+  });
+  const boundedSend = (
+    commandArg: unknown,
+    optionsOrCallbackArg?: TSendOptions | TSendCallback,
+    callbackArg?: TSendCallback,
+  ): Promise<unknown> | void => {
+    const callback = typeof optionsOrCallbackArg === 'function' ? optionsOrCallbackArg : callbackArg;
+    const options = typeof optionsOrCallbackArg === 'function' ? undefined : optionsOrCallbackArg;
+    const result = sendWithinDeadline(commandArg, options);
+    if (typeof callback !== 'function') {
+      return result;
+    }
+    // As the SDK's own callback form: a callback that throws must not become
+    // an unhandled rejection.
+    result.then(
+      (outputArg) => callback(null, outputArg),
+      (errorArg: unknown) => callback(errorArg),
+    ).catch(() => {});
+  };
+  // S3Client.send() is generic over the SDK's Command type, which the
+  // optional peer does not export; the bounded send keeps its signature.
+  clientArg.send = boundedSend as typeof clientArg.send;
+};

package/ts/objectstorage/plugins.ts

@@ -4,8 +4,9 @@
 import * as crypto from 'node:crypto';
 import * as path from 'node:path';
 import * as stream from 'node:stream';
+import * as nodeUtil from 'node:util';
 
-export { crypto, path, stream };
+export { crypto, nodeUtil, path, stream };
 
 // @push.rocks scope
 import * as smartmime from '@push.rocks/smartmime';