@ultimat3/realtime 21.0.0 → 22.0.0

package/src/transport-env.ts

@@ -1,20 +1,30 @@
-// Single responsibility: environment → fanout transport. The one place a boot decides whether this
-// process fans changes out inside its own heap or over NATS, so `x dev`, a `sync` container and any
-// custom host resolve it identically. The KV bucket and the presence TTL are decided here too:
+// Single responsibility: `realtime.transport` + environment → fanout transport. The one place a boot
+// decides whether this process fans changes out inside its own heap or over NATS, so `x dev`, a
+// `sync` container and any custom host resolve it identically. The KV bucket and the presence TTL are decided here too:
 // the bucket's whole-stream age limit and `PresenceRegistry`'s TTL are the same number seen from
 // two sides, and a caller that had to pass each one separately could quietly set them apart.
 
-import type { Clock } from '@ultimat3/core';
-import { finiteOption } from '@ultimat3/core';
+import type { Clock, RealtimeConfig } from '@ultimat3/core';
+import { ConfigInvalidError, finiteOption } from '@ultimat3/core';
 import type { Transport } from './fanout';
 import { InProcessTransport } from './fanout';
 import type { NatsConnect } from './nats-client';
 import { assertBucket } from './nats-jetstream';
 import { NatsTransport } from './nats-transport';
 
-/** The keys read here, and nothing else. Named once so docs and tests cannot drift from the code. */
+/**
+ * The keys read here, and nothing else. Named once so docs and tests cannot drift from the code.
+ * `NATS_URL` is the conventional bus variable: read under `transport: 'nats'` when `urlEnv` names
+ * it, and under `'memory'` only to refuse it — see `selectTransport`.
+ */
 export const TRANSPORT_ENV_KEYS = ['NATS_URL', 'NATS_KV_BUCKET'] as const;
 
