@friggframework/core 2.0.0--canary.657.ebe5c60.0 → 2.0.0--canary.657.8f335eb.0

package/CLAUDE.md

@@ -381,7 +381,10 @@ in this order:
 | 4 | The fixed `backOff` ladder (1, 3, 10, 30, 60, 180 s) |
 
 - A 429 with no hint from steps 1 to 3 keeps today's ladder: the same calls,
-  the same delays, then a plain `FetchError`. Nothing budgets it.
+  the same delays, then a plain `FetchError`. Nothing budgets it. A response
+  that `classify` names as a limit but that has no time follows the same
+  ladder, and the last error is a `FetchError` flagged `isRateLimited` with
+  the `reason`, so the queue worker does not halt it.
 - With a hint, the wait is `max(hint, minRetryAfterMs, 1 s)` plus at most 10 %
   jitter. The total sleep of one request is capped at `maxInProcessWaitMs`
   (default 5 minutes) and at the time left in the invocation less one request

package/errors/fetch-error.js

@@ -58,7 +58,7 @@ class FetchError extends BaseError {
         const provided = options.responseBody ?? options.body;
         let responseBody = provided;
         if (
-            !responseBody &&
+            responseBody === undefined &&
             response &&
             !response.bodyUsed &&
             typeof response.text === 'function'

package/modules/requester/rate-limit/parsers.js

@@ -90,7 +90,7 @@ function hintFromWait(waitMs, now, { source = 'header', ...extra } = {}) {
  * Builds a hint from an absolute time. A time in the past waits 0 ms.
  */
 function hintFromRetryAt(retryAt, now, { source = 'header', ...extra } = {}) {
-    const at = retryAt instanceof Date ? retryAt.getTime() : NaN;
+    const at = retryAt instanceof Date ? retryAt.getTime() : Number.NaN;
     if (Number.isNaN(at)) return null;
     const waitMs = Math.max(0, at - now);
     if (waitMs > MAX_HINT_WAIT_MS) return null;
@@ -216,7 +216,7 @@ function pickStructured(items) {
 
 function readKeyValue(text, key) {
     const match = new RegExp(
-        `(?:^|[,;\\s])${key}\\s*=\\s*([^,;\\s]+)`,
+        String.raw`(?:^|[,;\s])${key}\s*=\s*([^,;\s]+)`,
         'i'
     ).exec(text);
     return match ? match[1] : undefined;

package/modules/requester/rate-limit/policy.js

@@ -243,8 +243,10 @@ function classifyRateLimit(policy, signal, options = {}) {
 }
 
 /**
- * Like classifyRateLimit, but always answers: with no hint it returns the
- * step of the fixed backoff ladder, with source "backoff".
+ * Like classifyRateLimit, but a throttled response always gets a hint: with
+ * none found it gets the step of the fixed backoff ladder, with source
+ * "backoff". Null when the response is not throttled: a status other than 429
+ * that classify did not recognise.
  */
 function resolveRateLimitHint(policy, signal, options = {}) {
     const {
@@ -258,6 +260,7 @@ function resolveRateLimitHint(policy, signal, options = {}) {
         onClassifyError,
     });
     if (hint) return hint;
+    if (signal.status !== 429 && !classified) return null;
 
     const waitMs =
         attempt < backOff.length ? Number(backOff[attempt]) * 1000 || 0 : 0;

package/modules/requester/requester.js

@@ -10,7 +10,6 @@ const { redactUrl } = require('../../logs/redact');
 const { toSanitizedSurrogate } = require('../../logs/serialize');
 const { getLoggerScope } = require('../../logs/context');
 const {
-    classifyRateLimit,
     computeScopeKey,
     computeWaitMs,
     headerValue,
@@ -20,7 +19,18 @@ const {
 } = require('./rate-limit');
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
-const JSON_CONTENT_TYPE = /^application\/(json|vnd\.api\+json|hal\+json)/;
+
+function isJsonMediaType(contentType) {
+    const mediaType = String(contentType ?? '')
+        .split(';')[0]
+        .trim()
+        .toLowerCase();
+    return (
+        mediaType === 'application/json' ||
+        mediaType === 'text/json' ||
+        mediaType.endsWith('+json')
+    );
+}
 
 // A node-fetch error message holds the raw URL, and util.inspect prints the
 // cause chain, so the FetchError keeps only a sanitized copy.
@@ -46,6 +56,7 @@ class Requester extends Delegate {
         super(params);
         this.backOff = get(params, 'backOff', [1, 3, 10, 30, 60, 180]);
         this._rateLimitPolicy = readRateLimitPolicy(this.constructor);
+        this._random = params?.random ?? Math.random;
         this.isRefreshable = false;
         this.refreshCount = 0;
         this.authGraceRetryCount = 0;
@@ -294,7 +305,12 @@ class Requester extends Delegate {
                     clearRequestTimer();
                     const delay = this.backOff[attempt] * 1000;
                     await new Promise((resolve) => setTimeout(resolve, delay));
-                    return this._rawRequest(url, options, attempt + 1);
+                    return this._rawRequest(
+                        url,
+                        options,
+                        attempt + 1,
+                        waitedMs
+                    );
                 }
                 const fetchError = await FetchError.create({
                     resource: encodedUrl,
@@ -318,70 +334,27 @@ class Requester extends Delegate {
                 status,
                 attempt
             );
-            if (throttle?.throttled) {
-                const { hint } = throttle;
-                if (hint.source === 'backoff') {
-                    if (attempt < this.backOff.length) {
-                        clearRequestTimer();
-                        const delay = this.backOff[attempt] * 1000;
-                        await new Promise((resolve) =>
-                            setTimeout(resolve, delay)
-                        );
-                        return this._rawRequest(
-                            url,
-                            options,
-                            attempt + 1,
-                            waitedMs
-                        );
-                    }
-                } else {
-                    const budgetMs = inProcessBudgetMs({
-                        policy: this._rateLimitPolicy,
-                        requestTimeoutMs: this.requestTimeoutMs,
-                        remainingMs: remainingInvocationMs(),
-                        waitedMs,
-                    });
-                    const { waitMs, fits } = computeWaitMs({
-                        hint,
-                        policy: this._rateLimitPolicy,
-                        budgetMs,
-                    });
-                    this._logRateLimited({
-                        status,
-                        hint,
-                        waitMs,
-                        attempt,
-                        waitedMs,
-                        action: fits ? 'wait' : 'throw',
-                    });
-                    if (fits) {
-                        clearRequestTimer();
-                        await new Promise((resolve) =>
-                            setTimeout(resolve, waitMs)
-                        );
-                        return this._rawRequest(
-                            url,
-                            options,
-                            attempt + 1,
-                            waitedMs + waitMs
-                        );
-                    }
-                    this._logRequestFailed(encodedUrl, options, status);
-                    const rateLimitError = await RateLimitError.create({
-                        resource: encodedUrl,
-                        init: options,
-                        response,
-                        responseBody: throttle.responseBody,
-                        hint,
-                        waitMs,
-                        module: this._telemetryModuleLabel(),
-                        scopeKey: computeScopeKey(this._rateLimitPolicy, this),
-                    });
-                    throw this._maybeFlagTimeoutDuringBodyRead(
-                        rateLimitError,
-                        timeoutMs
-                    );
-                }
+            const throttleRetry = await this._throttleRetry({
+                throttle,
+                status,
+                attempt,
+                waitedMs,
+                encodedUrl,
+                options,
+                response,
+                timeoutMs,
+            });
+            if (throttleRetry) {
+                clearRequestTimer();
+                await new Promise((resolve) =>
+                    setTimeout(resolve, throttleRetry.delayMs)
+                );
+                return this._rawRequest(
+                    url,
+                    options,
+                    attempt + 1,
+                    waitedMs + throttleRetry.hintedMs
+                );
             }
 
             // If the status is retriable and there are back off requests left, retry the request
@@ -389,7 +362,7 @@ class Requester extends Delegate {
                 clearRequestTimer();
                 const delay = this.backOff[attempt] * 1000;
                 await new Promise((resolve) => setTimeout(resolve, delay));
-                return this._rawRequest(url, options, attempt + 1);
+                return this._rawRequest(url, options, attempt + 1, waitedMs);
             }
 
             if (status === 401) {
@@ -410,7 +383,12 @@ class Requester extends Delegate {
                     // This request did not try the current token. Retry with
                     // it. Do not spend one more provider-side rotation.
                     clearRequestTimer();
-                    return this._rawRequest(url, options, attempt + 1);
+                    return this._rawRequest(
+                        url,
+                        options,
+                        attempt + 1,
+                        waitedMs
+                    );
                 }
 
                 if (!this.isRefreshable) {
@@ -427,7 +405,12 @@ class Requester extends Delegate {
                         await new Promise((resolve) =>
                             setTimeout(resolve, delay)
                         );
-                        return this._rawRequest(url, options, attempt + 1);
+                        return this._rawRequest(
+                            url,
+                            options,
+                            attempt + 1,
+                            waitedMs
+                        );
                     }
 
                     throw await this._invalidateAuth(
@@ -460,7 +443,12 @@ class Requester extends Delegate {
                 const refreshSucceeded = await this._refreshAuthOnce();
                 if (refreshSucceeded) {
                     clearRequestTimer();
-                    return this._rawRequest(url, options, attempt + 1);
+                    return this._rawRequest(
+                        url,
+                        options,
+                        attempt + 1,
+                        waitedMs
+                    );
                 }
 
                 throw await this._invalidateAuth(encodedUrl, options, response);
@@ -477,6 +465,10 @@ class Requester extends Delegate {
                     response,
                     responseBody: throttle?.responseBody,
                 });
+                if (throttle?.throttled && status !== 429) {
+                    fetchError.isRateLimited = true;
+                    fetchError.reason = throttle.hint.reason;
+                }
                 throw this._maybeFlagTimeoutDuringBodyRead(
                     fetchError,
                     timeoutMs
@@ -505,6 +497,69 @@ class Requester extends Delegate {
         }
     }
 
+    /**
+     * What to do about a throttled response: the delay before the next
+     * attempt, or null when there is no attempt left. A wait that a hint set
+     * and that does not fit the budget throws RateLimitError.
+     *
+     * @returns {Promise<{delayMs: number, hintedMs: number}|null>}
+     *   `hintedMs` is the part of the delay that a provider or a policy set,
+     *   which counts against the in-process cap.
+     */
+    async _throttleRetry({
+        throttle,
+        status,
+        attempt,
+        waitedMs,
+        encodedUrl,
+        options,
+        response,
+        timeoutMs,
+    }) {
+        if (!throttle?.throttled) return null;
+        const { hint } = throttle;
+        if (hint.source === 'backoff') {
+            return attempt < this.backOff.length
+                ? { delayMs: this.backOff[attempt] * 1000, hintedMs: 0 }
+                : null;
+        }
+
+        const budgetMs = inProcessBudgetMs({
+            policy: this._rateLimitPolicy,
+            requestTimeoutMs: this.requestTimeoutMs,
+            remainingMs: remainingInvocationMs(),
+            waitedMs,
+        });
+        const { waitMs, fits } = computeWaitMs({
+            hint,
+            policy: this._rateLimitPolicy,
+            budgetMs,
+            random: this._random,
+        });
+        this._logRateLimited({
+            status,
+            hint,
+            waitMs,
+            attempt,
+            waitedMs,
+            action: fits ? 'wait' : 'throw',
+        });
+        if (fits) return { delayMs: waitMs, hintedMs: waitMs };
+
+        this._logRequestFailed(encodedUrl, options, status);
+        const rateLimitError = await RateLimitError.create({
+            resource: encodedUrl,
+            init: options,
+            response,
+            responseBody: throttle.responseBody,
+            hint,
+            waitMs,
+            module: this._telemetryModuleLabel(),
+            scopeKey: computeScopeKey(this._rateLimitPolicy, this),
+        });
+        throw this._maybeFlagTimeoutDuringBodyRead(rateLimitError, timeoutMs);
+    }
+
     /**
      * Decides whether a response says a limit was hit. A 429 always does. A
      * 4xx or 5xx other than 401 does only when the module's classify() names
@@ -528,21 +583,17 @@ class Requester extends Delegate {
                 await this._readBodyForClassify(response));
         }
 
-        const signal = { status, headers: response.headers, body };
-        const options = {
-            attempt,
-            backOff: this.backOff,
-            now: Date.now(),
-            onClassifyError: (error) => this._logClassifyFailed(status, error),
-        };
-        if (status === 429) {
-            return {
-                throttled: true,
-                hint: resolveRateLimitHint(policy, signal, options),
-                responseBody,
-            };
-        }
-        const hint = classifyRateLimit(policy, signal, options);
+        const hint = resolveRateLimitHint(
+            policy,
+            { status, headers: response.headers, body },
+            {
+                attempt,
+                backOff: this.backOff,
+                now: Date.now(),
+                onClassifyError: (error) =>
+                    this._logClassifyFailed(status, error),
+            }
+        );
         return { throttled: Boolean(hint), hint, responseBody };
     }
 
@@ -551,11 +602,7 @@ class Requester extends Delegate {
             return {};
         }
         const text = await response.text();
-        if (
-            !JSON_CONTENT_TYPE.test(
-                headerValue(response.headers, 'content-type') || ''
-            )
-        ) {
+        if (!isJsonMediaType(headerValue(response.headers, 'content-type'))) {
             return { text };
         }
         try {

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.657.ebe5c60.0",
+    "version": "2.0.0--canary.657.8f335eb.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -48,9 +48,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.657.ebe5c60.0",
-        "@friggframework/prettier-config": "2.0.0--canary.657.ebe5c60.0",
-        "@friggframework/test": "2.0.0--canary.657.ebe5c60.0",
+        "@friggframework/eslint-config": "2.0.0--canary.657.8f335eb.0",
+        "@friggframework/prettier-config": "2.0.0--canary.657.8f335eb.0",
+        "@friggframework/test": "2.0.0--canary.657.8f335eb.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -90,5 +90,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "ebe5c602d3aac76850912c731dd91851772856b3"
+    "gitHead": "8f335eb16f678038ad9448d9603c734ad663b3dc"
 }

package/types/errors/index.d.ts

@@ -16,6 +16,12 @@ declare module "@friggframework/errors" {
     readonly body: any;
     isTimeout?: boolean;
     timeoutMs?: number;
+    /**
+     * True when `classify` named the response as a limit but gave no time. A
+     * `RateLimitError` always has it.
+     */
+    isRateLimited?: boolean;
+    reason?: RateLimitReason;
 
     static create(options?: CreateFetchErrorParams): Promise<FetchError>;
   }