okengine 0.6.1 → 0.7.0

package/src/elements/vault/boot-chain.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared Vault resolution-chain assembly for app boot and Console.
+ *
+ * Order (first hit wins): process.env → .env.local → compose .env.docker →
+ * backend layer (`env` seed / openbao / memory / managed).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ConfigEnv } from "../../config/index.ts";
+import {
+  envVaultDriver,
+  managedVaultDriver,
+  memoryVaultDriver,
+  openbaoVaultDriver,
+} from "../../drivers/index.ts";
+import { parseDotenv } from "../../drivers/vault-dotenv-parse.ts";
+import type { VaultDriverId } from "../../drivers/vault-types.ts";
+import { resolveComposeEnvPath } from "./chain.ts";
+import type { VaultChainLayer } from "./runtime.ts";
+
+/** Options for {@link buildVaultBootChain}. */
+export interface BuildVaultBootChainOptions {
+  /** Project root (defaults to `process.cwd()`). */
+  readonly cwd?: string;
+  /** Resolved `drivers.vault` id for the active env. */
+  readonly driverId: VaultDriverId;
+  /** Active config env — controls fail-loud vs soft fallback for openbao. */
+  readonly env?: ConfigEnv;
+  /** Seed secrets for the terminal memory / managed layer. */
+  readonly seed?: Readonly<Record<string, string>>;
+  /**
+   * When `openbao` is selected but credentials are missing:
+   * - `"throw"` — fail loud (default for `prod` / `docker`)
+   * - `"memory"` — soft-fallback to a seeded memory bag (Console / local)
+   */
+  readonly missingOpenbao?: "throw" | "memory";
+}
+
+/**
+ * Normalize a config label to a {@link VaultDriverId}.
+ *
+ * Accepts legacy `"dotenv"` as an alias for `"env"`.
+ *
+ * @param raw - Config string
+ */
+export function normalizeVaultDriverId(raw: string): VaultDriverId {
+  if (raw === "dotenv") return "env";
+  if (raw === "env" || raw === "openbao" || raw === "memory" || raw === "managed") {
+    return raw;
+  }
+  throw new Error(
+    `oke boot: unknown vault driver "${raw}" (expected env · openbao · memory · managed)`,
+  );
+}
+
+/**
+ * Build the standard Vault resolution chain for app boot / Console.
+ *
+ * @param options - Driver id + cwd + seed
+ */
+export function buildVaultBootChain(options: BuildVaultBootChainOptions): VaultChainLayer[] {
+  const cwd = options.cwd ?? process.cwd();
+  const seed = options.seed ?? {};
+  const composeEnv = resolveComposeEnvPath(cwd);
+
+  let composeText = "";
+  if (existsSync(composeEnv.path)) {
+    composeText = readFileSync(composeEnv.path, "utf8").toString();
+  }
+  const envMap = parseDotenv(composeText);
+  const openbaoUrl = process.env.OKE_VAULT_URL ?? envMap.get("OKE_VAULT_URL");
+  const openbaoToken = process.env.OKE_VAULT_TOKEN ?? envMap.get("OKE_VAULT_TOKEN");
+  const openbaoMount = process.env.OKE_VAULT_MOUNT ?? envMap.get("OKE_VAULT_MOUNT") ?? "secret";
+
+  const envLayers: VaultChainLayer[] = [
+    { driver: envVaultDriver, source: "process.env" },
+    {
+      driver: envVaultDriver,
+      source: ".env.local",
+      options: { path: resolve(cwd, ".env.local") },
+    },
+    {
+      driver: envVaultDriver,
+      source: composeEnv.source,
+      options: { path: composeEnv.path },
+    },
+  ];
+
+  switch (options.driverId) {
+    case "memory":
+      return [
+        {
+          driver: memoryVaultDriver,
+          source: "driver",
+          options: { secrets: seed },
+        },
+      ];
+    case "managed":
+      return [
+        {
+          driver: managedVaultDriver,
+          source: "driver",
+          options: { secrets: seed },
+        },
+      ];
+    case "env":
+      return [
+        ...envLayers,
+        {
+          driver: memoryVaultDriver,
+          source: "driver",
+          options: { secrets: seed },
+        },
+      ];
+    case "openbao": {
+      if (openbaoUrl && openbaoToken) {
+        return [
+          ...envLayers,
+          {
+            driver: openbaoVaultDriver,
+            source: "driver",
+            options: { url: openbaoUrl, token: openbaoToken, mount: openbaoMount },
+          },
+        ];
+      }
+      const env = options.env ?? "local";
+      const missing =
+        options.missingOpenbao ?? (env === "prod" || env === "docker" ? "throw" : "memory");
+      if (missing === "throw") {
+        throw new Error(
+          'oke boot: vault driver "openbao" needs OKE_VAULT_URL and OKE_VAULT_TOKEN ' +
+            "(did `oke dev -d` bootstrap OpenBao / write docker/.env.docker?)",
+        );
+      }
+      return [
+        ...envLayers,
+        {
+          driver: memoryVaultDriver,
+          source: "driver",
+          options: { secrets: seed },
+        },
+      ];
+    }
+    default: {
+      const _exhaustive: never = options.driverId;
+      throw new Error(`oke boot: unhandled vault driver ${String(_exhaustive)}`);
+    }
+  }
+}

