@ultimat3/realtime 1.2.0 → 2.0.0

package/src/subscriber-gate.ts

@@ -0,0 +1,209 @@
+// The per-subscriber pass of a definition's row policy over the shared window, and the two numbers
+// it produces: rows denied, and gates that could not decide. It evaluates no policy of its own —
+// `policy-gate.ts` is this package's only authz seam — it calls `LiveQueryDefinition.visible` and
+// classifies what comes back, so a denial and a failure never arrive as the same event.
+
+import type { Actor } from '@ultimat3/core';
+import { isPolicyDenial } from './errors';
+import type { JsonValue, Row, RowPatch } from './json';
+import type { LiveQueryDefinition } from './live-contract';
+
+/**
+ * Who a decision is being made for. Every policy call in the live pipeline takes one, which is the
+ * shape of the rule: there is no path through the gate that reads a query id and no actor.
+ */
+export interface Subscriber {
+  readonly sid: string;
+  readonly actor: Actor | null;
+}
+
+/** One row withheld from one subscriber. Carries no row payload: the ids are the whole point. */
+export interface RowDenied {
+  readonly qid: string;
+  readonly sid: string;
+  readonly actorId: string | null;
+  readonly rowId: string;
+}
+
+/** Where a gate was standing when it failed. `authorize` is subscribe-time, the rest are rows. */
+export type GateStage = 'authorize' | 'snapshot' | 'patch';
+
+/**
+ * One gate that raised something other than a denial. `rowId` is absent for `authorize`, which
+ * decides about a subscription rather than a row, and `error` is passed through unwrapped so the
+ * node logs the driver's own message instead of a summary of it.
+ */
+export interface GateFailed {
+  readonly qid: string;
+  readonly sid: string;
+  readonly actorId: string | null;
+  readonly stage: GateStage;
+  readonly rowId?: string;
+  readonly error: unknown;
+}
+
+/**
+ * What the gate needs from a query entry and nothing more: the shared pre-policy window, the input
+ * the rules read, and the definition that owns `visible`. `QueryEntry` satisfies it structurally,
+ * so the registry passes its entry straight through and this file never learns what else is on it.
+ */
+export interface GateTarget {
+  readonly qid: string;
+  readonly input: JsonValue;
+  readonly definition: LiveQueryDefinition;
+  readonly rows: readonly Row[];
+}
+
+export interface SubscriberGateOptions {
+  /**
+   * `live.rows_denied`. A row an actor's policy refuses is dropped, never sent and never turned
+   * into an error — telling a client "there is a row you may not see" is itself the leak. Dropped
+   * silently it is also invisible, so the drop is a metric instead.
+   */
+  readonly onRowDenied?: (event: RowDenied) => void;
+  /**
+   * `live.gate_failed`. The gate raised something that is not a decision, so this subscriber's
+   * result set is unknown rather than empty. Separate from `onRowDenied` on purpose: an alert
+   * fires on this one, and a dashboard that summed them would show a permission change.
+   */
+  readonly onGateFailed?: (event: GateFailed) => void;
+}
+
+/** Both counters and the one call that classifies a throw. Owned per registry, never per query. */
+export class SubscriberGate {
+  readonly #options: SubscriberGateOptions;
+  #rowsDenied = 0;
+  #gateFailures = 0;
+
+  constructor(options: SubscriberGateOptions) {
+    this.#options = options;
+  }
+
+  /** Rows a subscriber's policy refused since boot. */
+  get rowsDenied(): number {
+    return this.#rowsDenied;
+  }
+
+  /** Gates that raised instead of deciding since boot. */
+  get gateFailures(): number {
+    return this.#gateFailures;
+  }
+
+  /**
+   * One snapshot, filtered for one subscriber. A failure raises rather than returning the rows it
+   * managed to admit: a short result set is indistinguishable from a correct one, and handing it
+   * over is the read silently losing rows.
+   */
+  async filterRows(target: GateTarget, who: Subscriber, rows: readonly Row[]): Promise<Row[]> {
+    const out: Row[] = [];
+    for (const row of rows) {
+      if (await this.#visible(target, who, row, 'snapshot')) out.push(row);
+      else this.#denied(target.qid, who, row.id);
+    }
+    return out;
+  }
+
+  /**
+   * Row-level authz over a patch list. A row that becomes invisible is converted to a `delete`
+   * when the subscriber holds it — otherwise a revoked grant would leave a stale row on screen
+   * forever.
+   */
+  async filterPatches(
+    target: GateTarget,
+    who: Subscriber,
+    patches: readonly RowPatch[],
+    held: ReadonlySet<string>,
+  ): Promise<RowPatch[]> {
+    const out: RowPatch[] = [];
+    for (const patch of patches) {
+      const allowed = await this.patch(target, who, patch, held.has(patch.id));
+      if (allowed !== null) out.push(allowed);
+    }
+    return out;
+  }
+
+  /** One patch, one decision. `holds` is whether this subscriber already has the row on screen. */
+  async patch(
+    target: GateTarget,
+    who: Subscriber,
+    patch: RowPatch,
+    holds: boolean,
+  ): Promise<RowPatch | null> {
+    if (patch.op === 'delete' || patch.row === null) return patch;
+    const full = target.rows.find((row) => row.id === patch.id);
+    // No whole row means no decision to take. An update patch carries the changed columns only, so
+    // a rule reading `row.ownerId` on one reads `undefined` and answers as if the row had said so —
+    // fail-closed for `=== actor.id`, and a leak for every `!row.private`. It is not a gate that
+    // failed either: the shared window *is* the result set, so a row it does not hold is a row this
+    // subscriber is not entitled to keep, and one that holds it is told so.
+    if (full === undefined) return holds ? withdrawn(patch) : null;
+    const row: Row = { ...full, ...patch.row, id: patch.id };
+    if (await this.#visible(target, who, row, 'patch')) return patch;
+    this.#denied(target.qid, who, patch.id);
+    return holds ? withdrawn(patch) : null;
+  }
+
+  /**
+   * `authorize` failed for a subscription that is being re-decided. Counted and reported here so
+   * every gate failure in the pipeline goes through one counter, whatever the caller then does
+   * with the subscription.
+   */
+  failedAuthorize(qid: string, who: Subscriber, error: unknown): void {
+    this.#failed(qid, who, 'authorize', undefined, error);
+  }
+
+  /** The definition's own predicate. A denial answers `false`; anything else is counted and raised. */
+  async #visible(
+    target: GateTarget,
+    who: Subscriber,
+    row: Row,
+    stage: GateStage,
+  ): Promise<boolean> {
+    try {
+      return await target.definition.visible({ actor: who.actor, row, input: target.input });
+    } catch (error) {
+      if (isPolicyDenial(error)) return false;
+      this.#failed(target.qid, who, stage, row.id, error);
+      throw error;
+    }
+  }
+
+  /** `live.rows_denied`. Counted here and nowhere else, so every drop is one increment. */
+  #denied(qid: string, who: Subscriber, rowId: string): void {
+    this.#rowsDenied += 1;
+    this.#options.onRowDenied?.({ qid, sid: who.sid, actorId: actorIdOf(who), rowId });
+  }
+
+  /** `live.gate_failed`. Same rule: one place counts, so the number and the events agree. */
+  #failed(
+    qid: string,
+    who: Subscriber,
+    stage: GateStage,
+    rowId: string | undefined,
+    error: unknown,
+  ): void {
+    this.#gateFailures += 1;
+    this.#options.onGateFailed?.({
+      qid,
+      sid: who.sid,
+      actorId: actorIdOf(who),
+      stage,
+      ...(rowId === undefined ? {} : { rowId }),
+      error,
+    });
+  }
+}
+
+const actorIdOf = (who: Subscriber): string | null => (who.actor === null ? null : who.actor.id);
+
+/**
+ * The one frame a subscriber gets for a row it may no longer keep, whether a rule refused it or the
+ * window stopped holding it. Written once so the two paths cannot answer differently: a client left
+ * holding the row instead renders a revoked grant until something else reconnects it.
+ */
+const withdrawn = (patch: RowPatch): RowPatch => ({
+  op: 'delete',
+  id: patch.id,
+  row: null,
+  lsn: patch.lsn,
+});

