@doist/comms-sdk 3.0.0 → 3.0.2

package/dist/esm/transport/fetch-with-retry.js

@@ -4,7 +4,8 @@ import { transformTimestamps } from '../utils/timestamp-conversion.js';
 import { getDefaultTransport } from './http-dispatcher.js';
 export async function fetchWithRetry(url, options, maxRetries = 3, customFetch) {
     let lastError;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    let attempt = 0;
+    for (; attempt <= maxRetries; attempt++) {
         let clearTimeoutFn;
         try {
             let requestSignal = options.signal || undefined;
@@ -56,7 +57,56 @@ export async function fetchWithRetry(url, options, maxRetries = 3, customFetch)
     if (lastError instanceof CommsRequestError) {
         throw lastError;
     }
-    throw new CommsRequestError(lastError?.message ?? 'Request failed');
+    throw new CommsRequestError(describeTransportFailure(lastError, attempt + 1), undefined, undefined, {
+        cause: lastError,
+    });
+}
+/** Causes reported before the rest of the chain is dropped. */
+const CAUSE_CHAIN_LIMIT = 3;
+/**
+ * Builds the message for a request that never produced a response.
+ *
+ * `fetch` reports every transport problem as the same `fetch failed`, and puts
+ * the reason a caller actually needs — `ENOTFOUND`, `ECONNRESET`, a TLS failure
+ * — in `cause`. Dropping that leaves an unattributable error in the logs, so
+ * unwrap the chain into the message and keep the original as `cause`.
+ */
+function describeTransportFailure(error, attempts) {
+    const base = error?.message ?? 'Request failed';
+    const cause = describeCauseChain(error);
+    const tries = attempts > 1 ? ` after ${attempts} attempts` : '';
+    return cause ? `${base} (${cause})${tries}` : `${base}${tries}`;
+}
+function describeCauseChain(error) {
+    const descriptions = [];
+    for (const cause of causeChain(error)) {
+        const description = describeCause(cause);
+        if (description) {
+            descriptions.push(description);
+        }
+    }
+    return descriptions.length > 0 ? descriptions.join(' <- ') : undefined;
+}
+/**
+ * Walks an error's `cause` chain, stopping at {@link CAUSE_CHAIN_LIMIT} and on
+ * a cycle. A failed connect can carry one error per address it tried; the first
+ * is representative and the rest repeat the same failure.
+ */
+function* causeChain(error) {
+    const seen = new Set();
+    let current = error?.cause;
+    let depth = 0;
+    while (current instanceof Error && !seen.has(current) && depth < CAUSE_CHAIN_LIMIT) {
+        seen.add(current);
+        depth++;
+        yield current;
+        const aggregated = current instanceof AggregateError ? current.errors[0] : undefined;
+        current = aggregated ?? current.cause;
+    }
+}
+function describeCause(error) {
+    const code = error.code;
+    return typeof code === 'string' && code.length > 0 ? `${code}: ${error.message}` : error.message;
 }
 async function fetchWithDefaultTransport(url, options, signal) {
     // Read the dispatcher and its paired `fetch` as one value so they can never
@@ -92,13 +142,60 @@ function createTimeoutError(timeoutMs) {
     error.name = timeoutErrorName;
     return error;
 }
+/**
+ * Transport-level failure codes worth another attempt: the request never got an
+ * answer, so nothing about the response argues against retrying. `UND_ERR_SOCKET`
+ * covers the HTTP/2 `GOAWAY` an edge proxy sends when it retires a pooled
+ * connection, which is otherwise indistinguishable from any other `fetch failed`.
+ */
+const NETWORK_ERROR_CODES = new Set([
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'EAI_AGAIN',
+    'ENOTFOUND',
+    'EPIPE',
+    'ETIMEDOUT',
+    'UND_ERR_SOCKET',
+]);
 function isNetworkError(error) {
     return (error.name === 'TypeError' ||
         error.name === timeoutErrorName ||
-        error.message.toLowerCase().includes('network'));
+        error.message.toLowerCase().includes('network') ||
+        hasNetworkErrorCode(error));
+}
+function hasNetworkErrorCode(error) {
+    // The code can be on the error itself — a `customFetch` is free to reject
+    // with one directly — or on anything `fetch` wrapped to produce it.
+    if (hasRetryableCode(error)) {
+        return true;
+    }
+    for (const cause of causeChain(error)) {
+        if (hasRetryableCode(cause)) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasRetryableCode(error) {
+    const code = error.code;
+    return typeof code === 'string' && NETWORK_ERROR_CODES.has(code);
 }
+/** First retry delay, doubling by {@link RETRY_DELAY_FACTOR} per attempt. */
+const RETRY_BASE_DELAY_MS = 100;
+const RETRY_DELAY_FACTOR = 4;
+const RETRY_MAX_DELAY_MS = 2000;
+/**
+ * How long to wait before retry `retryCount` (1-based).
+ *
+ * A retired connection takes a moment to be torn down and replaced, so retrying
+ * immediately just re-dispatches onto the socket that is going away and burns
+ * the whole retry budget inside a second. The delay grows so the later attempts
+ * land on a fresh connection, and carries jitter because one retirement hits
+ * every pooled connection at once: without it, every caller reconnects in step.
+ */
 function getRetryDelay(retryCount) {
-    return retryCount === 1 ? 0 : 500;
+    const delay = Math.min(RETRY_BASE_DELAY_MS * RETRY_DELAY_FACTOR ** (retryCount - 1), RETRY_MAX_DELAY_MS);
+    return delay / 2 + Math.random() * (delay / 2);
 }
 function createTimeoutSignal(timeoutMs, existingSignal) {
     const controller = new AbortController();

package/dist/esm/types/errors.js

@@ -1,7 +1,7 @@
 import { CustomError } from 'ts-custom-error';
 export class CommsRequestError extends CustomError {
-    constructor(message, httpStatusCode, responseData) {
-        super(message);
+    constructor(message, httpStatusCode, responseData, options) {
+        super(message, options);
         this.httpStatusCode = httpStatusCode;
         this.responseData = responseData;
     }

package/dist/types/types/errors.d.ts

@@ -2,5 +2,5 @@ import { CustomError } from 'ts-custom-error';
 export declare class CommsRequestError extends CustomError {
     httpStatusCode?: number;
     responseData?: unknown;
-    constructor(message: string, httpStatusCode?: number, responseData?: unknown);
+    constructor(message: string, httpStatusCode?: number, responseData?: unknown, options?: ErrorOptions);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/comms-sdk",
-    "version": "3.0.0",
+    "version": "3.0.2",
     "description": "A TypeScript wrapper for the Comms REST API.",
     "author": "Doist developers",
     "homepage": "https://doist.github.io/comms-sdk-typescript/",