@friggframework/core 2.0.0--canary.658.93c8e07.0 → 2.0.0--canary.656.4fb07b4.0

package/modules/module.js

@@ -51,8 +51,6 @@ class Module extends Delegate {
         this.delegateTypes.push(this.DLGT_CREDENTIAL_INVALIDATED);
         this.DLGT_CREDENTIAL_VALIDATED = 'CREDENTIAL_VALIDATED';
         this.delegateTypes.push(this.DLGT_CREDENTIAL_VALIDATED);
-        this.DLGT_RATE_LIMITED = 'RATE_LIMITED';
-        this.delegateTypes.push(this.DLGT_RATE_LIMITED);
 
         Object.assign(this, this.definition.requiredAuthMethods);
 
@@ -162,8 +160,6 @@ class Module extends Delegate {
             await this.deauthorize();
         } else if (delegateString === this.api.DLGT_INVALID_AUTH) {
             await this.markCredentialsInvalid(object);
-        } else if (delegateString === this.api.DLGT_RATE_LIMITED) {
-            await this.reportRateLimit(object);
         } else if (delegateString === this.api.DLGT_CREDENTIAL_RELOAD) {
             return this.reloadCredential();
         }
@@ -238,32 +234,6 @@ class Module extends Delegate {
         }
     }
 
