@worldlabsai/client 0.3.0 → 0.5.0

package/src/core/transport.ts

@@ -1,3 +1,4 @@
+import { NetworkError } from "./network-error.ts";
 import { sleep } from "./sleep.ts";
 
 /** Handles a `Request` for API calls and signed uploads; standard `fetch` is compatible. */
@@ -8,7 +9,11 @@ export type Fetch = (request: Request) => Promise<Response>;
  * without calling `next`, call `next` more than once for retries, or inspect the response.
  * Clone requests before sending them if a retry may need to reuse the body.
  */
-export type Middleware = (request: Request, next: Fetch) => Promise<Response>;
+export type Middleware = (
+  request: Request,
+  next: Fetch,
+  options?: Pick<RequestOptions, "retry">,
+) => Promise<Response>;
 
 /** Values accepted in a request query. `null` and `undefined` are omitted. */
 export type QueryValue = string | number | boolean | null | undefined;
@@ -40,7 +45,19 @@ export interface TransportOptions {
   pathParams?: Record<string, string>;
 }
 
-/** FastAPI puts its reason under `detail`; operation and storage errors use `message`. */
+/** One FastAPI validation issue, `{ loc: ["body", "frames"], msg: "Field required" }`. */
+const validationIssue = (issue: unknown): string => {
+  const location: unknown =
+    typeof issue === "object" && issue !== null ? Reflect.get(issue, "loc") : undefined;
+  const message: unknown =
+    typeof issue === "object" && issue !== null ? Reflect.get(issue, "msg") : issue;
+  return Array.isArray(location) ? `${location.join(".")}: ${String(message)}` : String(message);
+};
+
+/**
+ * FastAPI puts its reason under `detail`, as a list of validation issues for a
+ * 422; operation and storage errors use `message`.
+ */
 const errorDetail = (body: unknown): string | undefined => {
   if (typeof body !== "object" || body === null) {
     return undefined;
@@ -50,6 +67,9 @@ const errorDetail = (body: unknown): string | undefined => {
     if (typeof value === "string" && value !== "") {
       return value;
     }
+    if (Array.isArray(value) && value.length > 0) {
+      return value.map((issue) => validationIssue(issue)).join("; ");
+    }
   }
   return undefined;
 };
@@ -82,11 +102,15 @@ const fillPath = (path: string, params: Record<string, string>): string =>
     return encodeURIComponent(value);
   });
 
-const compose = (middleware: Middleware[], fetch: Fetch): Fetch => {
+const compose = (
+  middleware: Middleware[],
+  fetch: Fetch,
+  options?: Pick<RequestOptions, "retry">,
+): Fetch => {
   let next = fetch;
   for (const layer of middleware.toReversed()) {
     const inner = next;
-    next = async (request) => await layer(request, inner);
+    next = async (request) => await layer(request, inner, options);
   }
   return next;
 };
@@ -105,17 +129,27 @@ const parseBody = async (response: Response): Promise<unknown> => {
 
 const RETRYABLE_STATUS_CODES = new Set([429, 502, 503, 504]);
 
-const retryDelay = (error: unknown, attempt: number): number => {
-  const backoff = 1000 * 2 ** attempt * (0.5 + Math.random() / 2);
+/**
+ * Longest `Retry-After` a retry waits out. A concurrency cap, an hourly quota,
+ * or a closed task names minutes to hours, which the caller has to surface
+ * rather than sit through.
+ */
+const MAX_RETRY_AFTER_MS = 10_000;
+
+/** The wait a response names in `Retry-After`, as seconds or an HTTP date. */
+const retryAfterMs = (error: unknown): number | undefined => {
   const value =
     error instanceof ApiError ? error.response.headers.get("retry-after")?.trim() : undefined;
   if (!value) {
-    return backoff;
+    return undefined;
   }
   const delay = /^\d+$/u.test(value) ? Number(value) * 1000 : Date.parse(value) - Date.now();
-  return Math.max(backoff, Number.isFinite(delay) ? delay : 0);
+  return Number.isFinite(delay) ? Math.max(0, delay) : undefined;
 };
 
+const retryDelay = (error: unknown, attempt: number): number =>
+  Math.max(1000 * 2 ** attempt * (0.5 + Math.random() / 2), retryAfterMs(error) ?? 0);
+
 export interface Transport {
   /**
    * Send a request and parse its response as JSON, falling back to text.
@@ -150,10 +184,8 @@ export const createTransport = (options: TransportOptions): Transport => {
   return {
     fetch,
     send,
-    request: async <T>(
-      path: string,
-      { body, params, query, retry = false, ...init }: RequestOptions = {},
-    ): Promise<T> => {
+    request: async <T>(path: string, requestOptions: RequestOptions = {}): Promise<T> => {
+      const { body, params, query, retry = false, ...init } = requestOptions;
       const url = new URL(baseUrl + fillPath(path, { ...boundParams, ...params }));
       for (const [key, value] of Object.entries(query ?? {})) {
         if (value !== undefined && value !== null) {
@@ -172,16 +204,18 @@ export const createTransport = (options: TransportOptions): Transport => {
 
       // Provider and middleware TypeErrors must not be mistaken for network failures.
       let networkError: unknown;
-      const sendRequest = retry
-        ? compose(options.middleware ?? [], async (attempt) => {
-            try {
-              return await fetch(attempt);
-            } catch (error) {
-              networkError = error;
-              throw error;
-            }
-          })
-        : send;
+      const sendRequest = compose(
+        options.middleware ?? [],
+        async (attempt) => {
+          try {
+            return await fetch(attempt);
+          } catch (error) {
+            networkError = error;
+            throw error;
+          }
+        },
+        requestOptions,
+      );
 
       // oxlint-disable no-await-in-loop -- retries are sequential and preserve the original request
       for (let attempt = 0; ; attempt += 1) {
@@ -206,11 +240,14 @@ export const createTransport = (options: TransportOptions): Transport => {
           return parsed as T;
         } catch (error) {
           request.signal.throwIfAborted();
+          const networkFailure = error instanceof TypeError && error === networkError;
           const transient =
             error instanceof ApiError
-              ? RETRYABLE_STATUS_CODES.has(error.response.status)
-              : error instanceof TypeError && error === networkError;
+              ? RETRYABLE_STATUS_CODES.has(error.response.status) &&
+                (retryAfterMs(error) ?? 0) <= MAX_RETRY_AFTER_MS
+              : networkFailure;
           if (!retry || attempt >= 3 || !transient) {
+            if (networkFailure) throw new NetworkError(error);
             throw error;
           }
           await sleep(retryDelay(error, attempt), request.signal);