okengine 0.21.1 → 0.22.0

package/src/client/transport.ts

@@ -20,11 +20,18 @@ import {
   toQuery,
 } from "./wire.ts";
 
-/** Per-call transport options (binary decode, abort). */
+/** Per-call transport options (binary decode, abort, retry opt-in). */
 export interface TransportCallOptions {
   readonly headers?: ClientHeaders;
   readonly response?: "json" | "blob" | "arrayBuffer";
   readonly signal?: AbortSignal;
+  /**
+   * Repeat this call under the client `retry` policy even when it sends
+   * no idempotency key.
+   */
+  readonly retry?: boolean;
+  /** Stable key, or `false` to send none. */
+  readonly idempotencyKey?: string | false;
 }
 
 /** Internal transport handle. */
@@ -63,10 +70,25 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
       let delay = delay0;
       const callClientOpts: ClientOptions =
         callOpts.signal !== undefined ? { ...opts, signal: callOpts.signal } : opts;
+      const method = (opts.routes?.[key.replace("/", ".")]?.method ?? "POST").toUpperCase();
+      const idempotencyKey = resolveIdempotencyKey(method, callOpts.idempotencyKey);
+      const allowRetry =
+        callOpts.retry === true ||
+        method === "GET" ||
+        method === "QUERY" ||
+        idempotencyKey !== undefined;
 
       for (;;) {
         try {
-          const res = await once(base, key, input, callClientOpts, fetchFn, callOpts.headers);
+          const res = await once(
+            base,
+            key,
+            input,
+            callClientOpts,
+            fetchFn,
+            callOpts.headers,
+            idempotencyKey,
+          );
           if (
             res.status === 401 &&
             opts.auth &&
@@ -78,9 +100,22 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
             await opts.auth.refresh();
             continue;
           }
+          if (res.status === 409 && allowRetry && attempt < retries) {
+            const seconds = Number(res.headers.get("retry-after"));
+            const wait = seconds > 0 ? seconds * 1000 : delay;
+            const structured = await decodeIfEnvelope(res);
+            if (structured?.error?.code === "IdempotencyInProgress") {
+              await sleep(wait);
+              delay *= backoff;
+              attempt += 1;
+              continue;
+            }
+            if (structured) return stampReplay(structured, res);
+            return transportEnvelope("HTTP 409", 409);
+          }
           if (res.status >= 500) {
             const structured = await decodeIfEnvelope(res);
-            if (structured) return structured;
+            if (structured) return stampReplay(structured, res);
             throw new Error(`HTTP ${res.status}`);
           }
           if (callOpts.response === "blob" || callOpts.response === "arrayBuffer") {
@@ -89,7 +124,7 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
           return decode(res);
         } catch (err) {
           const transient = isTransient(err);
-          if (!transient || attempt >= retries) {
+          if (!transient || !allowRetry || attempt >= retries) {
             return transportEnvelope(err instanceof Error ? err.message : String(err));
           }
           await sleep(delay);
@@ -127,10 +162,20 @@ function normalizeCallOpts(
   if (Array.isArray(headersOrOpts)) return { headers: headersOrOpts };
   if (
     typeof headersOrOpts === "object" &&
-    ("response" in headersOrOpts || "signal" in headersOrOpts || "headers" in headersOrOpts)
+    ("response" in headersOrOpts ||
+      "signal" in headersOrOpts ||
+      "headers" in headersOrOpts ||
+      "retry" in headersOrOpts ||
+      "idempotencyKey" in headersOrOpts)
   ) {
     const o = headersOrOpts as TransportCallOptions;
-    if (o.response !== undefined || o.signal !== undefined || o.headers !== undefined) {
+    if (
+      o.response !== undefined ||
+      o.signal !== undefined ||
+      o.headers !== undefined ||
+      o.retry !== undefined ||
+      o.idempotencyKey !== undefined
+    ) {
       return o;
     }
   }
@@ -138,7 +183,9 @@ function normalizeCallOpts(
 }
 
 /**
- * Single HTTP attempt. Throws on network / abort / 5xx (retryable).
+ * Single HTTP attempt. Throws on network / abort / non-envelope 5xx.
+ * A client timeout is rethrown as a plain `Error` so the retry loop can
+ * repeat it. A caller `AbortSignal` stays an `AbortError` and is not retried.
  *
  * @param base - Origin
  * @param key - `unit/flow`
@@ -154,6 +201,7 @@ async function once(
   opts: ClientOptions,
   fetchFn: ClientFetch,
   callHeaders?: ClientHeaders,
+  idempotencyKey?: string,
 ): Promise<Response> {
   const route = opts.routes?.[key.replace("/", ".")];
   const { url, method, body } = route
@@ -163,6 +211,7 @@ async function once(
   const headers = new Headers();
   applyHeaderBag(headers, await resolveHeaders(opts));
   applyHeaderBag(headers, callHeaders);
+  if (idempotencyKey !== undefined) headers.set("Idempotency-Key", idempotencyKey);
   if (body !== undefined && !headers.has("content-type") && typeof body === "string") {
     headers.set("content-type", "application/json");
   }
@@ -172,13 +221,20 @@ async function once(
   const signal =
     opts.signal && timeout ? AbortSignal.any([opts.signal, timeout]) : (opts.signal ?? timeout);
 
-  return await fetchFn(url, {
-    method,
-    headers,
-    body: body as RequestInit["body"],
-    signal,
-    ...(opts.credentials !== undefined ? { credentials: opts.credentials } : {}),
-  });
+  try {
+    return await fetchFn(url, {
+      method,
+      headers,
+      body: body as RequestInit["body"],
+      signal,
+      ...(opts.credentials !== undefined ? { credentials: opts.credentials } : {}),
+    });
+  } catch (err) {
+    if (isAbortError(err) && timeout?.aborted === true && opts.signal?.aborted !== true) {
+      throw new Error(err instanceof Error ? err.message : "timeout");
+    }
+    throw err;
+  }
 }
 
 /**
@@ -253,12 +309,12 @@ function isRawBody(input: unknown): input is ClientBodyInit {
 
 async function decode(res: Response): Promise<ClientEnvelope> {
   if (res.status === 204) {
-    return { data: undefined, error: null };
+    return stampReplay({ data: undefined, error: null }, res);
   }
 
   const text = await res.text();
   if (!text) {
-    if (res.ok) return { data: undefined, error: null };
+    if (res.ok) return stampReplay({ data: undefined, error: null }, res);
     return transportEnvelope(`HTTP ${res.status}`, res.status);
   }
 
@@ -270,11 +326,11 @@ async function decode(res: Response): Promise<ClientEnvelope> {
   }
 
   if (json !== null && typeof json === "object" && "data" in json && "error" in json) {
-    return json as ClientEnvelope;
+    return stampReplay(json as ClientEnvelope, res);
   }
 
   if (res.ok) {
-    return { data: json, error: null };
+    return stampReplay({ data: json, error: null }, res);
   }
 
   return transportEnvelope(`HTTP ${res.status}`, res.status);
@@ -287,7 +343,64 @@ async function decodeBinary(res: Response, mode: "blob" | "arrayBuffer"): Promis
     return transportEnvelope(`HTTP ${res.status}`, res.status);
   }
   const data = mode === "blob" ? await res.blob() : await res.arrayBuffer();
-  return { data, error: null };
+  return stampReplay({ data, error: null }, res);
+}
+
+/**
+ * Default `okid()` alphabet, inlined.
+ *
+ * Same 64-character Base64URL order as {@link OKID_ALPHABET}. Importing
+ * `okid` would pull `lazyRequire` and every alphabet constant into the client.
+ */
+export const IDEMPOTENCY_KEY_ALPHABET =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/**
+ * 21-char key from `crypto.getRandomValues`.
+ *
+ * `getRandomValues` works on plain HTTP. When `crypto` is missing entirely,
+ * returns `undefined` so the call sends no key and runs once.
+ */
+export function mintIdempotencyKey(): string | undefined {
+  const webCrypto = globalThis.crypto;
+  if (webCrypto?.getRandomValues === undefined) return undefined;
+  const bytes = new Uint8Array(21);
+  webCrypto.getRandomValues(bytes);
+  let out = "";
+  for (let i = 0; i < 21; i++) out += IDEMPOTENCY_KEY_ALPHABET[bytes[i]! & 63]!;
+  return out;
+}
+
+/**
+ * Key for this logical call, or `undefined` when none is sent.
+ *
+ * @param method - HTTP method, already uppercased
+ * @param opt - Per-call override
+ */
+function resolveIdempotencyKey(
+  method: string,
+  opt: string | false | undefined,
+): string | undefined {
+  if (opt === false) return undefined;
+  if (typeof opt === "string") return opt;
+  if (method === "GET") return undefined;
+  return mintIdempotencyKey();
+}
+
+/**
+ * Copy `Idempotent-Replayed: true` onto result meta.
+ *
+ * @param envelope - Decoded envelope
+ * @param res - HTTP response
+ */
+function stampReplay(envelope: ClientEnvelope, res: Response): ClientEnvelope {
+  if (res.headers.get("idempotent-replayed") !== "true") return envelope;
+  const prev = envelope.meta;
+  return { ...envelope, meta: { ...prev, idempotentReplayed: true } };
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError");
 }
 
 function isTransient(err: unknown): boolean {

package/src/client/types.ts

@@ -146,6 +146,8 @@ export type ClientListMeta = {
   readonly prev?: ClientPagerLink | null;
   readonly total?: number;
   readonly offset?: number;
+  /** Set when the server replayed a completed idempotent call. */
+  readonly idempotentReplayed?: true;
 };
 
 /**
@@ -163,7 +165,11 @@ export type ClientEnvelope<
       readonly error: null;
       readonly meta?: ClientListMeta;
     }
-  | { readonly data: null; readonly error: ClientError<E> | TransportError };
+  | {
+      readonly data: null;
+      readonly error: ClientError<E> | TransportError;
+      readonly meta?: ClientListMeta;
+    };
 
 /**
  * Client call result — envelope plus always-callable `next` / `prev`.
@@ -251,7 +257,15 @@ export interface ClientOptions {
   readonly headers?: ClientHeaders | (() => ClientHeaders | Promise<ClientHeaders>);
   /** Abort the request after this many milliseconds. */
   readonly timeout?: number;
-  /** Retry transient failures (network / 5xx). */
+  /**
+   * Retry transient failures (network errors, client timeouts, and
+   * non-envelope 5xx).
+   *
+   * A call retries when it is `GET` or `QUERY`, or when it carries an
+   * idempotency key. Keys are sent automatically on every non-GET call.
+   * `idempotencyKey: false` runs once unless that call passes `{ retry: true }`.
+   * `409 IdempotencyInProgress` waits for `Retry-After` and counts as an attempt.
+   */
   readonly retry?: {
     /** Extra attempts after the first (default 0). */
     readonly retries?: number;
@@ -296,11 +310,22 @@ export interface ClientOptions {
 export type ClientThenableIterable<T> = PromiseLike<T> & AsyncIterable<T>;
 
 /**
- * Per-call options on a Flow invoke (binary decode / abort).
+ * Per-call options on a Flow invoke (binary decode, abort, retry opt-in).
  */
 export interface ClientCallOpts {
   readonly response?: "json" | "blob" | "arrayBuffer";
   readonly signal?: AbortSignal;
+  /**
+   * Repeat this call under the client `retry` policy even when it sends
+   * no idempotency key.
+   */
+  readonly retry?: boolean;
+  /**
+   * Stable `Idempotency-Key` for this logical call. A string is sent as-is
+   * (one key per form render dedupes double submits). `false` sends no key.
+   * Omitted on a non-GET call generates one key and reuses it across retries.
+   */
+  readonly idempotencyKey?: string | false;
 }
 
 /**
@@ -503,6 +528,7 @@ export interface ClientDescriptor {
         readonly stream?: true;
         readonly matchKey?: readonly string[];
         readonly gates?: readonly string[];
+        readonly idempotency?: { readonly mode: "off" | "auto" | "required"; readonly ttl: string };
       };
     };
   };