@ultimat3/realtime 9.0.0 → 11.0.0

package/src/server.ts

@@ -121,6 +121,9 @@ export {
   type ReplicationStreamStats,
 } from './pg-replication';
 export { bunPgStream, type PgTarget, parsePgUrl, type SslMode } from './pg-socket';
+// The value domain a WAL tuple lands in. Public because it is `PgOutputMessage`'s and
+// `entityRow`'s: a caller naming either type has to be able to name what is inside one.
+export { decodeValue, type PhysicalRow, type PhysicalValue } from './pg-values';
 export type { PgStream } from './pg-wire';
 export {
   type PgColumn,

package/src/socket.ts

@@ -185,7 +185,21 @@ export class SyncSocket {
       }
       return false;
     }
-    this.#ws.send(encode(frame));
+    // `WsLike.send` is declared `: number` for this line and no other: Bun answers `0` for a
+    // message it DROPPED — the socket closed between the buffered-amount check above and this
+    // write — and `-1` under backpressure. Discarded, a dropped frame read as delivered, so
+    // `live-fanout` advanced the subscriber's cursor past a patch that never left and
+    // `sync-frames`' desync mark was never taken: permanently stale on a healthy socket, which is
+    // the exact outcome every other `socket.send` on this node reads its answer to prevent.
+    if (this.#ws.send(encode(frame)) <= 0) {
+      this.droppedFrames += 1;
+      // The same ceiling backpressure takes: a socket the runtime keeps refusing is one to close,
+      // and the two are one failure — the write went nowhere either way.
+      if (this.droppedFrames > this.#maxDroppedFrames) {
+        this.close(CLOSE.overloaded, 'backpressure');
+      }
+      return false;
+    }
     this.sentFrames += 1;
     return true;
   }

package/src/sync-node.ts

@@ -6,6 +6,8 @@
 
 import { type Clock, logger, markReady, reportError, systemClock, uuid } from '@ultimat3/core';
 import type { ChannelHub, Topic } from './channel';
+import { detach } from './detach';
+import { evictInChunks } from './drain-evictions';
 import { isClientFault } from './errors';
 import type { Transport, TransportSubscription } from './fanout';
 import type { LiveQueryRegistry } from './live-query';
@@ -162,25 +164,6 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
   let reauthing: ReturnType<typeof setInterval> | null = null;
   let idling: ReturnType<typeof setInterval> | null = null;
 
-  /**
-   * Work nobody is waiting on — a presence leave from a synchronous close, a sweep on a timer, a
-   * fanout off the change bus. It reaches the bus or a policy, so it can fail; failing must not take
-   * a socket or the process with it, and must not be silent either, or "the room still shows someone
-   * who left" and "that change reached nobody" have nothing to read. `operation` stays low
-   * cardinality so the monitor can group on it; the topic or entity goes in `at`.
-   */
-  const detach = (work: Promise<unknown>, operation: string, at?: string): void => {
-    void work.catch((error: unknown) => {
-      logger.error(`${operation} failed`, {
-        ...(at === undefined ? {} : { at }),
-        error: error instanceof Error ? error.message : String(error),
-      });
-      // Nobody is awaiting this, so the log is the only trace it leaves — and a log is not a
-      // signal anyone is paged on. The bus is this node's dependency, never the client's.
-      reportError(error, { source: 'realtime', scope: { operation } });
-    });
-  };
-
   /**
    * Everything `start()` acquired that is not a socket: the change subscription and the presence
    * sweep. Both `drain()` and `stop()` run it, because a `drain()` is terminal on its own — it
@@ -205,8 +188,12 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
    * Everything one socket held, released once. Bun's `close` callback runs it, and so does a
    * revoked grant — a socket this node closes itself gets no callback in a unit test, and in
    * production the second run is the no-op every step here already is.
+   *
+   * Returns the presence leaves it started, which is the only step here that is not over when this
+   * function returns: `close` is a SYNCHRONOUS Bun callback and cannot await one, so the promise is
+   * both detached (that path has nobody to wait for it) and handed back (the drain does).
    */
