@ultimat3/realtime 22.15.0 → 24.0.0

package/src/sync-protocol.ts

@@ -80,6 +80,12 @@ export interface HelloFrame {
   /** Server-assigned on the reply, `null` on the client's opening frame. */
   readonly sessionId: string | null;
   readonly actorId: string | null;
+  /**
+   * On the NODE's reply only: how often this client must beat, in ms — a third of the node's real
+   * presence ttl, and never slower than the node's idle budget allows. Additive and optional, so
+   * no version bump: a node that says nothing leaves the client on its own default.
+   */
+  readonly heartbeatMs?: number;
 }
 
 export interface SubscribeFrame {
@@ -193,14 +199,18 @@ export function decode(raw: string | Uint8Array): Frame {
   }
   const kind = parsed['type'];
   switch (kind) {
-    case 'hello':
-      return {
+    case 'hello': {
+      const hello = {
         type: 'hello',
         v: PROTOCOL_VERSION,
         buildId: str(parsed, 'buildId'),
         sessionId: nullableStr(parsed, 'sessionId'),
         actorId: nullableStr(parsed, 'actorId'),
-      };
+      } as const;
+      return parsed['heartbeatMs'] === undefined
+        ? hello
+        : { ...hello, heartbeatMs: num(parsed, 'heartbeatMs') };
+    }
     case 'subscribe':
       return {
         type: 'subscribe',

package/src/sync-upgrade.ts

@@ -2,7 +2,14 @@
 // from `sync-node.ts` because deciding whether a request becomes a websocket is a different job
 // from what the socket then does — the same line `sync-frames.ts` and `sync-listen.ts` already draw.
 
-import { healthzPayload, readyzPayload, reportError } from '@ultimat3/core';
+import {
+  type HealthPayload,
+  healthBody,
+  healthPeerListed,
+  healthzPayload,
+  readyzPayload,
+  reportError,
+} from '@ultimat3/core';
 import {
   SocketAuthUnavailableError,
   SocketOriginRefusedError,
@@ -31,6 +38,11 @@ export interface WsData {
 /** Structural view of `Bun.serve`'s server object; keeps this module free of a Bun import. */
 export interface UpgradeTarget {
   upgrade(request: Request, options: { data: WsData }): boolean;
+  /**
+   * The peer's SOCKET address, as `Bun.serve`'s server answers it — what decides who is told the
+   * health detail. `null` when the host cannot say, which is told the verdict only.
+   */
+  requestIP(request: Request): { readonly address: string } | null;
 }
 
 /**
@@ -49,10 +61,18 @@ export interface UpgradeDeps {
   newSocketId(): string;
   readonly authenticate?: SyncAuthenticator | undefined;
   /**
-   * Exact origins a page may dial from besides the node's own host name — `APP_URL`'s, when the
-   * page is served on another host than the node (`sync-origin.ts`).
+   * Exact origins a page may dial from — `APP_URL`'s. Declared, they are the WHOLE list: the
+   * origin the node sees is `Host`-derived and is admitted only when nothing is declared
+   * (`sync-origin.ts`).
    */
   readonly allowedOrigins?: readonly string[] | undefined;
+  /** The `Host`-derived origin admitted beside a declared list too — `x dev` only. */
+  readonly admitReachedOrigin?: boolean | undefined;
+  /**
+   * Peers told the whole health report — address classes or exact IP literals, the app's
+   * `http.healthDetailPeers`. Everyone else gets `{ state, ready, role }`.
+   */
+  readonly healthDetailPeers: readonly string[];
   /**
    * Recorded BEFORE `server.upgrade`, because Bun runs `websocket.open` synchronously inside it
    * (measured on bun 1.4.0) and `open` is where the node reads this grant to build the socket's
@@ -83,16 +103,21 @@ export async function handleUpgrade(
   const url = new URL(request.url);
   // Health is the process's, readiness is this node's: a draining node stays healthy while it hands
   // its sockets to the rest of the fleet.
-  if (url.pathname === '/healthz') return json(healthzPayload());
+  if (url.pathname === '/healthz') return health(deps, request, server, healthzPayload());
   if (url.pathname === '/readyz') {
     const payload = readyzPayload({ deep: url.searchParams.get('deep') === '1' });
-    return deps.ready() ? json(payload) : json({ status: 503, body: payload.body });
+    return health(deps, request, server, deps.ready() ? payload : { ...payload, status: 503 });
   }
   if (url.pathname !== deps.path) return new Response('not found', { status: 404 });
   // First, and before anything is spent: a foreign page is refused whatever the node's load.
-  const origin = upgradeOrigin(request, url, deps.allowedOrigins ?? []);
-  if (!origin.ok)
-    return wireErrorResponse(403, new SocketOriginRefusedError({ reason: origin.reason }));
+  const origin = upgradeOrigin(request, url, deps.allowedOrigins ?? [], deps.admitReachedOrigin);
+  if (!origin.ok) {
+    const asked = { asked: request.headers.get('origin'), admitted: admittedList(deps) };
+    return wireErrorResponse(
+      403,
+      new SocketOriginRefusedError({ reason: origin.reason, ...asked }),
+    );
+  }
   // The count and readiness. Decided before `authenticate` so a full node costs no token service
   // call.
   if (deps.socketCount() >= deps.maxConnections || !deps.ready()) return shed(deps);
@@ -177,6 +202,42 @@ export async function handleUpgrade(
   return undefined;
 }
 
+/**
+ * What a proxy writes. Any one of them means the socket's address is the proxy's, not the
+ * caller's — and a proxy that writes none of them is indistinguishable from a direct peer, so a
+ * header-less proxy must not route the health paths at all.
+ */
+const FORWARDED_HEADERS = [
+  'forwarded',
+  'x-forwarded-for',
+  'x-forwarded-host',
+  'x-forwarded-proto',
+  'x-real-ip',
+  'via',
+] as const;
+
+/**
+ * The STATUS is everyone's, which is all a probe reads. The body beyond the verdict is for a peer
+ * the app listed, on a DIRECT socket: these paths answer before the origin check, the accept
+ * budget and `authenticate`. This node declares no trusted proxy, so a request that says it was
+ * forwarded is never told the detail — a proxy on this box makes every caller's socket loopback.
+ */
+function health(
+  deps: UpgradeDeps,
+  request: Request,
+  server: UpgradeTarget,
+  payload: HealthPayload,
+): Response {
+  const forwarded = FORWARDED_HEADERS.some((header) => request.headers.has(header));
+  const detailed =
+    !forwarded &&
+    healthPeerListed(deps.healthDetailPeers, server.requestIP(request)?.address ?? null);
+  return new Response(JSON.stringify(healthBody(payload.body, 'sync', detailed)), {
+    status: payload.status,
+    headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+  });
+}
+
 /** Load shedding with a delay attached: refusing without one just moves the herd next door. */
 function shed(deps: UpgradeDeps): Response {
   return new Response('retry', {
@@ -185,6 +246,13 @@ function shed(deps: UpgradeDeps): Response {
   });
 }
 
+/** What the refusal says this node admits: the declared list, and under `x dev` the reached-on origin. */
+function admittedList(deps: UpgradeDeps): readonly string[] {
+  const declared = deps.allowedOrigins ?? [];
+  if (declared.length === 0 || deps.admitReachedOrigin !== true) return declared;
+  return [...declared, 'the origin it was reached on'];
+}
+
 function wireErrorResponse(status: number, error: unknown): Response {
   return json({ status, body: { error: toWireError(error) } });
 }

package/src/use-mutation.ts

@@ -9,11 +9,12 @@ import {
   clientTransport,
   isSuperseded,
   isUltimateError,
+  pageClient,
   uuid,
 } from '@ultimat3/core/page';
 import type { JsonValue } from './json';
 import { type OutboxHandle, peekOutbox } from './outbox-slot';
-import { ServerRenderLiveError } from './page-errors';
+import { OfflineQueueAbandonedError, ServerRenderLiveError } from './page-errors';
 import { type PageWrites, pageRealtime } from './page-store';
 import { isServerRender, signalFor } from './reactivity';
 import { carriedBy } from './record-store';
@@ -127,6 +128,7 @@ export function useMutation(mutator: MutatorLike): Mutate {
   const call = async (input: JsonValue): Promise<unknown> => {
     if (writes === undefined) throw new ServerRenderLiveError({ operation: 'useMutation()' });
     const page = pageRealtime();
+    const issued = pageClient().scope.epoch;
     const key = `${mutator.name}:${uuid()}`;
     const local = mutator.local;
     // Called back through the mutator: `local` may be a method, and an unbound one loses `this`.
@@ -138,9 +140,31 @@ export function useMutation(mutator: MutatorLike): Mutate {
     // them over HTTP — a like queued offline and the unlike made once the network was back could
     // otherwise land swapped. The replay sends the queue in order, this write last, under its key.
     const queued = peekOutbox();
+    // The outbox may REFUSE: its queue's principal left mid-write (`X_OFFLINE_QUEUE_ABANDONED`),
+    // or the disk would not take it. Nothing will ever send this write then, so its twin comes
+    // off the screen and the caller is told — a rejected `mutate`, by code.
+    //
+    // And the hook has an await of its own — the POST — so WHOSE write this is was decided at the
+    // call (`issued`): asked for after a principal change, the outbox is the next principal's, and
+    // a write handed to it then would be queued, and sent, as them.
+    const enqueue = async (outbox: OutboxHandle): Promise<void> => {
+      try {
+        if (pageClient().scope.epoch !== issued) {
+          throw new OfflineQueueAbandonedError({ name: mutator.name });
+        }
+        await outbox.enqueue({ key, name: mutator.name, input });
+      } catch (error) {
+        page.store.drop(key);
+        // A principal change is nobody's failure to report; a disk that refused the write is.
+        if (!isUltimateError(error) || error.code !== 'X_OFFLINE_QUEUE_ABANDONED') {
+          writes.failed += 1;
+        }
+        throw error;
+      }
+    };
     if (queued !== undefined && queued.pending().length > 0) {
       try {
-        await queued.enqueue({ key, name: mutator.name, input });
+        await enqueue(queued);
         void queued.replay().catch(() => undefined);
         return undefined;
       } finally {
@@ -160,13 +184,17 @@ export function useMutation(mutator: MutatorLike): Mutate {
       });
     } catch (error) {
       const failure = transportFailure(error);
-      // No response at all: the write is the outbox's now, under the SAME idempotency key, and its
-      // overlay stays on screen until the replay settles or refuses it. Only a page the boot opened
+      // No response at all — which is NOT "the write did not land": the POST may have committed
+      // and lost its answer. The write is the outbox's now, under the SAME idempotency key, and
+      // that replay is safe only because `mutator()` refuses a declaration without
+      // `idempotent: true` (`X_MUTATOR_NOT_IDEMPOTENT`): the server reads the key and answers the
+      // replay from its idempotency store, so the handler never runs twice. The overlay stays on
+      // screen until the replay settles or refuses it. Only a page the boot opened
       // an outbox on can promise that; with none (no boot, so nothing on this page persists) the
       // write is refused like any other, never held in a memory queue a reload would silently lose.
       const outbox = failure === 'network' ? await bootedOutbox(page) : undefined;
       if (outbox !== undefined) {
-        await outbox.enqueue({ key, name: mutator.name, input });
+        await enqueue(outbox);
         return undefined;
       }
       if (failure === 'body') {

package/src/wire-channel.ts

@@ -65,7 +65,7 @@ export function channelTarget(value: JsonObject): ChannelSubscribeTarget {
       `channel params carry ${entries.length}, over the limit of ${FRAME_LIMITS.channelParams}`,
     );
   }
-  const params: Record<string, string> = {};
+  const params = bare<string>();
   for (const [key, param] of entries) {
     if (typeof param !== 'string') throw fail(`channel param "${key}" must be a string`);
     params[key] = param;
@@ -87,10 +87,10 @@ function sinceOf(value: unknown): ChannelSince {
 function adoptOf(value: unknown): ChannelAdopt {
   if (!isJsonObject(value)) throw fail('records.adopt must be an object');
   let total = 0;
-  const out: Record<string, Readonly<Record<string, Row>>> = {};
+  const out = bare<Readonly<Record<string, Row>>>();
   for (const [type, keyed] of Object.entries(value)) {
     if (!isJsonObject(keyed)) throw fail(`records.adopt.${type} must be an object`);
-    const rows: Record<string, Row> = {};
+    const rows = bare<Row>();
     for (const [key, row] of Object.entries(keyed)) {
       total += 1;
       if (total > FRAME_LIMITS.rows) {
@@ -105,7 +105,7 @@ function adoptOf(value: unknown): ChannelAdopt {
 
 function removeOf(value: unknown): ChannelRemove {
   if (!isJsonObject(value)) throw fail('records.remove must be an object');
-  const out: Record<string, readonly string[]> = {};
+  const out = bare<readonly string[]>();
   for (const type of Object.keys(value)) {
     out[type] = list(value, type, FRAME_LIMITS.rows, `records.remove.${type}`).map((key) => {
       if (typeof key !== 'string') throw fail(`records.remove.${type} must hold strings`);
@@ -114,3 +114,12 @@ function removeOf(value: unknown): ChannelRemove {
   }
   return out;
 }
+
+/**
+ * A map keyed by WIRE data — a record type, a record key, a channel param. Null-prototype, as the
+ * encoder's are (`channel-render.ts`): on a plain object `out['__proto__'] = rows` sets the map's
+ * prototype instead of a key, so that entry was dropped and every other read went through it.
+ */
+function bare<V>(): Record<string, V> {
+  return Object.create(null) as Record<string, V>;
+}