okengine 0.18.5 → 0.19.0

package/src/client/notes-contract.test.ts

@@ -8,6 +8,7 @@
 import { beforeEach, describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { oke } from "../kernel/app.ts";
+import { call } from "../kernel/call.ts";
 import { flow, resetFlowSeq } from "../kernel/flow.ts";
 import { on, resetBindings } from "../kernel/on.ts";
 import { http } from "../kernel/triggers.ts";
@@ -38,20 +39,15 @@ const NewNote = z.object({
 const NotFound = z.object({});
 
 const create = on(
-  http.post("/notes"),
+  http.post("/notes", { in: NewNote, out: NoteId }),
   flow("notes.create", {
-    in: NewNote,
-    out: NoteId,
     do: (input) => ({ id: `n_${input.title}` }),
   }),
 );
 
 const get = on(
-  http.get("/notes/:id"),
+  http.get("/notes/:id", { in: NoteId, out: Note, errors: { NotFound } }),
   flow("notes.get", {
-    in: NoteId,
-    out: Note,
-    errors: { NotFound },
     do: ({ id }, fx) =>
       id === "missing" ? fx.fail("NotFound", {}) : { id, title: "First", body: "Hello" },
   }),
@@ -252,7 +248,7 @@ describe("Notes — typeof app carries contracts", () => {
   });
 
   test("untriggered adopted flow is RPC-only on the client", async () => {
-    const stats = flow("notes.stats", {
+    const stats = call("notes.stats", {
       in: NoteId,
       out: z.object({ clicks: z.number() }),
       do: () => ({ clicks: 7 }),
@@ -280,8 +276,7 @@ describe("Notes — typeof app carries contracts", () => {
   });
 
   test("typeof app live exposure is subscribe, not JSON RPC", () => {
-    const orderStatus = signal("order-status", {
-      delivery: "live",
+    const orderStatus = signal.live("order-status", {
       optional: true,
       schema: z.object({ orderId: z.string(), status: z.string() }),
     });

package/src/client/sse.ts

@@ -0,0 +1,137 @@
+/**
+ * Shared SSE frame pump for live subscribe and JSON streams.
+ *
+ * @module
+ */
+
+/** Callback for one parsed SSE data frame. */
+export type SseFrameHandler = (event: unknown, id: string | undefined) => void;
+
+/**
+ * Read an SSE response body until `[DONE]`, abort, or EOF.
+ *
+ * @param res - Fetch response (`text/event-stream`)
+ * @param onEvent - Frame handler
+ * @param signal - Abort signal
+ * @param onOpen - Called after content-type validation
+ */
+export async function readSse(
+  res: Response,
+  onEvent: SseFrameHandler,
+  signal: AbortSignal,
+  onOpen?: () => void,
+): Promise<void> {
+  if (signal.aborted) return;
+  const ct = res.headers.get("content-type") ?? "";
+  if (!res.ok || !res.body) {
+    const text = await res.text().catch(() => "");
+    throw sseError(res.status, text);
+  }
+  if (!ct.includes("text/event-stream")) {
+    const text = await res.text().catch(() => "");
+    throw sseError(res.status, text || `Expected text/event-stream, got ${ct || "none"}`);
+  }
+  onOpen?.();
+  const reader = res.body.getReader();
+  const dec = new TextDecoder();
+  let buf = "";
+  try {
+    for (;;) {
+      if (signal.aborted) return;
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += dec.decode(value, { stream: true });
+      let sep = buf.indexOf("\n\n");
+      while (sep >= 0) {
+        const raw = buf.slice(0, sep);
+        buf = buf.slice(sep + 2);
+        const stop = dispatchFrame(raw, onEvent, signal);
+        if (stop || signal.aborted) return;
+        sep = buf.indexOf("\n\n");
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/**
+ * Yield SSE JSON frames as an async iterable until `[DONE]`.
+ *
+ * @param res - Fetch response
+ * @param signal - Abort signal
+ */
+export async function* iterateSse(res: Response, signal: AbortSignal): AsyncGenerator<unknown> {
+  const queue: unknown[] = [];
+  let wake: (() => void) | undefined;
+  let done = false;
+  let err: unknown;
+
+  const pump = readSse(
+    res,
+    (event) => {
+      queue.push(event);
+      wake?.();
+    },
+    signal,
+  )
+    .then(() => {
+      done = true;
+      wake?.();
+    })
+    .catch((e) => {
+      err = e;
+      done = true;
+      wake?.();
+    });
+
+  try {
+    for (;;) {
+      while (queue.length > 0) {
+        yield queue.shift();
+      }
+      if (done) break;
+      await new Promise<void>((r) => {
+        wake = r;
+      });
+      wake = undefined;
+    }
+    if (err) throw err;
+  } finally {
+    await pump.catch(() => {});
+  }
+}
+
+function dispatchFrame(raw: string, onEvent: SseFrameHandler, signal: AbortSignal): boolean {
+  const dataLines: string[] = [];
+  let id: string | undefined;
+  for (const line of raw.split("\n")) {
+    if (line.startsWith("id:")) id = line.slice(3).replace(/^ /, "");
+    if (line.startsWith("data:")) dataLines.push(line.slice(5).replace(/^ /, ""));
+  }
+  if (dataLines.length === 0) return false;
+  const data = dataLines.join("\n");
+  if (data === "[DONE]") return true;
+  if (signal.aborted) return true;
+  onEvent(JSON.parse(data) as unknown, id);
+  return false;
+}
+
+/** Build an Error with optional HTTP status. */
+export function sseError(status: number, body: string): Error {
+  let message = `HTTP ${status}`;
+  if (body) {
+    try {
+      const json: unknown = JSON.parse(body);
+      if (json !== null && typeof json === "object" && "error" in json) {
+        const err = (json as { error?: { code?: string; data?: { message?: string } } }).error;
+        message = err?.data?.message ?? err?.code ?? message;
+      }
+    } catch {
+      message = body.slice(0, 200);
+    }
+  }
+  const e = new Error(message);
+  (e as Error & { status?: number }).status = status;
+  return e;
+}

package/src/client/stream.ts

@@ -0,0 +1,147 @@
+/**
+ * Finite SSE stream consumer for `fx.json.stream` Flows.
+ *
+ * @module
+ */
+
+import { iterateSse, sseError } from "./sse.ts";
+import type { ClientFetch, ClientHeaders, ClientOptions, ClientRouteMap } from "./types.ts";
+
+/** Flow id → REST route for stream-only (non-live) SSE. */
+export type StreamByFlow = Readonly<
+  Record<string, { readonly method: string; readonly path: string }>
+>;
+
+/**
+ * Collect `stream: true` routes that are not live exposures.
+ *
+ * @param $routes - Runtime route map
+ */
+export function flattenStreamRoutes($routes: ClientRouteMap | undefined): StreamByFlow {
+  const out: Record<string, { readonly method: string; readonly path: string }> = {};
+  if (!$routes) return out;
+  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;
+      if (!("stream" in contract) || contract.stream !== true) continue;
+      if ("live" in contract && typeof contract.live === "string") continue;
+      const method = "method" in contract ? contract.method : undefined;
+      const path = "path" in contract ? contract.path : undefined;
+      if (typeof method === "string" && typeof path === "string") {
+        out[`${unit}.${flow}`] = { method, path };
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Open a one-shot SSE stream (no auto-resubscribe).
+ *
+ * @param base - Origin
+ * @param route - REST method/path
+ * @param input - JSON body / path params
+ * @param opts - Client options
+ */
+export async function* openStream(
+  base: string,
+  route: { readonly method: string; readonly path: string },
+  input: unknown,
+  opts: ClientOptions,
+): AsyncGenerator<unknown> {
+  const fetchFn: ClientFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+  let refreshed = false;
+  for (;;) {
+    const ctrl = new AbortController();
+    const parent = opts.signal;
+    if (parent) {
+      if (parent.aborted) {
+        ctrl.abort();
+      } else {
+        parent.addEventListener("abort", () => ctrl.abort(), { once: true });
+      }
+    }
+    const { url, method, body } = streamRequest(base, route.method, route.path, input);
+    const headers = new Headers({ accept: "text/event-stream" });
+    const extra = typeof opts.headers === "function" ? await opts.headers() : opts.headers;
+    applyHeaders(headers, extra);
+    if (body !== undefined && !headers.has("content-type")) {
+      headers.set("content-type", "application/json");
+    }
+    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 res = await fetchFn(url, {
+      method,
+      headers,
+      body,
+      signal: ctrl.signal,
+      ...(opts.credentials !== undefined ? { credentials: opts.credentials } : {}),
+    });
+    if (
+      res.status === 401 &&
+      opts.auth &&
+      "refresh" in opts.auth &&
+      typeof opts.auth.refresh === "function" &&
+      !refreshed
+    ) {
+      refreshed = true;
+      await opts.auth.refresh();
+      continue;
+    }
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw sseError(res.status, text);
+    }
+    yield* iterateSse(res, ctrl.signal);
+    return;
+  }
+}
+
+function streamRequest(
+  base: string,
+  method: string,
+  path: string,
+  input: unknown,
+): { url: string; method: string; body: string | undefined } {
+  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;
+    }
+  }
+  const upper = method.toUpperCase();
+  let body: string | undefined;
+  if (upper === "GET" || upper === "HEAD") {
+    const query: string[] = [];
+    for (const [k, v] of Object.entries(rest)) {
+      if (v !== undefined) {
+        query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+      }
+    }
+    const qs = query.length ? `?${query.join("&")}` : "";
+    return { url: `${base}${pathOut}${qs}`, method: upper, body: undefined };
+  }
+  body = JSON.stringify(Object.keys(rest).length > 0 ? rest : (input ?? {}));
+  return { url: `${base}${pathOut}`, method: upper, body };
+}
+
+function applyHeaders(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);
+  }
+}

package/src/client/transport.test.ts

@@ -142,3 +142,35 @@ describe("transport — auth refresh", () => {
     }
   });
 });
+
+describe("transport — binary response", () => {
+  test("response blob returns Blob data", async () => {
+    const bytes = new Uint8Array([37, 80, 68, 70]); // %PDF
+    const api = createClient<PingApp>("http://app.test", {
+      fetch: async () =>
+        new Response(bytes, {
+          status: 200,
+          headers: { "content-type": "application/pdf" },
+        }),
+    });
+    const { data, error } = await api.sys.ping({ response: "blob" });
+    expect(error).toBeNull();
+    expect(data).toBeInstanceOf(Blob);
+    expect((data as unknown as Blob).type).toContain("pdf");
+  });
+
+  test("response arrayBuffer returns bytes", async () => {
+    const bytes = new Uint8Array([1, 2, 3, 4]);
+    const api = createClient<PingApp>("http://app.test", {
+      fetch: async () =>
+        new Response(bytes, {
+          status: 200,
+          headers: { "content-type": "application/octet-stream" },
+        }),
+    });
+    const { data, error } = await api.sys.ping({ response: "arrayBuffer" });
+    expect(error).toBeNull();
+    expect(data).toBeInstanceOf(ArrayBuffer);
+    expect(new Uint8Array(data as unknown as ArrayBuffer)).toEqual(bytes);
+  });
+});

package/src/client/transport.ts

@@ -5,7 +5,20 @@
  * Optional `routes` map switches to REST (`method` + path template).
  */
 
-import type { ClientEnvelope, ClientFetch, ClientHeaders, ClientOptions } from "./types.ts";
+import type {
+  ClientBodyInit,
+  ClientEnvelope,
+  ClientFetch,
+  ClientHeaders,
+  ClientOptions,
+} from "./types.ts";
+
+/** Per-call transport options (binary decode, abort). */
+export interface TransportCallOptions {
+  readonly headers?: ClientHeaders;
+  readonly response?: "json" | "blob" | "arrayBuffer";
+  readonly signal?: AbortSignal;
+}
 
 /** Internal transport handle. */
 export interface Transport {
@@ -14,9 +27,13 @@ export interface Transport {
    *
    * @param key - `unit/flow`
    * @param input - JSON body / path-param source
-   * @param headers - Per-call extra headers (merged after static ones)
+   * @param headersOrOpts - Per-call headers or full call options
    */
-  call(key: string, input: unknown, headers?: ClientHeaders): Promise<ClientEnvelope>;
+  call(
+    key: string,
+    input: unknown,
+    headersOrOpts?: ClientHeaders | TransportCallOptions,
+  ): Promise<ClientEnvelope>;
 }
 
 /**
@@ -32,15 +49,24 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
   const backoff = opts.retry?.backoff ?? 2;
 
   return {
-    async call(key, input, callHeaders) {
+    async call(key, input, headersOrOpts) {
+      const callOpts = normalizeCallOpts(headersOrOpts);
       let refreshed = false;
       let attempt = 0;
       let delay = delay0;
+      const callClientOpts: ClientOptions =
+        callOpts.signal !== undefined ? { ...opts, signal: callOpts.signal } : opts;
 
       for (;;) {
         try {
-          const res = await once(base, key, input, opts, fetchFn, callHeaders);
-          if (res.status === 401 && opts.auth?.refresh && !refreshed) {
+          const res = await once(base, key, input, callClientOpts, fetchFn, callOpts.headers);
+          if (
+            res.status === 401 &&
+            opts.auth &&
+            "refresh" in opts.auth &&
+            typeof opts.auth.refresh === "function" &&
+            !refreshed
+          ) {
             refreshed = true;
             await opts.auth.refresh();
             continue;
@@ -50,6 +76,9 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
             if (structured) return structured;
             throw new Error(`HTTP ${res.status}`);
           }
+          if (callOpts.response === "blob" || callOpts.response === "arrayBuffer") {
+            return decodeBinary(res, callOpts.response);
+          }
           return decode(res);
         } catch (err) {
           const transient = isTransient(err);
@@ -73,6 +102,23 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
   };
 }
 
+function normalizeCallOpts(
+  headersOrOpts: ClientHeaders | TransportCallOptions | undefined,
+): TransportCallOptions {
+  if (headersOrOpts === undefined) return {};
+  if (Array.isArray(headersOrOpts)) return { headers: headersOrOpts };
+  if (
+    typeof headersOrOpts === "object" &&
+    ("response" in headersOrOpts || "signal" in headersOrOpts || "headers" in headersOrOpts)
+  ) {
+    const o = headersOrOpts as TransportCallOptions;
+    if (o.response !== undefined || o.signal !== undefined || o.headers !== undefined) {
+      return o;
+    }
+  }
+  return { headers: headersOrOpts as ClientHeaders };
+}
+
 /**
  * Single HTTP attempt. Throws on network / abort / 5xx (retryable).
  *
@@ -108,29 +154,34 @@ async function once(
   } else if (callHeaders) {
     for (const [k, v] of Object.entries(callHeaders)) headers.set(k, v);
   }
-  if (body !== undefined && !headers.has("content-type")) {
+  if (body !== undefined && !headers.has("content-type") && typeof body === "string") {
     headers.set("content-type", "application/json");
   }
 
-  const token = opts.auth ? await opts.auth.getToken() : undefined;
+  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 ctrl = opts.timeout !== undefined ? new AbortController() : undefined;
-  const timer =
-    ctrl && opts.timeout !== undefined ? setTimeout(() => ctrl.abort(), opts.timeout) : undefined;
-
-  try {
-    return await fetchFn(url, {
-      method,
-      headers,
-      body,
-      signal: ctrl?.signal,
-    });
-  } finally {
-    if (timer !== undefined) clearTimeout(timer);
+  const signals: AbortSignal[] = [];
+  if (opts.signal) signals.push(opts.signal);
+  if (opts.timeout !== undefined) {
+    const t = AbortSignal.timeout(opts.timeout);
+    signals.push(t);
   }
+  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 } : {}),
+  });
 }
 
 /**
@@ -158,10 +209,11 @@ function rpcRequest(
   base: string,
   key: string,
   input: unknown,
-): { url: string; method: string; body: string | undefined } {
+): { url: string; method: string; body: ClientBodyInit | undefined } {
   const url = `${base}/_oke/${key}`;
-  const body = input === undefined ? undefined : JSON.stringify(input ?? {});
-  return { url, method: "POST", body };
+  if (input === undefined) return { url, method: "POST", body: undefined };
+  if (isRawBody(input)) return { url, method: "POST", body: input };
+  return { url, method: "POST", body: JSON.stringify(input ?? {}) };
 }
 
 function restRequest(
@@ -169,7 +221,10 @@ function restRequest(
   method: string,
   path: string,
   input: unknown,
-): { url: string; method: string; body: string | undefined } {
+): { url: string; method: string; body: ClientBodyInit | undefined } {
+  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;
@@ -186,7 +241,7 @@ function restRequest(
   }
 
   const upper = method.toUpperCase();
-  let body: string | undefined;
+  let body: ClientBodyInit | undefined;
   if (upper === "GET" || upper === "HEAD") {
     for (const [k, v] of Object.entries(rest)) {
       if (v !== undefined) {
@@ -204,6 +259,16 @@ function restRequest(
   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;
+  return false;
+}
+
 async function decode(res: Response): Promise<ClientEnvelope> {
   if (res.status === 204) {
     return { data: undefined, error: null };
@@ -254,6 +319,38 @@ 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);
+    if (structured) return structured;
+    return {
+      data: null,
+      error: {
+        code: "TransportError",
+        data: { message: `HTTP ${res.status}`, status: res.status },
+      },
+    };
+  }
+  const data = mode === "blob" ? await res.blob() : await res.arrayBuffer();
+  return { data, error: null };
+}
+
+/** 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;
+}
+
 function isTransient(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
   if (err.name === "AbortError") return false;