@vertesia/api-fetch-client 1.2.0 → 1.4.0-dev.20260614.160504Z

package/src/base.ts

@@ -1,10 +1,61 @@
-import { ConnectionError, RequestError, ServerError } from "./errors.js";
-import { sse, ServerSentEvent } from "./sse/index.js";
-import { buildQueryString, join, removeTrailingSlash } from "./utils.js";
+import { ConnectionError, type RequestError, ServerError } from './errors.js';
+import { type ServerSentEvent, sse } from './sse/index.js';
+import { buildQueryString, join, removeTrailingSlash } from './utils.js';
 
 export type FETCH_FN = (input: RequestInfo, init?: RequestInit) => Promise<Response>;
 type IPrimitives = string | number | boolean | null | undefined | string[] | number[] | boolean[];
 
+export interface IRequestRetryPolicy {
+    /**
+     * Total attempts, including the first request. Defaults to 3 when a retry policy is enabled.
+     */
+    attempts?: number;
+    /**
+     * HTTP methods that may be retried. Defaults to idempotent methods.
+     */
+    methods?: string[];
+    /**
+     * HTTP response statuses that should be retried. Defaults to 502, 503, and 504.
+     */
+    statuses?: number[];
+    /**
+     * Retry network failures thrown by fetch. Defaults to true.
+     */
+    retryOnConnectionError?: boolean;
+    /**
+     * Initial backoff delay in milliseconds. Defaults to 250.
+     */
+    baseDelayMs?: number;
+    /**
+     * Maximum backoff delay in milliseconds. Defaults to 4000.
+     */
+    maxDelayMs?: number;
+    /**
+     * Use full jitter for backoff delays. Defaults to true.
+     */
+    jitter?: boolean;
+}
+
+type NormalizedRetryPolicy = {
+    attempts: number;
+    methods: Set<string>;
+    statuses: Set<number>;
+    retryOnConnectionError: boolean;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitter: boolean;
+};
+
+const DEFAULT_RETRY_METHODS = ['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE'];
+const DEFAULT_RETRY_STATUSES = [502, 503, 504];
+const DEFAULT_RETRY_ATTEMPTS = 3;
+const DEFAULT_RETRY_BASE_DELAY_MS = 250;
+const DEFAULT_RETRY_MAX_DELAY_MS = 4000;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === 'object';
+}
+
 export interface IRequestParams {
     query?: Record<string, IPrimitives> | null;
     headers?: Record<string, string> | null;
@@ -17,12 +68,17 @@ export interface IRequestParams {
      * If set to 'sse' the response will be treated as a server-sent event stream
      * and the request will return a Promise<ReadableStream<ServerSentEvent>> object
      */
-    reader?: 'sse' | ((response: Response) => any);
+    reader?: 'sse' | ((response: Response) => unknown);
     /**
      * Set to false to disable automatic JSON payload serialization
      * If you need to post other data than a json payload, set this to false and use the `payload` property to set the desired payload
      */
-    jsonPayload?: boolean
+    jsonPayload?: boolean;
+    /**
+     * Opt-in retry policy for this request. Retries are disabled by default.
+     * Set to false to disable a client-level retry policy for this request.
+     */
+    retryPolicy?: IRequestRetryPolicy | false | null;
 }
 
 export interface IRequestParamsWithPayload extends IRequestParams {
@@ -37,21 +93,74 @@ export function fetchPromise(fetchImpl?: FETCH_FN | Promise<FETCH_FN>) {
     } else {
         // install an error impl
         return Promise.resolve(() => {
-            throw new Error('No Fetch implementation found')
+            throw new Error('No Fetch implementation found');
         });
     }
 }
 
-function isInvalidJsonPayload(payload: any) {
-    return payload?.error === "Not a valid JSON payload" && typeof payload.text === "string";
+function isInvalidJsonPayload(payload: unknown) {
+    return isRecord(payload) && payload.error === 'Not a valid JSON payload' && typeof payload.text === 'string';
 }
 
-export abstract class ClientBase {
+function isReplayableBody(body: BodyInit | undefined) {
+    return !body || typeof ReadableStream === 'undefined' || !(body instanceof ReadableStream);
+}
+
+function normalizeRetryPolicy(policy: IRequestRetryPolicy): NormalizedRetryPolicy {
+    const attempts = Math.max(1, Math.floor(policy.attempts ?? DEFAULT_RETRY_ATTEMPTS));
+    const baseDelayMs = Math.max(0, policy.baseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS);
+    const maxDelayMs = Math.max(baseDelayMs, policy.maxDelayMs ?? DEFAULT_RETRY_MAX_DELAY_MS);
+    return {
+        attempts,
+        methods: new Set((policy.methods ?? DEFAULT_RETRY_METHODS).map((method) => method.toUpperCase())),
+        statuses: new Set(policy.statuses ?? DEFAULT_RETRY_STATUSES),
+        retryOnConnectionError: policy.retryOnConnectionError ?? true,
+        baseDelayMs,
+        maxDelayMs,
+        jitter: policy.jitter ?? true,
+    };
+}
+
+function retryAfterDelayMs(res: Response): number | undefined {
+    const retryAfter = res.headers.get('retry-after');
+    if (!retryAfter) {
+        return undefined;
+    }
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return seconds * 1000;
+    }
+    const retryAt = Date.parse(retryAfter);
+    if (!Number.isNaN(retryAt)) {
+        return Math.max(0, retryAt - Date.now());
+    }
+    return undefined;
+}
 
+function retryDelayMs(policy: NormalizedRetryPolicy, attempt: number, res?: Response): number {
+    const retryAfter = res ? retryAfterDelayMs(res) : undefined;
+    const delay = retryAfter ?? Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** attempt);
+    return policy.jitter ? Math.floor(Math.random() * delay) : delay;
+}
+
+function toError(err: unknown): Error {
+    return err instanceof Error ? err : new Error(String(err));
+}
+
+async function discardBody(res: Response) {
+    try {
+        await res.body?.cancel();
+    } catch {
+        // Ignore body cleanup failures while retrying the original request.
+    }
+}
+
+export abstract class ClientBase {
     _fetch: Promise<FETCH_FN>;
     baseUrl: string;
     errorFactory: (err: RequestError) => Error = (err) => err;
     verboseErrors = true;
+    retryPolicy?: IRequestRetryPolicy;
 
     abstract get headers(): Record<string, string>;
 
@@ -68,6 +177,15 @@ export abstract class ClientBase {
         throw this.errorFactory(err);
     }
 
+    withRetryPolicy(policy?: IRequestRetryPolicy | null): this {
+        this.retryPolicy = policy || undefined;
+        return this;
+    }
+
+    getRetryPolicy(): IRequestRetryPolicy | undefined {
+        return this.retryPolicy;
+    }
+
     /**
      * Resolve a path to a full URL. If the path is already an absolute URL
      * (starts with http:// or https://), it is returned as-is.
@@ -79,24 +197,24 @@ export abstract class ClientBase {
         return removeTrailingSlash(join(this.baseUrl, path));
     }
 
-    get(path: string, params?: IRequestParams) {
-        return this.request('GET', path, params);
+    get<T = unknown>(path: string, params?: IRequestParams): Promise<T> {
+        return this.request<T>('GET', path, params);
     }
 
-    del(path: string, params?: IRequestParams) {
-        return this.request('DELETE', path, params);
+    del<T = unknown>(path: string, params?: IRequestParams): Promise<T> {
+        return this.request<T>('DELETE', path, params);
     }
 
-    delete(path: string, params?: IRequestParams) {
+    delete(path: string, params?: IRequestParams): Promise<unknown> {
         return this.request('DELETE', path, params);
     }
 
-    post(path: string, params?: IRequestParamsWithPayload) {
-        return this.request('POST', path, params);
+    post<T = unknown>(path: string, params?: IRequestParamsWithPayload): Promise<T> {
+        return this.request<T>('POST', path, params);
     }
 
-    put(path: string, params?: IRequestParamsWithPayload) {
-        return this.request('PUT', path, params);
+    put<T = unknown>(path: string, params?: IRequestParamsWithPayload): Promise<T> {
+        return this.request<T>('PUT', path, params);
     }
 
     /**
@@ -104,82 +222,90 @@ export abstract class ClientBase {
      * @param text
      * @returns
      */
-    jsonParse(text: string) {
+    jsonParse(text: string): unknown {
         return JSON.parse(text);
     }
 
     /**
-    * Can be overridden to create the request
-    * @param fetch
-    * @param url
-    * @param init
-    * @returns
-    */
+     * Can be overridden to create the request
+     * @param fetch
+     * @param url
+     * @param init
+     * @returns
+     */
     createRequest(url: string, init: RequestInit): Promise<Request> {
         return Promise.resolve(new Request(url, init));
     }
 
-    createServerError(req: Request, res: Response, payload: any): RequestError {
+    handleFetchResponse(_req: Request, _res: Response): void {}
+
+    createServerError(req: Request, res: Response, payload: unknown): RequestError {
         const status = res.status;
-        let message = 'Server Error: ' + status;
+        let message = `Server Error: ${status}`;
         if (payload) {
             if (isInvalidJsonPayload(payload)) {
-                message += res.statusText ? ' ' + res.statusText : '';
+                message += res.statusText ? ` ${res.statusText}` : '';
                 message += ': non-JSON response';
-            } else if (payload.message) {
+            } else if (isRecord(payload) && payload.message) {
                 message = String(payload.message);
-            } else if (payload.error) {
+            } else if (isRecord(payload) && payload.error) {
                 if (typeof payload.error === 'string') {
                     message = String(payload.error);
-                } else if (typeof payload.error.message === 'string') {
-                    message = String(payload.error.message);
+                } else if (isRecord(payload.error) && typeof payload.error.message === 'string') {
+                    message = payload.error.message;
                 }
             }
         }
         return new ServerError(message, req, res.status, payload, this.verboseErrors);
     }
 
-
     async readJSONPayload(res: Response) {
-        return res.text().then(text => {
-            if (!text) {
-                return undefined;
-            } else {
-                try {
-                    return this.jsonParse(text);
-                } catch (err: any) {
-                    return {
-                        status: res.status,
-                        error: "Not a valid JSON payload",
-                        message: err.message,
-                        text: text,
-                    };
+        return res
+            .text()
+            .then((text) => {
+                if (!text) {
+                    return undefined;
+                } else {
+                    try {
+                        return this.jsonParse(text);
+                    } catch (err: unknown) {
+                        return {
+                            status: res.status,
+                            error: 'Not a valid JSON payload',
+                            message: err instanceof Error ? err.message : String(err),
+                            text: text,
+                        };
+                    }
                 }
-            }
-        }).catch((err) => {
-            return {
-                status: res.status,
-                error: "Unable to load response content",
-                message: err.message,
-            };
-        });
+            })
+            .catch((err: unknown) => {
+                return {
+                    status: res.status,
+                    error: 'Unable to load response content',
+                    message: err instanceof Error ? err.message : String(err),
+                };
+            });
     }
 
     /**
      * Subclasses You can override this to do something with the response
      * @param res
      */
-    handleResponse(req: Request, res: Response, params: IRequestParamsWithPayload | undefined) {
-        if (params && params.reader) {
+    handleResponse<T = unknown>(
+        req: Request,
+        res: Response,
+        params: IRequestParamsWithPayload | undefined,
+    ): T | Promise<T> {
+        if (params?.reader) {
             if (params.reader === 'sse') {
-                return sse(res);
+                return sse(res) as T;
             } else {
-                return params.reader.call(this, res);
+                return params.reader.call(this, res) as T | Promise<T>;
             }
         } else {
             return this.readJSONPayload(res).then((payload) => {
                 if (res.ok) {
-                    return payload;
+                    return payload as T;
                 } else {
                     this.throwError(this.createServerError(req, res, payload));
                 }
@@ -187,10 +313,10 @@ export abstract class ClientBase {
         }
     }
 
-    async request(method: string, path: string, params?: IRequestParamsWithPayload) {
+    async request<T = unknown>(method: string, path: string, params?: IRequestParamsWithPayload): Promise<T> {
         let url = this.getUrl(path);
         if (params?.query) {
-            url += '?' + buildQueryString(params.query);
+            url += `?${buildQueryString(params.query)}`;
         }
         const headers = this.headers ? Object.assign({}, this.headers) : {};
         const paramsHeaders = params?.headers;
@@ -205,29 +331,122 @@ export abstract class ClientBase {
             if (params && params.jsonPayload === false) {
                 body = payload as BodyInit;
             } else {
-                body = (typeof payload !== 'string') ? JSON.stringify(payload) : payload;
+                body = typeof payload !== 'string' ? JSON.stringify(payload) : payload;
                 if (!('content-type' in headers)) {
                     headers['content-type'] = 'application/json';
                 }
             }
         }
         // When using SSE reader, ensure the Accept header requests event-stream
-        if (params?.reader === 'sse' && !('accept' in headers)) {
-            headers['accept'] = 'text/event-stream';
+        if (params?.reader === 'sse') {
+            headers.accept = 'text/event-stream';
         }
 
-        const init: RequestInit = {
-            method: method,
-            headers: headers,
-            body: body,
+        const normalizedMethod = method.toUpperCase();
+        const createRequestInit = (): RequestInit => {
+            return {
+                method: normalizedMethod,
+                headers: Object.assign({}, headers),
+                body: body,
+            };
+        };
+        const retryPolicy = this.resolveRetryPolicy(params);
+        const fetch = await this._fetch;
+
+        if (!retryPolicy) {
+            const req = await this.createRequest(url, createRequestInit());
+            let res: Response;
+            try {
+                res = await fetch(req);
+            } catch (err: unknown) {
+                console.error(`Failed to connect to ${url}`, err);
+                this.throwError(new ConnectionError(req, toError(err)));
+            }
+            this.handleFetchResponse(req, res);
+            return this.handleResponse<T>(req, res, params);
         }
-        const req = await this.createRequest(url, init);
-        return this._fetch.then(fetch => fetch(req).catch(err => {
-            console.error(`Failed to connect to ${url}`, err);
-            this.throwError(new ConnectionError(req, err));
-        }).then(res => {
-            return this.handleResponse(req, res, params);
-        }));
+
+        const replayableBody = isReplayableBody(body);
+        let lastReq: Request | undefined;
+        for (let attempt = 0; attempt < retryPolicy.attempts; attempt++) {
+            const req = await this.createRequest(url, createRequestInit());
+            lastReq = req;
+            let res: Response;
+            try {
+                res = await fetch(req);
+            } catch (err: unknown) {
+                if (!this.shouldRetryConnectionError(retryPolicy, normalizedMethod, attempt, replayableBody)) {
+                    console.error(`Failed to connect to ${url}`, err);
+                    this.throwError(new ConnectionError(req, toError(err)));
+                }
+                await this.waitBeforeRetry(retryPolicy, attempt);
+                continue;
+            }
+            this.handleFetchResponse(req, res);
+            if (this.shouldRetryResponse(retryPolicy, normalizedMethod, attempt, replayableBody, res)) {
+                await discardBody(res);
+                await this.waitBeforeRetry(retryPolicy, attempt, res);
+                continue;
+            }
+            return this.handleResponse<T>(req, res, params);
+        }
+
+        if (lastReq) {
+            this.throwError(
+                new ConnectionError(lastReq, new Error(`Retry attempts exhausted for ${normalizedMethod} ${url}`)),
+            );
+        }
+        throw new Error(`Retry attempts exhausted for ${normalizedMethod} ${url}`);
+    }
+
+    protected resolveRetryPolicy(params: IRequestParamsWithPayload | undefined): NormalizedRetryPolicy | undefined {
+        if (params?.reader === 'sse' || params?.retryPolicy === false || params?.retryPolicy === null) {
+            return undefined;
+        }
+        const requestPolicy = params?.retryPolicy;
+        const clientPolicy = this.getRetryPolicy();
+        if (!requestPolicy && !clientPolicy) {
+            return undefined;
+        }
+        const policy = normalizeRetryPolicy({
+            ...clientPolicy,
+            ...requestPolicy,
+        });
+        return policy.attempts > 1 ? policy : undefined;
+    }
+
+    private shouldRetryResponse(
+        policy: NormalizedRetryPolicy,
+        method: string,
+        attempt: number,
+        replayableBody: boolean,
+        res: Response,
+    ) {
+        return (
+            attempt < policy.attempts - 1 &&
+            replayableBody &&
+            policy.methods.has(method) &&
+            policy.statuses.has(res.status)
+        );
+    }
+
+    private shouldRetryConnectionError(
+        policy: NormalizedRetryPolicy,
+        method: string,
+        attempt: number,
+        replayableBody: boolean,
+    ) {
+        return (
+            attempt < policy.attempts - 1 &&
+            replayableBody &&
+            policy.retryOnConnectionError &&
+            policy.methods.has(method)
+        );
+    }
+
+    private waitBeforeRetry(policy: NormalizedRetryPolicy, attempt: number, res?: Response) {
+        const delay = retryDelayMs(policy, attempt, res);
+        return new Promise<void>((resolve) => setTimeout(resolve, delay));
     }
 
     /**
@@ -246,10 +465,10 @@ export abstract class ClientBase {
         params: IRequestParamsWithPayload | undefined,
         onEvent: (event: ServerSentEvent) => void,
     ): Promise<ServerSentEvent | undefined> {
-        const stream = await this.request(method, path, {
+        const stream = (await this.request(method, path, {
             ...params,
             reader: 'sse',
-        }) as ReadableStream<ServerSentEvent>;
+        })) as ReadableStream<ServerSentEvent>;
 
         const reader = stream.getReader();
         let lastEvent: ServerSentEvent | undefined;
@@ -275,7 +494,6 @@ export abstract class ClientBase {
      * @returns
      */
     fetch(input: RequestInfo, init?: RequestInit): Promise<Response> {
-        return this._fetch.then(fetch => fetch(input, init));
+        return this._fetch.then((fetch) => fetch(input, init));
     }
-
 }

package/src/client.ts

@@ -1,13 +1,26 @@
-import { ClientBase, FETCH_FN, IRequestParamsWithPayload } from "./base.js";
-import { RequestError } from "./errors.js";
+import { ClientBase, type FETCH_FN, type IRequestParamsWithPayload } from './base.js';
+import type { RequestError } from './errors.js';
 
 function isAuthorizationHeaderSet(headers: HeadersInit | undefined): boolean {
     if (!headers) return false;
-    return "authorization" in headers;
+    return 'authorization' in headers;
 }
 
-export class AbstractFetchClient<T extends AbstractFetchClient<T>> extends ClientBase {
+function isServerFetchRuntime(): boolean {
+    const runtime = globalThis as typeof globalThis & {
+        Bun?: unknown;
+        process?: { versions?: { bun?: string; node?: string } };
+        window?: unknown;
+    };
+    return (
+        typeof runtime.window === 'undefined' &&
+        (typeof runtime.process?.versions?.node === 'string' ||
+            typeof runtime.process?.versions?.bun === 'string' ||
+            typeof runtime.Bun !== 'undefined')
+    );
+}
 
+export class AbstractFetchClient<T extends AbstractFetchClient<T>> extends ClientBase {
     headers: Record<string, string>;
     _auth?: () => Promise<string>;
     // callbacks useful to log requests and responses
@@ -23,7 +36,11 @@ export class AbstractFetchClient<T extends AbstractFetchClient<T>> extends Clien
     }
 
     get initialHeaders() {
-        return { accept: 'application/json' };
+        const headers: Record<string, string> = { accept: 'application/json' };
+        if (isServerFetchRuntime()) {
+            headers['accept-encoding'] = 'br, gzip, deflate';
+        }
+        return headers;
     }
 
     /**
@@ -75,38 +92,32 @@ export class AbstractFetchClient<T extends AbstractFetchClient<T>> extends Clien
             init.headers = headers;
             const auth = await this._auth();
             if (auth) {
-                init.headers["authorization"] = auth;
+                init.headers.authorization = auth;
             }
         }
         this.response = undefined;
         const request = await super.createRequest(url, init);
-        this.onRequest && this.onRequest(request);
+        this.onRequest?.(request);
         return request;
     }
 
-    async handleResponse(req: Request, res: Response, params: IRequestParamsWithPayload | undefined) {
+    handleFetchResponse(req: Request, res: Response): void {
         this.response = res; // store last response
-        this.onResponse && this.onResponse(res, req);
-        return super.handleResponse(req, res, params);
+        this.onResponse?.(res, req);
     }
-
 }
 
-export class FetchClient extends AbstractFetchClient<FetchClient> {
-
-    constructor(baseUrl: string, fetchImpl?: FETCH_FN | Promise<FETCH_FN>) {
-        super(baseUrl, fetchImpl);
-    }
-
-}
+export class FetchClient extends AbstractFetchClient<FetchClient> {}
 
 export abstract class ApiTopic extends ClientBase {
-
-    constructor(public client: ClientBase, basePath: string) {
+    constructor(
+        public client: ClientBase,
+        basePath: string,
+    ) {
         //TODO we should refactor the way ClientBase and ApiTopic is created
         // to avoid cloning all customizations
         super(client.getUrl(basePath), client._fetch);
-        this.createServerError = client.createServerError
+        this.createServerError = client.createServerError;
         this.errorFactory = client.errorFactory;
         this.verboseErrors = client.verboseErrors;
     }
@@ -115,12 +126,23 @@ export abstract class ApiTopic extends ClientBase {
         return this.client.createRequest(url, init);
     }
 
-    handleResponse(req: Request, res: Response, params: IRequestParamsWithPayload | undefined): Promise<any> {
-        return this.client.handleResponse(req, res, params);
+    handleResponse<T = unknown>(
+        req: Request,
+        res: Response,
+        params: IRequestParamsWithPayload | undefined,
+    ): T | Promise<T> {
+        return this.client.handleResponse<T>(req, res, params);
+    }
+
+    handleFetchResponse(req: Request, res: Response): void {
+        this.client.handleFetchResponse(req, res);
+    }
+
+    getRetryPolicy() {
+        return this.client.getRetryPolicy();
     }
 
     get headers() {
         return this.client.headers;
     }
-
 }