@rindle/api-server 0.5.0 → 0.6.3

package/src/index.ts

@@ -68,11 +68,13 @@ import {
 import type { RoomProfile, RoomScopeSpec, RoomTableSpec } from "./rooms.ts";
 // The room lease token (RINDLE-REALTIME §10.1): minted here, verified by the room SHELL against
 // its `downstream.tokenKeys` ring — the `/token` subpath is pure WebCrypto (no wasm, no shell).
-// Loaded LAZILY at the first mint: `@rindle/room` is a dev-only workspace dep (it is not published
-// to npm yet — infra/tests/publish-sync.mjs would flag a runtime dep on it), and the mint only
-// runs when `realtime.roomTokenKey` is configured. In-repo (workspace linking) the import always
-// resolves; an npm consumer without the package gets the serve decision's ordinary fail-open —
-// daemon-served leases plus a one-time warning naming the missing module.
+// Loaded LAZILY at the first mint: `@rindle/room` is an OPTIONAL dependency (see package.json), so
+// it is installed transitively — a consumer bundling api-server (Vite/Rollup/esbuild) can resolve
+// this dynamic import even when it never uses rooms — yet the mint only runs when
+// `realtime.roomTokenKey` is configured. Should the module be genuinely absent (an install that
+// skipped the optional dep), the serve decision fail-opens: daemon-served leases plus a one-time
+// warning naming the missing module. It is NOT a hard `dependency` because the entire code path is
+// optional; optionalDependencies keeps a failed install of it non-fatal.
 import type { mintRoomToken as MintRoomToken, scopeSpecsHash as ScopeSpecsHash } from "@rindle/room/token";
 let roomTokenModule: { mintRoomToken: typeof MintRoomToken; scopeSpecsHash: typeof ScopeSpecsHash } | undefined;
 async function loadRoomTokenModule(): Promise<{ mintRoomToken: typeof MintRoomToken; scopeSpecsHash: typeof ScopeSpecsHash }> {
@@ -297,6 +299,11 @@ export interface QueryLeaseRequest<User> {
    *  when there is no authenticated subject and no session cookie (READ-ROUTER-DESIGN.md §1.5/§2.2).
    *  A routing HINT only, never authorization. */
   clientId?: string;
+  /** The browser's opaque follower-affinity ticket (FOLLOWER-AFFINITY-DESIGN.md §3), read off the
+   *  query POST and forwarded OPAQUELY on `materialize` so the fleet `fly-replay`s to the follower
+   *  the browser's ws is pinned to (§2, §4) — both legs co-locate. The api-server does NOT verify
+   *  it (the fleet does); it holds no signing key. Absent ⇒ single daemon / affinity off. */
+  affinity?: string;
 }
 
 /**
@@ -306,11 +313,10 @@ export interface QueryLeaseRequest<User> {
  * client uses it to open the room transport for THIS query beside — never instead of — its daemon
  * session.
  *
- * It is a NEW dedicated block on purpose: the TOP-LEVEL `wsEndpoint` is the read-router's
- * whole-session migration signal (`packages/remote/src/optimistic-source.ts` — a lease whose
- * `wsEndpoint` differs migrates the client's ENTIRE ws session), so the room endpoint must never
- * ride that field. A room-served lease's top-level fields are byte-identical to the daemon-served
- * ones.
+ * It is a dedicated block on purpose: the ROOM ws is a SEPARATE connection this query opens beside
+ * its daemon session (never a migration of the daemon session — the daemon ws host is fixed and
+ * placed by the affinity ticket). A room-served lease's top-level fields are byte-identical to the
+ * daemon-served ones.
  */
 export interface QueryLeaseRealtime {
   /** The client store's gate/domain key for this room source (`connectSource`) AND the string the
@@ -318,8 +324,8 @@ export interface QueryLeaseRealtime {
    *  parses as a room source, and the established convention is `"room:" + doc`
    *  (e.g. `room:document/doc:d1`). */
   sourceKey: string;
-  /** Where the client opens the ROOM ws for this query (from `realtime.locateRoom`) — a separate
-   *  field from the top-level `wsEndpoint` (see above: no whole-session migration). */
+  /** Where the client opens the ROOM ws for this query (from `realtime.locateRoom`) — its OWN
+   *  connection, distinct from the daemon session's fixed ws host. */
   wsEndpoint: string;
   /** The room's self-authorizing signed lease (`@rindle/room/token`): the APPROVED query AST +
    *  doc + subject, HMAC-signed with `realtime.roomTokenKey` so the room shell's
@@ -349,9 +355,6 @@ export interface QueryLeaseLifecycleLease {
   /** Which system table this lease's subscription serves. */
   table: string;
   leaseToken: string;
-  /** The follower this system materialization lives on (routed deploys; mirrors the top-level
-   *  `wsEndpoint` semantics). Absent ⇒ single-daemon. */
-  wsEndpoint?: string;
   /** DOORBELL only: the §4.1 occupancy scope — the wire room doc (`"<profile>/<key>"`). */
   scope?: string;
   /** FENCE entries only: the room doc the predicate is scoped to. */
@@ -393,9 +396,6 @@ export interface QueryLeaseResponse {
   materializationId: string;
   queryKey?: string;
   reused?: boolean;
-  /** The follower this lease lives on (READ-ROUTER-DESIGN.md §2.3) — the browser opens its
-   *  subscription ws here. Absent ⇒ single-daemon (the client uses its static `wsUrl`). */
-  wsEndpoint?: string;
   /** The room-serve block (G-iv-b) — see {@link QueryLeaseRealtime}. Absent ⇒ the lease is
    *  byte-identical to the legacy daemon-served shape. */
   realtime?: QueryLeaseRealtime;
@@ -420,6 +420,9 @@ export interface QueryReadRequest<User> {
    *  {@link QueryLeaseRequest.clientId}). Lets the SSR read co-locate on the follower the booting
    *  client's first subscribe will hit (READ-ROUTER-DESIGN.md §2.4). */
   clientId?: string;
+  /** The browser's opaque follower-affinity ticket — see {@link QueryLeaseRequest.affinity}.
+   *  Forwarded on the one-shot `query` so an SSR read lands on the same pinned follower. */
+  affinity?: string;
 }
 
 /** The assembled (nested-by-name) first-paint snapshot the server-side Store seeds + dehydrates
@@ -428,9 +431,6 @@ export interface QueryReadResponse {
   rows: Array<{ cols: Record<string, unknown>; [rel: string]: unknown }>;
   cvMin?: number;
   queryKey?: string;
-  /** The follower this read warmed (READ-ROUTER-DESIGN.md §2.4) — inject it into the SSR bootstrap
-   *  so the booting client opens its ws to the same warm follower. Absent ⇒ single-daemon. */
-  wsEndpoint?: string;
 }
 
 /** The context a {@link MutationBackend} needs to run one mutation inside its transaction. */
@@ -548,6 +548,10 @@ export interface RoomBootResponse {
   /** Where the room opens its upstream subscription (a routed deploy's follower). Absent ⇒ the
    *  shell's statically configured rindled ws endpoint. */
   upstreamWsEndpoint?: string;
+  /** Fresh opaque follower-placement ticket minted alongside `upstreamLeaseToken`. The DO offers
+   *  it with `rindle.v1` on the separate upstream ws so a static fleet endpoint replays to the
+   *  exact follower holding that local lease. Absent when daemon affinity is off. */
+  upstreamAffinity?: string;
   /** Per-footprint-table scope specs (H-iv-b), compiled from the resolved footprint AST + the
    *  profile's context set (the legacy anonymous profile compiles with an empty context set):
    *  what the shell hands the wasm room's `enableWritesV2` — the §3.3 commit gate. Optional
@@ -593,14 +597,16 @@ export interface RindleRealtimeOptions<User> {
   /** 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. */
+  /** Static endpoint where rooms open their upstream subscription. In a follower fleet this is the
+   *  fleet ws URL; `/room-boot` pairs it with the materialization's fresh placement ticket so the
+   *  room lands on the exact follower holding its lease. Absent ⇒ no explicit upstream (the Node
+   *  room shell may use its own default; the shipped DO shell requires this endpoint). */
   upstreamWsEndpoint?: string;
   /** Locate (or place) the room serving `doc` and return the ROOM ws endpoint a room-served
    *  lease's client should open (G-iv-b; on the DO shell this is the Worker's room URL). The
-   *  endpoint rides the lease's dedicated `realtime.wsEndpoint` — NEVER the top-level
-   *  `wsEndpoint` (that field migrates the client's whole daemon session). Absent ⇒ room-serving
-   *  is OFF: labeled queries serve from the daemon exactly as today (fail-open). */
+   *  endpoint rides the lease's dedicated `realtime.wsEndpoint` — its OWN connection, distinct from
+   *  the daemon session's fixed ws host. Absent ⇒ room-serving is OFF: labeled queries serve from
+   *  the daemon exactly as today (fail-open). */
   locateRoom?: (doc: string) => MaybePromise<{ wsEndpoint: string }>;
   /** The room lease token signing key (`@rindle/room/token`): `kid` + secret, matching an entry
    *  in the room shell's `downstream.tokenKeys` ring. Required for room-serving (without it a
@@ -816,12 +822,11 @@ export interface RindleApiServerOptions<User> {
    *  HINT only — never authorization. Ignored by a single (unrouted) daemon, which has nothing to
    *  route. */
   routingKey?: string | ((input: QueryLeaseRequest<User>) => MaybePromise<string | undefined>);
-  /** The EXPLICIT fleet pin fan-out (READ-ROUTER-DESIGN.md §4.2 "push") — when set,
-   *  {@link RindleApiServer.assertPins} fans each resolved pin across ALL live followers through it
-   *  (e.g. `createRouterPinClient` from `@rindle/router`) instead of materializing each pin once on
-   *  the (single) daemon. A per-viewer `materialize` always routes ONE; a pin-assert always fans
-   *  ALL — never inferred from `policy.kind`. Absent ⇒ single-daemon behavior (one materialize per
-   *  pin). */
+  /** The EXPLICIT fleet pin fan-out — when set, {@link RindleApiServer.assertPins} fans each
+   *  resolved pin across ALL live followers through it (a fleet control action over the machine
+   *  list — FOLLOWER-AFFINITY-DESIGN.md §11) instead of materializing each pin once on the (single)
+   *  daemon. A per-viewer `materialize` always routes ONE; a pin-assert always fans ALL — never
+   *  inferred from `policy.kind`. Absent ⇒ single-daemon behavior (one materialize per pin). */
   pinFanout?: PinFanout;
   /** Named queries to keep permanently materialized via {@link RindleApiServer.assertPins}.
    *  Each is materialized with a `pinned` policy (survives zero subscribers) so late joiners
@@ -1008,18 +1013,18 @@ export class SplitDaemonClient implements RindleDaemonClient {
     if (!lmids) return Promise.reject(new Error("the write master lacks roomLmids"));
     return lmids(input);
   }
-  // Pure computation, but routed to the MASTER like the rest of the room ops: the master is a
-  // real rindled that hosts `/cover-check`; the read router may not proxy it.
+  // Pure computation hosted by rindled: keep it on the read/follower leg. The write master owns
+  // room durability, not query-cover analysis.
   coverQuery(input: CoverQueryInput): Promise<CoverQueryOutput> {
-    const cover = this.writes.coverQuery?.bind(this.writes);
-    if (!cover) return Promise.reject(new Error("the write master lacks coverQuery"));
+    const cover = this.reads.coverQuery?.bind(this.reads);
+    if (!cover) return Promise.reject(new Error("the read follower lacks coverQuery"));
     return cover(input);
   }
   migrate(input: MigrateInput): Promise<MigrateOutput> {
     return this.writes.migrate(input);
   }
 
-  // reads → the router (it stamps `wsEndpoint` onto the outputs)
+  // reads → the fleet (one FLEET_URL follower; the affinity ticket + Fly edge place the machine)
   materialize(input: MaterializeInput): Promise<MaterializeOutput> {
     return this.reads.materialize(input);
   }
@@ -1248,6 +1253,24 @@ class AbsorbedReplay extends Error {
   }
 }
 
+const MUTATOR_CONFLICT_MAX_ATTEMPTS = 5;
+
+function isRetryableCommitConflict(error: unknown): boolean {
+  if (!(error instanceof DaemonHttpError) || error.status !== 409) return false;
+  try {
+    const body = JSON.parse(error.body) as { code?: unknown; retryable?: unknown };
+    return body.code === "retryable-conflict" && body.retryable === true;
+  } catch {
+    return false;
+  }
+}
+
+async function mutatorConflictBackoff(attempt: number): Promise<void> {
+  const ceiling = Math.min(32, 2 ** attempt);
+  const millis = ceiling + Math.floor(Math.random() * 4);
+  await new Promise<void>((resolve) => setTimeout(resolve, millis));
+}
+
 /**
  * The daemon server tx (DAEMON-INTERACTIVE-TXN-DESIGN.md §5): ONE authoring surface, two
  * execution strategies. It starts ACCUMULATING — a pure-write mutator ships one batch to
@@ -1519,37 +1542,48 @@ class PgLiveTx implements ServerMutationTx {
 export function daemonBackend(daemon: RindleDaemonClient): MutationBackend {
   return {
     dialect: sqliteDialect,
-    async runMutation({ envelope, render, run }) {
-      const tx = new DaemonLazyTx(render, daemon, envelope);
-      try {
-        await run(tx);
-      } catch (err) {
-        // A begin-absorbed replay: the authoritative outcome already committed — answer it,
-        // whatever the body did with the unwind (§4.1; the latch, not the throw, decides).
-        if (tx.absorbed) return { accepted: true, output: tx.absorbed };
-        if (err instanceof BackendError) {
-          await tx.rollbackSessionQuietly();
-          throw err.driverError; // infra — never a user rejection
-        }
-        const reason = errMessage(err);
-        // Data first, watermark second: the rollback releases the single writer that the
-        // `/reject-mutation` lmid-only commit needs (§2.4 on the session path).
-        await tx.rollbackSessionQuietly();
-        const output = await daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
-        return { accepted: false, reason, output };
-      }
-      if (tx.absorbed) return { accepted: true, output: tx.absorbed };
-      if (tx.session) {
+    async runMutation(input) {
+      for (let attempt = 0; attempt < MUTATOR_CONFLICT_MAX_ATTEMPTS; attempt++) {
         try {
-          return { accepted: true, output: await tx.commitSession() };
-        } catch (err) {
-          if (err instanceof BackendError) throw err.driverError; // infra (client retries; dedup absorbs)
-          throw err;
+          const { envelope, render, run } = input;
+          const tx = new DaemonLazyTx(render, daemon, envelope);
+          try {
+            await run(tx);
+          } catch (err) {
+            // A begin-absorbed replay: the authoritative outcome already committed — answer it,
+            // whatever the body did with the unwind (§4.1; the latch, not the throw, decides).
+            if (tx.absorbed) return { accepted: true, output: tx.absorbed };
+            if (err instanceof BackendError) {
+              await tx.rollbackSessionQuietly();
+              throw err.driverError; // infra — never a user rejection
+            }
+            const reason = errMessage(err);
+            // Data first, watermark second: rollback releases this session's connection before
+            // the lmid-only rejection commit.
+            await tx.rollbackSessionQuietly();
+            const output = await daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
+            return { accepted: false, reason, output };
+          }
+          if (tx.absorbed) return { accepted: true, output: tx.absorbed };
+          if (tx.session) {
+            try {
+              return { accepted: true, output: await tx.commitSession() };
+            } catch (err) {
+              if (err instanceof BackendError) throw err.driverError;
+              throw err;
+            }
+          }
+          const txn: SqlTxn = { statements: [...tx.statements], clientID: envelope.clientID, mid: envelope.mid };
+          if (tx.idempotencyKey !== undefined) txn.idempotencyKey = tx.idempotencyKey;
+          return { accepted: true, output: await daemon.executeSqlTxn(txn) };
+        } catch (error) {
+          if (!isRetryableCommitConflict(error) || attempt + 1 === MUTATOR_CONFLICT_MAX_ATTEMPTS) {
+            throw error;
+          }
+          await mutatorConflictBackoff(attempt);
         }
       }
-      const txn: SqlTxn = { statements: [...tx.statements], clientID: envelope.clientID, mid: envelope.mid };
-      if (tx.idempotencyKey !== undefined) txn.idempotencyKey = tx.idempotencyKey;
-      return { accepted: true, output: await daemon.executeSqlTxn(txn) };
+      throw new Error("unreachable mutator conflict retry loop");
     },
     reject({ envelope, reason }) {
       return daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
@@ -2171,8 +2205,8 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
         return undefined;
       }
 
-      // Covered ⇒ assemble the realtime block. The room endpoint rides ITS OWN field — the
-      // top-level `wsEndpoint` stays exactly the daemon lease's (whole-session migration signal).
+      // Covered ⇒ assemble the realtime block. The room endpoint rides ITS OWN field
+      // (`realtime.wsEndpoint`) — a separate connection from the daemon session's fixed ws host.
       const { wsEndpoint } = await realtime.locateRoom(doc);
       const now = Date.now();
       const ttlMs = realtime.roomTokenTtlMs ?? DEFAULT_ROOM_TOKEN_TTL_MS;
@@ -2266,11 +2300,14 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
           subject,
           leaseTtlMs: opts.leaseTtlMs,
           metadata: routingKey !== undefined ? { routingKey } : undefined,
+          // Lifecycle leases are follower-local exactly like the primary lease. Forward the SAME
+          // opaque placement ticket so every doorbell/fence materialization is minted on the
+          // browser socket's follower instead of independently anycasting across the fleet.
+          ...(input.affinity !== undefined ? { affinity: input.affinity } : {}),
         });
       const lease = (table: string, out: MaterializeOutput, id: { scope?: string; doc?: string; clientId?: string }): QueryLeaseLifecycleLease => ({
         table,
         leaseToken: out.leaseToken,
-        ...(out.wsEndpoint !== undefined ? { wsEndpoint: out.wsEndpoint } : {}),
         ...(id.scope !== undefined ? { scope: id.scope } : {}),
         ...(id.doc !== undefined ? { doc: id.doc } : {}),
         ...(id.clientId !== undefined ? { clientId: id.clientId } : {}),
@@ -2456,6 +2493,10 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
       // The anonymous routing key rides `metadata.routingKey`; the router keys on
       // `subject ?? metadata.routingKey` (§2.2). Omitted when there is none.
       metadata: routingKey !== undefined ? { routingKey } : undefined,
+      // Forward the browser's opaque affinity ticket (if any) so the fleet `fly-replay`s this
+      // materialize to the follower the ws is pinned to (FOLLOWER-AFFINITY-DESIGN.md §4). Opaque —
+      // never verified here. Inert when the reads client is a single daemon (no fleet edge).
+      ...(input.affinity !== undefined ? { affinity: input.affinity } : {}),
     });
     const res = queryLeaseResponse(out);
     // I-iv (§4.1): the occupancy step FIRST — session sweep+upsert, then the D6 gate verdict. A
@@ -2505,10 +2546,13 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
     const subject = await resolveSubject(opts.subject, input);
     const routingKey = await resolveRoutingKey(opts.routingKey, input);
     const visibilityKey = subject ?? routingKey;
-    const out = await opts.daemon.query({ ast, visibilityKey, ttlMs: opts.readIdleTtlMs });
-    const res: QueryReadResponse = { rows: out.rows, cvMin: out.cvMin, queryKey: out.queryKey };
-    if (out.wsEndpoint !== undefined) res.wsEndpoint = out.wsEndpoint;
-    return res;
+    const out = await opts.daemon.query({
+      ast,
+      visibilityKey,
+      ttlMs: opts.readIdleTtlMs,
+      ...(input.affinity !== undefined ? { affinity: input.affinity } : {}),
+    });
+    return { rows: out.rows, cvMin: out.cvMin, queryKey: out.queryKey };
   };
 
   const pushMutation = async (input: PushMutationRequest<User>): Promise<PushMutationResponse> => {
@@ -2866,7 +2910,8 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
             headers,
           },
         };
-        const upstreamWsEndpoint = realtime.upstreamWsEndpoint ?? lease.wsEndpoint;
+        if (lease.affinity !== undefined) res.upstreamAffinity = lease.affinity;
+        const upstreamWsEndpoint = realtime.upstreamWsEndpoint;
         if (upstreamWsEndpoint !== undefined) res.upstreamWsEndpoint = upstreamWsEndpoint;
         return { status: 200, body: res };
       } catch (e) {
@@ -2881,6 +2926,7 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
         args: msg.args ?? null,
         request: context.request,
         clientId: typeof msg.clientId === "string" ? msg.clientId : undefined,
+        affinity: typeof msg.affinity === "string" ? msg.affinity : undefined,
       });
     },
     handleReadJson: (body, context) => {
@@ -2891,6 +2937,7 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
         args: msg.args ?? null,
         request: context.request,
         clientId: typeof msg.clientId === "string" ? msg.clientId : undefined,
+        affinity: typeof msg.affinity === "string" ? msg.affinity : undefined,
       });
     },
     handleMutateJson: (body, context) => {
@@ -3062,15 +3109,12 @@ async function resolveRoutingKey<User>(
 }
 
 function queryLeaseResponse(out: MaterializeOutput): QueryLeaseResponse {
-  const res: QueryLeaseResponse = {
+  return {
     leaseToken: out.leaseToken,
     materializationId: out.materializationId,
     queryKey: out.queryKey,
     reused: out.reused,
   };
-  // Only present in a routed deploy — absent reproduces today's single-daemon response exactly.
-  if (out.wsEndpoint !== undefined) res.wsEndpoint = out.wsEndpoint;
-  return res;
 }
 
 function errMessage(reason: unknown): string {