@radiusplus/api-sdk-v2 0.5.0

package/src/rateLimitedTransport.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRateLimitedTransport = createRateLimitedTransport;
+const retryTransport_js_1 = require("./retryTransport.js");
+const rateLimitedQueue_js_1 = require("./rateLimitedQueue.js");
+// Thrown by the executor to route a 429 through the queue's pause/retry path. Carries the result
+// so the transport can surface it (letting the client's throwOnError build a proper error) once
+// retries are exhausted.
+class RateLimitError extends Error {
+    result;
+    constructor(result) {
+        super("Rate limited");
+        this.result = result;
+        this.name = "RateLimitError";
+    }
+}
+// Statuses the inner layer retries with backoff. 429 is intentionally excluded — it is driven by
+// the queue's pause-and-retry path instead.
+const DEFAULT_RETRYABLE_STATUSES = [408, 500, 502, 503, 504];
+// Floor for a 429 pause: a reset time at or just before "now" (window boundary / clock skew) must
+// still produce a real, short wait. A 0 would leave the queue's pauseMs unset and fall through to
+// reservoirRefreshInterval (default 60s).
+const MIN_RATE_LIMIT_WAIT_MS = 1000;
+function parseBackpressure(headers) {
+    const remaining = parseInt(headers.get("x-ratelimit-remaining") ?? "", 10);
+    const reset = parseInt(headers.get("x-ratelimit-reset") ?? "", 10);
+    return {
+        remaining: Number.isFinite(remaining) ? remaining : null,
+        resetAt: Number.isFinite(reset) ? reset * 1000 : null, // X-RateLimit-Reset is Unix seconds
+    };
+}
+// v2 has no Retry-After on 429; derive the wait from X-RateLimit-Reset. Honor Retry-After if a
+// future response ever sends it. Floored so a past/near reset never collapses to 0.
+function rateLimitWaitMs(headers, fallback) {
+    const retryAfter = parseInt(headers.get("retry-after") ?? "", 10);
+    if (Number.isFinite(retryAfter))
+        return Math.max(MIN_RATE_LIMIT_WAIT_MS, retryAfter * 1000);
+    const reset = parseInt(headers.get("x-ratelimit-reset") ?? "", 10);
+    if (Number.isFinite(reset))
+        return Math.max(MIN_RATE_LIMIT_WAIT_MS, reset * 1000 - Date.now());
+    return fallback;
+}
+/**
+ * A rate-limited transport: a shared per-client queue enforcing `maxConcurrent`, `minTime`, and
+ * proactive backpressure from `X-RateLimit-*` headers (pausing before a 429), plus 429 pause-and-retry
+ * driven by `X-RateLimit-Reset`. Composed over {@link createRetryTransport} so 5xx and network errors
+ * are retried with backoff and each attempt can time out. Pass to `new RadiusApiV2({ transport })`.
+ */
+function createRateLimitedTransport(options = {}) {
+    const { maxConcurrent = 10, minTime = 0, reservoir, reservoirRefreshAmount, reservoirRefreshInterval = 60_000, maxRetries = 3, timeoutMs, baseDelayMs, maxDelayMs, retryStatuses = DEFAULT_RETRYABLE_STATUSES, transport, sleep, } = options;
+    const inner = (0, retryTransport_js_1.createRetryTransport)({
+        transport,
+        // 429 is always handled by the queue's pause path; never let the inner layer retry it.
+        retryStatuses: retryStatuses.filter((status) => status !== 429),
+        maxRetries,
+        baseDelayMs,
+        maxDelayMs,
+        timeoutMs,
+        sleep,
+    });
+    const queue = new rateLimitedQueue_js_1.RateLimitedQueue(async (request, queueSignal) => {
+        const signal = request.signal ? AbortSignal.any([request.signal, queueSignal]) : queueSignal;
+        const result = await inner({ ...request, signal });
+        if (result.status === 429)
+            throw new RateLimitError(result);
+        return { result, backpressure: parseBackpressure(result.headers) };
+    }, {
+        maxConcurrent,
+        minTime,
+        reservoir,
+        reservoirRefreshAmount,
+        reservoirRefreshInterval,
+        maxRetries,
+        sleep,
+        onError: (error, { retryAfter, skip }) => {
+            if (error instanceof RateLimitError) {
+                retryAfter(rateLimitWaitMs(error.result.headers, reservoirRefreshInterval));
+            }
+            else {
+                skip(); // inner already exhausted 5xx/network retries; propagate
+            }
+        },
+    });
+    const transportFn = (async (request) => {
+        try {
+            return await queue.push(request);
+        }
+        catch (error) {
+            // 429 that outlived its retries: return the response so the client's throwOnError handles it.
+            if (error instanceof RateLimitError)
+                return error.result;
+            throw error;
+        }
+    });
+    transportFn.queue = queue;
+    return transportFn;
+}

package/src/retryTransport.d.ts

