okengine 0.23.0 → 0.23.2

package/src/elements/store/cache-bus.ts

@@ -0,0 +1,278 @@
+/**
+ * Cross-instance cache invalidation.
+ *
+ * Redis publishes `{ origin, resources }` on `oke:cache:invalidate`.
+ * Postgres, when Redis is not configured, inserts into `oke_cache_invalidations`
+ * and polls on database time. A process applies remote notices with
+ * {@link StoreCache.acceptRemote} and does not publish them again.
+ * Memory and single-instance apps do not broadcast. A missed notice is
+ * bounded by the cache TTL.
+ */
+
+import type { ResourceRef } from "../../manifest/types.ts";
+import type { StoreCache } from "./cache.ts";
+
+/** Redis pub/sub channel for cache invalidation. */
+export const CACHE_INVALIDATE_CHANNEL = "oke:cache:invalidate";
+
+/** Postgres table for cache invalidation when Redis is not configured. */
+export const CACHE_INVALIDATIONS_TABLE = "oke_cache_invalidations";
+
+/** Default overlap when polling the Postgres invalidation table. */
+const DEFAULT_LAG_MS = 30_000;
+
+/** Drop Postgres rows older than this. */
+const RETAIN_MS = 120_000;
+
+/** Redis commands the bus needs. */
+export interface CacheBusRedis {
+  /**
+   * Publish one message.
+   *
+   * @param channel - Channel name
+   * @param message - JSON payload
+   */
+  publish(channel: string, message: string): Promise<unknown>;
+  /**
+   * Subscribe. The returned function removes the listener.
+   *
+   * @param channel - Channel name
+   * @param listener - Message callback
+   */
+  subscribe(channel: string, listener: (message: string) => void): Promise<() => void>;
+}
+
+/** SQL surface the Postgres bus uses. Placeholders are `?`. */
+export interface CacheBusSql {
+  /**
+   * Run a query and return rows.
+   *
+   * @param sql - Statement
+   * @param params - Bound parameters
+   */
+  query(sql: string, params?: readonly unknown[]): Promise<ReadonlyArray<Record<string, unknown>>>;
+  /**
+   * Run a statement.
+   *
+   * @param sql - Statement
+   * @param params - Bound parameters
+   */
+  exec(sql: string, params?: readonly unknown[]): Promise<{ changes: number }>;
+}
+
+/** How {@link openCacheInvalidation} reaches other instances. */
+export type CacheBusOptions =
+  | {
+      readonly kind: "redis";
+      readonly redis: CacheBusRedis;
+      /** Sender id. Remote notices with this origin are ignored. */
+      readonly origin?: string;
+    }
+  | {
+      readonly kind: "postgres";
+      readonly sql: () => Promise<CacheBusSql | undefined>;
+      readonly origin?: string;
+      /** Overlap behind the cursor. Default 30_000. */
+      readonly lagMs?: number;
+    };
+
+/** Handle returned by {@link openCacheInvalidation}. */
+export interface CacheInvalidationBus {
+  /** Tell other instances these resources changed. */
+  publish(resources: readonly ResourceRef[]): void;
+  /** Pull Postgres notices. No-op for Redis. */
+  poll(): Promise<void>;
+  /** Stop the subscription or poll. */
+  stop(): Promise<void>;
+}
+
+/**
+ * Bind `cache` to Redis or Postgres invalidation.
+ *
+ * @param cache - Local cache
+ * @param options - Transport
+ */
+export function openCacheInvalidation(
+  cache: StoreCache,
+  options: CacheBusOptions,
+): CacheInvalidationBus {
+  const origin = options.origin ?? crypto.randomUUID();
+  if (options.kind === "redis") return openRedis(cache, options.redis, origin);
+  return openPostgres(cache, options.sql, origin, options.lagMs ?? DEFAULT_LAG_MS);
+}
+
+/**
+ * Bun Redis client for the invalidation channel.
+ * Subscribe uses its own connection.
+ *
+ * @param url - Redis URL
+ */
+export function bunRedisCacheClient(url: string): CacheBusRedis {
+  const pub = new Bun.RedisClient(url);
+  const sub = new Bun.RedisClient(url);
+  return {
+    publish: (channel, message) => pub.publish(channel, message),
+    async subscribe(channel, listener) {
+      await sub.subscribe(channel, (message) => {
+        listener(message);
+      });
+      return () => {
+        void sub.unsubscribe(channel);
+      };
+    },
+  };
+}
+
+function openRedis(cache: StoreCache, redis: CacheBusRedis, origin: string): CacheInvalidationBus {
+  let unsub: (() => void) | undefined;
+  let stopped = false;
+  const ready = redis
+    .subscribe(CACHE_INVALIDATE_CHANNEL, (message) => {
+      if (stopped) return;
+      const resources = resourcesFromMessage(message, origin);
+      if (resources.length > 0) cache.acceptRemote(resources);
+    })
+    .then((stop) => {
+      unsub = stop;
+    })
+    .catch((err: unknown) => {
+      console.error(err);
+    });
+  return {
+    publish(resources) {
+      if (stopped || resources.length === 0) return;
+      const body = JSON.stringify({ origin, resources });
+      void redis.publish(CACHE_INVALIDATE_CHANNEL, body).catch((err: unknown) => {
+        console.error(err);
+      });
+    },
+    poll: async () => {},
+    async stop() {
+      stopped = true;
+      await ready;
+      unsub?.();
+      unsub = undefined;
+    },
+  };
+}
+
+function openPostgres(
+  cache: StoreCache,
+  connect: () => Promise<CacheBusSql | undefined>,
+  origin: string,
+  lagMs: number,
+): CacheInvalidationBus {
+  let stopped = false;
+  let ready: Promise<void> | undefined;
+  let cursor = 0;
+  let head = true;
+  const seen = new Set<string>();
+
+  async function sql(): Promise<CacheBusSql | undefined> {
+    if (stopped) return undefined;
+    const conn = await connect();
+    if (!conn || stopped) return undefined;
+    if (!ready) ready = ensure(conn);
+    await ready;
+    return conn;
+  }
+
+  return {
+    publish(resources) {
+      if (stopped || resources.length === 0) return;
+      void insert(sql, origin, resources);
+    },
+    async poll() {
+      const conn = await sql();
+      if (!conn || stopped) return;
+      const clock = await conn.query(DB_NOW_SQL);
+      const dbNow = asNumber(clock[0]?.db_now);
+      const since = head ? 0 : cursor - lagMs;
+      const rows = await conn.query(POLL_SQL, [since]);
+      const fresh: ResourceRef[] = [];
+      for (const row of rows) {
+        const id = asString(row.id);
+        if (!id || seen.has(id)) continue;
+        seen.add(id);
+        if (head || asString(row.origin) === origin) continue;
+        const resource = asString(row.resource);
+        if (resource) fresh.push(resource as ResourceRef);
+      }
+      if (!head && fresh.length > 0) cache.acceptRemote(fresh);
+      head = false;
+      cursor = dbNow;
+      await conn.exec(DELETE_SQL, [dbNow - RETAIN_MS]);
+      if (seen.size > 10_000) {
+        seen.clear();
+      }
+    },
+    async stop() {
+      stopped = true;
+    },
+  };
+}
+
+async function ensure(conn: CacheBusSql): Promise<void> {
+  await conn.exec(CREATE_SQL);
+  await conn.exec(INDEX_SQL);
+}
+
+async function insert(
+  connect: () => Promise<CacheBusSql | undefined>,
+  origin: string,
+  resources: readonly ResourceRef[],
+): Promise<void> {
+  const conn = await connect();
+  if (!conn) return;
+  for (const resource of resources) {
+    await conn.exec(INSERT_SQL, [crypto.randomUUID(), resource, origin]);
+  }
+}
+
+function resourcesFromMessage(message: string, origin: string): ResourceRef[] {
+  try {
+    const parsed: unknown = JSON.parse(message);
+    if (parsed === null || typeof parsed !== "object") return [];
+    const rec = parsed as Record<string, unknown>;
+    if (rec.origin === origin) return [];
+    if (!Array.isArray(rec.resources)) return [];
+    const out: ResourceRef[] = [];
+    for (const item of rec.resources) {
+      if (typeof item === "string" && item.length > 0) out.push(item as ResourceRef);
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function asNumber(value: unknown): number {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    if (Number.isFinite(n)) return n;
+  }
+  return 0;
+}
+
+const CREATE_SQL = `CREATE TABLE IF NOT EXISTS ${CACHE_INVALIDATIONS_TABLE} (
+  id TEXT PRIMARY KEY,
+  resource TEXT NOT NULL,
+  origin TEXT NOT NULL,
+  created_at BIGINT NOT NULL DEFAULT ((extract(epoch from clock_timestamp()) * 1000)::bigint)
+)`;
+
+const INDEX_SQL = `CREATE INDEX IF NOT EXISTS ${CACHE_INVALIDATIONS_TABLE}_created_at ON ${CACHE_INVALIDATIONS_TABLE} (created_at)`;
+
+const INSERT_SQL = `INSERT INTO ${CACHE_INVALIDATIONS_TABLE} (id, resource, origin) VALUES (?, ?, ?)`;
+
+const DB_NOW_SQL = `SELECT (extract(epoch from clock_timestamp()) * 1000)::bigint AS db_now`;
+
+const POLL_SQL = `SELECT id, resource, origin, created_at FROM ${CACHE_INVALIDATIONS_TABLE} WHERE created_at >= ?`;
+
+const DELETE_SQL = `DELETE FROM ${CACHE_INVALIDATIONS_TABLE} WHERE created_at < ?`;

package/src/elements/store/cache.test.ts

@@ -17,6 +17,7 @@ import {
   isInvalidatedByWrite,
   resolveCacheEffects,
   tier1DimsByResource,
+  tier1FlowDims,
   tier1KeysForReads,
   tier1Lookup,
 } from "./cache.ts";
@@ -79,21 +80,41 @@ describe("tier-1 cache — exact per-resource invalidation (path b)", () => {
 });
 
 describe("autoCacheEligible", () => {
-  test("read-only flows cache by default; mutations / asks / durable / cache:false do not", () => {
-    expect(autoCacheEligible({ effects: { reads: ["sql:notes"] } })).toBe(true);
-    expect(autoCacheEligible({ cache: true, effects: { reads: ["sql:notes"] } })).toBe(true);
-    expect(autoCacheEligible({ cache: "30s", effects: { reads: ["sql:notes"] } })).toBe(true);
-    expect(autoCacheEligible({ cache: false, effects: { reads: ["sql:notes"] } })).toBe(false);
-    expect(autoCacheEligible({ durable: true, effects: { reads: ["sql:notes"] } })).toBe(false);
-    expect(autoCacheEligible({ effects: { reads: ["sql:notes"], writes: ["sql:notes"] } })).toBe(
-      false,
-    );
-    expect(autoCacheEligible({ effects: { reads: ["sql:notes"], asks: ["task-suggest"] } })).toBe(
+  test("pure store reads cache by default; side effects never cache", () => {
+    const reads: Effects = { reads: ["sql:notes"] };
+    expect(autoCacheEligible({ effects: reads })).toBe(true);
+    expect(autoCacheEligible({ auto: false, effects: reads })).toBe(false);
+    expect(autoCacheEligible({ auto: false, cache: true, effects: reads })).toBe(true);
+    expect(autoCacheEligible({ auto: true, effects: reads })).toBe(true);
+    expect(autoCacheEligible({ cache: true, effects: reads })).toBe(true);
+    expect(autoCacheEligible({ cache: "30s", effects: reads })).toBe(true);
+    expect(autoCacheEligible({ auto: true, cache: false, effects: reads })).toBe(false);
+    expect(autoCacheEligible({ cache: true, durable: true, effects: reads })).toBe(false);
+    expect(
+      autoCacheEligible({ cache: true, effects: { reads: ["sql:notes"], writes: ["sql:notes"] } }),
+    ).toBe(false);
+    expect(
+      autoCacheEligible({ cache: true, effects: { reads: ["sql:notes"], asks: ["task-suggest"] } }),
+    ).toBe(false);
+    for (const extra of [
+      { emits: ["note.created"] },
+      { sends: ["welcome"] },
+      { fetches: ["api.example.com"] },
+      { secrets: ["stripe"] },
+      { calls: ["notes.create"] },
+      { embeds: ["embed-small"] },
+      { decides: ["route"] },
+    ]) {
+      expect(autoCacheEligible({ auto: true, effects: { reads: ["sql:notes"], ...extra } })).toBe(
+        false,
+      );
+    }
+    expect(autoCacheEligible({ auto: true, effects: { reads: ["runs"] } })).toBe(false);
+    expect(autoCacheEligible({ auto: true, effects: { reads: ["signal:notify"] } })).toBe(false);
+    expect(autoCacheEligible({ auto: true, effects: { reads: ["sql:notes", "runs"] } })).toBe(
       false,
     );
-    expect(autoCacheEligible({ effects: { reads: ["runs"] } })).toBe(false);
-    expect(autoCacheEligible({ effects: { reads: ["signal:notify"] } })).toBe(false);
-    expect(autoCacheEligible({ effects: {} })).toBe(false);
+    expect(autoCacheEligible({ auto: true, effects: {} })).toBe(false);
   });
 
   test("flow+input dims keep list and get from colliding; invalidation still uses the resource", () => {
@@ -107,7 +128,7 @@ describe("autoCacheEligible", () => {
     expect(isInvalidatedByWrite(getKeys[0]!, { writes: ["sql:views"] })).toBe(true);
   });
 
-  test("effectsFromLedger keeps store reads/writes and asks; drops runs", () => {
+  test("effectsFromLedger keeps store effects and side effects, including non-store reads", () => {
     expect(
       effectsFromLedger([
         { kind: "read", resource: "sql:views" },
@@ -117,14 +138,98 @@ describe("autoCacheEligible", () => {
         { kind: "write", resource: "sql:views" },
         { kind: "ask", resource: "summarize" },
         { kind: "emit", resource: "view-changed" },
+        { kind: "send", resource: "welcome" },
+        { kind: "fetch", resource: "api.example.com" },
+        { kind: "secret", resource: "stripe" },
+        { kind: "call", resource: "notes.create" },
+        { kind: "embed", resource: "embed-small" },
+        { kind: "decide", resource: "route" },
       ]),
     ).toEqual({
-      reads: ["sql:views"],
+      reads: ["sql:views", "runs", "signal:notify"],
       writes: ["sql:views"],
       asks: ["summarize"],
+      emits: ["view-changed"],
+      sends: ["welcome"],
+      fetches: ["api.example.com"],
+      secrets: ["stripe"],
+      calls: ["notes.create"],
+      embeds: ["embed-small"],
+      decides: ["route"],
     });
   });
 
+  test("tier-1 dims always include tenant, locale, scopes, and roles", () => {
+    const effects: Effects = { reads: ["sql:notes"] };
+    const a = tier1FlowDims(
+      "notes.list",
+      {},
+      {
+        userId: "u1",
+        tenantId: "ta",
+        locale: "en",
+        scopes: ["b", "a"],
+        roles: ["admin"],
+      },
+    );
+    const b = tier1FlowDims(
+      "notes.list",
+      {},
+      {
+        userId: "u1",
+        tenantId: "tb",
+        locale: "en",
+        scopes: ["a", "b"],
+        roles: ["admin"],
+      },
+    );
+    const locale = tier1FlowDims(
+      "notes.list",
+      {},
+      {
+        userId: "u1",
+        tenantId: "ta",
+        locale: "ar",
+        scopes: ["a", "b"],
+        roles: ["member"],
+      },
+    );
+    expect(a).toContain("t:ta");
+    expect(a).toContain("l:en");
+    expect(a).toContain("s:a,b");
+    expect(a).toContain("r:admin");
+    expect(a).not.toEqual(b);
+    expect(
+      tier1DimsByResource(
+        effects,
+        "notes.list",
+        {},
+        {
+          userId: "u1",
+          tenantId: "ta",
+          locale: "en",
+          scopes: ["a"],
+          roles: ["admin"],
+        },
+      )["sql:notes"],
+    ).not.toEqual(
+      tier1DimsByResource(
+        effects,
+        "notes.list",
+        {},
+        {
+          userId: "u1",
+          tenantId: "ta",
+          locale: "ar",
+          scopes: ["a"],
+          roles: ["member"],
+        },
+      )["sql:notes"],
+    );
+    expect(locale).toContain("l:ar");
+    expect(locale).toContain("r:member");
+  });
+
   test("resolveCacheEffects prefers stamped reads, then learned reads", () => {
     expect(resolveCacheEffects({ reads: ["sql:views"] }, ["sql:tasks"])).toEqual({
       reads: ["sql:views"],
@@ -153,3 +258,62 @@ describe("autoCacheEligible", () => {
     expect(tier1Lookup((key) => cache.get<number>(key), ["a", "b"])).toBe(1);
   });
 });
+
+describe("tier-1 cache bounds", () => {
+  test("LRU drops the oldest entry past the cap and a remote invalidation is not republished", () => {
+    const seen: string[][] = [];
+    let now = 1_000;
+    const cache = createStoreCache({
+      now: () => now,
+      maxEntries: 2,
+      fanout: (resources) => {
+        seen.push([...resources]);
+      },
+    });
+    cache.set({ tier: 1, key: "a", value: 1, resources: ["sql:a"], expiresAt: now + 60_000 });
+    cache.set({ tier: 1, key: "b", value: 2, resources: ["sql:b"], expiresAt: now + 60_000 });
+    cache.get("a");
+    cache.set({ tier: 1, key: "c", value: 3, resources: ["sql:c"], expiresAt: now + 60_000 });
+    expect(cache.get<number>("b")).toBeUndefined();
+    expect(cache.get<number>("a")).toBe(1);
+    cache.invalidate(["sql:a"]);
+    expect(seen).toEqual([["sql:a"]]);
+    expect(cache.generationOf("sql:a")).toBe(1);
+    cache.acceptRemote(["sql:c"]);
+    expect(seen).toEqual([["sql:a"]]);
+    expect(cache.get("c")).toBeUndefined();
+  });
+
+  test("a flight that is invalidated does not cache, and the waiter refetches", async () => {
+    const cache = createStoreCache({ maxEntries: 10 });
+    let reads = 0;
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const leader = cache.coalesce("k", ["sql:notes"], async () => {
+      reads += 1;
+      await gate;
+      return reads;
+    });
+    const waiter = cache.coalesce("k", ["sql:notes"], async () => {
+      reads += 1;
+      return reads;
+    });
+    cache.invalidate(["sql:notes"]);
+    release();
+    const first = await leader;
+    const second = await waiter;
+    expect(first.cacheable).toBe(false);
+    expect(second.value).not.toBe(first.value);
+    expect(reads).toBe(2);
+  });
+
+  test("verified and operator are part of the key", () => {
+    const anon = tier1FlowDims("read", {}, { verified: false, operatorId: null });
+    const verified = tier1FlowDims("read", {}, { verified: true, operatorId: "op-1" });
+    expect(anon.join("/")).not.toBe(verified.join("/"));
+    expect(verified.join("/")).toContain("v:1");
+    expect(verified.join("/")).toContain("o:op-1");
+  });
+});