okengine 0.21.0 → 0.22.0

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 };
       };
     };
   };

package/src/client/wire.ts

@@ -0,0 +1,119 @@
+/**
+ * Shared REST wire helpers for transport, live subscribe, and streams.
+ */
+
+import type { ClientHeaders, ClientOptions, ClientRouteMap, FlowContract } from "./types.ts";
+
+/**
+ * Visit every flow contract in `app.$routes`.
+ *
+ * @param $routes - Runtime route map
+ * @param visit - Called with unit, flow, and contract
+ */
+export function walkContracts(
+  $routes: ClientRouteMap | undefined,
+  visit: (unit: string, flow: string, contract: FlowContract) => void,
+): void {
+  if (!$routes) return;
+  for (const [unit, flows] of Object.entries($routes)) {
+    if (!flows || typeof flows !== "object") continue;
+    for (const [flow, contract] of Object.entries(flows)) {
+      if (!contract || typeof contract !== "object") continue;
+      visit(unit, flow, contract);
+    }
+  }
+}
+
+/**
+ * Read `method` and `path` when both are strings.
+ *
+ * @param contract - One flow contract
+ */
+export function methodAndPath(
+  contract: object,
+): { readonly method: string; readonly path: string } | undefined {
+  const method = "method" in contract ? contract.method : undefined;
+  const path = "path" in contract ? contract.path : undefined;
+  if (typeof method === "string" && typeof path === "string") return { method, path };
+  return undefined;
+}
+
+/**
+ * Replace `:param` tokens in `path`. Unmatched keys land in `rest`.
+ *
+ * @param path - Path template
+ * @param input - JSON object, or anything else (ignored)
+ */
+export function interpolatePath(
+  path: string,
+  input: unknown,
+): { readonly path: string; readonly rest: Record<string, unknown> } {
+  const params =
+    input !== null && typeof input === "object" ? (input as Record<string, unknown>) : {};
+  let pathOut = path;
+  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;
+    }
+  }
+  return { path: pathOut, rest };
+}
+
+/**
+ * Encode a query string, skipping `undefined` values.
+ *
+ * @param rest - Keys that were not path params
+ */
+export function toQuery(rest: Record<string, unknown>): string {
+  const query: string[] = [];
+  for (const [k, v] of Object.entries(rest)) {
+    if (v !== undefined) {
+      query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    }
+  }
+  return query.length > 0 ? `?${query.join("&")}` : "";
+}
+
+/**
+ * Copy a header bag onto `headers` (later keys win within the bag).
+ *
+ * @param headers - Target
+ * @param extra - Record or tuple list
+ */
+export function applyHeaderBag(headers: Headers, extra: ClientHeaders | undefined): void {
+  if (!extra) return;
+  if (Array.isArray(extra)) {
+    for (const [k, v] of extra) headers.set(k, v);
+  } else {
+    for (const [k, v] of Object.entries(extra)) headers.set(k, v);
+  }
+}
+
+/**
+ * Resolve `opts.headers` when it is a function.
+ *
+ * @param opts - Client options
+ */
+export async function resolveHeaders(opts: ClientOptions): Promise<ClientHeaders | undefined> {
+  return typeof opts.headers === "function" ? await opts.headers() : opts.headers;
+}
+
+/**
+ * Set `Authorization` from `opts.auth.getToken` when the caller did not.
+ *
+ * @param headers - Target
+ * @param opts - Client options
+ */
+export async function applyAuthHeader(headers: Headers, opts: ClientOptions): Promise<void> {
+  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}`);
+  }
+}

package/src/compiler/aot.ts

@@ -6,30 +6,20 @@
  * {@link compileDynamic} / `aot: false` on edge runtimes that ban `eval`.
  */
 
-import type { FlowFailure } from "../kernel/errors.ts";
 import { validate, type SchemaInput } from "../validation/standard-schema.ts";
 import {
   assembleInput,
-  extractParts,
   parseBody,
   parseCookie,
   parseHeaders,
   parseQuery,
   type ContextInference,
-  type InputParts,
 } from "./http-parse.ts";
+import { createInterpretedParseValidate, type CompiledParseValidate } from "./interpret.ts";
 import { sucrose } from "./sucrose.ts";
 
-/** Result of parse + validate for one request. */
-export type ParseValidateResult =
-  | { readonly ok: true; readonly input: unknown }
-  | { readonly ok: false; readonly failure: FlowFailure };
-
-/** Compiled parse/validate function. */
-export type CompiledParseValidate = (
-  request: Request,
-  params: Readonly<Record<string, string>>,
-) => Promise<ParseValidateResult>;
+export type { CompiledParseValidate, ParseValidateResult } from "./interpret.ts";
+export { createInterpretedParseValidate };
 
 /** Options for {@link compileAot}. */
 export interface CompileRouteOptions {
@@ -152,25 +142,6 @@ function generateParseValidate(
   return factory(helpers);
 }
 
-/**
- * Interpreted parse/validate using the same helpers (AoT fallback).
- *
- * @param inference - Context flags
- * @param schema - Input schema
- */
-export function createInterpretedParseValidate(
-  inference: ContextInference,
-  schema: SchemaInput | undefined,
-): CompiledParseValidate {
-  return async (request, params) => {
-    const parts: InputParts = await extractParts(request, params, inference);
-    const raw = assembleInput(parts);
-    const result = await validate(schema, raw);
-    if (!result.ok) return { ok: false, failure: result.failure };
-    return { ok: true, input: result.value };
-  };
-}
-
 /**
  * Re-export sucrose for tests and tooling.
  */

package/src/compiler/dynamic.ts

@@ -7,15 +7,18 @@
  * a requirement). Produces byte-identical responses to {@link compileAot}.
  */
 
+import { lazyRequire } from "../kernel/lazy-require.ts";
 import type { SchemaInput } from "../validation/standard-schema.ts";
-import {
-  compileAot,
-  createInterpretedParseValidate,
-  type CompiledRoute,
-  type CompileRouteOptions,
-} from "./aot.ts";
+import type { CompiledRoute, CompileRouteOptions } from "./aot.ts";
 import { FULL_INFERENCE } from "./http-parse.ts";
-import { dynamicInference } from "./sucrose.ts";
+import { createInterpretedParseValidate } from "./interpret.ts";
+
+/**
+ * Load AoT codegen. Computed stem so the edge profile keeps the interpreted path only.
+ */
+function loadAot(): typeof import("./aot.ts") {
+  return lazyRequire(import.meta.dir, ["ao", "t"].join(""));
+}
 
 /**
  * Compile a route with the dynamic fallback (full context every request).
@@ -23,10 +26,9 @@ import { dynamicInference } from "./sucrose.ts";
  * @param options - Route metadata
  */
 export function compileDynamic(options: CompileRouteOptions): CompiledRoute {
-  const inference = dynamicInference();
   return {
-    inference,
-    parseValidate: createInterpretedParseValidate(inference, options.schema),
+    inference: FULL_INFERENCE,
+    parseValidate: createInterpretedParseValidate(FULL_INFERENCE, options.schema),
     aot: false,
   };
 }
@@ -39,7 +41,7 @@ export function compileDynamic(options: CompileRouteOptions): CompiledRoute {
  */
 export function compileRoute(options: CompileRouteOptions, aot: boolean = true): CompiledRoute {
   if (!aot) return compileDynamic(options);
-  return compileAot(options);
+  return loadAot().compileAot(options);
 }
 
 /**