@@ -0,0 +1,25 @@
+import type { Transport } from "./_generated/index.js";
+export interface RetryOptions {
+    /** Max retry attempts after the initial request. Default 3. */
+    maxRetries?: number;
+    /** Base backoff delay in ms, doubled each attempt. Default 500. */
+    baseDelayMs?: number;
+    /** Upper bound on a single delay in ms. Default 10_000. */
+    maxDelayMs?: number;
+    /** HTTP statuses that trigger a retry. Default [429, 500, 502, 503, 504]. */
+    retryStatuses?: number[];
+    /** Honor a `Retry-After` header (delta-seconds or HTTP-date) on retryable responses. Default true. */
+    respectRetryAfter?: boolean;
+    /** Per-attempt timeout in ms via AbortSignal. Unset = no timeout. */
+    timeoutMs?: number;
+    /** Base transport to wrap. Defaults to a built-in fetch transport (JSON responses). */
+    transport?: Transport;
+    /** Injectable sleep, for tests. Default real setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Wraps a transport with retry + exponential backoff on 429/5xx (honoring `Retry-After`),
+ * an optional per-attempt timeout, and retry-on-network-error. Pass to a client as
+ * `new RadiusApiV2({ transport: createRetryTransport() })`.
+ */
+export declare function createRetryTransport(options?: RetryOptions): Transport;

package/src/retryTransport.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRetryTransport = createRetryTransport;
+const DEFAULT_RETRY_STATUSES = [429, 500, 502, 503, 504];
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// Mirrors the generated defaultTransport for the JSON-only Radius API: used only when no base
+// transport is supplied. Keep in sync with _generated/.kubb/client.ts if response handling changes.
+const fetchTransport = async (request) => {
+    const init = {
+        ...request.options,
+        method: request.method,
+        headers: request.headers,
+        body: request.body,
+        signal: request.signal,
+    };
+    if (request.credentials)
+        init.credentials = request.credentials;
+    const nativeRequest = new Request(request.url, init);
+    const response = await fetch(nativeRequest);
+    const noBody = response.status === 204 || response.status === 205 || response.status === 304 || !response.body;
+    const text = noBody ? "" : await response.text();
+    // Tolerate non-JSON bodies (e.g. an HTML 502 or a text/plain 429) instead of throwing, matching
+    // the generated defaultTransport's parseResponse fallback.
+    let data;
+    if (text) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            data = text;
+        }
+    }
+    return {
+        data,
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+        request: nativeRequest,
+        response,
+    };
+};
+function backoffDelay(attempt, base, max) {
+    const ceiling = Math.min(max, base * 2 ** attempt);
+    // Half fixed, half jittered, to spread out simultaneous retries.
+    return Math.round(ceiling / 2 + Math.random() * (ceiling / 2));
+}
+function retryAfterMs(headers) {
+    const raw = headers.get("Retry-After");
+    if (!raw)
+        return undefined;
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const date = Date.parse(raw);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+function withTimeout(request, ms) {
+    const timeout = AbortSignal.timeout(ms);
+    const signal = request.signal ? AbortSignal.any([request.signal, timeout]) : timeout;
+    return { ...request, signal };
+}
+/**
+ * Wraps a transport with retry + exponential backoff on 429/5xx (honoring `Retry-After`),
+ * an optional per-attempt timeout, and retry-on-network-error. Pass to a client as
+ * `new RadiusApiV2({ transport: createRetryTransport() })`.
+ */
+function createRetryTransport(options = {}) {
+    const { maxRetries = 3, baseDelayMs = 500, maxDelayMs = 10_000, retryStatuses = DEFAULT_RETRY_STATUSES, respectRetryAfter = true, timeoutMs, transport = fetchTransport, sleep = defaultSleep, } = options;
+    const retryable = new Set(retryStatuses);
+    return async (request) => {
+        let attempt = 0;
+        for (;;) {
+            const attemptRequest = timeoutMs ? withTimeout(request, timeoutMs) : request;
+            let result;
+            try {
+                result = await transport(attemptRequest);
+            }
+            catch (error) {
+                // Caller cancellation (or queue.cancel()) aborts request.signal — fail fast rather than
+                // burning retries. A per-attempt timeout aborts only the composed timeout signal, leaving
+                // request.signal intact, so genuine timeouts still retry.
+                if (request.signal?.aborted || attempt >= maxRetries)
+                    throw error;
+                await sleep(backoffDelay(attempt, baseDelayMs, maxDelayMs));
+                attempt++;
+                continue;
+            }
+            if (!retryable.has(result.status) || attempt >= maxRetries)
+                return result;
+            // A server-dictated Retry-After is honored as-is; only our own computed backoff is bounded by
+            // maxDelayMs (backoffDelay already clamps to it).
+            const retryAfter = respectRetryAfter ? retryAfterMs(result.headers) : undefined;
+            await sleep(retryAfter ?? backoffDelay(attempt, baseDelayMs, maxDelayMs));
+            attempt++;
+        }
+    };
+}