+/** The two fields of `app.config.ts`'s `realtime` section that decide the bus. */
+export type RealtimeTopology = Pick<RealtimeConfig, 'transport' | 'urlEnv'>;
+
+/** Named in every refusal, so the reader edits the file the decision lives in. */
+const CONFIG_FILE = 'app.config.ts';
+
 /**
  * One bucket per deployment, not per cluster: two apps sharing a nats-server would otherwise share
  * one presence namespace, and a room name that collided would list the other app's members.
@@ -59,13 +69,22 @@ const nonEmpty = (value: string | undefined): string | undefined =>
   value === undefined || value.trim().length === 0 ? undefined : value.trim();
 
 /**
- * No url means the in-process transport — the same "an unset variable means the embedded default"
- * law the db, mail, storage and replication bindings follow. The bucket name is validated here
- * rather than on first connect: a typo'd bucket is a boot that reports a healthy bus and then
- * fails every presence write, which is the failure this whole selector exists to move earlier.
+ * The config decides the transport and the environment supplies its url — never the other way
+ * round. Until 22.0.0 `NATS_URL` alone decided and `realtime.transport` / `realtime.urlEnv` were
+ * read by nothing, so `transport: 'nats'` with the variable unset booted the in-process bus and
+ * reached no other node, with no error on either side. Both mismatches are refused here:
+ *
+ * - `'nats'` with the variable `urlEnv` names unset or blank.
+ * - `'memory'` with a bus url set (`NATS_URL`, or the variable `urlEnv` names). An operator who set
+ *   one expected fanout across nodes; keeping every change in this heap instead is the same silent
+ *   failure seen from the other side, so the two are refused rather than reconciled.
+ *
+ * The bucket name is validated here rather than on first connect: a typo'd bucket is a boot that
+ * reports a healthy bus and then fails every presence write.
  */
 export function selectTransport(
   env: TransportEnvironment,
+  topology: RealtimeTopology,
   options: SelectTransportOptions = {},
 ): TransportSelection {
   const presenceTtlMs = finiteOption(
@@ -73,22 +92,32 @@ export function selectTransport(
     'presenceTtlMs',
     options.presenceTtlMs ?? DEFAULT_PRESENCE_TTL_MS,
   );
-  const url = nonEmpty(env['NATS_URL']);
 
-  if (url === undefined) {
+  if (topology.transport === 'memory') {
+    refuseStrayBusUrl(env, topology);
     const transport = new InProcessTransport(
       options.clock === undefined ? {} : { clock: options.clock },
     );
     return {
       transport,
       mode: 'embedded',
-      detail: 'in-process fanout — set NATS_URL to reach the other nodes',
+      detail: `in-process fanout — set realtime.transport 'nats' in ${CONFIG_FILE} and NATS_URL to reach the other nodes`,
       bucket: null,
       presenceTtlMs,
       connect: () => Promise.resolve(),
     };
   }
 
+  const urlEnv = topology.urlEnv ?? 'NATS_URL';
+  const url = nonEmpty(env[urlEnv]);
+  if (url === undefined) {
+    throw new ConfigInvalidError({
+      cause: `realtime.transport is 'nats' and realtime.urlEnv names ${urlEnv}, which is unset in this process's environment, so no node would be reachable`,
+      fix: `set ${urlEnv} to the nats-server url for every realtime role (web, sync, replicator), or set realtime: { transport: 'memory' } in ${CONFIG_FILE} for a single node`,
+      meta: { key: 'realtime.urlEnv', variable: urlEnv },
+    });
+  }
+
   const bucket = nonEmpty(env['NATS_KV_BUCKET']) ?? DEFAULT_PRESENCE_BUCKET;
   assertBucket(bucket);
   const transport = new NatsTransport({
@@ -101,9 +130,21 @@ export function selectTransport(
   return {
     transport,
     mode: 'external',
-    detail: 'NATS_URL',
+    detail: urlEnv,
     bucket,
     presenceTtlMs,
     connect: () => transport.connect(),
   };
 }
+
+/** `'memory'` with a bus url in the environment: the conflict `selectTransport` refuses. */
+function refuseStrayBusUrl(env: TransportEnvironment, topology: RealtimeTopology): void {
+  const names = topology.urlEnv === undefined ? ['NATS_URL'] : ['NATS_URL', topology.urlEnv];
+  const set = names.find((name) => nonEmpty(env[name]) !== undefined);
+  if (set === undefined) return;
+  throw new ConfigInvalidError({
+    cause: `${set} is set but realtime.transport is 'memory', so this process would fan out in its own heap and reach no other node`,
+    fix: `set realtime: { transport: 'nats', urlEnv: '${set}' } in ${CONFIG_FILE} to use the bus, or unset ${set} for a single node`,
+    meta: { key: 'realtime.transport', variable: set },
+  });
+}

package/src/use-mutation.ts

@@ -134,6 +134,19 @@ export function useMutation(mutator: MutatorLike): Mutate {
       page.store.push(key, (tx) => mutator.local?.(tx, input), mutator.conflict ?? 'server-wins');
     }
     count(writes, mutator.name, 1);
+    // Older writes still wait in the outbox: this one queues BEHIND them rather than overtaking
+    // 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();
+    if (queued !== undefined && queued.pending().length > 0) {
+      try {
+        await queued.enqueue({ key, name: mutator.name, input });
+        void queued.replay().catch(() => undefined);
+        return undefined;
+      } finally {
+        count(writes, mutator.name, -1);
+      }
+    }
     let output: unknown;
     /** The records the answer carried, `type:key` — what the overlay may be settled against. */
     const carried = new Set<string>();

package/src/use-query.ts

@@ -161,7 +161,9 @@ function readAccessor<R extends object>(
    * read's records in answer order (`records[type]`, which `rowsOf` fills first-seen = data order).
    * The browser never derives a key: an answer with no records envelope holds its rows itself.
    */
-  const fetch = (append: boolean): Promise<{ rows: readonly Row[]; keys: string[] | null }> => {
+  const fetch = (
+    append: boolean,
+  ): Promise<{ rows: readonly Row[]; keys: string[] | null; next?: string | null }> => {
     let keysOf: string[] | null = null;
     const onEnvelope = (envelope: RecordEnvelope): void => {
       const records = type === undefined ? undefined : envelope.records?.[type];
@@ -173,10 +175,12 @@ function readAccessor<R extends object>(
     }
     const controls =
       append && after !== null ? { first: options.first, after } : { first: options.first };
-    return method.page(input, controls, { onEnvelope }).then((page) => {
-      after = page.hasNextPage ? page.endCursor : null;
-      return answered(page.rows as readonly Row[]);
-    });
+    // The page's cursor travels WITH its rows and is taken only where the rows are: a `more()`
+    // a refetch superseded wrote its cursor here, before the generation check discarded its rows.
+    return method.page(input, controls, { onEnvelope }).then((page) => ({
+      ...answered(page.rows as readonly Row[]),
+      next: page.hasNextPage ? page.endCursor : null,
+    }));
   };
 
   const load = (append = false): void => {
@@ -186,6 +190,7 @@ function readAccessor<R extends object>(
     fetch(append).then(
       (answer) => {
         if (released || mine !== generation) return;
+        if (answer.next !== undefined) after = answer.next;
         if (type === undefined || answer.keys === null) {
           // Not records — no type named, or no envelope: the list holds its own rows.
           own = append ? [...own, ...answer.rows] : answer.rows;