@littlebigbrain/client 0.5.1 → 0.6.0

package/dist/transport.d.ts

@@ -3,8 +3,10 @@ export interface CallOptions {
     idempotencyKey?: string;
     /** Override the client's per-attempt timeout. Set 0 to disable it. */
     timeoutMs?: number;
-    /** Override the client's retry count for this request. */
+    /** Override the client's retry count (secondary cap) for this request. */
     maxRetries?: number;
+    /** Override the client's deadline-based retry budget (ms) for this request. */
+    retryBudgetMs?: number;
     /** Override retry safety classification. Read-only POST namespaces set this automatically. */
     retry?: boolean;
     /** Abort the request and suppress any further retries. */
@@ -41,6 +43,34 @@ export declare function retryableStatus(status: number): boolean;
 export declare function retryAllowed(method: string, idempotencyKey?: string): boolean;
 /** Parse a Retry-After delta-seconds or HTTP-date value, capped at one minute. */
 export declare function parseRetryAfterMs(value: string | null | undefined, nowMs?: number): number | undefined;
-export declare function retryDelayForAttempt(baseDelayMs: number, attempt: number, retryAfter?: string | null): number;
+/**
+ * Full-jitter exponential backoff: `uniform(0, base * 2**attempt)`, capped at
+ * one minute. Replaces linear backoff so many clients recovering from one
+ * outage do not retry in lockstep (a thundering herd that re-triggers it).
+ */
+export declare function fullJitterBackoffMs(baseDelayMs: number, attempt: number, rng?: () => number): number;
+/**
+ * The server's own body hint `error.retry_after_seconds` in ms (capped), or
+ * `undefined` when the body is naked (a bare LB 5xx) or carries no hint. Used
+ * as the backoff when the `Retry-After` *header* is absent.
+ */
+export declare function retryAfterFromBodyMs(body: string): number | undefined;
+/** The parsed `error.code` from an error body, or `undefined` when absent/naked. */
+export declare function errorCodeFromBody(body: string): string | undefined;
+/**
+ * True iff the server explicitly marked this error non-retryable in the body
+ * (`error.retryable === false`) — a durable rejection (e.g. an exhausted quota)
+ * the client must surface immediately instead of spending its retry budget.
+ */
+export declare function bodyMarksTerminal(body: string): boolean;
+/**
+ * The backoff (ms) before the next attempt: the `Retry-After` header, else the
+ * server's body `retry_after_seconds` hint, else full-jitter exponential
+ * backoff.
+ */
+export declare function retryDelayMs(baseDelayMs: number, attempt: number, opts?: {
+    retryAfterHeader?: string | null;
+    body?: string;
+}, rng?: () => number): number;
 export declare function parseResponseJson<T>(text: string, status: number, requestId?: string): T;
 export declare function parseLbbError(status: number, body: string, fallbackRequestId?: string): LbbError;

package/dist/transport.js

@@ -62,9 +62,73 @@ export function parseRetryAfterMs(value, nowMs = Date.now()) {
         return undefined;
     return Math.min(Math.max(0, dateMs - nowMs), MAX_RETRY_AFTER_MS);
 }
-export function retryDelayForAttempt(baseDelayMs, attempt, retryAfter) {
-    const fallback = Math.max(0, baseDelayMs) * (attempt + 1);
-    return parseRetryAfterMs(retryAfter) ?? fallback;
+/**
+ * Full-jitter exponential backoff: `uniform(0, base * 2**attempt)`, capped at
+ * one minute. Replaces linear backoff so many clients recovering from one
+ * outage do not retry in lockstep (a thundering herd that re-triggers it).
+ */
+export function fullJitterBackoffMs(baseDelayMs, attempt, rng = Math.random) {
+    const ceiling = Math.min(Math.max(0, baseDelayMs) * 2 ** attempt, MAX_RETRY_AFTER_MS);
+    return rng() * ceiling;
+}
+/**
+ * The server's own body hint `error.retry_after_seconds` in ms (capped), or
+ * `undefined` when the body is naked (a bare LB 5xx) or carries no hint. Used
+ * as the backoff when the `Retry-After` *header* is absent.
+ */
+export function retryAfterFromBodyMs(body) {
+    try {
+        const parsed = JSON.parse(body);
+        const seconds = parsed.error?.retry_after_seconds;
+        if (typeof seconds === "number" &&
+            Number.isFinite(seconds) &&
+            seconds >= 0) {
+            return Math.min(seconds * 1_000, MAX_RETRY_AFTER_MS);
+        }
+    }
+    catch {
+        // Naked LB body (no error envelope) — no hint.
+    }
+    return undefined;
+}
+/** The parsed `error.code` from an error body, or `undefined` when absent/naked. */
+export function errorCodeFromBody(body) {
+    try {
+        const parsed = JSON.parse(body);
+        const code = parsed.error?.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True iff the server explicitly marked this error non-retryable in the body
+ * (`error.retryable === false`) — a durable rejection (e.g. an exhausted quota)
+ * the client must surface immediately instead of spending its retry budget.
+ */
+export function bodyMarksTerminal(body) {
+    try {
+        const parsed = JSON.parse(body);
+        return parsed.error?.retryable === false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The backoff (ms) before the next attempt: the `Retry-After` header, else the
+ * server's body `retry_after_seconds` hint, else full-jitter exponential
+ * backoff.
+ */
+export function retryDelayMs(baseDelayMs, attempt, opts = {}, rng = Math.random) {
+    const header = parseRetryAfterMs(opts.retryAfterHeader);
+    if (header !== undefined)
+        return header;
+    const bodyHint = opts.body !== undefined ? retryAfterFromBodyMs(opts.body) : undefined;
+    if (bodyHint !== undefined)
+        return bodyHint;
+    return fullJitterBackoffMs(baseDelayMs, attempt, rng);
 }
 export function parseResponseJson(text, status, requestId) {
     try {

package/dist/types.d.ts

@@ -171,16 +171,27 @@ export interface LbbClientOptions {
     fetch?: FetchLike;
     /** API version header sent on every request. Defaults to the beta reset contract. */
     apiVersion?: string;
-    /** Retry count for 429/5xx responses and network failures. Defaults to 2. */
+    /**
+     * Secondary safety cap on retries for 429/5xx responses and network failures.
+     * The binding limit is `retryBudgetMs`. Defaults to 6.
+     */
     maxRetries?: number;
     /** Base delay between retries. Defaults to 100ms. Tests can set 0. */
     retryDelayMs?: number;
+    /**
+     * Deadline-based retry budget (ms): keep retrying a retryable request until
+     * this much wall-clock has elapsed, so a server's advertised `Retry-After`
+     * window is honored rather than truncated by `maxRetries`. Defaults to 60000.
+     */
+    retryBudgetMs?: number;
     /** Per-attempt timeout, including response-body reads. Defaults to 120 seconds; 0 disables it. */
     timeoutMs?: number;
     /** Called immediately before each network attempt. Bodies and credentials are never included. */
     onRequest?: (event: LbbRequestEvent) => void;
     /** Called once after the final HTTP response. Bodies and credentials are never included. */
     onResponse?: (event: LbbResponseEvent) => void;
+    /** Called before each backoff sleep, so absorbed retries are observable. Bodies and credentials are never included. */
+    onRetry?: (event: LbbRetryEvent) => void;
 }
 export interface LbbRequestEvent {
     method: string;
@@ -198,6 +209,20 @@ export interface LbbResponseEvent {
     retryCount: number;
     elapsedMs: number;
 }
+export interface LbbRetryEvent {
+    method: string;
+    url: string;
+    /** 1-based number of the attempt that just failed and triggered this retry. */
+    attempt: number;
+    /** HTTP status of the failed attempt, or `undefined` for a network error. */
+    status?: number;
+    /** Parsed `error.code` of the failed attempt, when the body carried one. */
+    errorCode?: string;
+    /** The backoff (ms) about to be slept — header, body hint, or jittered backoff. */
+    delayMs: number;
+    /** Inclusive wall-clock elapsed (ms) across attempts and waits so far. */
+    elapsedMs: number;
+}
 export type LbbStackActivityWindow = "1h" | "4h" | "12h" | "24h";
 export interface LbbStackActivityResponse {
     ok: true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/client",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "TypeScript client for the little big brain graph + hybrid search HTTP API",
   "license": "Apache-2.0",
   "repository": {