@ultimat3/realtime 1.2.0 → 2.0.0

package/src/sync-frames.ts

@@ -0,0 +1,185 @@
+// What a RECEIVED frame does to server state — the mirror of `client-frames.ts`, and the only
+// inbound surface the `sync` node exposes. Every dependency is injected, so the router is
+// exercisable without a socket, a bus or a server.
+
+import type { ChannelHub } from './channel';
+import { topic as makeTopic } from './channel';
+import { FrameRateLimitError } from './errors';
+import { FrameLanes, laneKeyOf } from './frame-lanes';
+import type { JsonValue, Row } from './json';
+import type { LiveQueryRegistry } from './live-query';
+import { type PresenceRegistry, presenceFrame } from './presence';
+import type { SyncSocket } from './socket';
+import { type Frame, PROTOCOL_VERSION, toWireError } from './sync-protocol';
+
+/** Server-authoritative mutation execution. Injected: `sync` never owns business logic. */
+export type MutationHandler = (args: {
+  socket: SyncSocket;
+  name: string;
+  key: string;
+  seq: number;
+  input: JsonValue;
+}) => Promise<{ lsn?: string | null; entity?: string; row?: Row | null }>;
+
+export interface FrameRouterOptions {
+  readonly hub: ChannelHub;
+  readonly registry: LiveQueryRegistry;
+  readonly buildId: string;
+  readonly presence?: PresenceRegistry | undefined;
+  readonly onMutate?: MutationHandler | undefined;
+}
+
+export type FrameRouter = (socket: SyncSocket, frame: Frame) => Promise<void>;
+
+/**
+ * What a failure ack refers to. `ack.ref` is how a client finds the thing that failed —
+ * `queue.fail(frame.ref)` looks up a mutation by its idempotency key — so an ack built with the
+ * SOCKET id names a key no queue can hold and the whole rollback path is inert end to end: the
+ * optimistic write stays on screen and the mutation stays queued.
+ *
+ * The socket id is the answer for a frame nothing could read (a decode failure) and for the kinds
+ * that carry no reference of their own, because there is nothing else true to say.
+ */
+export function ackRefOf(frame: Frame | null, socketId: string): string {
+  if (frame === null) return socketId;
+  if (frame.type === 'mutate') return frame.key;
+  if (frame.type === 'subscribe') return frame.sid;
+  return socketId;
+}
+
+export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
+  const presence = options.presence;
+  // Weakly keyed, so one socket's lanes die with it and no close path has to remember them.
+  const lanes = new WeakMap<SyncSocket, FrameLanes>();
+
+  const routeFrame: FrameRouter = async (socket, frame) => {
+    // Before `touch()` and before every amplifier below it: a frame this node refuses to route
+    // must not also renew the idle window that would otherwise close a flooding socket.
+    if (!socket.frameBudget.tryAccept()) {
+      throw new FrameRateLimitError({
+        socketId: socket.id,
+        perSecond: socket.frameBudget.perSecond,
+      });
+    }
+    socket.touch();
+    const key = laneKeyOf(frame);
+    if (key === null) return await apply(socket, frame);
+    // Entered synchronously — an `async` body runs to its first await on the call — so the lane
+    // order is the order `sync-node.message` was called in, which is the order the bytes arrived.
+    const lane = lanes.get(socket) ?? new FrameLanes();
+    lanes.set(socket, lane);
+    return await lane.run(key, () => apply(socket, frame));
+  };
+  return routeFrame;
+
+  async function apply(socket: SyncSocket, frame: Frame): Promise<void> {
+    switch (frame.type) {
+      case 'hello': {
+        socket.send({
+          type: 'hello',
+          v: PROTOCOL_VERSION,
+          buildId: options.buildId,
+          sessionId: socket.id,
+          // The actor the upgrade resolved, so a client can render who the server thinks it is
+          // rather than who it thinks it sent.
+          actorId: socket.actorId,
+        });
+        if (socket.skewed) {
+          socket.send({ type: 'update-available', v: PROTOCOL_VERSION, buildId: options.buildId });
+        }
+        return;
+      }
+      case 'subscribe': {
+        if (frame.target.kind === 'topic') {
+          const name = makeTopic(...frame.target.topic.split('.'));
+          if (frame.op === 'drop') {
+            options.hub.unsubscribe(socket, name);
+            if (presence) await presence.leave(name, socket.id);
+            return;
+          }
+          await options.hub.subscribe(socket, name);
+          // Subscribing to a topic IS joining its presence set: presence has no frame of its own,
+          // so a second round trip saying "and I am here" would be a second way to do one thing,
+          // and a client that skipped it would be invisible in a room it is receiving from.
+          // Repeating the frame is therefore also the heartbeat — `join` re-`put`s the member.
+          if (presence) {
+            const roster = await presence.join(name, { id: socket.id, actorId: socket.actorId });
+            socket.send(presenceFrame(name, 'sync', roster.members, roster.total));
+          }
+          return;
+        }
+        if (frame.op === 'drop') {
+          // Scoped to this socket: a sid is client data, and an unscoped drop let one client
+          // end another's live stream by guessing — or reusing — its id.
+          options.registry.unsubscribe(socket.id, frame.sid);
+          return;
+        }
+        const { frame: reply } = await options.registry.subscribe({
+          socket,
+          name: frame.target.qid,
+          input: frame.target.input,
+          sid: frame.sid,
+          cursor: frame.target.cursor,
+        });
+        socket.send(reply);
+        return;
+      }
+      case 'mutate': {
+        if (!options.onMutate) {
+          socket.send({
+            type: 'ack',
+            v: PROTOCOL_VERSION,
+            ref: frame.key,
+            lsn: null,
+            error: toWireError({
+              code: 'X_NOT_IMPLEMENTED',
+              cause: 'this sync node was started without a mutation handler',
+              fix: 'pass onMutate to createSyncNode({ onMutate })',
+            }),
+          });
+          return;
+        }
+        const result = await options.onMutate({
+          socket,
+          name: frame.name,
+          key: frame.key,
+          seq: frame.seq,
+          input: frame.input,
+        });
+        // The rebase FIRST, and the ack last. The ack is the receipt, and a receipt is what
+        // retires the client's record of the mutation — its journal row and its rebase-log entry,
+        // both of which stay forever otherwise. A rebase that lands after that has no entry left
+        // to read the mutator's conflict strategy off (every merge silently becomes server-wins)
+        // and no sequence to decide which later optimistic writes to replay over server truth.
+        // These are two frames on one socket, so the order is the only coordination there is.
+        if (result.entity !== undefined) {
+          socket.send({
+            type: 'rebase',
+            v: PROTOCOL_VERSION,
+            key: frame.key,
+            entity: result.entity,
+            strategy: 'server-wins',
+            row: result.row ?? null,
+          });
+        }
+        socket.send({
+          type: 'ack',
+          v: PROTOCOL_VERSION,
+          ref: frame.key,
+          lsn: result.lsn ?? null,
+          error: null,
+        });
+        return;
+      }
+      // Server-authored frames are never received from a client.
+      case 'snapshot':
+      case 'patch':
+      case 'ack':
+      case 'rebase':
+      case 'presence':
+      case 'reconnect':
+      case 'update-available':
+        return;
+    }
+  }
+}