-    /**
-     * Passes a rate limit the api reported to the parent delegate, best
-     * effort. The payload never holds the error's message, url, body or
-     * headers, because the parent shows it to end users.
-     * @param {import('../errors').RateLimitError} rateLimitError
-     */
-    async reportRateLimit(rateLimitError) {
-        const { reason, retryAt, policy, statusCode } = rateLimitError;
-        const links = this.apiClass.rateLimit?.userHints?.[reason]?.links ?? [];
-        try {
-            await this.notify(this.DLGT_RATE_LIMITED, {
-                moduleName: this.name,
-                reason,
-                retryAt,
-                policy,
-                statusCode,
-                links,
-            });
-        } catch (err) {
-            this.logger.error('Failed to propagate RATE_LIMITED', {
-                eventName: `${this.logger.name}.rate_limited_propagation_failed`,
-                error: err,
-            });
-        }
-    }
-
     async deauthorize() {
         //todo: Check if this is correct, we're instantiating a new api without params (credentials, tokens, etc...)
         this.api = new this.apiClass();

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

@@ -34,11 +34,6 @@ function readKeys(headers, wanted) {
     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();
@@ -70,10 +65,6 @@ function definedOnly(fields) {
     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;
@@ -86,9 +77,6 @@ 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() : Number.NaN;
     if (Number.isNaN(at)) return null;
@@ -103,9 +91,6 @@ function parseDate(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();
@@ -145,10 +130,6 @@ function parseResetValue(text, now, extra) {
     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)
@@ -222,11 +203,6 @@ function readKeyValue(text, key) {
     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;
@@ -259,6 +235,7 @@ const BUILT_IN_PARSERS = {
 module.exports = {
     BUILT_IN_PARSERS,
     MAX_HINT_WAIT_MS,
+    definedOnly,
     headerValue,
     hintFromRetryAt,
     hintFromWait,

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

@@ -1,5 +1,6 @@
 const {
     BUILT_IN_PARSERS,
+    definedOnly,
     hintFromRetryAt,
     hintFromWait,
 } = require('./parsers');
@@ -24,6 +25,7 @@ const normalizedPolicies = new WeakSet();
 const policiesByClass = new WeakMap();
 
 const isObject = (value) => value !== null && typeof value === 'object';
+const isThenable = (value) => typeof value?.then === 'function';
 
 function isPlainObject(value) {
     if (!isObject(value) || Array.isArray(value)) return false;
@@ -31,14 +33,6 @@ function isPlainObject(value) {
     return prototype === Object.prototype || prototype === null;
 }
 
-function definedOnly(fields) {
-    const result = {};
-    for (const [key, value] of Object.entries(fields)) {
-        if (value !== undefined) result[key] = value;
-    }
-    return result;
-}
-
 function readParsers(raw, owner) {
     if (!Array.isArray(raw.parsers)) return [...DEFAULT_PARSERS];
     for (const name of raw.parsers) {
@@ -79,11 +73,6 @@ function normalizePolicy(raw, owner) {
     return policy;
 }
 
-/**
- * Reads the static `rateLimit` policy of an API module class. Returns
- * undefined when the class declares none. The result is memoized per class.
- * Throws a TypeError for a parser name that is not built in.
- */
 function readRateLimitPolicy(ctor) {
     if (typeof ctor !== 'function') return undefined;
     if (policiesByClass.has(ctor)) return policiesByClass.get(ctor);
@@ -98,10 +87,6 @@ function asPolicy(value) {
     return normalizePolicy(value, 'policy');
 }
 
-/**
- * The key a limit counts against, for one requester. Undefined when the
- * scope needs an id that the requester does not have.
- */
 function computeScopeKey(policy, requester) {
     const label = requester?._telemetryModuleLabel?.() ?? 'unknown';
     const scope = policy?.scope ?? 'entity';
@@ -136,8 +121,18 @@ function computeScopeKey(policy, requester) {
     return undefined;
 }
 
+function toDate(value) {
+    if (value === undefined || value === null) return null;
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+
 function normalizeClassified(raw, now) {
     if (!isObject(raw)) return null;
+    const retryAt = toDate(raw.retryAt);
+    if (!REASONS.has(raw.reason) && !Number.isFinite(raw.waitMs) && !retryAt) {
+        return null;
+    }
 
     const extra = {
         reason: REASONS.has(raw.reason) ? raw.reason : 'unknown',
@@ -146,12 +141,7 @@ function normalizeClassified(raw, now) {
         source: CLASSIFY_SOURCES.has(raw.source) ? raw.source : 'body',
     };
 
-    let hint = null;
-    if (raw.retryAt !== undefined && raw.retryAt !== null) {
-        const date =
-            raw.retryAt instanceof Date ? raw.retryAt : new Date(raw.retryAt);
-        hint = hintFromRetryAt(date, now, extra);
-    }
+    let hint = retryAt ? hintFromRetryAt(retryAt, now, extra) : null;
     if (!hint && Number.isFinite(raw.waitMs)) {
         hint = hintFromWait(raw.waitMs, now, extra);
     }
@@ -172,6 +162,12 @@ function runClassify(policy, signal, now, onClassifyError) {
             headers: signal.headers,
             body: signal.body,
         });
+        if (isThenable(raw)) {
+            Promise.resolve(raw).catch(() => {});
+            throw new TypeError(
+                'classify() must return a hint or null, not a Promise'
+            );
+        }
     } catch (error) {
         if (!onClassifyError) throw error;
         onClassifyError(error);
@@ -226,28 +222,12 @@ function resolveCandidates(policy, signal, { now, onClassifyError }) {
     return { hint: null, classified };
 }
 
-/**
- * Finds the hint of a throttled response: the module's classify(), then the
- * header parsers, then the static policy. Returns null when there is none.
- * A status other than 429 counts only when classify recognised it.
- *
- * @param {object} [policy] The static `rateLimit` object of an API module.
- * @param {{status?: number, headers?: object, body?: unknown}} signal
- * @param {{now?: number, onClassifyError?: (error: Error) => void}} [options]
- *   Without `onClassifyError` an error thrown by classify propagates.
- */
 function classifyRateLimit(policy, signal, options = {}) {
     const { now = Date.now(), onClassifyError } = options;
     return resolveCandidates(asPolicy(policy), signal, { now, onClassifyError })
         .hint;
 }
 
-/**
- * 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 {
         attempt = 0,
@@ -276,11 +256,6 @@ function resolveRateLimitHint(policy, signal, options = {}) {
     };
 }
 
-/**
- * The wait before the next attempt, for a hint that came from the provider
- * or the policy. Jitter only adds to the wait and never passes the budget.
- * `fits` is false when the wait alone is over the budget.
- */
 function computeWaitMs({ hint, policy, budgetMs, random = Math.random }) {
     const base = Math.max(
         hint.waitMs,
@@ -295,10 +270,6 @@ function computeWaitMs({ hint, policy, budgetMs, random = Math.random }) {
     return { waitMs: Math.min(base + jitter, budgetMs), fits: true };
 }
 
-/**
- * How long this request may still sleep in process: the cap, less what it
- * slept already, and the time left in the invocation, less one request.
- */
 function inProcessBudgetMs({
     policy,
     requestTimeoutMs = 0,
@@ -306,10 +277,8 @@ function inProcessBudgetMs({
     waitedMs = 0,
 } = {}) {
     const cap = policy?.maxInProcessWaitMs ?? DEFAULT_MAX_IN_PROCESS_WAIT_MS;
-    return Math.max(
-        0,
-        Math.min(cap - waitedMs, remainingMs - (requestTimeoutMs || 0))
-    );
+    const reserveMs = Math.min(requestTimeoutMs || 0, remainingMs / 2);
+    return Math.max(0, Math.min(cap - waitedMs, remainingMs - reserveMs));
 }
 
 module.exports = {

package/modules/requester/requester.js

@@ -12,7 +12,6 @@ const { getLoggerScope } = require('../../logs/context');
 const {
     computeScopeKey,
     computeWaitMs,
-    headerValue,
     inProcessBudgetMs,
     readRateLimitPolicy,
     resolveRateLimitHint,
@@ -20,18 +19,6 @@ const {
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 
-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.
 function sanitizedCause(err) {
@@ -67,8 +54,6 @@ class Requester extends Delegate {
         this._authGeneration = 0;
         this.DLGT_INVALID_AUTH = 'INVALID_AUTH';
         this.delegateTypes.push(this.DLGT_INVALID_AUTH);
-        this.DLGT_RATE_LIMITED = 'RATE_LIMITED';
-        this.delegateTypes.push(this.DLGT_RATE_LIMITED);
         this.agent = get(params, 'agent', null);
 
         // Per-attempt HTTP timeout. Without this the framework called fetch()
@@ -237,9 +222,6 @@ class Requester extends Delegate {
      * @param {number} attempt - 0-based count of retries already made for
      *   this call. Indexes `this.backOff` for the next delay and is passed
      *   back in on each recursive retry.
-     * @param {number} waitedMs - Milliseconds this call has slept already
-     *   for a wait that a provider or a policy set. It counts against the
-     *   in-process cap.
      */
     async _rawRequest(url, options, attempt = 0, waitedMs = 0) {
         let encodedUrl = encodeURI(url);
@@ -336,7 +318,7 @@ class Requester extends Delegate {
                 status,
                 attempt
             );
-            const throttleRetry = await this._throttleRetry({
+            const hintedDelayMs = await this._hintedRetryDelayMs({
                 throttle,
                 status,
                 attempt,
@@ -346,21 +328,24 @@ class Requester extends Delegate {
                 response,
                 timeoutMs,
             });
-            if (throttleRetry) {
+            if (hintedDelayMs !== null) {
                 clearRequestTimer();
                 await new Promise((resolve) =>
-                    setTimeout(resolve, throttleRetry.delayMs)
+                    setTimeout(resolve, hintedDelayMs)
                 );
                 return this._rawRequest(
                     url,
                     options,
                     attempt + 1,
-                    waitedMs + throttleRetry.hintedMs
+                    waitedMs + hintedDelayMs
                 );
             }
 
             // If the status is retriable and there are back off requests left, retry the request
-            if (status >= 500 && attempt < this.backOff.length) {
+            if (
+                (throttle?.throttled || status >= 500) &&
+                attempt < this.backOff.length
+            ) {
                 clearRequestTimer();
                 const delay = this.backOff[attempt] * 1000;
                 await new Promise((resolve) => setTimeout(resolve, delay));
@@ -499,16 +484,7 @@ 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({
+    async _hintedRetryDelayMs({
         throttle,
         status,
         attempt,
@@ -518,35 +494,28 @@ class Requester extends Delegate {
         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;
+        if (!throttle?.throttled || throttle.hint.source === 'backoff') {
+            return null;
         }
-
-        const budgetMs = inProcessBudgetMs({
-            policy: this._rateLimitPolicy,
-            requestTimeoutMs: this.requestTimeoutMs,
-            remainingMs: remainingInvocationMs(),
-            waitedMs,
-        });
+        const { hint } = throttle;
+        const budgetMs = this.backOff.length
+            ? inProcessBudgetMs({
+                  policy: this._rateLimitPolicy,
+                  requestTimeoutMs: this.requestTimeoutMs,
+                  remainingMs: remainingInvocationMs(),
+                  waitedMs,
+              })
+            : 0;
         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 };
+        if (fits) {
+            this._logRateLimited({ status, hint, waitMs, attempt, waitedMs });
+            return waitMs;
+        }
 
         this._logRequestFailed(encodedUrl, options, status);
         const rateLimitError = await RateLimitError.create({
@@ -559,18 +528,9 @@ class Requester extends Delegate {
             module: this._telemetryModuleLabel(),
             scopeKey: computeScopeKey(this._rateLimitPolicy, this),
         });
-        await this._notifyRateLimited(rateLimitError);
         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
-     * a limit. The body is read here, once, only for classify(); the text is
-     * handed on so the error need not read the stream again.
-     *
-     * @returns {Promise<{throttled: boolean, hint?: object, responseBody?: string}|null>}
-     */
     async _detectThrottle(response, status, attempt) {
         const policy = this._rateLimitPolicy;
         const canClassify =
@@ -605,9 +565,6 @@ class Requester extends Delegate {
             return {};
         }
         const text = await response.text();
-        if (!isJsonMediaType(headerValue(response.headers, 'content-type'))) {
-            return { text };
-        }
         try {
             return { text, json: JSON.parse(text) };
         } catch {
@@ -615,9 +572,9 @@ class Requester extends Delegate {
         }
     }
 
-    _logRateLimited({ status, hint, waitMs, attempt, waitedMs, action }) {
+    _logRateLimited({ status, hint, waitMs, attempt, waitedMs }) {
         const logger = this.logger;
-        logger.info('Rate limited', {
+        logger.trace('Rate limited', {
             eventName: `${logger.name}.rate_limited`,
             statusCode: status,
             waitMs,
@@ -626,7 +583,6 @@ class Requester extends Delegate {
             hintSource: hint.source,
             attempt,
             waitedMs,
-            action,
         });
     }
 
@@ -639,24 +595,6 @@ class Requester extends Delegate {
         });
     }
 
-    /**
-     * Tells the delegate a wait was too long to sleep. Best effort: a failed
-     * notification is logged and never replaces the RateLimitError the caller
-     * is about to receive.
-     */
-    async _notifyRateLimited(rateLimitError) {
-        try {
-            await this.notify(this.DLGT_RATE_LIMITED, rateLimitError);
-        } catch (error) {
-            const logger = this.logger;
-            logger.warn('Rate limit notification failed', {
-                eventName: `${logger.name}.rate_limit_notify_failed`,
-                statusCode: rateLimitError.statusCode,
-                error,
-            });
-        }
-    }
-
     _logRequestFailed(encodedUrl, options, status) {
         const logger = this.logger;
         if (!logger.isLevelEnabled('DEBUG')) return;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.658.93c8e07.0",
+    "version": "2.0.0--canary.656.4fb07b4.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -47,9 +47,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.658.93c8e07.0",
-        "@friggframework/prettier-config": "2.0.0--canary.658.93c8e07.0",
-        "@friggframework/test": "2.0.0--canary.658.93c8e07.0",
+        "@friggframework/eslint-config": "2.0.0--canary.656.4fb07b4.0",
+        "@friggframework/prettier-config": "2.0.0--canary.656.4fb07b4.0",
+        "@friggframework/test": "2.0.0--canary.656.4fb07b4.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -89,5 +89,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "93c8e078d4ff1bf00ed831152712b442abe615cd"
+    "gitHead": "4fb07b4e92324bbbf0d19153e2168642facc1182"
 }

package/types/core/index.d.ts

@@ -58,22 +58,13 @@ declare module "@friggframework/core" {
 
   export function loadInstalledModules(): any[];
 
-  /**
-   * Runs `fn` with the time the invocation ends, as epoch milliseconds. A
-   * nested scope can shorten the deadline and never extend it.
-   */
   export function runWithInvocationDeadline<T>(
     deadlineAt: number | undefined,
     fn: () => T
   ): T;
 
-  /** Milliseconds left in the invocation. `Infinity` outside a Lambda. */
   export function remainingInvocationMs(now?: number): number;
 
-  /**
-   * Finds the hint of a throttled response: the module's classify(), then the
-   * header parsers, then the static policy. Null when there is none.
-   */
   export function classifyRateLimit(
     policy: RateLimitPolicy | undefined,
     signal: RateLimitSignal,

package/types/errors/index.d.ts

@@ -16,10 +16,6 @@ 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;
 
@@ -35,29 +31,19 @@ declare module "@friggframework/errors" {
 
   export type RateLimitSource = "header" | "body" | "static" | "backoff";
 
-  /** What Frigg knows about when calls are accepted again. */
   export type RateLimitHint = {
-    /** When calls are accepted again. */
     retryAt: Date;
-    /** Milliseconds from the time the hint was read until `retryAt`. */
     waitMs: number;
     reason: RateLimitReason;
-    /** A provider policy name, when the response names one. */
     policy?: string;
-    /** Calls left in the window, when the response says. */
     remaining?: number;
     source: RateLimitSource;
   };
 
-  /**
-   * A FetchError for a response that said a limit was hit, and for which the
-   * response or the module's policy says when to call again.
-   */
   export class RateLimitError extends FetchError {
     constructor(options?: RateLimitErrorConstructor);
 
     isRateLimited: true;
-    /** When calls are accepted again. */
     retryAt: Date;
     waitMs: number;
     reason: RateLimitReason;
@@ -73,7 +59,6 @@ declare module "@friggframework/errors" {
 
   type RateLimitErrorConstructor = FetchErrorConstructor & {
     hint?: Partial<RateLimitHint>;
-    /** Wait from `now`. When absent, `hint.retryAt` sets the time. */
     waitMs?: number;
     module?: string;
     scopeKey?: string;

package/types/integrations/index.d.ts

@@ -1,27 +1,6 @@
 declare module "@friggframework/integrations" {
   import { Delegate, IFriggDelegate } from "@friggframework/core";
 
-  export type IntegrationMessageAction =
-    | { type: "RETRY_WHEN_READY" }
-    | { type: "LINK"; label: string; url: string };
-
-  /**
-   * A stored message. The framework stores the keys of an item as given, so a
-   * caller can add its own. A rate limit adds `code: "RATE_LIMITED"`,
-   * `module`, `reason`, `retryAt` (ISO 8601) and `actions`.
-   */
-  export interface IntegrationMessage {
-    title: string;
-    message: string;
-    timestamp: number;
-    code?: string;
-    module?: string;
-    reason?: string;
-    retryAt?: string;
-    actions?: IntegrationMessageAction[];
-    [key: string]: unknown;
-  }
-
   export interface Integration {
     entities: any[];
     userId: string;
@@ -29,10 +8,10 @@ declare module "@friggframework/integrations" {
     config: any;
     version: string;
     messages: {
-      errors: IntegrationMessage[];
-      warnings: IntegrationMessage[];
-      info: IntegrationMessage[];
-      logs: IntegrationMessage[];
+      errors: [];
+      warnings: [];
+      info: [];
+      logs: [];
     };
   }