package/src/elements/vault/runtime.ts

@@ -87,6 +87,11 @@ export interface CreateVaultRuntimeOptions {
 export interface VaultRuntime {
   /** Declared contracts by name. */
   readonly contracts: ReadonlyMap<string, VaultSecretDecl>;
+  /**
+   * Driver ids of each chain layer in order (`env` · `openbao` · `memory` · `managed`).
+   * Available before {@link boot}.
+   */
+  readonly chainDriverIds: readonly string[];
   /**
    * Open every chain layer, merge (first wins), validate all contracts,
    * register redaction. Throws {@link VaultBootError} listing every gap.
@@ -245,8 +250,11 @@ export function createVaultRuntime(options: CreateVaultRuntimeOptions = {}): Vau
     booted = true;
   }
 
+  const chainDriverIds = (options.chain ?? []).map((layer) => layer.driver.id);
+
   return {
     contracts,
+    chainDriverIds,
     get booted() {
       return booted;
     },

package/src/kernel/app.ts

@@ -55,6 +55,7 @@ import {
 } from "./fx.ts";
 import {
   currentDevSurface,
+  failureDetailFromResponse,
   logDevRequest,
   shouldLogDevRequests,
 } from "../runtime/dev-request-log.ts";
@@ -1180,7 +1181,7 @@ export function oke(options: OkeOptions): OkeApp {
       const url = new URL(request.url);
       const method = request.method.toUpperCase();
 
-      const respond = (response: Response): Response => {
+      const respond = async (response: Response): Promise<Response> => {
         if (shouldLogDevRequests()) {
           logDevRequest({
             surface: currentDevSurface(),
@@ -1189,6 +1190,7 @@ export function oke(options: OkeOptions): OkeApp {
             flow: flowLabel,
             status: response.status,
             ms: Math.round(performance.now() - started),
+            detail: await failureDetailFromResponse(response),
           });
         }
         return response;

package/src/kernel/boot-bind/clock.ts

@@ -2,9 +2,13 @@
  * Lazy clock binder — loaded only when Clock is declared.
  */
 
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import {
   clock as declareClock,
   createClockRuntime,
+  createFileCronStore,
+  createMemoryCronStore,
   createTestClockRuntime,
   type ClockDecl,
   type ClockRuntime,
@@ -18,9 +22,27 @@ export interface BindClockResult {
   readonly clockDecls: ReadonlyMap<string, ClockDecl>;
 }
 
+/** Default on-disk cron store path (multi-process leader election). */
+export const DEFAULT_FILE_CRON_PATH = ".oke/crons.json";
+
+/**
+ * Resolve `drivers.clock` for the active env.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+export function resolveClockDriverId(options: BootOptions, env: ConfigEnv): string {
+  const resolved = resolveDriverId(options.config?.drivers?.clock, env);
+  if (resolved) return resolved;
+  return env === "test" ? "frozen" : "memory";
+}
+
 /**
  * Construct / adopt a Clock runtime, register decls, reconcile.
  *
+ * Supported ids: `frozen` · `memory` · `file`. `postgres` (and any other id)
+ * fail loud — there is no postgres CronStore.
+ *
  * @param options - Boot options
  * @param env - Active environment
  * @param now - Clock
@@ -32,13 +54,36 @@ export async function bindClock(
   now: () => number,
   prebuilt?: ClockRuntime,
 ): Promise<BindClockResult> {
-  const clockDriver =
-    resolveDriverId(options.config?.drivers?.clock, env) ?? (env === "test" ? "frozen" : "memory");
-  const clock =
-    prebuilt ??
-    (clockDriver === "frozen" || env === "test"
-      ? createTestClockRuntime(now(), { instanceId: options.instanceId })
-      : createClockRuntime({ instanceId: options.instanceId, now }));
+  const clockDriver = resolveClockDriverId(options, env);
+
+  let clock: ClockRuntime;
+  if (prebuilt) {
+    clock = prebuilt;
+  } else if (clockDriver === "frozen" || env === "test") {
+    clock = createTestClockRuntime(now(), { instanceId: options.instanceId });
+  } else if (clockDriver === "memory") {
+    clock = createClockRuntime({
+      instanceId: options.instanceId,
+      now,
+      store: createMemoryCronStore(),
+    });
+  } else if (clockDriver === "file") {
+    const path = resolve(process.cwd(), DEFAULT_FILE_CRON_PATH);
+    mkdirSync(dirname(path), { recursive: true });
+    clock = createClockRuntime({
+      instanceId: options.instanceId,
+      now,
+      store: createFileCronStore(path),
+    });
+  } else if (clockDriver === "postgres") {
+    throw new Error(
+      'oke boot: clock driver "postgres" is not implemented — use "memory", "file", or "frozen"',
+    );
+  } else {
+    throw new Error(
+      `oke boot: unknown clock driver "${clockDriver}" (expected memory · file · frozen)`,
+    );
+  }
 
   const clockDecls = new Map<string, ClockDecl>();
   for (const c of options.clocks ?? []) {

package/src/kernel/boot-bind/gate.ts

@@ -2,18 +2,86 @@
  * Lazy gate binder — loaded only when Gate is declared (or required by AI).
  */
 
+import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import { memoryDrivers } from "../../drivers/memory.ts";
+import { redisDriver } from "../../drivers/redis.ts";
+import type { KvClientLike } from "../../drivers/types.ts";
 import { createGateRuntime, type GateRuntime } from "../../elements/gate.ts";
 import type { BootOptions } from "../boot.ts";
 
+/** Namespace for gate rate-limit counters (never shares an app kv declaration). */
+export const GATE_KV_NAMESPACE = "oke:gates";
+
 /**
- * Construct a Gate runtime backed by a memory kv namespace.
+ * Resolve the KV backend for Gate rates — same facet as `drivers.store.kv`.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ * @param docker - Docker mode
+ */
+export function resolveGateKvDriverId(
+  options: BootOptions,
+  env: ConfigEnv,
+  docker = false,
+): "memory" | "redis" {
+  const fromEnv = process.env.OKE_KV_DRIVER?.trim();
+  if (docker && fromEnv === "redis") return "redis";
+  if (docker && fromEnv === "memory") return "memory";
+  const resolved = resolveDriverId(options.config?.drivers?.store?.kv, env);
+  if (resolved === "redis") return "redis";
+  if (resolved === "memory") return "memory";
+  return docker ? "redis" : "memory";
+}
+
+function kvUrlFor(docker: boolean): string | undefined {
+  const url = process.env.REDIS_URL ?? process.env.OKE_STORE_KV_URL ?? undefined;
+  if (!url) {
+    if (docker) {
+      throw new Error(
+        "oke boot: gate redis kv needs REDIS_URL (did `oke dev -d` write docker/.env.docker?)",
+      );
+    }
+    return undefined;
+  }
+  return url;
+}
+
+/**
+ * Construct a Gate runtime backed by `drivers.store.kv` (namespace {@link GATE_KV_NAMESPACE}).
  *
  * @param options - Boot options
  * @param now - Clock
+ * @param env - Active environment
+ * @param docker - Docker mode
  */
-export async function bindGate(options: BootOptions, now: () => number): Promise<GateRuntime> {
-  const kvNs = await memoryDrivers.kv.open({ name: "oke:gates" });
+export async function bindGate(
+  options: BootOptions,
+  now: () => number,
+  env: ConfigEnv = "local",
+  docker = false,
+): Promise<GateRuntime> {
+  const kvId = resolveGateKvDriverId(options, env, docker);
+  const injected = options.clients?.kv as KvClientLike | undefined;
+
+  let kvNs;
+  if (kvId === "redis") {
+    const url = injected ? undefined : kvUrlFor(docker);
+    if (!injected && url === undefined) {
+      // Local without REDIS_URL — soft-fallback to memory (same as missing redis for store would fail;
+      // gate rates should not brick local apps that only declared policy gates).
+      kvNs = await memoryDrivers.kv.open({ name: GATE_KV_NAMESPACE, nowMs: now });
+    } else {
+      kvNs = await redisDriver.open({
+        name: GATE_KV_NAMESPACE,
+        ...(url !== undefined ? { url } : {}),
+        ...(injected !== undefined ? { client: injected } : {}),
+        nowMs: now,
+      });
+    }
+  } else {
+    kvNs = await memoryDrivers.kv.open({ name: GATE_KV_NAMESPACE, nowMs: now });
+  }
+
   return createGateRuntime({
     gates: options.gates ?? [],
     kv: kvNs,

package/src/kernel/boot-bind/honor-config.test.ts

@@ -0,0 +1,247 @@
+/**
+ * Boot-level acceptance: binders honour `drivers.*` config pins.
+ *
+ * Asserts runtime identity (driverId / store kind / chain), not hero strings.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRedisFakeClient } from "../../drivers/redis.ts";
+import { createSignalRedisFake } from "../../drivers/signal-redis.ts";
+import { clock } from "../../elements/clock.ts";
+import { gate } from "../../elements/gate.ts";
+import { signal } from "../../elements/signal.ts";
+import { vault } from "../../elements/vault.ts";
+import { buildVaultBootChain } from "../../elements/vault/boot-chain.ts";
+import { bootApplication } from "../boot.ts";
+
+describe("boot binders honour drivers.* config", () => {
+  const prevCwd = process.cwd();
+  let tmp: string | undefined;
+
+  afterEach(async () => {
+    process.chdir(prevCwd);
+    if (tmp) {
+      await rm(tmp, { recursive: true, force: true });
+      tmp = undefined;
+    }
+    delete process.env.OKE_VAULT_URL;
+    delete process.env.OKE_VAULT_TOKEN;
+    delete process.env.REDIS_URL;
+  });
+
+  test("vault: drivers.vault env builds env chain layers", async () => {
+    process.env.APP_NAME = "honor-config";
+    try {
+      const result = await bootApplication({
+        env: "local",
+        secrets: [vault.config("APP_NAME", { description: "app" })],
+        config: {
+          drivers: {
+            vault: { local: "env", docker: "openbao", test: "memory", prod: "openbao" },
+          },
+        },
+      });
+      try {
+        expect(result.vault).toBeDefined();
+        expect(result.vault!.chainDriverIds).toContain("env");
+        expect(result.vault!.chainDriverIds).toContain("memory");
+        expect(result.vault!.chainDriverIds[0]).toBe("env");
+      } finally {
+        await result.close();
+      }
+    } finally {
+      delete process.env.APP_NAME;
+    }
+  });
+
+  test("vault: drivers.vault openbao with credentials selects openbao layer", () => {
+    process.env.OKE_VAULT_URL = "http://127.0.0.1:8200";
+    process.env.OKE_VAULT_TOKEN = "test-token";
+    const chain = buildVaultBootChain({
+      driverId: "openbao",
+      env: "local",
+      missingOpenbao: "throw",
+    });
+    expect(chain.map((l) => l.driver.id)).toContain("openbao");
+    expect(chain.map((l) => l.driver.id)).toContain("env");
+  });
+
+  test("vault: openbao without credentials fails loud in prod", async () => {
+    delete process.env.OKE_VAULT_URL;
+    delete process.env.OKE_VAULT_TOKEN;
+    await expect(
+      bootApplication({
+        env: "prod",
+        secrets: [vault.config("APP_NAME", { description: "app", dev: "x" })],
+        vault: { allowDevFallbacks: true },
+        config: {
+          drivers: {
+            vault: { prod: "openbao" },
+          },
+        },
+      }),
+    ).rejects.toThrow(/openbao.*OKE_VAULT_URL/);
+  });
+
+  test("clock: drivers.clock memory binds memory CronStore", async () => {
+    const result = await bootApplication({
+      env: "local",
+      startScheduler: false,
+      clocks: [clock("tick", { every: "1h" })],
+      config: {
+        drivers: {
+          clock: { local: "memory", docker: "file", test: "frozen", prod: "file" },
+        },
+      },
+    });
+    try {
+      expect(result.clock!.driverId).toBe("memory");
+      expect(result.clock!.store.kind).toBe("memory");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("clock: drivers.clock file binds file CronStore", async () => {
+    tmp = await mkdtemp(join(tmpdir(), "oke-clock-file-"));
+    process.chdir(tmp);
+    const result = await bootApplication({
+      env: "local",
+      startScheduler: false,
+      clocks: [clock("tick", { every: "1h" })],
+      config: {
+        drivers: {
+          clock: { local: "file", docker: "file", test: "frozen", prod: "file" },
+        },
+      },
+    });
+    try {
+      expect(result.clock!.driverId).toBe("file");
+      expect(result.clock!.store.kind).toBe("file");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("clock: drivers.clock postgres fails loud", async () => {
+    await expect(
+      bootApplication({
+        env: "local",
+        startScheduler: false,
+        clocks: [clock("tick", { every: "1h" })],
+        config: {
+          drivers: {
+            clock: { local: "postgres" },
+          },
+        },
+      }),
+    ).rejects.toThrow(/clock driver "postgres" is not implemented/);
+  });
+
+  test("gate: drivers.store.kv redis opens redis-backed oke:gates", async () => {
+    const fake = createRedisFakeClient();
+    const result = await bootApplication({
+      env: "local",
+      gates: [gate.rate({ max: 10, per: "1m" })],
+      clients: { kv: fake },
+      config: {
+        drivers: {
+          store: {
+            kv: { local: "redis", docker: "redis", prod: "redis" },
+          },
+        },
+      },
+    });
+    try {
+      expect(result.gate!.kvDriverId).toBe("redis");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("gate: drivers.store.kv memory keeps memory oke:gates", async () => {
+    const result = await bootApplication({
+      env: "local",
+      gates: [gate.rate({ max: 10, per: "1m" })],
+      config: {
+        drivers: {
+          store: {
+            kv: { local: "memory", docker: "redis", prod: "redis" },
+          },
+        },
+      },
+    });
+    try {
+      expect(result.gate!.kvDriverId).toBe("memory");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("signal: drivers.signal memory binds memory", async () => {
+    const result = await bootApplication({
+      env: "local",
+      signals: [signal("ping", { delivery: "once" })],
+      config: {
+        drivers: {
+          signal: { local: "memory", docker: "redis", prod: "redis" },
+        },
+      },
+    });
+    try {
+      expect(result.signal!.driverId).toBe("memory");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("signal: drivers.signal redis binds redis", async () => {
+    const fake = createSignalRedisFake();
+    const result = await bootApplication({
+      env: "local",
+      signals: [signal("ping", { delivery: "once" })],
+      clients: { signalRedis: fake },
+      config: {
+        drivers: {
+          signal: { local: "redis", docker: "redis", prod: "redis" },
+        },
+      },
+    });
+    try {
+      expect(result.signal!.driverId).toBe("redis");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("signal: drivers.signal postgres fails loud (never silent memory)", async () => {
+    await expect(
+      bootApplication({
+        env: "local",
+        signals: [signal("ping", { delivery: "once" })],
+        config: {
+          drivers: {
+            signal: { local: "postgres" },
+          },
+        },
+      }),
+    ).rejects.toThrow(/signal driver "postgres"/);
+  });
+
+  test("signal: drivers.signal nats fails loud", async () => {
+    await expect(
+      bootApplication({
+        env: "local",
+        signals: [signal("ping", { delivery: "once" })],
+        config: {
+          drivers: {
+            signal: { local: "nats" },
+          },
+        },
+      }),
+    ).rejects.toThrow(/signal driver "nats"/);
+  });
+});