@ultimat3/realtime 20.2.1 → 22.0.0

package/src/channel-records.ts

@@ -0,0 +1,87 @@
+// A committed change → the record updates each declared channel owes its subscribers. Pure: no
+// socket, no seq, no policy — `ChannelHub` does those per node and per socket. The only derivation
+// of "which channel carries this row" lives here, so a write never names a channel (axiom 2).
+
+import type { Row } from '@ultimat3/core/page';
+import type { RecordProjection } from '@ultimat3/entity/record';
+import type { ChangeEvent } from './changefeed';
+import type { Channel, Topic } from './channel-decl';
+import type { RecordPart } from './channel-ring';
+
+/** One topic's share of one change. `row` is what a per-row policy decides on. */
+export interface TopicUpdate {
+  readonly channel: Channel;
+  readonly topic: Topic;
+  readonly params: Readonly<Record<string, string>>;
+  readonly adopt: readonly RecordPart[];
+  readonly remove: readonly { readonly type: string; readonly key: string }[];
+  readonly row: Row;
+}
+
+/**
+ * `change.entity` is the replicated RELATION name (`pg-replication.ts` reads it off the Relation
+ * message), so it is matched against each projection's `table`, never its `type`.
+ *
+ * - insert/update: the new row is adopted on the topic its params name.
+ * - an update that moved the row to other params (`orgId` changed): a remove on the OLD topic too.
+ * - delete: a remove on the topic the old image names — which needs the params columns in the
+ *   `before` image, i.e. `REPLICA IDENTITY FULL`; a key-only image names no topic and is skipped.
+ */
+export function updatesFor(channels: Iterable<Channel>, change: ChangeEvent): TopicUpdate[] {
+  const updates: TopicUpdate[] = [];
+  // A truncate names no row, so it routes to no topic here: `ChannelLogs` announces a gap on every
+  // open topic of every channel carrying the relation instead (`truncatedTopics`).
+  if (change.op === 'truncate') return updates;
+  for (const channel of channels) {
+    const projection = channel.records.find((candidate) => candidate.table === change.entity);
+    if (projection === undefined) continue;
+    const after = change.op === 'delete' ? null : change.after;
+    const before = change.before;
+    const afterParams = after === null ? null : channel.paramsOf(after);
+    const beforeParams = before === null ? null : channel.paramsOf(before);
+    const afterTopic = afterParams === null ? null : channel.topic(afterParams);
+    const beforeTopic = beforeParams === null ? null : channel.topic(beforeParams);
+
+    if (after !== null && afterParams !== null && afterTopic !== null) {
+      updates.push({
+        channel,
+        topic: afterTopic,
+        params: afterParams,
+        adopt: [{ type: projection.type, key: projection.key(after), row: after }],
+        remove: [],
+        row: after,
+      });
+    }
+    if (
+      before !== null &&
+      beforeParams !== null &&
+      beforeTopic !== null &&
+      beforeTopic !== afterTopic
+    ) {
+      updates.push(removal(channel, projection, beforeTopic, beforeParams, before));
+    }
+  }
+  return updates;
+}
+
+function removal(
+  channel: Channel,
+  projection: RecordProjection,
+  topic: Topic,
+  params: Readonly<Record<string, string>>,
+  row: Row,
+): TopicUpdate {
+  return {
+    channel,
+    topic,
+    params,
+    adopt: [],
+    remove: [{ type: projection.type, key: projection.key(row) }],
+    row,
+  };
+}
+
+/** The channels whose records a truncate of `table` wiped: every one listing that relation. */
+export function carriesTable(channel: Channel, table: string): boolean {
+  return channel.records.some((projection) => projection.table === table);
+}

package/src/channel-ref.ts