package/src/sync-listen.ts

@@ -0,0 +1,73 @@
+// Binding a `sync` node to a real socket, and to the process lifecycle. Kept out of `sync-node.ts`
+// so the node itself stays testable with no server: this file is the only place realtime calls
+// `Bun.serve`, and the only thing in the package that knows a port exists.
+
+import { markListening, onShutdown } from '@ultimat3/core';
+import type { SyncNode } from './sync-node';
+
+export interface ListenOptions {
+  readonly port?: number;
+}
+
+export interface SyncListener {
+  /** The bound websocket origin, e.g. `ws://localhost:3001`. With `port: 0` only the OS knows it. */
+  readonly url: string;
+  stop(): void;
+}
+
+/**
+ * Binds the node to `Bun.serve` and wires SIGTERM to `drain()`. Kept tiny so the node itself stays
+ * testable without a server.
+ */
+export function listenSyncNode(node: SyncNode, options: ListenOptions = {}): SyncListener {
+  const server = Bun.serve({
+    port: options.port ?? 3001,
+    fetch: node.fetch,
+    websocket: node.websocket,
+  });
+  // Same rule as @ultimat3/http: every socket the framework opens announces itself, so a request
+  // back to it is recognisably this process calling itself rather than egress.
+  const stopListening = markListening(server.url.origin);
+  // Two phases, because they answer two different questions. `accept` runs first on SIGTERM: the
+  // node stops taking new sockets and `/readyz` flips to 503, so the load balancer routes away
+  // while every socket this node already holds keeps its patch stream — registered with no phase,
+  // this landed in `close`, and until that last phase ran `fetch` went on upgrading new websockets
+  // onto a process that was going away. The same split `@ultimat3/http`, the worker and the
+  // scheduler already have.
+  //
+  // Both are unregistered by `stop()`: a hook left behind after the listener is gone drains a node
+  // that is already stopped, and the next process-wide shutdown hangs on it.
+  const stopAccepting = onShutdown(
+    'realtime:sync:accept',
+    () => {
+      node.stopAccepting();
+    },
+    { phase: 'accept' },
+  );
+  const unregister = onShutdown('realtime:sync', async () => {
+    await node.drain();
+    await node.stop();
+    server.stop();
+    stopListening();
+  });
+  return {
+    url: websocketOrigin(server.url),
+    stop: () => {
+      stopAccepting();
+      unregister();
+      server.stop();
+      stopListening();
+    },
+  };
+}
+
+/**
+ * The listener reports where it actually landed: a caller asking for `port: 0` cannot guess the
+ * port, and a guessed URL is a client that connects to someone else. Swapped on the URL's
+ * protocol, never on the string — a hostname is allowed to contain "http".
+ */
+function websocketOrigin(url: URL): string {
+  const ws = new URL(url);
+  ws.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+  return ws.origin;
+}