package/src/subscription-book.ts

@@ -0,0 +1,237 @@
+// Who holds which subscription, and the composite identity that makes that answerable. A `sid`
+// is CLIENT data — unique only to the socket that chose it — so every lookup here takes the
+// owner too, and the per-socket and per-tenant caps are answered from this book because it is
+// the only thing that knows what exists. Every question it answers is indexed, never scanned.
+
+import type { Actor } from '@ultimat3/core';
+import { SubscriptionIdTakenError, SubscriptionLimitError } from './errors';
+import type { LiveSubscription } from './live-contract';
+import type { SyncSocket } from './socket';
+
+/**
+ * A slot taken synchronously at the top of `subscribe` and given back when it has either become a
+ * subscription or failed. It exists because every cap here is answered from what the book HOLDS,
+ * and a subscribe does not hold anything until three awaits later: one WebSocket write carrying N
+ * subscribe frames is dispatched concurrently, so N of them read `size === 0` and every cap is
+ * bypassed by batching. Releasing twice is a no-op — the caller's `finally` runs once per path.
+ */
+export interface SubscriptionSlot {
+  release(): void;
+}
+
+/**
+ * The identity of one subscription. `\u0000` because a socket id and a sid are both opaque
+ * strings and nothing else can appear in one, so no pair of them can collide with another.
+ */
+export function subscriptionKey(socketId: string, sid: string): string {
+  return `${socketId}\u0000${sid}`;
+}
+
+export interface SubscriptionCaps {
+  readonly maxPerSocket?: number;
+  readonly maxPerTenant?: number;
+  readonly tenantOf?: (actor: Actor | null) => string | null;
+}
+
+/** Sockets may open this many live queries before `X_SUBSCRIPTION_LIMIT`. */
+export const DEFAULT_MAX_PER_SOCKET = 128;
+
+/**
+ * Every live subscription on this node, keyed by `(socket, sid)`.
+ *
+ * Keyed by the sid alone, socket B reusing socket A's sid overwrote A's entry — A's subscription
+ * stayed in its query entry's `subscribers` map, unreachable, so `unsubscribeSocket(A)` freed
+ * nothing and that entry's matcher and shared window were pinned for the process's life, fanning
+ * every change out to a dead socket. A `drop` frame from B likewise ended A's stream with no
+ * error either side.
+ *
+ * **Two secondary indexes, because both of this book's sweeps run once per socket.** `ofSocket`
+ * copied the node's whole map and filtered it, so a teardown or a re-auth pass cost
+ * `sockets x subscriptions` — 100,000 entries measured at 17.7s of blocking work, with no
+ * attacker capability required: a deploy, a network blip or a batch of grants expiring together
+ * is the trigger. The per-tenant cap walked the same map on every subscribe FRAME (7.96 ms each
+ * at that size), which is one authenticated socket consuming the node. Both are `Map` reads now,
+ * maintained in `add`/`delete` — the shape `lru.ts` and `presence.ts` already use.
+ */
+export class SubscriptionBook {
+  readonly #bySid = new Map<string, LiveSubscription>();
+  /** socket id -> its sids. The drop list on close, the retry list on re-auth. */
+  readonly #bySocket = new Map<string, Set<string>>();
+  /** tenant -> live subscriptions held by its sockets. The per-tenant cap's whole answer. */
+  readonly #perTenant = new Map<string, number>();
+  /**
+   * The tenant each socket's subscriptions were counted under. Remembered rather than re-derived,
+   * because `socket.actor` is replaced by a re-auth: deriving it again at `delete` time would
+   * decrement a tenant that was never incremented and leave the old one counting forever.
+   */
+  readonly #tenantOfSocket = new Map<string, string>();
+  /** sids a socket has claimed but not yet attached. Empty between subscribes, so it never grows. */
+  readonly #claimedBySocket = new Map<string, Set<string>>();
+  /** The same claims counted per tenant, because that cap spans sockets and a lane cannot see it. */
+  readonly #claimedPerTenant = new Map<string, number>();
+  readonly #caps: SubscriptionCaps;
+
+  constructor(caps: SubscriptionCaps = {}) {
+    this.#caps = caps;
+  }
+
+  get(socketId: string, sid: string): LiveSubscription | undefined {
+    return this.#bySid.get(subscriptionKey(socketId, sid));
+  }
+
+  has(socketId: string, sid: string): boolean {
+    return this.#bySid.has(subscriptionKey(socketId, sid));
+  }
+
+  add(subscription: LiveSubscription): void {
+    const socketId = subscription.socket.id;
+    const key = subscriptionKey(socketId, subscription.sid);
+    // A re-add is the one thing that could double-count a tenant, so it is refused here rather
+    // than relied on not to happen: `subscribe` already answers `X_SUBSCRIPTION_ID_TAKEN`.
+    if (this.#bySid.has(key)) return;
+    this.#bySid.set(key, subscription);
+    const sids = this.#bySocket.get(socketId);
+    if (sids) sids.add(subscription.sid);
+    else this.#bySocket.set(socketId, new Set([subscription.sid]));
+    const tenant = this.#tenantFor(subscription.socket);
+    if (tenant === null) return;
+    this.#tenantOfSocket.set(socketId, tenant);
+    this.#perTenant.set(tenant, (this.#perTenant.get(tenant) ?? 0) + 1);
+  }
+
+  delete(socketId: string, sid: string): void {
+    if (!this.#bySid.delete(subscriptionKey(socketId, sid))) return;
+    const sids = this.#bySocket.get(socketId);
+    sids?.delete(sid);
+    const empty = sids === undefined || sids.size === 0;
+    if (empty) this.#bySocket.delete(socketId);
+    const tenant = this.#tenantOfSocket.get(socketId);
+    if (tenant === undefined) return;
+    this.#bump(tenant, -1);
+    if (empty) this.#tenantOfSocket.delete(socketId);
+  }
+
+  /** A copy, because every caller mutates the book while walking it. */
+  all(): readonly LiveSubscription[] {
+    return [...this.#bySid.values()];
+  }
+
+  /** One socket's subscriptions — the drop list when it closes, the retry list when it reauths. */
+  ofSocket(socketId: string): readonly LiveSubscription[] {
+    const sids = this.#bySocket.get(socketId);
+    if (!sids) return [];
+    const out: LiveSubscription[] = [];
+    for (const sid of sids) {
+      const subscription = this.#bySid.get(subscriptionKey(socketId, sid));
+      if (subscription) out.push(subscription);
+    }
+    return out;
+  }
+
+  /** Live subscriptions counted against one tenant. The metric the cap reads. */
+  tenantCount(tenant: string): number {
+    return this.#perTenant.get(tenant) ?? 0;
+  }
+
+  /**
+   * A re-auth moved this socket to another tenant, so its subscriptions move with it. Without
+   * this the count the cap reads drifts from the book for the rest of the process — one tenant
+   * refused for subscriptions it does not hold, another admitted past its cap.
+   */
+  retenant(socket: SyncSocket): void {
+    const held = this.#bySocket.get(socket.id)?.size ?? 0;
+    const before = this.#tenantOfSocket.get(socket.id) ?? null;
+    const after = this.#caps.tenantOf?.(socket.actor) ?? null;
+    if (before === after) return;
+    if (before !== null) this.#bump(before, -held);
+    if (after === null) this.#tenantOfSocket.delete(socket.id);
+    else {
+      this.#tenantOfSocket.set(socket.id, after);
+      if (held > 0) this.#perTenant.set(after, (this.#perTenant.get(after) ?? 0) + held);
+    }
+  }
+
+  /**
+   * Refuse a subscribe that would exceed a cap. Load shedding, not a crash: both scopes throw
+   * `X_SUBSCRIPTION_LIMIT` naming which one refused, so the fix line points at one knob.
+   *
+   * Claims count, because the thing being bounded is work that starts before it is held: a
+   * subscribe that has passed this check and is awaiting its snapshot has already committed this
+   * node to an entry, a matcher and a read.
+   */
+  assertCapacity(socket: SyncSocket): void {
+    const perSocket = this.#caps.maxPerSocket ?? DEFAULT_MAX_PER_SOCKET;
+    const claimed = this.#claimedBySocket.get(socket.id)?.size ?? 0;
+    if (socket.queries.size + claimed >= perSocket) {
+      throw new SubscriptionLimitError({
+        scope: 'socket',
+        id: socket.id,
+        limit: perSocket,
+        knob: 'maxPerSocket',
+      });
+    }
+    const perTenant = this.#caps.maxPerTenant;
+    const tenant = this.#tenantFor(socket);
+    if (perTenant === undefined || tenant === null) return;
+    if (this.tenantCount(tenant) + (this.#claimedPerTenant.get(tenant) ?? 0) >= perTenant) {
+      throw new SubscriptionLimitError({
+        scope: 'tenant',
+        id: tenant,
+        limit: perTenant,
+        knob: 'maxPerTenant',
+      });
+    }
+  }
+
+  /**
+   * Take the slot this subscribe is going to fill — the sid and the two caps — before it awaits
+   * anything. Every refusal a subscribe can answer with is decided here, in one synchronous step,
+   * so N frames arriving in one write are N decisions against a count that already includes the
+   * ones still in flight.
+   *
+   * The sid is claimed here for the same reason: keyed by `(socket, sid)`, two concurrent frames
+   * reusing one sid both passed `has()` and the second attach replaced the first, stranding it
+   * inside its query entry where nothing can reach it again. The tenant is captured rather than
+   * re-derived — a re-auth may `retenant` this socket while the read is in flight, and the release
+   * has to give the slot back to the tenant that took it.
+   */
+  reserve(socket: SyncSocket, sid: string): SubscriptionSlot {
+    const socketId = socket.id;
+    if (this.has(socketId, sid) || this.#claimedBySocket.get(socketId)?.has(sid) === true) {
+      throw new SubscriptionIdTakenError({ sid, socketId });
+    }
+    this.assertCapacity(socket);
+    const claims = this.#claimedBySocket.get(socketId);
+    if (claims) claims.add(sid);
+    else this.#claimedBySocket.set(socketId, new Set([sid]));
+    const tenant = this.#tenantFor(socket);
+    if (tenant !== null) {
+      this.#claimedPerTenant.set(tenant, (this.#claimedPerTenant.get(tenant) ?? 0) + 1);
+    }
+    let released = false;
+    return {
+      release: (): void => {
+        if (released) return;
+        released = true;
+        const held = this.#claimedBySocket.get(socketId);
+        held?.delete(sid);
+        if (held !== undefined && held.size === 0) this.#claimedBySocket.delete(socketId);
+        if (tenant === null) return;
+        const next = (this.#claimedPerTenant.get(tenant) ?? 0) - 1;
+        if (next > 0) this.#claimedPerTenant.set(tenant, next);
+        else this.#claimedPerTenant.delete(tenant);
+      },
+    };
+  }
+
+  /** The tenant this socket's subscriptions are counted under: the remembered one, or the actor's. */
+  #tenantFor(socket: SyncSocket): string | null {
+    return this.#tenantOfSocket.get(socket.id) ?? this.#caps.tenantOf?.(socket.actor) ?? null;
+  }
+
+  #bump(tenant: string, by: number): void {
+    const next = (this.#perTenant.get(tenant) ?? 0) + by;
+    if (next > 0) this.#perTenant.set(tenant, next);
+    else this.#perTenant.delete(tenant);
+  }
+}

package/src/sync-auth.ts

@@ -0,0 +1,124 @@
+// Who a socket is, and for how long. The `sync` node evaluates no credential of its own — an app
+// supplies `authenticate`, exactly as it supplies `onMutate` — so this file owns the shape of that
+// answer, the per-node book that holds it, and the pass that re-decides one whose window has closed.
+
+import type { Actor, Clock } from '@ultimat3/core';
+
+/**
+ * One connection's identity. A grant, not an `Actor`, because a websocket outlives every credential
+ * that opened it: a token with a 15-minute TTL on a socket that stays up for hours is a subscription
+ * authorized once and served forever, which is the hole `expiresAt` closes.
+ *
+ * `refresh` is the app's, and the framework retains no credential of its own for it. That is the
+ * whole reason the seam is a closure: re-reading the upgrade `Request` would mean holding one per
+ * socket for the life of the connection, and an app that closes over a token string holds the two
+ * fields it actually needs. Omit it and an expired grant simply closes the socket — the client
+ * re-dials with a fresh credential, which is the safe default and costs one reconnect.
+ */
+export interface SyncGrant {
+  readonly actor: Actor;
+  /** Epoch ms this grant stops being true. Omitted = never re-decided on a clock. */
+  readonly expiresAt?: number;
+  /** Re-resolve this connection without a reconnect. `null` means the actor is gone. */
+  refresh?: () => Promise<SyncGrant | null>;
+}
+
+/**
+ * The app's answer to "who is dialling". Called once per upgrade, before `server.upgrade`, so a
+ * refused credential never costs a websocket. `null` is a decision (nobody may open this socket);
+ * a throw is a failure (nothing was decided) — the node answers those differently, because reading
+ * an auth backend timeout as a denial is the same class of bug as reading a dead pool as a row
+ * policy refusing a row.
+ */
+export type SyncAuthenticator = (request: Request) => Promise<SyncGrant | null>;
+
+/**
+ * The grants of the sockets on this node, keyed by socket id.
+ *
+ * Off `SyncSocket` on purpose: that object's budget is ~1KB per connection and it is the only
+ * per-socket allocation a million-socket node is costed against, so an auth lifetime — a closure,
+ * an expiry and an actor — lives beside the socket table instead of inside it. Empty, and costing
+ * nothing, on a node with no authenticator.
+ */
+export class GrantBook {
+  readonly #grants = new Map<string, SyncGrant>();
+
+  set(socketId: string, grant: SyncGrant): void {
+    this.#grants.set(socketId, grant);
+  }
+
+  get(socketId: string): SyncGrant | undefined {
+    return this.#grants.get(socketId);
+  }
+
+  delete(socketId: string): void {
+    this.#grants.delete(socketId);
+  }
+
+  get size(): number {
+    return this.#grants.size;
+  }
+
+  /** Grants whose window has closed. One with no `expiresAt` never appears here. */
+  expired(now: number): readonly (readonly [string, SyncGrant])[] {
+    const out: (readonly [string, SyncGrant])[] = [];
+    for (const [socketId, grant] of this.#grants) {
+      if (grant.expiresAt !== undefined && grant.expiresAt <= now) out.push([socketId, grant]);
+    }
+    return out;
+  }
+}
+
+export interface GrantSweepDeps {
+  readonly grants: GrantBook;
+  readonly clock: Clock;
+  /** The grant was renewed: re-decide every subscription this socket holds, under the new actor. */
+  onActor: (socketId: string, actor: Actor) => Promise<void>;
+  /** Nobody may hold this socket any longer. The caller closes it. */
+  onRevoked: (socketId: string) => void;
+  /** `refresh` raised instead of deciding. The grant is kept and retried on the next pass. */
+  onRefreshFailed?: (socketId: string, error: unknown) => void;
+}
+
+export interface GrantSweepResult {
+  readonly refreshed: number;
+  readonly revoked: number;
+  readonly failed: number;
+}
+
+/**
+ * One pass over the expired grants. The clock is injected because a re-auth only provable by
+ * sleeping is a re-auth no test proves — the same rule the client's reconnect timer already follows.
+ *
+ * A `refresh` that raises keeps its grant: a denial and a failure never share an answer here either,
+ * and signing every connected user out because the auth backend timed out is a bigger outage than
+ * the one it would be responding to. It stays expired, so the next pass retries it — and every
+ * failure is reported, because a socket that cannot be re-decided is not a socket anyone should
+ * discover from a graph of connection counts.
+ */
+export async function sweepGrants(deps: GrantSweepDeps): Promise<GrantSweepResult> {
+  const now = deps.clock.now().getTime();
+  let refreshed = 0;
+  let revoked = 0;
+  let failed = 0;
+  for (const [socketId, grant] of deps.grants.expired(now)) {
+    let next: SyncGrant | null;
+    try {
+      next = grant.refresh ? await grant.refresh() : null;
+    } catch (error) {
+      failed += 1;
+      deps.onRefreshFailed?.(socketId, error);
+      continue;
+    }
+    if (next === null) {
+      deps.grants.delete(socketId);
+      deps.onRevoked(socketId);
+      revoked += 1;
+      continue;
+    }
+    deps.grants.set(socketId, next);
+    await deps.onActor(socketId, next.actor);
+    refreshed += 1;
+  }
+  return { refreshed, revoked, failed };
+}