-  const teardown = (socket: SyncSocket): void => {
+  const teardown = (socket: SyncSocket): readonly Promise<unknown>[] => {
     options.registry.unsubscribeSocket(socket.id);
     const topics = [...socket.topics] as Topic[];
     for (const name of topics) options.hub.unsubscribe(socket, name);
@@ -215,9 +202,17 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     // A closed socket is a leave, said now rather than left to TTL: everyone else would otherwise
     // keep rendering a member who is provably gone for the rest of its window. The write is on the
     // bus and the close callback is synchronous, so it cannot be awaited here.
+    const leaves: Promise<unknown>[] = [];
     if (presence) {
-      for (const name of topics) detach(presence.leave(name, socket.id), 'presence.leave', name);
+      for (const name of topics) {
+        const leave = presence.leave(name, socket.id);
+        // Detached as well as returned: `detach` attaches the reporting catch, so a caller that
+        // awaits this later is awaiting a promise whose rejection is already handled.
+        detach(leave, 'presence.leave', name);
+        leaves.push(leave);
+      }
     }
+    return leaves;
   };
 
   /**
@@ -226,9 +221,9 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
    * because dropping the socket from the table is three of `teardown`'s five steps and the two it
    * misses are the ones another node can see.
    */
-  const evict = (socket: SyncSocket, code: number, reason: string): void => {
+  const evict = (socket: SyncSocket, code: number, reason: string): readonly Promise<unknown>[] => {
     socket.close(code, reason);
-    teardown(socket);
+    return teardown(socket);
   };
 
   /**
@@ -478,9 +473,12 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
       // five steps, and the two they skip are the ones the rest of the fleet can see. A drained
       // socket that never left its presence set is a member every other node renders for a full
       // TTL — during a rolling restart, beside the same client's reconnection under a new id —
-      // and its live subscriptions stay in the registry, so `entry.subscribers` never empties and
-      // the matcher, the shared window and the retained ring are pinned for the process's life.
-      for (const socket of [...sockets.all()]) evict(socket, CLOSE.goingAway, 'drain');
+      // and its live subscriptions stay in the registry, so `entry.subscribers` never empties.
+      //
+      // AWAITED, in chunks: a leave is a write to the shared set, so a drain that merely started
+      // them released, closed the hub and let the process exit with N·M writes still on the wire —
+      // which is that same full-TTL double vision, reached the long way round.
+      await evictInChunks([...sockets.all()], (socket) => evict(socket, CLOSE.goingAway, 'drain'));
       // Released once the sockets are gone rather than at the top: a client is entitled to its
       // patches for the whole grace window, and it is entitled to them *before* the hub the
       // fanout writes through is closed.

package/src/sync-upgrade.ts

@@ -101,12 +101,21 @@ export async function handleUpgrade(
       );
     }
   }
-  // Asked again, because `authenticate` is app code and awaiting it is awaiting a token service: a
-  // request that passed the check above can be parked there when SIGTERM lands, and the `accept`
-  // phase is over by the time it gets here. Upgrading then is the one socket that phase exists to
-  // refuse — the load balancer has already been told this node is out, so nothing takes it over. No
-  // second `tryAccept()`: that budget was spent above.
-  if (!deps.ready()) return shed(deps);
+  // BOTH facts asked again, because `authenticate` is app code and awaiting it is awaiting a token
+  // service: everything this request read above is history by the time it gets here.
+  //
+  // `ready`, because SIGTERM can land while the request is parked and the `accept` phase is over
+  // by now — upgrading then is the one socket that phase exists to refuse, on a node the load
+  // balancer has already been told is out.
+  //
+  // The socket COUNT, for the same reason and it was the half that was missing: a restart storm
+  // dials every client of a dead node at this one at once, each parked in the token service having
+  // passed the cap while the node still held nothing — so a node capped at 2 accepted as many
+  // sockets as there were parked requests, and `maxConnections` bounded nothing that a herd could
+  // reach. Sound because there is no await between this line and `server.upgrade`, and the count
+  // moves INSIDE it: Bun runs `websocket.open` synchronously there, which is where `sockets.add`
+  // runs. No second `tryAccept()`: that budget was spent above.
+  if (!deps.ready() || deps.socketCount() >= deps.maxConnections) return shed(deps);
   const data: WsData = {
     socketId: deps.newSocketId(),
     clientBuildId: url.searchParams.get('build') ?? deps.buildId,

package/src/type-pins.ts

@@ -7,7 +7,7 @@
 // stops catching the typo that makes a subscription match nothing.
 
 import type { Query } from '@ultimat3/query';
-import type { LiveHandle, Unsubscribe } from './client';
+import type { LiveClient, LiveClientLike, LiveHandle, Unsubscribe } from './client';
 import type { LiveRows } from './hooks';
 import type { LiveQueryHook, LiveQuerySource } from './query-hook';
 
@@ -70,3 +70,14 @@ export type _LiveRowsIsDisposable = Assert<[LiveRows] extends [Disposable] ? tru
 
 /** `channel.subscribe()`'s return must stay both callable and `Disposable`. */
 export type _UnsubscribeIsDisposable = Assert<[Unsubscribe] extends [Disposable] ? true : false>;
+
+/**
+ * The hook seam takes `LiveClientLike`, not `LiveClient` — a structural shape, so the server
+ * render's client can satisfy it without dragging the connection lifecycle into every island that
+ * calls `useLive` (measured: 8,368 B → 26,571 B). This is what keeps the two in step: a member
+ * `hooks.ts` needs and `LiveClient` stops providing fails HERE, at the build, rather than at the
+ * one app that registered a real client.
+ */
+export type _LiveClientSatisfiesTheHookSeam = Assert<
+  [LiveClient] extends [LiveClientLike] ? true : false
+>;