@pramen/server 0.0.12 → 0.0.14

package/src/worker.ts

@@ -8,10 +8,12 @@ import { authorizeTenant, HmacStrategy, isAdmin, JwksStrategy, resolveIdentity,
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
 import { createMail } from "./runtime/mail";
+import { createQueue, type QueueProducerBinding } from "./runtime/queue";
+import { dispatchQueueBatch, type QueueBatch, type QueueContext } from "./runtime/queue-consumer";
 import { migrate } from "./runtime/migrate";
 import { compileAcl } from "./runtime/acl";
 import { Db } from "./runtime/db";
-import { D1Driver, type Driver } from "./runtime/driver";
+import { D1Driver, type D1SessionStart, type Driver } from "./runtime/driver";
 import { toResponse } from "./runtime/errors";
 import { Kv } from "./runtime/kv";
 import { listDOs, partitionDoName } from "./runtime/registry";
@@ -45,12 +47,37 @@ export interface Env {
   CORS_ORIGINS?: string;
   /** "true" to apply destructive schema migrations on the D1 path. Off by default. */
   PRAMEN_ALLOW_DESTRUCTIVE?: string;
+  /** Default store for /rpc when no `x-pramen-store` header is sent: `"d1"` runs the
+   * Worker+D1 path by default (requires DB bound); `"do"` (the default) routes to the
+   * per-tenant Durable Object. The header still overrides per-request. /live always
+   * needs the DO regardless of this setting. */
+  PRAMEN_STORE?: string;
+  /** Cloudflare Queues producer binding for ctx.queue (declared in oblaka.ts). Optional —
+   * ctx.queue discovers any producer binding by name; this just types the common one. */
+  JOBS?: QueueProducerBinding;
 }
 
 /** The secret used to sign/verify file tokens — a dedicated FILES_SECRET if set,
  * else AUTH_SECRET (so HS256 setups work out of the box). */
 const filesSecret = (env: Env): string => env.FILES_SECRET || env.AUTH_SECRET;
 
+/** Request/response header carrying the D1 session bookmark for read-your-writes: a
+ * client echoes the last response's value on its next request, anchoring a fresh
+ * session at that write so it reads its own writes (even off a lagging replica). */
+const D1_BOOKMARK_HEADER = "x-pramen-d1-bookmark";
+
+/** Decide whether an /rpc request runs on the D1 store. **Live queries ALWAYS use the
+ * DO** (they need a single writer + a socket host), regardless of header or default —
+ * so enabling `PRAMEN_STORE=d1` never silently breaks `/live`. Otherwise an explicit
+ * `x-pramen-store` header wins (`d1`/`do`), then the `PRAMEN_STORE` default. Pure +
+ * exported for unit testing. */
+export function useD1Store(opts: { storeHeader: string | null; isLive: boolean; defaultStore: string | undefined }): boolean {
+  if (opts.isLive) return false; // live is DO-only — never the D1 path
+  if (opts.storeHeader === "d1") return true;
+  if (opts.storeHeader === "do") return false;
+  return opts.defaultStore === "d1";
+}
+
 const json = (body: unknown, status = 200) => Response.json(body, { status });
 const forbidden = (what: string) => json({ ok: false, error: `access denied: ${what}`, code: "forbidden" }, 403);
 const badRequest = (msg: string) => json({ ok: false, error: msg, code: "bad_request" }, 400);
@@ -65,7 +92,10 @@ function corsHeaders(origin: string | null, env: Env): Record<string, string> {
   return {
     "access-control-allow-origin": allow.includes("*") ? "*" : origin,
     "access-control-allow-methods": "GET, POST, OPTIONS",
-    "access-control-allow-headers": "content-type, authorization, x-pramen-tenant, x-pramen-store",
+    "access-control-allow-headers": "content-type, authorization, x-pramen-tenant, x-pramen-store, x-pramen-d1-bookmark",
+    // Expose the D1 read-your-writes bookmark so a browser client can read it off the
+    // response and carry it forward on the next request.
+    "access-control-expose-headers": "x-pramen-d1-bookmark",
     vary: "origin",
   };
 }
@@ -83,6 +113,15 @@ function withCors(res: Response, cors: Record<string, string>): Response {
  * `tenant` for the default partition (so `idFromName(tenant)` is byte-for-byte unchanged
  * — backward-compat) and `${tenant}:${partition}` for any other partition. */
 function partitionStubFor(env: Env, tenant: string, partition: string = DEFAULT_PARTITION): DurableObjectStub {
+  // Fail with a clear message rather than a cryptic `Cannot read 'get' of undefined`
+  // when the Durable Object isn't bound (e.g. a D1-only deployment that fell through to
+  // the DO path). The Worker RPC surface depends on this binding existing.
+  if (!env.PRAMEN) {
+    throw new Error(
+      "pramen: no Durable Object bound (PRAMEN). Pin the D1 store per request with the " +
+        "'x-pramen-store: d1' header (or set PRAMEN_STORE=d1), or bind the PramenDO.",
+    );
+  }
   return env.PRAMEN.get(env.PRAMEN.idFromName(partitionDoName(tenant, partition)));
 }
 
@@ -151,21 +190,24 @@ export function makeWorker(app: PramenApp) {
     const files = createFiles({ tenant: "main", secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
     const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema, suppressTriggers: true }, app.schema);
     const kv = new Kv(env.KV);
-    return { db, kv, files, env: env as unknown as Record<string, unknown>, identity, tasks: tasksFacade(driver), mail: createMail(env as unknown as Record<string, unknown>, kv) };
+    return { db, kv, files, env: env as unknown as Record<string, unknown>, identity, tasks: tasksFacade(driver), mail: createMail(env as unknown as Record<string, unknown>, kv), queue: createQueue(env as unknown as Record<string, unknown>) };
   };
 
   /** Drain the D1 outbox in the Worker (no DO/alarm on this path) — called by the
    * /admin/tasks/drain route with `x-pramen-store: d1`, and by `scheduled()` (Cron). */
   const drainD1 = async (env: Env): Promise<unknown> => {
     if (!env.DB) throw new Error("D1 store is not configured");
-    const driver = new D1Driver(env.DB);
+    // The drain reads due tasks then writes their status — pin the primary so it sees
+    // and updates current outbox state (not a lagging replica).
+    const driver = new D1Driver(env.DB, { start: "first-primary" });
     await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
     return drainOutbox(driver, bindTasks(app.tasks, d1TaskCtx(driver, env)), Date.now());
   };
 
   const listD1Tasks = async (env: Env, status?: string, limit?: number): Promise<unknown> => {
     if (!env.DB) throw new Error("D1 store is not configured");
-    const driver = new D1Driver(env.DB);
+    // Inspection listing — pin the primary so it reflects current outbox state.
+    const driver = new D1Driver(env.DB, { start: "first-primary" });
     await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
     return listTasks(driver, { status, limit });
   };
@@ -344,23 +386,42 @@ export function makeWorker(app: PramenApp) {
     const tenant = req.headers.get("x-pramen-tenant") ?? "main";
     if (!authorizeTenant(identity, tenant)) return withCors(forbidden(`tenant '${tenant}'`), cors);
 
-    // --- Worker + D1 (no DO): the same schema/ACL/read engine over a D1 binding,
-    // selected per-request via `x-pramen-store: d1`. RPC only — live queries need the
-    // DO (single writer + a socket host). This proof uses ONE shared D1 database
-    // across tenants; a real product would add a tenant column or a per-tenant DB.
-    if (req.headers.get("x-pramen-store") === "d1") {
+    // --- Worker + D1 (no DO): the same schema/ACL/read engine over a D1 binding.
+    // Selected per-request via `x-pramen-store: d1`, OR as the app-wide default when
+    // PRAMEN_STORE=d1 (the header still overrides: `x-pramen-store: do` forces the DO).
+    // RPC only — live queries need the DO (single writer + a socket host). This proof
+    // uses ONE shared D1 database across tenants; a real product would add a tenant
+    // column or a per-tenant DB.
+    const storeHeader = req.headers.get("x-pramen-store");
+    const useD1 = useD1Store({ storeHeader, isLive, defaultStore: env.PRAMEN_STORE });
+    if (useD1) {
       if (!env.DB) return badRequest("D1 store is not configured");
-      if (isLive) return badRequest("live queries require the default (DO) store");
+      // (isLive is excluded by useD1Store — live always routes to the DO below.)
       const name = url.pathname.replace(/^\/rpc\//, "");
       let input: unknown;
       if (request.method === "POST") input = await request.json().catch(() => undefined);
-      const driver = new D1Driver(env.DB);
+
+      // Pick where the D1 session may start its first read. A client-supplied bookmark
+      // wins (read-your-writes); otherwise default by handler kind: a mutation pins the
+      // primary so its reads see current data, a query may begin at the nearest replica.
+      const inboundBookmark = req.headers.get(D1_BOOKMARK_HEADER);
+      const kind = app.handlers[name]?.kind;
+      let start: D1SessionStart;
+      if (inboundBookmark) start = inboundBookmark;
+      else if (kind === "mutation") start = "first-primary";
+      else start = "first-unconstrained";
+
+      const driver = new D1Driver(env.DB, { start });
       const files = createFiles({ tenant, secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
       const envBag = env as unknown as Record<string, unknown>;
       try {
         await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
         const { result } = await dispatch(app.handlers, app.schema, driver, new Kv(env.KV), files, envBag, { acl: d1Acl, identity }, name, input);
-        return withCors(json({ ok: true, result }), cors);
+        const res = json({ ok: true, result });
+        // Thread the session's latest bookmark back so the client can read its own writes.
+        const bookmark = driver.getBookmark();
+        if (bookmark) res.headers.set(D1_BOOKMARK_HEADER, bookmark);
+        return withCors(res, cors);
       } catch (err) {
         const { status, body } = toResponse(err);
         return withCors(json(body, status), cors);
@@ -384,6 +445,21 @@ export function makeWorker(app: PramenApp) {
     else headers.delete("x-pramen-identity");
     headers.set("x-pramen-partition", partition);
 
+    // Routed to the DO but no DO is bound — return a clear, actionable error instead of
+    // crashing the whole RPC surface. (A D1-only deployment should pin the D1 store with
+    // the `x-pramen-store: d1` header; the `PRAMEN_STORE` env default can be dropped by
+    // some adapters' env proxies, so the header is the reliable way to pin it.)
+    if (!env.PRAMEN) {
+      return withCors(
+        badRequest(
+          isLive
+            ? "live queries require a Durable Object, but no PRAMEN binding is configured"
+            : "no Durable Object (PRAMEN) is bound — pin the D1 store with the 'x-pramen-store: d1' header (or bind the DO)",
+        ),
+        cors,
+      );
+    }
+
     const stub = partitionStubFor(env, tenant, partition);
     // WebSocket upgrades (101) must be returned untouched; only add CORS to HTTP.
     const res = await stub.fetch(new Request(req, { headers }));
@@ -395,5 +471,21 @@ export function makeWorker(app: PramenApp) {
     async scheduled(_event: unknown, env: Env): Promise<void> {
       if (env.DB) await drainD1(env);
     },
+
+    // Cloudflare Queues consumer entry: routes a batch to the matching `app.queues`
+    // handler (ACK on success / RETRY on throw, per message). A consumer is Worker-level
+    // (no tenant DO): its ctx carries env/kv/mail/queue + callPrivileged to reach a DO.
+    async queue(batch: QueueBatch, env: Env): Promise<void> {
+      const envBag = env as unknown as Record<string, unknown>;
+      const kv = new Kv(env.KV);
+      const ctx: QueueContext = {
+        env: envBag,
+        kv,
+        mail: createMail(envBag, kv),
+        queue: createQueue(envBag),
+        callPrivileged: (opts) => callPrivileged(env, opts),
+      };
+      await dispatchQueueBatch(app.queues ?? {}, ctx, batch);
+    },
   };
 }