@@ -0,0 +1,83 @@
+// A channel's CLIENT half: its name, params and catch-up read, and the one topic builder — no
+// entity, no policy, no registration. An island holds this; the server declares the same ref's
+// records and policy with `channel(ref, { … })`, so name and params are written once and a browser
+// chunk never carries `@ultimat3/entity`.
+
+import { invariant } from '@ultimat3/core/page';
+import { TopicForbiddenError } from './errors';
+
+/** Branded so a raw string can never be published to; `topic()` is the only constructor. */
+export type Topic = string & { readonly __ultimateTopic: unique symbol };
+
+export const SEGMENT = /^[A-Za-z0-9_-]+$/;
+
+/** `topic('org', orgId, 'cursors')` -> `org.<orgId>.cursors`. Segments are validated, never escaped. */
+export function topic(...parts: readonly (string | number)[]): Topic {
+  const segments = parts.map((part) => String(part));
+  for (const segment of segments) {
+    if (!SEGMENT.test(segment)) {
+      throw new TopicForbiddenError({
+        topic: segments.join('.'),
+        actorId: null,
+        reason: `segment "${segment}" must match ${SEGMENT.source} (dots and wildcards are reserved)`,
+      });
+    }
+  }
+  return segments.join('.') as Topic;
+}
+
+export type ChannelParams<K extends string> = Readonly<Record<K, string>>;
+
+export interface ChannelRefInit<K extends string> {
+  /** Ordered param names. Each becomes one topic segment, so each value is a segment-safe string. */
+  readonly params: readonly K[];
+  /**
+   * The read a client re-runs on `replay-gap` or a new epoch — a query, by name. Read on every
+   * access, never at declaration: `registerQueries()` stamps a declared query's name at boot.
+   */
+  readonly catchUp: { readonly name: string };
+}
+
+/** What a browser subscribes by — `useChannel(ref, params)`. */
+export interface ChannelHandle<K extends string = string> {
+  readonly kind: 'channel-ref';
+  readonly name: string;
+  readonly params: readonly K[];
+  readonly catchUp: string;
+  /** The topic for one set of params — the one spelling both halves use. */
+  topic(params: ChannelParams<K>): Topic;
+}
+
+export function refuseChannel(name: string, detail: string, fix: string): never {
+  invariant(false, 'X_CHANNEL_DECLARATION_INVALID', `channel("${name}"): ${detail}`, fix);
+}
+
+/** Refuses a bad name or a repeated param, and builds the ref. `channel()` is built on this. */
+export function channelRef<const K extends string>(
+  name: string,
+  init: ChannelRefInit<K>,
+): ChannelHandle<K> {
+  if (!SEGMENT.test(name)) {
+    refuseChannel(
+      name,
+      `the name must match ${SEGMENT.source}`,
+      `rename it, e.g. channel('org-feed', …)`,
+    );
+  }
+  if (new Set(init.params).size !== init.params.length) {
+    refuseChannel(name, 'a param is listed twice', 'list each param once in params: [...]');
+  }
+  // `Object.hasOwn`, never a bare `params[param]`: params arrive off a subscribe frame, and an
+  // inherited member would spell a topic nobody declared. Absent is `''`, which `topic()` refuses.
+  const topicOf = (params: ChannelParams<K>): Topic =>
+    topic(name, ...init.params.map((param) => (Object.hasOwn(params, param) ? params[param] : '')));
+  return Object.freeze({
+    kind: 'channel-ref' as const,
+    name,
+    params: init.params,
+    get catchUp(): string {
+      return init.catchUp.name;
+    },
+    topic: topicOf,
+  });
+}

package/src/channel-registry.ts

