@rindle/api-server 0.4.2 → 0.4.4

package/src/index.ts

@@ -1,4 +1,4 @@
-import { driveMutationAsync, isoTx } from "@rindle/client";
+import { driveMutationAsync, insertCell, insertPlan, isoTx, toCell } from "@rindle/client";
 import type {
   Ast,
   ColType,
@@ -9,6 +9,7 @@ import type {
   MutatorCtx,
   NamedQuery,
   Query,
+  QueryResultRow,
   Schema,
   SharedMutator,
   SharedMutatorWithArgs,
@@ -65,6 +66,8 @@ export const DEFAULT_RINDLE_API_ROUTES = {
   applyRowChangeTxn: "/api/rindle/apply-row-change-txn",
   claimRoomEpoch: "/api/rindle/claim-room-epoch",
   roomLmids: "/api/rindle/room-lmids",
+  // The DO shell's cold-boot callback (§10.1) — active only when `realtime` is configured.
+  roomBoot: "/api/rindle/room-boot",
 } as const;
 
 export type MaybePromise<T> = T | PromiseLike<T>;
@@ -257,6 +260,7 @@ export interface RindleApiRoutes {
   applyRowChangeTxn: string;
   claimRoomEpoch: string;
   roomLmids: string;
+  roomBoot: string;
 }
 
 /** A room-host reply the transport writes VERBATIM (`status` + JSON `body`): the
@@ -282,6 +286,165 @@ export interface PinFanout {
   assertPins(pins: readonly MaterializeInput[]): Promise<void>;
 }
 
+// --------------------------------------------------------------------------- realtime (room) host
+//
+// Enabling Rindle Realtime for an app (RINDLE-REALTIME-ENABLEMENT-DESIGN.md §3.1) is ONE named
+// opt-in: the `realtime` options block. Its presence activates the flush trio AND `/room-boot`;
+// its absence keeps every room endpoint 403 and adds no route. The deprecated bare `authorizeRoom`
+// still gates the trio alone (it never activates `/room-boot`).
+
+/** The room-boot flush leg (enablement §5): where the placed room's write-behind lands and what
+ *  credential it presents. `urls` are the trio's ROUTE PATHS (root-relative — the shell resolves
+ *  them against the boot call's origin), so an app that overrides `routes` needs no out-of-band
+ *  sync; `headers` ride every flush call verbatim (`httpAuthority`'s `headers`). */
+export interface RoomBootFlush {
+  urls: { apply: string; claim: string; lmids: string };
+  headers: Record<string, string>;
+}
+
+/** The `/room-boot` response (RINDLE-REALTIME-DESIGN.md §10.1 — the DO shell's cold-boot
+ *  callback): the claimed placement epoch, the room's upstream footprint lease, and the flush
+ *  leg. A cold room boots inert and serves nothing until this returns. */
+export interface RoomBootResponse {
+  epoch: number;
+  upstreamLeaseToken: string;
+  /** Where the room opens its upstream subscription (a routed deploy's follower). Absent ⇒ the
+   *  shell's statically configured rindled ws endpoint. */
+  upstreamWsEndpoint?: string;
+  flush: RoomBootFlush;
+}
+
+export interface RindleRealtimeOptions<User> {
+  /** The boot shell secret (§10.1 — a host binding, never client-derived). Authenticates the
+   *  room's `Authorization: Bearer` on `/room-boot` (the default {@link authorizeBoot}) and keys
+   *  the DEFAULT epoch-bound flush credential. */
+  shellSecret: string;
+  /** doc → the room's approved upstream footprint (§3.1) — an `Ast` or fluent `Query`. MAY
+   *  delegate to the named-query registry internally; throw `RindleApiError("not-found", …, 404)`
+   *  for a doc that shouldn't exist. The §9 footprint budget belongs here — it runs once per
+   *  placement, at lease mint. */
+  resolveFootprint: (doc: string, ctx: ApiContext<User>) => MaybePromise<ApiQueryResult>;
+  /** Gates the flush trio — `authorizeRoom`, relocated. Default: verify the default flush
+   *  credential from the {@link ROOM_FLUSH_CREDENTIAL_HEADER} request header — which requires the
+   *  transport to pass its incoming request as `context.request` (Fetch `Request` and node
+   *  `IncomingMessage` shapes are both understood). */
+  authorize?: Authorizer<ApiContext<User>>;
+  /** Gates `/room-boot`. Default: constant-time `Authorization: Bearer` check against
+   *  {@link shellSecret} (same `context.request` requirement as {@link authorize}). */
+  authorizeBoot?: Authorizer<ApiContext<User>>;
+  /** Mint the flush headers a placed room presents on every flush call. Default:
+   *  {@link mintRoomFlushCredential} under {@link ROOM_FLUSH_CREDENTIAL_HEADER}. Override this
+   *  and {@link authorize} TOGETHER — they are the two ends of one credential. */
+  mintFlushHeaders?: (input: { doc: string; epoch: number }) => MaybePromise<Record<string, string>>;
+  /** Lease TTL for the room's upstream footprint materialization (defaults to the server-wide
+   *  `leaseTtlMs`, else the daemon's default). */
+  upstreamLeaseTtlMs?: number;
+  /** Static override for where rooms open their upstream subscription; default is the
+   *  `wsEndpoint` the materialize returns (set in routed deploys), else absent. */
+  upstreamWsEndpoint?: string;
+}
+
+// The DEFAULT flush credential: `rfc1.<b64url payload>.<b64url hmac-sha256>`, payload
+// `{v:1, doc, epoch, iat}`. Deliberately EPOCH-bound, not time-bound: the credential's lifecycle
+// IS the placement fence (§8.3 — a superseded epoch's flushes 409 at the store no matter what
+// credential they carry), and platform revocation is registry suspension, so an `exp` would only
+// force spurious re-boots of long-lived rooms. HMAC via WebCrypto (`crypto.subtle`) so the exact
+// same code runs in Node and a Cloudflare Worker — no `node:crypto` import (matching
+// `@rindle/room`'s token module).
+
+export const ROOM_FLUSH_CREDENTIAL_HEADER = "x-rindle-room-credential";
+
+const FLUSH_CREDENTIAL_PREFIX = "rfc1";
+
+export interface RoomFlushCredentialPayload {
+  v: 1;
+  doc: string;
+  epoch: number;
+  iat: number;
+}
+
+function b64url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// Return type inferred (`Uint8Array<ArrayBuffer>` under TS ≥5.7 libs) — an explicit
+// `Uint8Array` annotation widens to `ArrayBufferLike` and fails `crypto.subtle`'s
+// `BufferSource` under consumers compiling this source with newer lib types.
+function unb64url(s: string) {
+  const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/"));
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+async function flushHmacKey(secret: string, usage: "sign" | "verify") {
+  return crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    [usage],
+  );
+}
+
+/** Sign the default epoch-bound flush credential (`/room-boot` mints one per placement). */
+export async function mintRoomFlushCredential(opts: {
+  shellSecret: string;
+  doc: string;
+  epoch: number;
+  /** Mint time; defaults to `Date.now()`. Injectable for tests. */
+  now?: number;
+}): Promise<string> {
+  const payload: RoomFlushCredentialPayload = {
+    v: 1,
+    doc: opts.doc,
+    epoch: opts.epoch,
+    iat: opts.now ?? Date.now(),
+  };
+  const body = b64url(new TextEncoder().encode(JSON.stringify(payload)));
+  const signed = `${FLUSH_CREDENTIAL_PREFIX}.${body}`;
+  const key = await flushHmacKey(opts.shellSecret, "sign");
+  const sig = new Uint8Array(
+    await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(signed)),
+  );
+  return `${signed}.${b64url(sig)}`;
+}
+
+/** Verify a flush credential's MAC, then its claims; returns the payload or throws. The MAC is
+ *  checked FIRST — no claim is trusted before it passes. */
+export async function verifyRoomFlushCredential(
+  credential: string,
+  shellSecret: string,
+): Promise<RoomFlushCredentialPayload> {
+  const parts = credential.split(".");
+  if (parts.length !== 3 || parts[0] !== FLUSH_CREDENTIAL_PREFIX) {
+    throw new Error("not a room flush credential");
+  }
+  const [, body, sig] = parts;
+  const key = await flushHmacKey(shellSecret, "verify");
+  const ok = await crypto.subtle.verify(
+    "HMAC",
+    key,
+    unb64url(sig),
+    new TextEncoder().encode(`${FLUSH_CREDENTIAL_PREFIX}.${body}`),
+  );
+  if (!ok) throw new Error("bad signature");
+  let payload: RoomFlushCredentialPayload;
+  try {
+    payload = JSON.parse(new TextDecoder().decode(unb64url(body))) as RoomFlushCredentialPayload;
+  } catch {
+    throw new Error("malformed payload");
+  }
+  if (payload.v !== 1) throw new Error("unknown version");
+  if (typeof payload.doc !== "string" || payload.doc.length === 0) {
+    throw new Error("missing doc");
+  }
+  if (typeof payload.epoch !== "number") throw new Error("missing epoch");
+  return payload;
+}
+
 export interface RindleApiServerOptions<User> {
   daemon: RindleDaemonClient;
   /** Where mutations are applied and `lmid` is stamped ({@link MutationBackend}). Default:
@@ -298,10 +461,16 @@ export interface RindleApiServerOptions<User> {
   mutators?: ApiMutators<User>;
   authorizeQuery?: Authorizer<AuthorizeQueryInput<User>>;
   authorizeMutation?: Authorizer<AuthorizeMutationInput<User>>;
+  /** Rindle Realtime (RINDLE-REALTIME-ENABLEMENT-DESIGN.md §3.1): the ONE named opt-in.
+   *  Presence activates the room flush trio AND `/room-boot`; absence keeps every room
+   *  endpoint 403. Takes precedence over the deprecated {@link authorizeRoom}. */
+  realtime?: RindleRealtimeOptions<User>;
   /** The room write-authority gate (§5.3.1): validates the caller is a placed room —
    *  the epoch-bound flush credential rides `context.request`, and what it means is
    *  the app's to define. The room endpoints are DISABLED (403) until this is set:
-   *  hosting a write authority is an explicit opt-in, never a default. */
+   *  hosting a write authority is an explicit opt-in, never a default.
+   *  @deprecated Use {@link realtime} (its `authorize`) — this bare form gates the
+   *  flush trio but never activates `/room-boot`. When both are set, `realtime` wins. */
   authorizeRoom?: Authorizer<ApiContext<User>>;
   routes?: Partial<RindleApiRoutes>;
   mode?: StreamMode;
@@ -383,6 +552,10 @@ export interface RindleApiServer<User> {
   handleClaimRoomEpochJson(body: unknown, context: ApiContext<User>): Promise<RoomHostResponse>;
   /** The room's boot probe (§3.3), same gate + envelope. */
   handleRoomLmidsJson(body: unknown, context: ApiContext<User>): Promise<RoomHostResponse>;
+  /** The DO shell's cold-boot callback (§10.1; enablement §3.1): authenticate the shell
+   *  secret, resolve the doc's footprint, claim the placement epoch, mint the upstream
+   *  lease and the flush leg. 403 until {@link RindleApiServerOptions.realtime} is set. */
+  handleRoomBootJson(body: unknown, context: ApiContext<User>): Promise<RoomHostResponse>;
 }
 
 export type RindleApiErrorCode = "bad-request" | "forbidden" | "not-found" | "rejected";
@@ -522,6 +695,10 @@ export interface TableRenderMeta {
   pkNames: string[];
   /** Column name → declared type (only consulted by {@link SqlDialect.encodeValue}). */
   types: Record<string, ColType>;
+  /** Columns a full insert must name — the non-nullable ones (design 206 §6.2). */
+  required: string[];
+  /** The nullable (omittable-to-null) columns — an omitted one binds `NULL` (design 206 §6.2). */
+  nullable: ReadonlySet<string>;
 }
 
 export type RenderIndex = Record<string, TableRenderMeta>;
@@ -535,7 +712,10 @@ export function buildRenderIndex(schema: Schema): RenderIndex {
     const columns = Object.keys(meta.columns);
     const types: Record<string, ColType> = {};
     for (const c of columns) types[c] = meta.columns[c].type;
-    out[name] = { columns, pkNames: [...meta.primaryKey], types };
+    // Same schema-derived plan the client funnel uses (design 206 §6.1), so their required-sets
+    // and null-fills can't drift.
+    const { required, nullable } = insertPlan(schema.tables[name]);
+    out[name] = { columns, pkNames: [...meta.primaryKey], types, required, nullable };
   }
   return out;
 }
@@ -554,14 +734,15 @@ function tableMeta(render: RenderIndex, table: string): TableRenderMeta {
 }
 
 /** Validate a keyed row against a table: reject unknown columns; require the pk columns; with
- *  `full`, require EVERY column (an insert carries a whole row — there are no defaults). Mirrors the
- *  client `trackingTx.checkColumns` messages so an author sees the same error on both tiers. */
+ *  `full`, require every NON-nullable column (a nullable column may be omitted and is filled with
+ *  `NULL`, design 206 §6.2). Mirrors the client `trackingTx.checkColumns` messages so an author sees
+ *  the same error on both tiers. */
 function checkColumns(table: string, obj: KeyedRow, meta: TableRenderMeta, full: boolean): void {
   const unknown = Object.keys(obj).filter((k) => !meta.columns.includes(k));
   if (unknown.length) {
     throw new Error(`unknown column${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")} on ${table} — columns: ${meta.columns.join(", ")}`);
   }
-  const required = full ? meta.columns : meta.pkNames;
+  const required = full ? meta.required : meta.pkNames;
   const missing = required.filter((c) => !(c in obj));
   if (missing.length) {
     throw new Error(`missing ${full ? "column" : "primary-key column"}${missing.length > 1 ? "s" : ""} ${missing.join(", ")} on ${table}`);
@@ -577,8 +758,12 @@ export function renderOp(op: MutationOp, meta: TableRenderMeta, dialect: SqlDial
   const t = quoteIdent(op.table);
   const params: WireValue[] = [];
   // Bind a value and return its placeholder at the correct 1-based index (post-push length).
+  // `insertCell` fills NULL for an omitted nullable column on the insert arm (design 206 §6.2);
+  // on update/delete every bound column is guaranteed present, so it is a pass-through there.
+  // `toCell` stringifies a `json` object (a typed mutator passes the parsed object) — a string
+  // passes through, so an author may still pass pre-stringified json.
   const bind = (c: string, row: KeyedRow): string => {
-    params.push(encode(dialect, row[c], meta.types[c]));
+    params.push(encode(dialect, toCell(insertCell(row, c), meta.types[c]), meta.types[c]));
     return dialect.placeholder(params.length);
   };
 
@@ -1287,8 +1472,9 @@ export async function dumpQueryShapes<User>(opts: {
   exemplars?: Partial<Record<string, ReadonlyArray<ShapeExemplar<User>>>>;
 }): Promise<QueryShapesDoc> {
   const tables = Object.values(opts.schema.tables)
-    // Local-only tables live in the browser's memory source, never a TableSource — no indexes.
-    .filter((t) => t.local !== true)
+    // Local-only tables (both `true` and `"session"`) live in the browser's memory source,
+    // never a TableSource — no indexes.
+    .filter((t) => !t.local)
     .map((t) => ({ name: t.name, primaryKey: [...t.primaryKey] }))
     .sort((a, b) => a.name.localeCompare(b.name));
   const queries: QueryShapesDoc["queries"] = [];
@@ -1517,13 +1703,18 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
     }
   };
 
-  // The room write-authority gate (§5.3.1): endpoints are disabled until the app
-  // opts in with `authorizeRoom` — hosting an authority is never a default.
+  // The room write-authority gate (§5.3.1): endpoints are disabled until the app opts in —
+  // the `realtime` block (which also activates `/room-boot`) or the deprecated bare
+  // `authorizeRoom` (trio only). Hosting an authority is never a default.
+  const realtime = opts.realtime;
+  const roomAuthorizer: Authorizer<ApiContext<User>> | undefined = realtime
+    ? (realtime.authorize ?? defaultFlushGate(realtime.shellSecret))
+    : opts.authorizeRoom;
   const roomGate = async (context: ApiContext<User>): Promise<void> => {
-    if (!opts.authorizeRoom) {
+    if (!roomAuthorizer) {
       throw new RindleApiError("forbidden", "room authority not configured", 403);
     }
-    await assertAuthorized(opts.authorizeRoom, context);
+    await assertAuthorized(roomAuthorizer, context);
   };
 
   // The store's verdict rides specific statuses + body shapes (fence / conflict /
@@ -1588,6 +1779,58 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
         return daemonVerdict(e);
       }
     },
+    handleRoomBootJson: async (body, context) => {
+      if (!realtime) {
+        throw new RindleApiError("forbidden", "realtime not configured", 403);
+      }
+      await assertAuthorized(realtime.authorizeBoot ?? defaultBootGate(realtime.shellSecret), context);
+      const msg = parseObject(body, "room-boot request");
+      const doc = parseString(msg.doc, "doc");
+      if (msg.instance !== undefined) parseString(msg.instance, "instance"); // diagnostic identity only
+      const ast = queryResultToAst(await realtime.resolveFootprint(doc, context));
+      const claim = opts.daemon.claimRoomEpoch?.bind(opts.daemon);
+      if (!claim) {
+        throw new Error("the configured daemon client does not implement claimRoomEpoch");
+      }
+      try {
+        // Claim FIRST (§2.5): the lease below is minted for THIS placement, so a boot
+        // that loses the epoch race learns it here, before any materialization exists.
+        const { epoch } = await claim({ doc });
+        const lease = await opts.daemon.materialize({
+          ast,
+          // The room's upstream leg IS the normalized protocol (§3) — never the app's
+          // viewer `mode`.
+          mode: "normalized",
+          leaseTtlMs: realtime.upstreamLeaseTtlMs ?? opts.leaseTtlMs,
+        });
+        const headers = realtime.mintFlushHeaders
+          ? await realtime.mintFlushHeaders({ doc, epoch })
+          : {
+              [ROOM_FLUSH_CREDENTIAL_HEADER]: await mintRoomFlushCredential({
+                shellSecret: realtime.shellSecret,
+                doc,
+                epoch,
+              }),
+            };
+        const res: RoomBootResponse = {
+          epoch,
+          upstreamLeaseToken: lease.leaseToken,
+          flush: {
+            urls: {
+              apply: routes.applyRowChangeTxn,
+              claim: routes.claimRoomEpoch,
+              lmids: routes.roomLmids,
+            },
+            headers,
+          },
+        };
+        const upstreamWsEndpoint = realtime.upstreamWsEndpoint ?? lease.wsEndpoint;
+        if (upstreamWsEndpoint !== undefined) res.upstreamWsEndpoint = upstreamWsEndpoint;
+        return { status: 200, body: res };
+      } catch (e) {
+        return daemonVerdict(e);
+      }
+    },
     handleQueryJson: (body, context) => {
       const msg = parseObject(body, "query request");
       return createQueryLease({
@@ -1638,6 +1881,18 @@ export function runSharedMutation<Args, Ctx extends MutatorCtx>(
   return driveMutationAsync(mutator(isoTx, args, ctx), {
     apply: (op) => applyOpToServerTx(tx, op),
     read: (table, pk) => tx.row(table, pk),
+    query: async (q) => {
+      // The shared-seam contract is ALWAYS an array of rows: the client's `WriteTxn.query` returns
+      // an array even for a root `.one()` (the root unwrap is the Store's `materialize()`, not the
+      // in-mutator read — rust/src/wasm/db.rs). The server's `tx.query` returns a scalar (object|null)
+      // for a `.one()` root, so normalize it to `[]`/`[row]` here — one body sees the same shape on
+      // both tiers. (Postgres backend: `tx.query` rejects until POSTGRES-READ-COMPILER-DESIGN.md
+      // Phase B; the daemon/SQLite backend compiles + rides the open session — DAEMON §5.4.)
+      const ast = q.ast();
+      const res = await tx.query(ast);
+      if (ast.one === true) return res == null ? [] : [res as QueryResultRow];
+      return (res ?? []) as QueryResultRow[];
+    },
   });
 }
 
@@ -1678,6 +1933,66 @@ async function assertAuthorized<T>(authorizer: Authorizer<T> | undefined, input:
   if (result === false) throw new RindleApiError("forbidden", "rindle request forbidden", 403);
 }
 
+/** The default flush-trio gate: verify the default epoch-bound credential from the request
+ *  header. The two refusal messages are deliberately distinct — "missing" is a transport wiring
+ *  bug (no `context.request`), "refused" is an invalid credential. */
+function defaultFlushGate<User>(shellSecret: string): Authorizer<ApiContext<User>> {
+  return async (context) => {
+    const credential = requestHeader(context.request, ROOM_FLUSH_CREDENTIAL_HEADER);
+    if (!credential) {
+      throw new RindleApiError(
+        "forbidden",
+        `missing ${ROOM_FLUSH_CREDENTIAL_HEADER} header — is the transport passing its incoming request as context.request?`,
+        403,
+      );
+    }
+    try {
+      await verifyRoomFlushCredential(credential, shellSecret);
+    } catch (e) {
+      throw new RindleApiError("forbidden", `flush credential refused: ${errMessage(e)}`, 403);
+    }
+  };
+}
+
+/** The default `/room-boot` gate: `Authorization: Bearer <shell secret>` (README contract),
+ *  compared constant-time. */
+function defaultBootGate<User>(shellSecret: string): Authorizer<ApiContext<User>> {
+  return (context) => {
+    const auth = requestHeader(context.request, "authorization");
+    const bearer = auth && /^bearer\s/i.test(auth) ? auth.replace(/^bearer\s+/i, "") : undefined;
+    if (!bearer || !timingSafeEqualStr(bearer, shellSecret)) {
+      throw new RindleApiError("forbidden", "room-boot: shell secret refused", 403);
+    }
+  };
+}
+
+/** Best-effort header extraction from whatever the transport put in `context.request`: a Fetch
+ *  `Request` (`headers.get`), a node `IncomingMessage` (lowercased header map), or a plain
+ *  `{headers: {...}}`. `undefined` when there is no request or no such header. */
+function requestHeader(request: unknown, name: string): string | undefined {
+  if (!request || typeof request !== "object") return undefined;
+  const headers = (request as { headers?: unknown }).headers;
+  if (!headers || typeof headers !== "object") return undefined;
+  if (typeof (headers as { get?: unknown }).get === "function") {
+    return (headers as { get(n: string): string | null }).get(name) ?? undefined;
+  }
+  const map = headers as Record<string, unknown>;
+  const v = map[name.toLowerCase()] ?? map[name];
+  if (typeof v === "string") return v;
+  if (Array.isArray(v) && typeof v[0] === "string") return v[0];
+  return undefined;
+}
+
+/** Constant-time string equality (a length mismatch fails fast — length is not the secret). */
+function timingSafeEqualStr(a: string, b: string): boolean {
+  const ab = new TextEncoder().encode(a);
+  const bb = new TextEncoder().encode(b);
+  if (ab.length !== bb.length) return false;
+  let diff = 0;
+  for (let i = 0; i < ab.length; i++) diff |= ab[i] ^ bb[i];
+  return diff === 0;
+}
+
 async function resolvePolicy<User>(
   policy: RindleApiServerOptions<User>["materializationPolicy"],
   input: QueryLeaseRequest<User>,