okengine 0.21.0 → 0.22.0

package/src/client/transport.test.ts

@@ -3,7 +3,9 @@
  */
 
 import { describe, expect, test } from "bun:test";
+import { OKID_ALPHABET } from "../okid-shared.ts";
 import { createClient } from "./create.ts";
+import { IDEMPOTENCY_KEY_ALPHABET } from "./transport.ts";
 import type { AppOf } from "./types.ts";
 
 type PingApp = AppOf<{
@@ -15,11 +17,16 @@ type PingApp = AppOf<{
   };
 }>;
 
+const getPing = {
+  "sys.ping": { method: "GET", path: "/ping" },
+} as const;
+
 describe("transport — retry", () => {
   test("retries 5xx then succeeds", async () => {
     let n = 0;
     const api = createClient<PingApp>("http://app.test", {
       retry: { retries: 2, delay: 1, backoff: 1 },
+      routes: getPing,
       fetch: async () => {
         n += 1;
         if (n < 3) return new Response("nope", { status: 503 });
@@ -37,6 +44,7 @@ describe("transport — retry", () => {
     let n = 0;
     const api = createClient<PingApp>("http://app.test", {
       retry: { retries: 1, delay: 1, backoff: 1 },
+      routes: getPing,
       fetch: async () => {
         n += 1;
         return new Response("nope", { status: 502 });
@@ -73,6 +81,223 @@ describe("transport — retry", () => {
     expect(error?.code).toBe("InternalError");
     expect(error?.message).toMatch(/password policy/i);
   });
+
+  test("POST retries when it carries an idempotency key", async () => {
+    let handled = 0;
+    const keys: string[] = [];
+    const api = createClient<PingApp>("http://app.test", {
+      retry: { retries: 2, delay: 1, backoff: 1 },
+      fetch: async (_input, init) => {
+        handled += 1;
+        keys.push(new Headers(init?.headers).get("idempotency-key") ?? "");
+        throw new TypeError("Failed to fetch");
+      },
+    });
+
+    const lost = await api.sys.ping();
+    expect(lost.error?.code).toBe("TransportError");
+    expect(handled).toBe(3);
+    expect(keys[0]).toBe(keys[1]);
+    expect(keys[1]).toBe(keys[2]);
+    expect(keys[0]!.length).toBeGreaterThanOrEqual(16);
+  });
+
+  test("idempotencyKey false runs once unless retry is opted in", async () => {
+    let handled = 0;
+    const api = createClient<PingApp>("http://app.test", {
+      retry: { retries: 2, delay: 1, backoff: 1 },
+      fetch: async (_input, init) => {
+        handled += 1;
+        expect(new Headers(init?.headers).get("idempotency-key")).toBeNull();
+        throw new TypeError("Failed to fetch");
+      },
+    });
+
+    const lost = await api.sys.ping({ idempotencyKey: false });
+    expect(lost.error?.code).toBe("TransportError");
+    expect(handled).toBe(1);
+
+    handled = 0;
+    const opted = await api.sys.ping({ idempotencyKey: false, retry: true });
+    expect(opted.error?.code).toBe("TransportError");
+    expect(handled).toBe(3);
+  });
+
+  test("two calls mint two keys; a string key is reused", async () => {
+    const keys: string[] = [];
+    const api = createClient<PingApp>("http://app.test", {
+      fetch: async (_input, init) => {
+        keys.push(new Headers(init?.headers).get("idempotency-key") ?? "");
+        return Response.json({ data: { ok: true }, error: null });
+      },
+    });
+    await api.sys.ping();
+    await api.sys.ping();
+    expect(keys[0]).not.toBe(keys[1]);
+    keys.length = 0;
+    await api.sys.ping({ idempotencyKey: "form-key-0123456789" });
+    expect(keys).toEqual(["form-key-0123456789"]);
+  });
+
+  test("inlined idempotency alphabet matches OKID_ALPHABET", () => {
+    expect(IDEMPOTENCY_KEY_ALPHABET).toBe(OKID_ALPHABET);
+    expect(IDEMPOTENCY_KEY_ALPHABET).toHaveLength(64);
+  });
+
+  test("missing crypto sends no idempotency key", async () => {
+    const original = globalThis.crypto;
+    Object.defineProperty(globalThis, "crypto", {
+      value: undefined,
+      configurable: true,
+      writable: true,
+    });
+    try {
+      const api = createClient<PingApp>("http://app.test", {
+        fetch: async (_input, init) => {
+          expect(new Headers(init?.headers).get("idempotency-key")).toBeNull();
+          return Response.json({ data: { ok: true }, error: null });
+        },
+      });
+      const { error } = await api.sys.ping();
+      expect(error).toBeNull();
+    } finally {
+      Object.defineProperty(globalThis, "crypto", {
+        value: original,
+        configurable: true,
+        writable: true,
+      });
+    }
+  });
+
+  test("GET sends no idempotency key", async () => {
+    const api = createClient<PingApp>("http://app.test", {
+      routes: getPing,
+      fetch: async (_input, init) => {
+        expect(new Headers(init?.headers).get("idempotency-key")).toBeNull();
+        return Response.json({ data: { ok: true }, error: null });
+      },
+    });
+    const { error } = await api.sys.ping();
+    expect(error).toBeNull();
+  });
+
+  test("401 resend reuses the idempotency key", async () => {
+    const keys: string[] = [];
+    let token = "old";
+    const api = createClient<PingApp>("http://app.test", {
+      auth: {
+        getToken: () => token,
+        refresh: async () => {
+          token = "new";
+          return token;
+        },
+      },
+      fetch: async (_input, init) => {
+        const headers = new Headers(init?.headers);
+        keys.push(headers.get("idempotency-key") ?? "");
+        if (headers.get("authorization") === "Bearer old") {
+          return new Response("unauthorized", { status: 401 });
+        }
+        return Response.json({ data: { ok: true }, error: null });
+      },
+    });
+    const { error } = await api.sys.ping();
+    expect(error).toBeNull();
+    expect(keys).toHaveLength(2);
+    expect(keys[0]).toBe(keys[1]);
+  });
+
+  test("IdempotencyInProgress waits for Retry-After then replays", async () => {
+    let n = 0;
+    const api = createClient<PingApp>("http://app.test", {
+      retry: { retries: 2, delay: 1, backoff: 1 },
+      timeout: 30,
+      fetch: async (_input, init) => {
+        n += 1;
+        const signal = init?.signal;
+        if (n === 1) {
+          await new Promise<void>((_resolve, reject) => {
+            if (signal?.aborted) {
+              reject(new DOMException("Aborted", "AbortError"));
+              return;
+            }
+            signal?.addEventListener("abort", () => {
+              reject(new DOMException("Aborted", "AbortError"));
+            });
+          });
+        }
+        if (n === 2) {
+          return Response.json(
+            { data: null, error: { code: "IdempotencyInProgress", data: {} } },
+            { status: 409, headers: { "retry-after": "0.01" } },
+          );
+        }
+        return Response.json(
+          { data: { ok: true }, error: null },
+          { headers: { "idempotent-replayed": "true" } },
+        );
+      },
+    });
+
+    const result = await api.sys.ping();
+    expect(result.error).toBeNull();
+    expect(result.data).toEqual({ ok: true });
+    expect(result.meta?.idempotentReplayed).toBe(true);
+    expect(n).toBe(3);
+  });
+
+  test("other 409 envelopes are not retried", async () => {
+    let n = 0;
+    const api = createClient<PingApp>("http://app.test", {
+      retry: { retries: 2, delay: 1, backoff: 1 },
+      fetch: async () => {
+        n += 1;
+        return Response.json(
+          { data: null, error: { code: "Conflict", data: {} } },
+          { status: 409 },
+        );
+      },
+    });
+    const { error } = await api.sys.ping();
+    expect(error?.code).toBe("Conflict");
+    expect(n).toBe(1);
+  });
+
+  test("GET still retries a network error", async () => {
+    let n = 0;
+    const api = createClient<PingApp>("http://app.test", {
+      retry: { retries: 1, delay: 1, backoff: 1 },
+      routes: getPing,
+      fetch: async () => {
+        n += 1;
+        if (n < 2) throw new TypeError("Failed to fetch");
+        return Response.json({ data: { ok: true }, error: null });
+      },
+    });
+
+    const { data, error } = await api.sys.ping();
+    expect(error).toBeNull();
+    expect(data).toEqual({ ok: true });
+    expect(n).toBe(2);
+  });
+
+  test("QUERY still retries a network error", async () => {
+    let n = 0;
+    const api = createClient<PingApp>("http://app.test", {
+      retry: { retries: 1, delay: 1, backoff: 1 },
+      routes: { "sys.ping": { method: "QUERY", path: "/ping" } },
+      fetch: async () => {
+        n += 1;
+        if (n < 2) throw new TypeError("Failed to fetch");
+        return Response.json({ data: { ok: true }, error: null });
+      },
+    });
+
+    const { data, error } = await api.sys.ping();
+    expect(error).toBeNull();
+    expect(data).toEqual({ ok: true });
+    expect(n).toBe(2);
+  });
 });
 
 describe("transport — timeout", () => {

package/src/client/transport.ts

@@ -12,12 +12,26 @@ import type {
   ClientHeaders,
   ClientOptions,
 } from "./types.ts";
+import {
+  applyAuthHeader,
+  applyHeaderBag,
+  interpolatePath,
+  resolveHeaders,
+  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. */
@@ -56,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 &&
@@ -71,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") {
@@ -82,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);
@@ -102,7 +144,7 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
  * @param message - Human-readable failure text
  * @param status - Optional HTTP status
  */
-function transportEnvelope(message: string, status?: number): ClientEnvelope {
+export function transportEnvelope(message: string, status?: number): ClientEnvelope {
   return {
     data: null,
     error: {
@@ -120,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;
     }
   }
@@ -131,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`
@@ -147,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
@@ -154,45 +209,32 @@ async function once(
     : rpcRequest(base, key, input);
 
   const headers = new Headers();
-  const extra = typeof opts.headers === "function" ? await opts.headers() : opts.headers;
-  if (Array.isArray(extra)) {
-    for (const [k, v] of extra) headers.set(k, v);
-  } else if (extra) {
-    for (const [k, v] of Object.entries(extra)) headers.set(k, v);
-  }
-  if (Array.isArray(callHeaders)) {
-    for (const [k, v] of callHeaders) headers.set(k, v);
-  } else if (callHeaders) {
-    for (const [k, v] of Object.entries(callHeaders)) headers.set(k, v);
-  }
+  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");
   }
+  await applyAuthHeader(headers, opts);
 
-  const token =
-    opts.auth && "getToken" in opts.auth && typeof opts.auth.getToken === "function"
-      ? await opts.auth.getToken()
-      : undefined;
-  if (token && !headers.has("authorization")) {
-    headers.set("authorization", `Bearer ${token}`);
-  }
+  const timeout = opts.timeout !== undefined ? AbortSignal.timeout(opts.timeout) : undefined;
+  const signal =
+    opts.signal && timeout ? AbortSignal.any([opts.signal, timeout]) : (opts.signal ?? timeout);
 
-  const signals: AbortSignal[] = [];
-  if (opts.signal) signals.push(opts.signal);
-  if (opts.timeout !== undefined) {
-    const t = AbortSignal.timeout(opts.timeout);
-    signals.push(t);
+  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;
   }
-  const signal =
-    signals.length === 0 ? undefined : signals.length === 1 ? signals[0] : AbortSignal.any(signals);
-
-  return await fetchFn(url, {
-    method,
-    headers,
-    body: body as RequestInit["body"],
-    signal,
-    ...(opts.credentials !== undefined ? { credentials: opts.credentials } : {}),
-  });
 }
 
 /**
@@ -236,58 +278,43 @@ function restRequest(
   if (isRawBody(input)) {
     return { url: `${base}${path}`, method: method.toUpperCase(), body: input };
   }
-  const params =
-    input !== null && typeof input === "object" ? (input as Record<string, unknown>) : {};
-  let pathOut = path;
-  const query: string[] = [];
-  const rest: Record<string, unknown> = {};
-
-  for (const [k, v] of Object.entries(params)) {
-    const token = `:${k}`;
-    if (pathOut.includes(token)) {
-      pathOut = pathOut.replaceAll(token, encodeURIComponent(String(v)));
-    } else {
-      rest[k] = v;
-    }
-  }
+  const interpolated = interpolatePath(path, input);
+  const pathOut = interpolated.path;
+  const rest = interpolated.rest;
 
   const upper = method.toUpperCase();
+  const hasRest = Object.keys(rest).length > 0;
   let body: ClientBodyInit | undefined;
+  let qs = "";
   if (upper === "GET" || upper === "HEAD") {
-    for (const [k, v] of Object.entries(rest)) {
-      if (v !== undefined) {
-        query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
-      }
-    }
+    qs = toQuery(rest);
   } else if (upper === "QUERY") {
     // RFC 10008 QUERY always carries JSON content (empty object when only path params).
-    body = JSON.stringify(Object.keys(rest).length > 0 ? rest : {});
-  } else if (Object.keys(rest).length > 0 || path === pathOut) {
-    body = JSON.stringify(Object.keys(rest).length > 0 ? rest : (input ?? {}));
+    body = JSON.stringify(hasRest ? rest : {});
+  } else if (hasRest || path === pathOut) {
+    body = JSON.stringify(hasRest ? rest : (input ?? {}));
   }
 
-  const qs = query.length ? `?${query.join("&")}` : "";
   return { url: `${base}${pathOut}${qs}`, method: upper, body };
 }
 
 function isRawBody(input: unknown): input is ClientBodyInit {
-  if (input === null || input === undefined) return false;
-  if (typeof Blob !== "undefined" && input instanceof Blob) return true;
-  if (typeof FormData !== "undefined" && input instanceof FormData) return true;
-  if (typeof ArrayBuffer !== "undefined" && input instanceof ArrayBuffer) return true;
-  if (typeof ArrayBuffer !== "undefined" && ArrayBuffer.isView(input)) return true;
-  if (typeof ReadableStream !== "undefined" && input instanceof ReadableStream) return true;
+  if (input instanceof Blob) return true;
+  if (input instanceof FormData) return true;
+  if (input instanceof ArrayBuffer) return true;
+  if (ArrayBuffer.isView(input)) return true;
+  if (input instanceof ReadableStream) return true;
   return false;
 }
 
 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);
   }
 
@@ -299,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);
@@ -311,28 +338,69 @@ async function decode(res: Response): Promise<ClientEnvelope> {
 
 async function decodeBinary(res: Response, mode: "blob" | "arrayBuffer"): Promise<ClientEnvelope> {
   if (!res.ok) {
-    const structured = await decodeIfEnvelopeClone(res);
+    const structured = await decodeIfEnvelope(res);
     if (structured) return structured;
     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);
 }
 
-/** Try JSON envelope from an error response without assuming the body is reusable. */
-async function decodeIfEnvelopeClone(res: Response): Promise<ClientEnvelope | null> {
-  const text = await res.text();
-  if (!text) return null;
-  let json: unknown;
-  try {
-    json = JSON.parse(text);
-  } catch {
-    return null;
-  }
-  if (json !== null && typeof json === "object" && "data" in json && "error" in json) {
-    return json as ClientEnvelope;
-  }
-  return null;
+/**
+ * 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 {