okengine 0.16.0 → 0.17.0

package/src/kernel/fx-live-stream.ts

@@ -0,0 +1,149 @@
+/**
+ * `fx.live` SSE + Last-Event-ID resume — lazy so Store-only `oke()` graphs
+ * do not pin `checkLiveResume` / 410 encoding.
+ *
+ * Do not import `fx.ts` (type or value): that cycle pulls `createFx` into
+ * this chunk the same way a static `fx-auth-keys` import would.
+ */
+
+import { currentAbortSignal, linkAbort } from "./abort-scope.ts";
+import { isDryRun } from "./dry-run.ts";
+import type { EffectKind } from "./effects.ts";
+
+const jsonResultBrand = Symbol.for("oke.json");
+const sseFrameBrand = Symbol.for("oke.sse.frame");
+
+function sseFrame(data: unknown, id?: string): unknown {
+  return id !== undefined ? { [sseFrameBrand]: true, data, id } : { [sseFrameBrand]: true, data };
+}
+
+/** Minimal bus surface used by {@link createLiveStream}. */
+export interface LiveStreamRuntime {
+  live(
+    name: string,
+    opts?: { readonly afterId?: string },
+  ): AsyncIterable<{ readonly id: string; readonly payload: unknown }>;
+  checkLiveResume(name: string, afterId: string): Promise<void>;
+}
+
+/** Capability gate used by {@link createLiveStream}. */
+export type LiveStreamGate = <T>(
+  kind: EffectKind,
+  resource: string,
+  body: () => T | Promise<T>,
+) => Promise<T>;
+
+/** Options for {@link createLiveStream}. */
+export interface CreateLiveStreamOptions {
+  readonly name: string;
+  readonly afterId?: string;
+  readonly match?: (payload: unknown) => boolean;
+  readonly gated: LiveStreamGate;
+  readonly signalRuntime: LiveStreamRuntime | undefined;
+}
+
+/**
+ * SSE carrier from {@link createLiveStream}.
+ *
+ * Runtime brand is `Symbol.for("oke.json")` — same as `fx.json.stream`.
+ * Callers in `fx.ts` assert this onto `JsonStreamResult`.
+ */
+export interface LiveStreamResult {
+  readonly kind: "stream";
+  readonly status: 200;
+  readonly chunks: AsyncIterable<unknown>;
+  ready?: () => Promise<void>;
+  finalize?: () => Promise<void>;
+}
+
+/**
+ * Build the SSE carrier for `fx.live`.
+ *
+ * @param options - Signal name, cursor, gate, runtime
+ */
+export function createLiveStream(options: CreateLiveStreamOptions): LiveStreamResult {
+  const { name, afterId, match, gated, signalRuntime } = options;
+  const bind = async (): Promise<boolean> => {
+    await gated("read", `signal:${name}`, async () => undefined);
+    if (isDryRun()) return false;
+    if (!signalRuntime) throw new Error("fx.live requires a bound signal runtime");
+    return true;
+  };
+  const chunks = (async function* () {
+    if (!(await bind())) return;
+    const ambient = currentAbortSignal();
+    const local = new AbortController();
+    const unlink = linkAbort(ambient, local);
+    const iter = signalRuntime!.live(name, { afterId })[Symbol.asyncIterator]();
+    const onAbort = (): void => {
+      void iter.return?.();
+    };
+    local.signal.addEventListener("abort", onAbort, { once: true });
+    try {
+      for (;;) {
+        if (local.signal.aborted) break;
+        const step = await iter.next();
+        if (step.done || local.signal.aborted) break;
+        if (match && !match(step.value.payload)) continue;
+        yield sseFrame(step.value.payload, step.value.id);
+      }
+    } finally {
+      local.signal.removeEventListener("abort", onAbort);
+      unlink();
+      await iter.return?.();
+      if (!local.signal.aborted) local.abort();
+    }
+  })();
+  const carrier: LiveStreamResult = {
+    kind: "stream",
+    status: 200,
+    chunks,
+    ready: async () => {
+      if (afterId && (await bind())) await signalRuntime!.checkLiveResume(name, afterId);
+    },
+  };
+  // Brand at runtime (`isJsonStreamResult`); not on {@link LiveStreamResult}
+  // so this file does not import `fx.ts` unique-symbol types (cycle / TS2353).
+  return Object.assign(carrier, { [jsonResultBrand]: true });
+}
+
+/**
+ * Map OKE1014 to HTTP 410 `{ error: { code: "LiveResumeGap" } }`.
+ *
+ * @param err - Thrown value
+ */
+export function encodeGap(err: unknown): Response | undefined {
+  const o = err as { code?: unknown; params?: { signal?: string; afterId?: string } };
+  if (o?.code !== 1014) return;
+  return Response.json(
+    {
+      data: null,
+      error: {
+        code: "LiveResumeGap",
+        data: { signal: o.params?.signal ?? "", afterId: o.params?.afterId ?? "" },
+      },
+    },
+    { status: 410 },
+  );
+}
+
+/**
+ * Await stream `ready` before the 200 SSE body.
+ *
+ * @param stream - Live / json.stream carrier
+ * @returns 410 response when the cursor is missing; otherwise `undefined`
+ */
+export async function awaitLiveReady(stream: {
+  readonly ready?: () => Promise<void>;
+  readonly finalize?: () => Promise<void>;
+}): Promise<Response | undefined> {
+  try {
+    await stream.ready?.();
+  } catch (err) {
+    await stream.finalize?.();
+    const gap = encodeGap(err);
+    if (gap) return gap;
+    throw err;
+  }
+  return undefined;
+}

