@forgecart/sdk 1.202610251643.0 → 1.202610251830.0

package/dist/client.generated.d.ts

@@ -200,6 +200,25 @@ export declare class BaseGraphQLClient {
      * error.
      */
     private getFirstValueBudgetMs;
+    /**
+     * The longest graphql-ws waits before any re-dial (#3452): half the shorter
+     * of the handshake bound and a read's first-value deadline, so 5_000 ms at
+     * the defaults and 1_000 ms at a connectionTimeout of 2_000. A wait that
+     * starts with an operation therefore ends inside that operation's own
+     * bound, and the dial it leads to keeps the other half to be answered.
+     * A get*, not a find*: derived configuration, never a lookup.
+     */
+    private getRetryWaitCeilingMs;
+    /**
+     * graphql-ws's retryWait (#3452): the library's own randomised exponential
+     * delay, never longer than getRetryWaitCeilingMs(). graphql-ws resets its
+     * retry count only on an ack, so uncapped the delay doubles past its ladder
+     * for as long as an outage lasts; capped, the next operation after the
+     * outage re-dials within seconds. The timer stays a plain, reffed
+     * setTimeout: it replaces graphql-ws's own one for one and changes only
+     * how long it runs.
+     */
+    private waitBeforeRedial;
     /**
      * The name the document declares: `query ChannelPlugins` gives
      * "ChannelPlugins". Every generated document is a named operation, so the

package/dist/client.generated.js

@@ -89,6 +89,18 @@ var WsTimeoutBudgetMs;
     WsTimeoutBudgetMs[WsTimeoutBudgetMs["QUERY_FIRST_VALUE"] = 10000] = "QUERY_FIRST_VALUE";
     WsTimeoutBudgetMs[WsTimeoutBudgetMs["MUTATION_FIRST_VALUE"] = 60000] = "MUTATION_FIRST_VALUE";
 })(WsTimeoutBudgetMs || (WsTimeoutBudgetMs = {}));
+/**
+ * graphql-ws's own randomised exponential backoff, which the library does
+ * not export: it waits BASE * 2 ** retries plus JITTER_MIN..JITTER_MAX of
+ * jitter before every re-dial. Restated so waitBeforeRedial can keep that
+ * delay and only cap it (#3452).
+ */
+var WsRetryBackoffMs;
+(function (WsRetryBackoffMs) {
+    WsRetryBackoffMs[WsRetryBackoffMs["BASE"] = 1000] = "BASE";
+    WsRetryBackoffMs[WsRetryBackoffMs["JITTER_MIN"] = 300] = "JITTER_MIN";
+    WsRetryBackoffMs[WsRetryBackoffMs["JITTER_MAX"] = 3000] = "JITTER_MAX";
+})(WsRetryBackoffMs || (WsRetryBackoffMs = {}));
 /**
  * The per-OPERATION first-value budgets (#2245). A kind default sizes the
  * average operation of that kind; an operation that holds the socket for a
@@ -160,7 +172,8 @@ class BaseGraphQLClient {
         // A healthy handshake is milliseconds, and graphql-ws waits ~1-4 s before
         // its first re-dial — so 10 s still lets ONE transient non-101 refusal heal
         // (the retry-safety in getWsClient) while cutting the SILENT window from the
-        // measured 32.5-46 s ladder to a bounded, logged failure (#2102).
+        // retry ladder (18.6-24 s at the default bounds, every wait capped by
+        // getRetryWaitCeilingMs, #3452) to a bounded, logged failure (#2102).
         this.connectionTimeout = options?.connectionTimeout ?? 10_000;
         this.tokenStorageKey = `forgecart:auth:${this.endpoint}:${this.baseHeaders["forgecart-token"] ?? ""}`;
         if (this.persistSession) {
@@ -206,8 +219,17 @@ class BaseGraphQLClient {
                 // exponential backoff. A DISPOSED client answers false (#1994):
                 // graphql-ws consults its own disposed flag before asking, so a
                 // pending operation completes at dispose() instead of re-dialing
-                // a dead endpoint for 32-46 s and erroring onto whoever runs then.
+                // a dead endpoint through the rest of the ladder and erroring onto
+                // whoever runs then.
                 shouldRetry: () => !this.disposed,
+                // graphql-ws waits BEFORE it checks that an operation still holds
+                // the socket, and resets its count only on an ack: past the ladder
+                // every refused dial adds one, so its own waits double without end
+                // (32, 64, 128, 256 s) while every operation gives up at its bound
+                // first — after a long outage a quiet client never dialled again.
+                // The cap keeps every wait inside the bound of the operation that
+                // waits on it, so the shared socket heals on the next call (#3452).
+                retryWait: (retries) => this.waitBeforeRedial(retries),
             });
             const connectionState = { connected: false, disposed: false, pending: new Set() };
             WS_CONNECTION_STATE.set(this.wsClient, connectionState);
@@ -539,7 +561,7 @@ class BaseGraphQLClient {
                 },
             });
             // Armed only while the socket is not ACK-live. An unanswered handshake
-            // otherwise rides the whole graphql-ws retry ladder (32.5-46 s) with
+            // otherwise rides the whole graphql-ws retry ladder (18.6-24 s) with
             // nothing logged anywhere — the shape a pathless endpoint produces, and
             // a Suspense hole with no line to explain it. The shared socket is NOT
             // disposed and shouldRetry is untouched: graphql-ws keeps healing for the
@@ -692,6 +714,32 @@ class BaseGraphQLClient {
             return WsTimeoutBudgetMs.QUERY_FIRST_VALUE;
         return WsTimeoutBudgetMs.MUTATION_FIRST_VALUE;
     }
+    /**
+     * The longest graphql-ws waits before any re-dial (#3452): half the shorter
+     * of the handshake bound and a read's first-value deadline, so 5_000 ms at
+     * the defaults and 1_000 ms at a connectionTimeout of 2_000. A wait that
+     * starts with an operation therefore ends inside that operation's own
+     * bound, and the dial it leads to keeps the other half to be answered.
+     * A get*, not a find*: derived configuration, never a lookup.
+     */
+    getRetryWaitCeilingMs() {
+        return Math.min(this.connectionTimeout, WsTimeoutBudgetMs.QUERY_FIRST_VALUE) / 2;
+    }
+    /**
+     * graphql-ws's retryWait (#3452): the library's own randomised exponential
+     * delay, never longer than getRetryWaitCeilingMs(). graphql-ws resets its
+     * retry count only on an ack, so uncapped the delay doubles past its ladder
+     * for as long as an outage lasts; capped, the next operation after the
+     * outage re-dials within seconds. The timer stays a plain, reffed
+     * setTimeout: it replaces graphql-ws's own one for one and changes only
+     * how long it runs.
+     */
+    async waitBeforeRedial(retries) {
+        const jitterMs = Math.floor(Math.random() * (WsRetryBackoffMs.JITTER_MAX - WsRetryBackoffMs.JITTER_MIN) + WsRetryBackoffMs.JITTER_MIN);
+        const backoffMs = WsRetryBackoffMs.BASE * 2 ** retries + jitterMs;
+        const waitMs = Math.min(backoffMs, this.getRetryWaitCeilingMs());
+        await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
     /**
      * The name the document declares: `query ChannelPlugins` gives
      * "ChannelPlugins". Every generated document is a named operation, so the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgecart/sdk",
-  "version": "1.202610251643.0",
+  "version": "1.202610251830.0",
   "description": "ForgeCart Client SDK",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/client.generated.ts

@@ -21,9 +21,12 @@ export interface ForgeCartAdminClientConfig {
   // Upper bound (ms) on an UNANSWERED graphql-ws handshake, per operation.
   // Defaults to 10_000. A healthy handshake is milliseconds and graphql-ws
   // waits ~1-4 s before its first re-dial, so the default still lets one
-  // transient refusal heal while the caller stops waiting out the 32.5-46 s
-  // retry ladder in silence (#2102). Never bounds a connected operation: a
-  // live subscription runs for as long as the server streams.
+  // transient refusal heal while the caller stops waiting out the 18.6-24 s
+  // retry ladder in silence (#2102). Half the shorter of this and a read's
+  // 10 s deadline caps every wait before a re-dial — 5 s at the default —
+  // so after an outage of any length the next operation re-dials within
+  // that cap (#3452). Never bounds a connected operation: a live
+  // subscription runs for as long as the server streams.
   connectionTimeout?: number;
   channelToken: string;
   adminSecret?: string;
@@ -51,9 +54,12 @@ export interface ForgeCartShopClientConfig {
   // Upper bound (ms) on an UNANSWERED graphql-ws handshake, per operation.
   // Defaults to 10_000. A healthy handshake is milliseconds and graphql-ws
   // waits ~1-4 s before its first re-dial, so the default still lets one
-  // transient refusal heal while the caller stops waiting out the 32.5-46 s
-  // retry ladder in silence (#2102). Never bounds a connected operation: a
-  // live subscription runs for as long as the server streams.
+  // transient refusal heal while the caller stops waiting out the 18.6-24 s
+  // retry ladder in silence (#2102). Half the shorter of this and a read's
+  // 10 s deadline caps every wait before a re-dial — 5 s at the default —
+  // so after an outage of any length the next operation re-dials within
+  // that cap (#3452). Never bounds a connected operation: a live
+  // subscription runs for as long as the server streams.
   connectionTimeout?: number;
   channelToken: string;
   uploadEndpoint?: string;
@@ -77,9 +83,12 @@ export interface ForgeCartClientConfig {
   // Upper bound (ms) on an UNANSWERED graphql-ws handshake, per operation.
   // Defaults to 10_000. A healthy handshake is milliseconds and graphql-ws
   // waits ~1-4 s before its first re-dial, so the default still lets one
-  // transient refusal heal while the caller stops waiting out the 32.5-46 s
-  // retry ladder in silence (#2102). Never bounds a connected operation: a
-  // live subscription runs for as long as the server streams.
+  // transient refusal heal while the caller stops waiting out the 18.6-24 s
+  // retry ladder in silence (#2102). Half the shorter of this and a read's
+  // 10 s deadline caps every wait before a re-dial — 5 s at the default —
+  // so after an outage of any length the next operation re-dials within
+  // that cap (#3452). Never bounds a connected operation: a live
+  // subscription runs for as long as the server streams.
   connectionTimeout?: number;
   channelToken: string;
   adminSecret?: string;
@@ -214,6 +223,18 @@ enum WsTimeoutBudgetMs {
   MUTATION_FIRST_VALUE = 60_000,
 }
 
+/**
+ * graphql-ws's own randomised exponential backoff, which the library does
+ * not export: it waits BASE * 2 ** retries plus JITTER_MIN..JITTER_MAX of
+ * jitter before every re-dial. Restated so waitBeforeRedial can keep that
+ * delay and only cap it (#3452).
+ */
+enum WsRetryBackoffMs {
+  BASE = 1_000,
+  JITTER_MIN = 300,
+  JITTER_MAX = 3_000,
+}
+
 /**
  * The per-OPERATION first-value budgets (#2245). A kind default sizes the
  * average operation of that kind; an operation that holds the socket for a
@@ -302,7 +323,8 @@ export class BaseGraphQLClient {
     // A healthy handshake is milliseconds, and graphql-ws waits ~1-4 s before
     // its first re-dial — so 10 s still lets ONE transient non-101 refusal heal
     // (the retry-safety in getWsClient) while cutting the SILENT window from the
-    // measured 32.5-46 s ladder to a bounded, logged failure (#2102).
+    // retry ladder (18.6-24 s at the default bounds, every wait capped by
+    // getRetryWaitCeilingMs, #3452) to a bounded, logged failure (#2102).
     this.connectionTimeout = options?.connectionTimeout ?? 10_000;
     this.tokenStorageKey = `forgecart:auth:${this.endpoint}:${this.baseHeaders["forgecart-token"] ?? ""}`;
     if (this.persistSession) {
@@ -349,8 +371,17 @@ export class BaseGraphQLClient {
         // exponential backoff. A DISPOSED client answers false (#1994):
         // graphql-ws consults its own disposed flag before asking, so a
         // pending operation completes at dispose() instead of re-dialing
-        // a dead endpoint for 32-46 s and erroring onto whoever runs then.
+        // a dead endpoint through the rest of the ladder and erroring onto
+        // whoever runs then.
         shouldRetry: () => !this.disposed,
+        // graphql-ws waits BEFORE it checks that an operation still holds
+        // the socket, and resets its count only on an ack: past the ladder
+        // every refused dial adds one, so its own waits double without end
+        // (32, 64, 128, 256 s) while every operation gives up at its bound
+        // first — after a long outage a quiet client never dialled again.
+        // The cap keeps every wait inside the bound of the operation that
+        // waits on it, so the shared socket heals on the next call (#3452).
+        retryWait: (retries) => this.waitBeforeRedial(retries),
       });
       const connectionState = { connected: false, disposed: false, pending: new Set<PendingOperation>() };
       WS_CONNECTION_STATE.set(this.wsClient, connectionState);
@@ -700,7 +731,7 @@ export class BaseGraphQLClient {
       );
 
       // Armed only while the socket is not ACK-live. An unanswered handshake
-      // otherwise rides the whole graphql-ws retry ladder (32.5-46 s) with
+      // otherwise rides the whole graphql-ws retry ladder (18.6-24 s) with
       // nothing logged anywhere — the shape a pathless endpoint produces, and
       // a Suspense hole with no line to explain it. The shared socket is NOT
       // disposed and shouldRetry is untouched: graphql-ws keeps healing for the
@@ -851,6 +882,34 @@ export class BaseGraphQLClient {
     return WsTimeoutBudgetMs.MUTATION_FIRST_VALUE;
   }
 
+  /**
+   * The longest graphql-ws waits before any re-dial (#3452): half the shorter
+   * of the handshake bound and a read's first-value deadline, so 5_000 ms at
+   * the defaults and 1_000 ms at a connectionTimeout of 2_000. A wait that
+   * starts with an operation therefore ends inside that operation's own
+   * bound, and the dial it leads to keeps the other half to be answered.
+   * A get*, not a find*: derived configuration, never a lookup.
+   */
+  private getRetryWaitCeilingMs(): number {
+    return Math.min(this.connectionTimeout, WsTimeoutBudgetMs.QUERY_FIRST_VALUE) / 2;
+  }
+
+  /**
+   * graphql-ws's retryWait (#3452): the library's own randomised exponential
+   * delay, never longer than getRetryWaitCeilingMs(). graphql-ws resets its
+   * retry count only on an ack, so uncapped the delay doubles past its ladder
+   * for as long as an outage lasts; capped, the next operation after the
+   * outage re-dials within seconds. The timer stays a plain, reffed
+   * setTimeout: it replaces graphql-ws's own one for one and changes only
+   * how long it runs.
+   */
+  private async waitBeforeRedial(retries: number): Promise<void> {
+    const jitterMs = Math.floor(Math.random() * (WsRetryBackoffMs.JITTER_MAX - WsRetryBackoffMs.JITTER_MIN) + WsRetryBackoffMs.JITTER_MIN);
+    const backoffMs = WsRetryBackoffMs.BASE * 2 ** retries + jitterMs;
+    const waitMs = Math.min(backoffMs, this.getRetryWaitCeilingMs());
+    await new Promise<void>((resolve) => setTimeout(resolve, waitMs));
+  }
+
   /**
    * The name the document declares: `query ChannelPlugins` gives
    * "ChannelPlugins". Every generated document is a named operation, so the