@friggframework/core 2.0.0--canary.654.6d3a665.0 → 2.0.0--canary.656.10f1676.0

package/CLAUDE.md

@@ -369,6 +369,48 @@ class MyIntegration extends IntegrationBase {
 - `ApiKeyRequester` - API key authentication
 - `BasicAuthRequester` - Basic authentication
 
+**Rate limits** (ADR-049): an API module declares `static rateLimit` on its
+`Requester` subclass. For a throttled response the Requester looks for a hint
+in this order:
+
+| Step | Source |
+|---|---|
+| 1 | `classify({ status, headers, body })` of the module. It recognises a limit that is not a plain 429 (a 403 limit code, a `policyName` in the body) and may name only a `reason` |
+| 2 | The header parsers in `parsers` order. Default: `retryAfter`, `resetHeaders`, `ietf` |
+| 3 | The static policy: `minRetryAfterMs`, or the `perMs` of the window named by the `reason` |
+| 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.
+- 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
+  timeout (`remainingInvocationMs()`).
+- A wait that does not fit throws `RateLimitError` (`isRateLimited`, `retryAt`,
+  `waitMs`, `reason`, `policy`, `source`, `module`, `scopeKey`). The queue
+  worker does not halt it, whatever its status.
+- `Retry-After` is read on a 429 only. Another status counts only when
+  `classify` recognises it. A 5xx keeps the 5xx ladder.
+- `maxInProcessWaitMs: 0` turns off sleeping: every hinted wait throws.
+- A module that does not use the Requester (for example one on jsforce) calls
+  `classifyRateLimit(policy, { status, headers, body })` around its own client
+  and throws `RateLimitError` itself.
+
+```javascript
+class Api extends OAuth2Requester {
+    static rateLimit = {
+        scope: 'entity',
+        minRetryAfterMs: 1_000,
+        classify({ status, body }) {
+            if (status === 403 && body?.code === 'DAILY_LIMIT') {
+                return { reason: 'daily', waitMs: 60 * 60_000 };
+            }
+            return null;
+        },
+    };
+}
+```
+
 **Module Factory**:
 - `ModuleFactory` - Creates and configures API module instances
 - Handles credential injection
@@ -477,7 +519,8 @@ handlers (`{ req, res, next }`) and `this.on` events do not.
 `isLastAttempt` is `false` when either count is unknown: a local or non-SQS
 invocation, or a queue whose redrive policy the stack does not own
 (`ownership.queue: 'external'`). The value is information only: core still
-rethrows retryable errors and discards halt errors (4xx except 408/429).
+rethrows retryable errors and discards halt errors (4xx except 408, 429 and
+errors with `isRateLimited`).
 
 Use it to end a run or count lost work on the final try: when a retryable
 error (429, 5xx, network) is about to be rethrown and `isLastAttempt` is
@@ -507,6 +550,7 @@ it as `FRIGG_QUEUE_MAX_RECEIVE_COUNT` on the queue worker function.
 **Error Types**:
 - `BaseError` - Base error class
 - `FetchError` - HTTP request failures
+- `RateLimitError` - A `FetchError` for a limit the provider or the module's policy says when to retry (`retryAt`)
 - `HaltError` - Stop processing without retry
 - `RequiredPropertyError` - Missing required parameters
 - `ParameterTypeError` - Invalid parameter type

package/core/CLAUDE.md

@@ -130,7 +130,7 @@ class MyIntegration extends Delegate {
 ### Lambda Handler Lifecycle
 1. **Pre-Execution Setup**:
    ```javascript
-   runInvocationScope({ requestId, handlerName, method, route, invocation }, …); // Logger scope for the invocation
+   runInvocationScope({ requestId, handlerName, method, route, invocation }, …); // Logger scope + invocation deadline (remainingInvocationMs())
    log.info('Handler invoked', { eventName: 'frigg.handler.invoked' });
    await secretsToEnv();                     // Secrets Manager injection
    await parametersToEnv();                  // SSM Parameter Store fetch (only when SSM_PARAMETER_PREFIX + FRIGG_SSM_OFFLOADED_KEYS are set)
@@ -226,6 +226,8 @@ const handler = createHandler({
    - Logs error but returns success
    - Prevents infinite retries for known issues
    - Used for graceful degradation scenarios
+   - The queue worker sets it on a 4xx except 408, 429 and errors with
+     `isRateLimited` (a provider limit signalled with 403 clears with time)
 
 ### Logging Strategy
 ```javascript

package/core/index.js

@@ -3,6 +3,10 @@ const { Worker } = require('./Worker');
 const { loadInstalledModules } = require('./load-installed-modules');
 const { createHandler } = require('./create-handler');
 const { runInvocationScope } = require('./invocation-scope');
+const {
+    runWithInvocationDeadline,
+    remainingInvocationMs,
+} = require('./invocation-deadline');
 
 module.exports = {
     Delegate,
@@ -10,4 +14,6 @@ module.exports = {
     loadInstalledModules,
     createHandler,
     runInvocationScope,
+    runWithInvocationDeadline,
+    remainingInvocationMs,
 };

package/core/invocation-deadline.js

@@ -0,0 +1,56 @@
+const { AsyncLocalStorage } = require('node:async_hooks');
+
+const STORE_KEY = Symbol.for('@friggframework/core.invocation-deadline');
+
+function storage() {
+    if (!globalThis[STORE_KEY]) {
+        globalThis[STORE_KEY] = new AsyncLocalStorage();
+    }
+    return globalThis[STORE_KEY];
+}
+
+/**
+ * Runs fn with the time the invocation ends, as epoch milliseconds. A nested
+ * scope can shorten the deadline and never extend it. A deadline that is not
+ * a finite number runs fn with no limit.
+ */
+function runWithInvocationDeadline(deadlineAt, fn) {
+    if (typeof deadlineAt !== 'number' || !Number.isFinite(deadlineAt)) {
+        return fn();
+    }
+    const outer = storage().getStore();
+    const effective = outer
+        ? Math.min(outer.deadlineAt, deadlineAt)
+        : deadlineAt;
+    return storage().run(Object.freeze({ deadlineAt: effective }), fn);
+}
+
+/**
+ * The end of a Lambda invocation, from its context. Undefined when the
+ * context cannot tell.
+ */
+function deadlineFromContext(context) {
+    try {
+        const remaining = context?.getRemainingTimeInMillis?.();
+        return typeof remaining === 'number' && Number.isFinite(remaining)
+            ? Date.now() + remaining
+            : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * Milliseconds left in the invocation. Infinity outside a deadline scope
+ * (tests, `frigg start`, scripts).
+ */
+function remainingInvocationMs(now = Date.now()) {
+    const store = storage().getStore();
+    return store ? Math.max(0, store.deadlineAt - now) : Infinity;
+}
+
+module.exports = {
+    deadlineFromContext,
+    remainingInvocationMs,
+    runWithInvocationDeadline,
+};

package/core/invocation-scope.js

@@ -1,6 +1,10 @@
 const { runInContext, LOGGER_SCOPE_KEY } = require('../logs/context');
 const { summarizeMessageBody } = require('../logs/summarize-event');
 const { flushSinks, hasFlushableSinks } = require('../logs/logger-runtime');
+const {
+    deadlineFromContext,
+    runWithInvocationDeadline,
+} = require('./invocation-deadline');
 
 // Bounds the tail latency telemetry adds to every warm invocation. Kept low so
 // an unreachable OTLP endpoint (e.g. a VPC Lambda with no NAT/egress) costs at
@@ -168,21 +172,26 @@ async function runInvocationScope(fields, fn, opts = {}) {
         flushTimeoutMs = DEFAULT_FLUSH_TIMEOUT_MS,
         context,
     } = opts;
-    return runInContext({ [LOGGER_SCOPE_KEY]: { ...(fields || {}) } }, async () => {
-        try {
-            return await fn();
-        } finally {
-            // Every step is guarded, so a flush never changes the result.
-            await flushInvocation({
-                telemetry,
-                usageRollup,
-                eventSummary,
-                shouldUseDatabase,
-                flushTimeoutMs,
-                context,
-            });
-        }
-    });
+    return runWithInvocationDeadline(deadlineFromContext(context), () =>
+        runInContext(
+            { [LOGGER_SCOPE_KEY]: { ...(fields || {}) } },
+            async () => {
+                try {
+                    return await fn();
+                } finally {
+                    // Every step is guarded, so a flush never changes the result.
+                    await flushInvocation({
+                        telemetry,
+                        usageRollup,
+                        eventSummary,
+                        shouldUseDatabase,
+                        flushTimeoutMs,
+                        context,
+                    });
+                }
+            }
+        )
+    );
 }
 
 function toCount(value) {

package/errors/fetch-error.js

@@ -55,12 +55,18 @@ class FetchError extends BaseError {
 
     static async create(options = {}) {
         const { response } = options;
-        let responseBody =
-            response && !response.bodyUsed && typeof response.text === 'function'
-                ? await response.text()
-                : null;
-        if (!responseBody) responseBody = options.responseBody ?? options.body;
-        return new FetchError({ ...options, responseBody });
+        const provided = options.responseBody ?? options.body;
+        let responseBody = provided;
+        if (
+            !responseBody &&
+            response &&
+            !response.bodyUsed &&
+            typeof response.text === 'function'
+        ) {
+            responseBody = (await response.text()) || provided;
+        }
+        const ErrorClass = typeof this === 'function' ? this : FetchError;
+        return new ErrorClass({ ...options, responseBody });
     }
 }
 

package/errors/index.js

@@ -1,6 +1,7 @@
 const { BaseError } = require('./base-error');
 const { FetchError } = require('./fetch-error');
 const { HaltError } = require('./halt-error');
+const { RateLimitError } = require('./rate-limit-error');
 const {
     RequiredPropertyError,
     ParameterTypeError,
@@ -11,6 +12,7 @@ module.exports = {
     BaseError,
     FetchError,
     HaltError,
+    RateLimitError,
     RequiredPropertyError,
     ParameterTypeError,
     ClientSafeError,

package/errors/rate-limit-error.js

@@ -0,0 +1,44 @@
+const { FetchError } = require('./fetch-error');
+
+function resolveTiming({ hint, waitMs, now }) {
+    if (waitMs !== undefined) {
+        return { waitMs, retryAt: new Date(now + waitMs) };
+    }
+    if (hint?.retryAt) {
+        const retryAt = new Date(hint.retryAt);
+        if (!Number.isNaN(retryAt.getTime())) {
+            return { waitMs: Math.max(0, retryAt.getTime() - now), retryAt };
+        }
+    }
+    const fallbackWaitMs = hint?.waitMs ?? 0;
+    return { waitMs: fallbackWaitMs, retryAt: new Date(now + fallbackWaitMs) };
+}
+
+/**
+ * A FetchError for a response that said a limit was hit and told us, or the
+ * module's policy told us, when to call again. `retryAt` is that time.
+ */
+class RateLimitError extends FetchError {
+    constructor({
+        hint,
+        waitMs,
+        module,
+        scopeKey,
+        now = Date.now(),
+        ...fetchErrorArgs
+    } = {}) {
+        super(fetchErrorArgs);
+
+        const timing = resolveTiming({ hint, waitMs, now });
+        this.isRateLimited = true;
+        this.waitMs = timing.waitMs;
+        this.retryAt = timing.retryAt;
+        this.reason = hint?.reason ?? 'unknown';
+        this.policy = hint?.policy;
+        this.source = hint?.source ?? 'unknown';
+        this.module = module;
+        this.scopeKey = scopeKey;
+    }
+}
+
+module.exports = { RateLimitError };

package/handlers/backend-utils.js

@@ -285,7 +285,8 @@ const createQueueWorker = (integrationClass) => {
                     status >= 400 &&
                     status < 500 &&
                     status !== 408 &&
-                    status !== 429
+                    status !== 429 &&
+                    !error.isRateLimited
                 ) {
                     error.isHaltError = true;
                     console.warn(

package/index.js

@@ -12,6 +12,8 @@ const {
     loadInstalledModules,
     createHandler,
     runInvocationScope,
+    runWithInvocationDeadline,
+    remainingInvocationMs,
 } = require('./core/index');
 const {
     prisma,
@@ -55,6 +57,7 @@ const {
     BaseError,
     FetchError,
     HaltError,
+    RateLimitError,
     RequiredPropertyError,
     ParameterTypeError,
 } = require('./errors/index');
@@ -100,6 +103,12 @@ const {
     ModuleConstants,
     ModuleFactory,
 } = require('./modules/index');
+const {
+    classifyRateLimit,
+    parseRetryAfter,
+    parseResetHeaders,
+    parseIetfRateLimit,
+} = require('./modules/requester/rate-limit');
 const application = require('./application');
 const utils = require('./utils');
 
@@ -120,6 +129,8 @@ module.exports = {
     loadInstalledModules,
     createHandler,
     runInvocationScope,
+    runWithInvocationDeadline,
+    remainingInvocationMs,
 
     // database
     prisma,
@@ -142,9 +153,16 @@ module.exports = {
     BaseError,
     FetchError,
     HaltError,
+    RateLimitError,
     RequiredPropertyError,
     ParameterTypeError,
 
+    // rate limit
+    classifyRateLimit,
+    parseRetryAfter,
+    parseResetHeaders,
+    parseIetfRateLimit,
+
     // integrations
     IntegrationBase,
     Options,

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

@@ -0,0 +1,4 @@
+const parsers = require('./parsers');
+const policy = require('./policy');
+
+module.exports = { ...parsers, ...policy };

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

@@ -0,0 +1,268 @@
+const MAX_HINT_WAIT_MS = 366 * 24 * 60 * 60 * 1000;
+
+const SECONDS_PATTERN = /^\d+(?:\.\d+)?$/;
+const HAS_LETTER = /[A-Za-z]/;
+const EPOCH_SECONDS_MIN = 1e9;
+const EPOCH_MILLISECONDS_MIN = 1e12;
+
+const RESET_HEADERS = [
+    'x-ratelimit-reset',
+    'ratelimit-reset',
+    'x-rate-limit-reset',
+];
+const REMAINING_HEADERS = [
+    'x-ratelimit-remaining',
+    'ratelimit-remaining',
+    'x-rate-limit-remaining',
+];
+
+const isMissing = (value) => value === undefined || value === null;
+
+function readEntries(headers, wanted) {
+    for (const entry of headers) {
+        if (Array.isArray(entry) && String(entry[0]).toLowerCase() === wanted) {
+            return entry[1];
+        }
+    }
+    return undefined;
+}
+
+function readKeys(headers, wanted) {
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === wanted) return headers[key];
+    }
+    return undefined;
+}
+
+/**
+ * Reads one header from a Headers-like object, a Map, an entries array or a
+ * plain object. The name match is case-insensitive.
+ * @returns {string|undefined}
+ */
+function headerValue(headers, name) {
+    if (!headers || typeof headers !== 'object') return undefined;
+    const wanted = name.toLowerCase();
+    const hasGet = typeof headers.get === 'function';
+
+    let value;
+    if (hasGet) {
+        value = headers.get(name);
+        if (isMissing(value)) value = headers.get(wanted);
+    }
+    if (isMissing(value) && typeof headers[Symbol.iterator] === 'function') {
+        value = readEntries(headers, wanted);
+    }
+    if (isMissing(value) && !hasGet && !Array.isArray(headers)) {
+        value = readKeys(headers, wanted);
+    }
+    if (Array.isArray(value)) value = value[0];
+    if (isMissing(value)) return undefined;
+
+    const text = String(value).trim();
+    return text === '' ? undefined : text;
+}
+
+function definedOnly(fields) {
+    const result = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (value !== undefined) result[key] = value;
+    }
+    return result;
+}
+
+/**
+ * Builds a hint from a wait in ms. Returns null for a wait that is not a
+ * finite number in [0, MAX_HINT_WAIT_MS].
+ */
+function hintFromWait(waitMs, now, { source = 'header', ...extra } = {}) {
+    if (!Number.isFinite(waitMs) || waitMs < 0 || waitMs > MAX_HINT_WAIT_MS) {
+        return null;
+    }
+    return {
+        waitMs,
+        retryAt: new Date(now + waitMs),
+        ...definedOnly(extra),
+        source,
+    };
+}
+
+/**
+ * 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;
+    if (Number.isNaN(at)) return null;
+    const waitMs = Math.max(0, at - now);
+    if (waitMs > MAX_HINT_WAIT_MS) return null;
+    return { waitMs, retryAt: new Date(at), ...definedOnly(extra), source };
+}
+
+function parseDate(text) {
+    if (!HAS_LETTER.test(text)) return null;
+    const at = Date.parse(text);
+    return Number.isNaN(at) ? null : new Date(at);
+}
+
+/**
+ * Retry-After: delta seconds, an HTTP-date or an ISO timestamp.
+ */
+function parseRetryAfter(value, { now = Date.now() } = {}) {
+    if (isMissing(value)) return null;
+    const text = String(value).trim();
+    if (text === '') return null;
+    if (SECONDS_PATTERN.test(text))
+        return hintFromWait(Number(text) * 1000, now);
+    const date = parseDate(text);
+    return date ? hintFromRetryAt(date, now) : null;
+}
+
+function numberOrUndefined(text) {
+    if (text === undefined) return undefined;
+    const number = Number(text);
+    return Number.isFinite(number) ? number : undefined;
+}
+
+function firstHeader(headers, names) {
+    for (const name of names) {
+        const value = headerValue(headers, name);
+        if (value !== undefined) return value;
+    }
+    return undefined;
+}
+
+function parseResetValue(text, now, extra) {
+    if (SECONDS_PATTERN.test(text)) {
+        const number = Number(text);
+        if (number >= EPOCH_MILLISECONDS_MIN) {
+            return hintFromRetryAt(new Date(number), now, extra);
+        }
+        if (number >= EPOCH_SECONDS_MIN) {
+            return hintFromRetryAt(new Date(number * 1000), now, extra);
+        }
+        return hintFromWait(number * 1000, now, extra);
+    }
+    const date = parseDate(text);
+    return date ? hintFromRetryAt(date, now, extra) : null;
+}
+
+/**
+ * X-RateLimit-Reset and the other reset headers. The magnitude tells the
+ * unit: epoch milliseconds, epoch seconds, or delta seconds.
+ */
+function parseResetHeaders(headers, { now = Date.now() } = {}) {
+    const remaining = numberOrUndefined(
+        firstHeader(headers, REMAINING_HEADERS)
+    );
+    const extra = { remaining };
+
+    const after = headerValue(headers, 'x-ratelimit-reset-after');
+    if (after !== undefined && SECONDS_PATTERN.test(after)) {
+        return hintFromWait(Number(after) * 1000, now, extra);
+    }
+
+    for (const name of RESET_HEADERS) {
+        const value = headerValue(headers, name);
+        if (value === undefined) continue;
+        const hint = parseResetValue(value, now, extra);
+        if (hint) return hint;
+    }
+    return null;
+}
+
+function splitList(text) {
+    const items = [];
+    let current = '';
+    let quoted = false;
+    for (const char of text) {
+        if (char === '"') quoted = !quoted;
+        if (char === ',' && !quoted) {
+            items.push(current);
+            current = '';
+        } else {
+            current += char;
+        }
+    }
+    items.push(current);
+    return items.map((item) => item.trim()).filter(Boolean);
+}
+
+function parseStructuredItem(item) {
+    const [head, ...params] = item.split(';').map((part) => part.trim());
+    const values = {};
+    for (const param of params) {
+        const [key, raw] = param.split('=').map((part) => part.trim());
+        if (key) values[key] = numberOrUndefined(raw);
+    }
+    const name = head.replace(/^"|"$/g, '');
+    return {
+        name: name || undefined,
+        remaining: values.r,
+        waitSeconds: values.t,
+    };
+}
+
+function pickStructured(items) {
+    const usable = items.filter(
+        (item) => Number.isFinite(item.waitSeconds) && item.waitSeconds >= 0
+    );
+    usable.sort((a, b) => {
+        const byRemaining =
+            (a.remaining ?? Infinity) - (b.remaining ?? Infinity);
+        if (byRemaining !== 0 && !Number.isNaN(byRemaining)) return byRemaining;
+        return b.waitSeconds - a.waitSeconds;
+    });
+    return usable[0];
+}
+
+function readKeyValue(text, key) {
+    const match = new RegExp(
+        `(?:^|[,;\\s])${key}\\s*=\\s*([^,;\\s]+)`,
+        'i'
+    ).exec(text);
+    return match ? match[1] : undefined;
+}
+
+/**
+ * The IETF RateLimit field: the key=value form (limit=, remaining=, reset=)
+ * and the structured-field form ("name";r=0;t=12). The list form picks the
+ * policy with the fewest remaining calls, then the longest wait.
+ */
+function parseIetfRateLimit(headers, { now = Date.now() } = {}) {
+    const raw = headerValue(headers, 'ratelimit');
+    if (raw === undefined) return null;
+    const policyHeader = headerValue(headers, 'ratelimit-policy');
+
+    if (/;\s*t\s*=/.test(raw)) {
+        const chosen = pickStructured(splitList(raw).map(parseStructuredItem));
+        if (!chosen) return null;
+        return hintFromWait(chosen.waitSeconds * 1000, now, {
+            remaining: chosen.remaining,
+            policy: chosen.name ?? policyHeader,
+        });
+    }
+
+    const reset = readKeyValue(raw, 'reset');
+    if (reset === undefined || !SECONDS_PATTERN.test(reset)) return null;
+    return hintFromWait(Number(reset) * 1000, now, {
+        remaining: numberOrUndefined(readKeyValue(raw, 'remaining')),
+        policy: policyHeader,
+    });
+}
+
+const BUILT_IN_PARSERS = {
+    retryAfter: (headers, { now } = {}) =>
+        parseRetryAfter(headerValue(headers, 'retry-after'), { now }),
+    resetHeaders: parseResetHeaders,
+    ietf: parseIetfRateLimit,
+};
+
+module.exports = {
+    BUILT_IN_PARSERS,
+    MAX_HINT_WAIT_MS,
+    headerValue,
+    hintFromRetryAt,
+    hintFromWait,
+    parseIetfRateLimit,
+    parseResetHeaders,
+    parseRetryAfter,
+};