package/src/kernel/fx-live.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, test } from "bun:test";
+import { encodeExecuteResult } from "../compiler/response.ts";
+import { memorySignalDriver } from "../drivers/index.ts";
+import { createSignalRuntime, signal, type SignalDecl } from "../elements/signal.ts";
+import { withAbortSignal } from "./abort-scope.ts";
+import { OkeError } from "./errors.ts";
+import { createFx, createFxContext, isSseFrame, signalReadRef } from "./fx.ts";
+
+describe("fx.live", () => {
+  test("undeclared signal read throws OKE1001", async () => {
+    const orderStatus = signal("order-status", { delivery: "live", optional: true });
+    const runtime = openRuntime(orderStatus);
+    const fx = createFx({
+      flow: "orders.events",
+      effects: { reads: [signalReadRef("order-status")] },
+      signalRuntime: runtime,
+    });
+    const other = signal("other-status", { delivery: "live", optional: true });
+    let err: unknown;
+    try {
+      const stream = fx.live(other);
+      await stream.chunks[Symbol.asyncIterator]().next();
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(OkeError);
+    const oke = err as OkeError;
+    expect(oke.code).toBe(1001);
+    expect(oke.causeText).toBe(
+      'Flow "orders.events" reads "signal:other-status" without declaring it.',
+    );
+    await runtime.close();
+  });
+
+  test("throws when no signal runtime is bound", async () => {
+    const fx = createFx({
+      flow: "orders.events",
+      effects: { reads: [signalReadRef("order-status")] },
+    });
+    const stream = fx.live("order-status");
+    await expect(stream.chunks[Symbol.asyncIterator]().next()).rejects.toThrow(
+      "fx.live requires a bound signal runtime",
+    );
+  });
+
+  test("ALS abort unsubscribes the live handler", async () => {
+    const orderStatus = signal("order-status", { delivery: "live", optional: true });
+    const runtime = openRuntime(orderStatus);
+    const bus = await runtime.start();
+    const { fx } = createFxContext({
+      flow: "orders.events",
+      effects: { reads: [signalReadRef("order-status")] },
+      signalRuntime: runtime,
+    });
+
+    const ctrl = new AbortController();
+    await withAbortSignal(ctrl.signal, async () => {
+      const stream = fx.live(orderStatus);
+      const it = stream.chunks[Symbol.asyncIterator]();
+      const pending = it.next();
+      const started = Date.now();
+      while ((await bus.inspect("order-status"))[0]?.connections !== 1) {
+        if (Date.now() - started > 500) throw new Error("live handler did not attach");
+        await new Promise((r) => setTimeout(r, 5));
+      }
+      ctrl.abort();
+      const step = await pending;
+      expect(step.done).toBe(true);
+    });
+
+    const after = await bus.inspect("order-status");
+    expect(after[0]?.connections).toBe(0);
+    await runtime.close();
+  });
+
+  test("yields branded SSE frames with id + payload", async () => {
+    const orderStatus = signal("order-status", { delivery: "live", optional: true });
+    const runtime = openRuntime(orderStatus);
+    const bus = await runtime.start();
+    await runtime.emit("order-status", { orderId: "ord_1", status: "placed" });
+    await bus.drain();
+
+    const { fx, ledger } = createFxContext({
+      flow: "orders.events",
+      effects: { reads: [signalReadRef("order-status")] },
+      signalRuntime: runtime,
+    });
+    const stream = fx.live(orderStatus);
+    const it = stream.chunks[Symbol.asyncIterator]();
+    const step = await it.next();
+    expect(step.done).toBe(false);
+    expect(isSseFrame(step.value)).toBe(true);
+    if (isSseFrame(step.value)) {
+      expect(step.value.data).toEqual({ orderId: "ord_1", status: "placed" });
+      expect(typeof step.value.id).toBe("string");
+    }
+    expect(ledger.entries.map((e) => `${e.kind}:${e.resource}`)).toEqual([
+      "read:signal:order-status",
+    ]);
+    await it.return?.();
+    await runtime.close();
+  });
+
+  test("afterId skips already-delivered events", async () => {
+    const orderStatus = signal("order-status", { delivery: "live", optional: true });
+    const runtime = openRuntime(orderStatus);
+    const bus = await runtime.start();
+    await runtime.emit("order-status", { orderId: "ord_1", status: "placed" });
+    await runtime.emit("order-status", { orderId: "ord_1", status: "shipped" });
+    await bus.drain();
+
+    const first = bus.live("order-status")[Symbol.asyncIterator]();
+    const a = await first.next();
+    await first.return?.();
+    const firstId = a.value?.id as string;
+
+    const { fx } = createFxContext({
+      flow: "orders.events",
+      effects: { reads: [signalReadRef("order-status")] },
+      signalRuntime: runtime,
+    });
+    const stream = fx.live(orderStatus, { afterId: firstId });
+    const it = stream.chunks[Symbol.asyncIterator]();
+    const step = await it.next();
+    expect(isSseFrame(step.value) && step.value.data).toEqual({
+      orderId: "ord_1",
+      status: "shipped",
+    });
+    await it.return?.();
+    await runtime.close();
+  });
+
+  test("ready throws OKE1014 for a missing afterId", async () => {
+    const orderStatus = signal("order-status", { delivery: "live", optional: true });
+    const runtime = openRuntime(orderStatus);
+    const fx = createFx({
+      flow: "orders.events",
+      effects: { reads: [signalReadRef("order-status")] },
+      signalRuntime: runtime,
+    });
+    const stream = fx.live(orderStatus, { afterId: "missing" });
+    await expect(stream.ready?.()).rejects.toMatchObject({ code: 1014 });
+    const res = await encodeExecuteResult({ output: stream });
+    expect(res.status).toBe(410);
+    expect(await res.json()).toMatchObject({
+      data: null,
+      error: { code: "LiveResumeGap", data: { signal: "order-status", afterId: "missing" } },
+    });
+    await runtime.close();
+  });
+});
+
+function openRuntime(decl: SignalDecl) {
+  const runtime = createSignalRuntime({ driver: memorySignalDriver });
+  runtime.register(decl);
+  return runtime;
+}

package/src/kernel/fx-runtime.ts

@@ -0,0 +1,15 @@
+/**
+ * Execute-time `fx` helpers — lazy chunk off Store-only `oke()` construction.
+ *
+ * `app.ts` / HTTP encode load this via computed require so `createFx` does
+ * not sit on graphs that never run a Flow.
+ */
+
+export {
+  createFxContext,
+  freezePrincipal,
+  isJsonResult,
+  isJsonStreamResult,
+  isSseFrame,
+  resolveName,
+} from "./fx.ts";

package/src/kernel/fx-tenant-store.ts

@@ -0,0 +1,213 @@
+/**
+ * Tenant KV prefix + vault request-time path — lazy chunk.
+ *
+ * Inlined wrappers would sit on every `createFx` / Store-only `oke()` graph
+ * even when `gate.auth.tenant` is off.
+ */
+
+import type { KvStoreDecl } from "../elements/store.ts";
+import type { VaultRuntime } from "../elements/vault.ts";
+import type { Manifest } from "../manifest/types.ts";
+import type { SessionCrypto, SessionStore } from "../auth/sessions.ts";
+import type { TenantStore } from "../auth/tenants.ts";
+import { throwOke } from "./errors.ts";
+import type { FxAuthIdentity } from "./fx-auth-keys.ts";
+import { bind, type AttachAuthTenantMethodsOptions } from "./fx-auth-tenants.ts";
+
+/**
+ * Whether this KV namespace is tenant-prefixed.
+ *
+ * @param decl - KV store decl
+ * @param tenantEnabled - `gate.auth.tenant` is on
+ */
+export function kvTenantScoped(decl: KvStoreDecl, tenantEnabled: boolean): boolean {
+  if (decl.tenantScoped === false) return false;
+  if (decl.tenantScoped === true) return true;
+  return tenantEnabled;
+}
+
+/**
+ * Prefix KV args with `{tenantId}:`. Fails loud when no tenant is resolved.
+ *
+ * @param tenantId - Live `fx.tenant.id`
+ * @param decl - KV store decl
+ * @param tenantEnabled - Tenancy switch
+ * @param prop - Handle method
+ * @param args - Original args
+ */
+export function rewriteKvArgs(
+  tenantId: string | null,
+  decl: KvStoreDecl,
+  tenantEnabled: boolean,
+  prop: string | symbol,
+  args: unknown[],
+): unknown[] {
+  if (!kvTenantScoped(decl, tenantEnabled)) return args;
+  if (!tenantId) throwOke("TENANT_REQUIRED");
+  const prefix = `${tenantId}:`;
+  if (prop === "list") {
+    const userPrefix = typeof args[0] === "string" ? args[0] : "";
+    return [`${prefix}${userPrefix}`];
+  }
+  if (typeof args[0] !== "string") return args;
+  return [`${prefix}${args[0]}`, ...args.slice(1)];
+}
+
+/**
+ * Strip the tenant prefix from `list()` results.
+ *
+ * @param tenantId - Live `fx.tenant.id`
+ * @param decl - KV store decl
+ * @param tenantEnabled - Tenancy switch
+ * @param keys - Physical keys
+ */
+export function stripKvPrefix(
+  tenantId: string | null,
+  decl: KvStoreDecl,
+  tenantEnabled: boolean,
+  keys: string[],
+): string[] {
+  if (!kvTenantScoped(decl, tenantEnabled) || !tenantId) return keys;
+  const prefix = `${tenantId}:`;
+  return keys.map((k) => (k.startsWith(prefix) ? k.slice(prefix.length) : k));
+}
+
+/**
+ * Request-time vault path `{tenantId}/{contract}` when the contract is per-tenant.
+ *
+ * @param tenantId - Live `fx.tenant.id`
+ * @param tenantEnabled - Tenancy switch
+ * @param contracts - Vault runtime contracts
+ * @param contractName - Capability name
+ */
+export function vaultStoragePath(
+  tenantId: string | null,
+  tenantEnabled: boolean,
+  contracts: VaultRuntime["contracts"] | undefined,
+  contractName: string,
+): string {
+  const decl = contracts?.get(contractName);
+  const perTenant =
+    decl?.perTenant === true || (tenantEnabled && decl !== undefined && decl.perTenant !== false);
+  if (!perTenant) return contractName;
+  if (!tenantId) throwOke("TENANT_REQUIRED");
+  return `${tenantId}/${contractName}`;
+}
+
+/**
+ * Compact KV rewrite used by `createFx` so long helper names stay off the
+ * Store-only `oke()` graph.
+ *
+ * @param mode - `in` prefixes args; `out` strips `list()` keys
+ * @param tenantId - Live `fx.tenant.id`
+ * @param decl - KV store decl
+ * @param tenantEnabled - Tenancy switch
+ * @param prop - Handle method
+ * @param payload - Args or list keys
+ */
+export function kv(
+  mode: "in" | "out",
+  tenantId: string | null,
+  decl: KvStoreDecl,
+  tenantEnabled: boolean,
+  prop: string | symbol,
+  payload: unknown,
+): unknown {
+  if (mode === "out") return stripKvPrefix(tenantId, decl, tenantEnabled, payload as string[]);
+  return rewriteKvArgs(tenantId, decl, tenantEnabled, prop, payload as unknown[]);
+}
+
+/**
+ * Compact vault path used by `createFx`.
+ *
+ * @param tenantId - Live `fx.tenant.id`
+ * @param tenantEnabled - Tenancy switch
+ * @param contracts - Vault runtime contracts
+ * @param contractName - Capability name
+ */
+export function path(
+  tenantId: string | null,
+  tenantEnabled: boolean,
+  contracts: VaultRuntime["contracts"] | undefined,
+  contractName: string,
+): string {
+  return vaultStoragePath(tenantId, tenantEnabled, contracts, contractName);
+}
+
+/**
+ * Fail loud when a per-tenant vault row is missing.
+ *
+ * @param storagePath - Physical `{tenantId}/{contract}` path
+ */
+export function missingVault(storagePath: string): Error {
+  return new Error(`fx.vault.get: missing per-tenant secret "${storagePath}"`);
+}
+
+/**
+ * Attach tenant auth methods and KV prefixing onto a live `fx` bag.
+ * Called from `createFx` only when tenancy is on.
+ *
+ * @param fx - Mutable fx bag
+ * @param ctx - Tenant id + createFx options + gates
+ */
+export function install(
+  fx: {
+    auth: FxAuthIdentity;
+    store: (ref: never) => object;
+  },
+  ctx: {
+    readonly tenantId: string | null;
+    readonly options: {
+      readonly tenantStore?: TenantStore;
+      readonly tenantEnabled?: boolean;
+      readonly sessions?: SessionStore;
+      readonly sessionCrypto?: SessionCrypto;
+      readonly manifest?: Manifest | null;
+    };
+    readonly now: () => number;
+    readonly gated: AttachAuthTenantMethodsOptions["gated"];
+  },
+): void {
+  const next = bind(
+    fx.auth,
+    {
+      tenantStore: ctx.options.tenantStore,
+      sessions: ctx.options.sessions,
+      sessionCrypto: ctx.options.sessionCrypto,
+      manifest: ctx.options.manifest ?? undefined,
+    },
+    ctx.now,
+    ctx.gated,
+  );
+  fx.auth = next;
+  if (ctx.options.tenantEnabled !== true) return;
+  const inner = fx.store;
+  (fx as { store: typeof inner }).store = ((ref: never) => {
+    const handle = inner(ref);
+    if (
+      typeof ref === "object" &&
+      ref !== null &&
+      "facet" in ref &&
+      (ref as KvStoreDecl).facet === "kv"
+    ) {
+      const decl = ref as KvStoreDecl;
+      return new Proxy(handle, {
+        get(target, prop, receiver) {
+          const val = Reflect.get(target, prop, receiver);
+          if (typeof val !== "function" || prop === "then") return val;
+          return (...args: unknown[]) => {
+            const callArgs = rewriteKvArgs(ctx.tenantId, decl, true, prop, args);
+            const result = (val as (...a: unknown[]) => unknown).apply(target, callArgs);
+            if (prop === "list") {
+              return Promise.resolve(result as Promise<string[]>).then((keys) =>
+                stripKvPrefix(ctx.tenantId, decl, true, keys),
+              );
+            }
+            return result;
+          };
+        },
+      });
+    }
+    return handle;
+  }) as typeof inner;
+}

package/src/kernel/fx.test.ts

@@ -86,6 +86,52 @@ describe("fx — capability enforcement", () => {
     expect(ttl).toBeGreaterThan(0);
   });
 
+  test("kv prefixes keys with tenant id and fails loud without one", async () => {
+    const { createStoreRuntime, store } = await import("../elements/store.ts");
+    const { memoryKvDriver } = await import("../drivers/index.ts");
+    const decl = store.kv("drafts");
+    const rt = createStoreRuntime({
+      drivers: { kv: memoryKvDriver },
+      kv: { drafts: {} },
+    });
+    rt.register(decl);
+    const acme = createFx({
+      flow: "drafts.acme",
+      effects: { reads: ["kv:drafts"], writes: ["kv:drafts"] },
+      storeRuntime: rt,
+      tenantEnabled: true,
+      tenant: { id: "acme" },
+    });
+    const globex = createFx({
+      flow: "drafts.globex",
+      effects: { reads: ["kv:drafts"], writes: ["kv:drafts"] },
+      storeRuntime: rt,
+      tenantEnabled: true,
+      tenant: { id: "globex" },
+    });
+    await acme.store(decl).set("note", "alice");
+    await globex.store(decl).set("note", "bob");
+    expect(await acme.store(decl).get("note")).toBe("alice");
+    expect(await globex.store(decl).get("note")).toBe("bob");
+    expect(await acme.store(decl).list()).toEqual(["note"]);
+
+    const none = createFx({
+      flow: "drafts.none",
+      effects: { writes: ["kv:drafts"] },
+      storeRuntime: rt,
+      tenantEnabled: true,
+      tenant: { id: null },
+    });
+    let err: unknown;
+    try {
+      await none.store(decl).set("note", "x");
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(OkeError);
+    expect((err as OkeError).code).toBe(1015);
+  });
+
   test("index driverId is meilisearch before first I/O (not a function, not memory)", async () => {
     const { createStoreRuntime, store } = await import("../elements/store.ts");
     const { meilisearchDriver } = await import("../drivers/index.ts");
@@ -334,6 +380,28 @@ describe("fx.vault — object surface", () => {
       /fx\.vault\.status needs a bound Vault backend/,
     );
   });
+
+  test("per-tenant contracts store under {tenantId}/{contract}", async () => {
+    const { createVaultRuntime, vault } = await import("../elements/vault.ts");
+    const { adapter, rows } = memoryAdapter();
+    const stripe = vault.secret("STRIPE_KEY", { perTenant: true, dev: "sk_unused" });
+    const runtime = createVaultRuntime({
+      secrets: [stripe],
+      tenantEnabled: true,
+    });
+    const fx = createFx({
+      flow: "billing.key",
+      effects: { secrets: ["STRIPE_KEY"] },
+      vaultRuntime: runtime,
+      vaultAdapter: adapter as never,
+      tenantEnabled: true,
+      tenant: { id: "acme" },
+    });
+    await fx.vault.set("STRIPE_KEY", "sk_acme");
+    expect([...rows.keys()]).toEqual(["acme/STRIPE_KEY"]);
+    const redacted = await fx.vault.get("STRIPE_KEY");
+    expect(redacted.reveal()).toBe("sk_acme");
+  });
 });
 
 describe("fx — wholesale swap", () => {
@@ -364,6 +432,9 @@ describe("fx — wholesale swap", () => {
       async deadLetters() {
         return [];
       },
+      live() {
+        throw new Error("live must not be used");
+      },
       async call() {
         return null;
       },
@@ -448,6 +519,26 @@ describe("fx — wholesale swap", () => {
         updateApiKey: async () => {
           throw new Error("auth.updateApiKey must not be used");
         },
+        listTenants: async () => [],
+        switchTenant: async () => {
+          throw new Error("auth.switchTenant must not be used");
+        },
+        createTenant: async () => {
+          throw new Error("auth.createTenant must not be used");
+        },
+        deleteTenant: async () => {
+          throw new Error("auth.deleteTenant must not be used");
+        },
+        addMember: async () => {
+          throw new Error("auth.addMember must not be used");
+        },
+        removeMember: async () => {
+          throw new Error("auth.removeMember must not be used");
+        },
+        listMembers: async () => [],
+        upsertTenantRole: async () => {
+          throw new Error("auth.upsertTenantRole must not be used");
+        },
       },
       operator: { id: null },
       principal: { userId: "u1", operatorId: null, scopes: new Set(["a"]) },