@@ -0,0 +1,35 @@
+// Every `channel()` declared in this process, keyed by name — the realtime twin of the entity and
+// query registries. `channel()` registers itself, so a host builds `new ChannelHub()` with no list
+// and the manifest reads the same table (`channel-describe.ts`); a second declaration of one name
+// is refused. Browser-safe: `channel()` runs in islands too.
+
+import { invariant } from '@ultimat3/core';
+import type { Channel } from './channel-decl';
+
+const channels = new Map<string, Channel>();
+
+export function registerChannel(declared: Channel): Channel {
+  invariant(
+    !channels.has(declared.name),
+    'X_CHANNEL_DECLARATION_INVALID',
+    `two channel() declarations share the name "${declared.name}"`,
+    'rename one of them: a channel name is its topic prefix, so it must be unique per app',
+  );
+  channels.set(declared.name, declared);
+  return declared;
+}
+
+/** The declaration of that name, or `undefined`. A `Map`, so a prototype member is never one. */
+export function getChannel(name: string): Channel | undefined {
+  return channels.get(name);
+}
+
+/** Sorted by name: a projection of the registry is a build input and must diff cleanly. */
+export function registeredChannels(): readonly Channel[] {
+  return [...channels.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Test seam. Production code never unregisters a channel. */
+export function clearChannels(): void {
+  channels.clear();
+}

package/src/channel-render.ts

@@ -0,0 +1,37 @@
+// One ring entry → the `records` frame every member of its topic receives. The same frame for all
+// of them: a channel's scope is its params, decided once at subscribe, never re-decided per row.
+
+import type { Row } from '@ultimat3/core/page';
+import type { RecordsEntry } from './channel-ring';
+import type { ChannelAdopt, ChannelRecordsFrame, ChannelRemove } from './channel-wire';
+import { PROTOCOL_VERSION } from './sync-protocol';
+
+export function renderRecords(
+  topic: string,
+  epoch: string,
+  entry: RecordsEntry,
+): ChannelRecordsFrame {
+  // Null-prototype maps: a record type and a record key are data, and `'__proto__'` stays a key.
+  const adopt = Object.create(null) as Record<string, Record<string, Row>>;
+  const remove = Object.create(null) as Record<string, string[]>;
+  for (const part of entry.adopt) {
+    const byKey = adopt[part.type] ?? (Object.create(null) as Record<string, Row>);
+    byKey[part.key] = part.row;
+    adopt[part.type] = byKey;
+  }
+  for (const part of entry.remove) {
+    const keys = remove[part.type] ?? [];
+    keys.push(part.key);
+    remove[part.type] = keys;
+  }
+  return {
+    type: 'records',
+    v: PROTOCOL_VERSION,
+    channel: topic,
+    seq: entry.seq,
+    epoch,
+    ...(entry.adopt.length === 0 ? {} : { adopt: adopt as ChannelAdopt }),
+    ...(entry.remove.length === 0 ? {} : { remove: remove as ChannelRemove }),
+    ...(entry.write === undefined ? {} : { write: entry.write }),
+  };
+}

package/src/channel-ring.ts

@@ -0,0 +1,75 @@
+// One channel topic's record log on THIS node: the epoch, the next seq, and a bounded ring of the
+// last frames' contents so a resubscribe `since` a recent seq replays instead of re-reading.
+// Seq is minted here — at the delivering node — because a records frame never crosses the bus.
+
+import { finiteOption, type Row } from '@ultimat3/core';
+import type { ChannelSince } from './channel-wire';
+
+/** One committed change on one topic, before it is rendered for a particular socket. */
+export interface RecordsEntry {
+  readonly seq: number;
+  readonly adopt: readonly RecordPart[];
+  readonly remove: readonly { readonly type: string; readonly key: string }[];
+  /** The write that produced the change (`ChangeEvent.write`), kept so a replay still names it. */
+  readonly write?: string;
+}
+
+export interface RecordPart {
+  readonly type: string;
+  readonly key: string;
+  readonly row: Row;
+}
+
+/** Frames a ring keeps per topic. A resume further back than this is answered `replay-gap`. */
+export const DEFAULT_CHANNEL_RING = 256;
+
+export class ChannelRing {
+  /**
+   * New per ring, never per hub: a topic whose last subscriber left drops its ring, and the next
+   * one restarts seq at 1 — under the SAME epoch a client resuming `since: 50` would read seq 1..49
+   * as duplicates and silently drop them. A fresh epoch makes that a reset instead.
+   */
+  readonly epoch: string;
+  readonly #capacity: number;
+  readonly #entries: RecordsEntry[] = [];
+  #seq = 0;
+
+  constructor(epoch: string, capacity: number = DEFAULT_CHANNEL_RING) {
+    this.epoch = epoch;
+    this.#capacity = finiteOption('ChannelRing', 'capacity', capacity);
+  }
+
+  /** The seq the last `append` minted; 0 before the first. */
+  get seq(): number {
+    return this.#seq;
+  }
+
+  append(
+    adopt: readonly RecordPart[],
+    remove: RecordsEntry['remove'],
+    write?: string,
+  ): RecordsEntry {
+    this.#seq += 1;
+    const entry: RecordsEntry = {
+      seq: this.#seq,
+      adopt,
+      remove,
+      ...(write === undefined ? {} : { write }),
+    };
+    this.#entries.push(entry);
+    if (this.#entries.length > this.#capacity) this.#entries.shift();
+    return entry;
+  }
+
+  /**
+   * Every entry after `since.seq`, oldest first — or `null` when the ring cannot prove it holds
+   * all of them: another epoch, a seq from the future, or one older than the ring's oldest.
+   */
+  since(since: ChannelSince): readonly RecordsEntry[] | null {
+    if (since.epoch !== this.epoch || since.seq > this.#seq || since.seq < 0) return null;
+    if (since.seq === this.#seq) return [];
+    const oldest = this.#entries[0];
+    if (oldest === undefined || oldest.seq > since.seq + 1) return null;
+    return this.#entries.filter((entry) => entry.seq > since.seq);
+  }
+}

package/src/channel-wire.ts

@@ -0,0 +1,66 @@
+// The three channel frames a node sends, and the subscribe target a client sends — browser-safe
+// types, members of `sync-protocol.ts`'s `Frame` union since protocol 3. `records` writes the page's store; `events` never does; `replay-gap` is the server's
+// verdict that this socket lost a `records` frame and must re-read the channel's catch-up query.
+
+import type { Row } from '@ultimat3/core/page';
+import type { JsonObject } from './json';
+
+/** Where a resubscribe resumes: the last `records` frame the client applied on this channel. */
+export interface ChannelSince {
+  readonly epoch: string;
+  readonly seq: number;
+}
+
+/** `subscribe.target` for a declared channel. `channel` is the declaration NAME, never a topic. */
+export interface ChannelSubscribeTarget {
+  readonly kind: 'channel';
+  readonly channel: string;
+  readonly params: Readonly<Record<string, string>>;
+  readonly since?: ChannelSince;
+}
+
+/** type → record key → row: the same keyed shape as core's `RecordEnvelope.records`. */
+export type ChannelAdopt = Readonly<Record<string, Readonly<Record<string, Row>>>>;
+/** type → record keys to drop. */
+export type ChannelRemove = Readonly<Record<string, readonly string[]>>;
+
+/**
+ * One committed change on one channel. `channel` is the TOPIC (`name.param1.param2`), which the
+ * client derives from the same declaration. `seq` counts up by one per frame within `epoch`; a
+ * numeric hole is NOT a gap (a row the socket may not see is skipped for that socket) — only
+ * `replay-gap` is.
+ */
+export interface ChannelRecordsFrame {
+  readonly type: 'records';
+  readonly v: number;
+  readonly channel: string;
+  readonly seq: number;
+  readonly epoch: string;
+  readonly adopt?: ChannelAdopt;
+  readonly remove?: ChannelRemove;
+  /**
+   * The write that produced this change: `writeDigest` of the idempotency key its request carried
+   * (`@ultimat3/core`), never the key. Absent for a write no page keyed — a job, a script, SQL.
+   * The page whose pending write this names settles it against these rows in the same
+   * notification, so its own echo is never painted under its own optimistic twin.
+   */
+  readonly write?: string;
+}
+
+/** Ephemeral (typing, a cursor, a toast). No seq, never written to the store, never replayed. */
+export interface ChannelEventsFrame {
+  readonly type: 'events';
+  readonly v: number;
+  readonly channel: string;
+  readonly event: JsonObject;
+}
+
+/** "Your copy of this channel is wrong since `epoch`": re-run its catch-up read, then resume. */
+export interface ReplayGapFrame {
+  readonly type: 'replay-gap';
+  readonly v: number;
+  readonly channel: string;
+  readonly epoch: string;
+}
+
+export type ChannelWireFrame = ChannelRecordsFrame | ChannelEventsFrame | ReplayGapFrame;