@ultimat3/realtime 1.2.0 → 2.0.0

package/src/nats-transport.ts

@@ -1,15 +1,16 @@
 // Single responsibility: the production `Transport` — core NATS for fanout, JetStream KV for the
-// shared presence sets. Subscriptions are held as intent rather than as socket state, so a lost
-// connection is re-established and re-subscribed underneath the caller: that is what makes a `sync`
-// node stateless and lets any client resubscribe to any node.
+// shared presence sets. The client underneath owns the wire and the reconnect, including
+// re-establishing subscriptions, which is what makes a `sync` node stateless: a lost connection is
+// re-dialled and re-subscribed underneath the caller, and this file keeps no socket state at all.
 
-import { type Clock, isUltimateError, logger, systemClock } from '@ultimat3/core';
+import { type Clock, isUltimateError, logger, renderThrowable, systemClock } from '@ultimat3/core';
 import { TransportUnavailableError } from './errors';
 import type { Transport, TransportHandler, TransportSet, TransportSubscription } from './fanout';
-import { NatsConnection, type NatsSubscription } from './nats-connection';
+import type { NatsClient, NatsConnect } from './nats-client';
+import { parseNatsUrl } from './nats-client';
 import { ensureKvBucket } from './nats-jetstream';
 import { NatsKvSet } from './nats-kv';
-import { bunNatsStream, type NatsStream, type NatsTarget, parseNatsUrl } from './nats-socket';
+import { openNatsClient } from './nats-lib-client';
 import { type BackoffPolicy, backoffDelay, defaultBackoff, type Rng } from './thundering-herd';
 
 const encoder = new TextEncoder();
@@ -28,44 +29,37 @@ export interface NatsTransportOptions {
   readonly onError?: (error: unknown, subject: string) => void;
   readonly rng?: Rng;
   /** Injected so the whole transport — reconnect included — runs in a test with no network. */
-  readonly open?: (target: NatsTarget) => Promise<NatsStream>;
-  readonly sleep?: (ms: number) => Promise<void>;
-}
-
-interface Wanted {
-  readonly subject: string;
-  readonly handler: TransportHandler;
-  live: NatsSubscription | undefined;
+  readonly connect?: NatsConnect;
 }
 
 const DEFAULT_ATTEMPTS = 10;
+const DEFAULT_PRESENCE_TTL_MS = 30_000;
 
 /** The production bus: NATS subjects for fanout, a JetStream KV bucket for presence. */
 export class NatsTransport implements Transport {
   readonly name = 'nats';
   readonly shared: TransportSet;
-  readonly #target: NatsTarget;
   readonly #options: NatsTransportOptions;
-  readonly #wanted = new Map<number, Wanted>();
+  readonly #connect: NatsConnect;
   readonly #backoff: BackoffPolicy;
   readonly #attempts: number;
   readonly #rng: Rng;
-  readonly #sleep: (ms: number) => Promise<void>;
-  #connection: NatsConnection | undefined;
-  #dialing: Promise<NatsConnection> | undefined;
-  #next = 0;
-  #losses = 0;
+  #client: NatsClient | undefined;
+  #dialing: Promise<NatsClient> | undefined;
+  #retries = 0;
   #closed = false;
 
   constructor(options: NatsTransportOptions) {
-    this.#target = parseNatsUrl(options.url);
+    // Parsed here rather than at the first publish: a malformed NATS_URL is a boot-time fault, and
+    // a container that reports itself healthy on one is a container nothing will ever page about.
+    parseNatsUrl(options.url);
     this.#options = options;
+    this.#connect = options.connect ?? openNatsClient;
     this.#backoff = options.backoff ?? defaultBackoff;
     this.#attempts = options.maxReconnectAttempts ?? DEFAULT_ATTEMPTS;
     this.#rng = options.rng ?? Math.random;
-    this.#sleep = options.sleep ?? ((ms) => Bun.sleep(ms));
     this.shared = new NatsKvSet({
-      connection: () => this.#ensure(),
+      client: () => this.#ensure(),
       bucket: options.bucket,
       clock: options.clock ?? systemClock,
     });
@@ -77,107 +71,88 @@ export class NatsTransport implements Transport {
   }
 
   get connected(): boolean {
-    return this.#connection !== undefined && !this.#connection.closed;
+    return this.#client?.connected === true;
   }
 
   async publish(subject: string, payload: string): Promise<void> {
-    const connection = await this.#ensure();
-    await connection.publish(subject, encoder.encode(payload));
+    const client = await this.#ensure();
+    // `client.publish` is synchronous and refuses locally: a bad subject, a payload over the
+    // server's `max_payload`, a connection torn down between the `#ensure` and this line. Those
+    // are the LIBRARY's errors — or an app-supplied `connect`'s — so they arrive uncoded, and
+    // `ChannelHub`'s bridge, `SocketRegistry` and the replicator all await this call.
+    this.#translating(`publish to ${subject}`, () =>
+      client.publish(subject, encoder.encode(payload)),
+    );
   }
 
+  /**
+   * The subscription is the client's to keep: it survives a drop and comes back with the reconnect,
+   * so there is no intent map here to re-bind from — and therefore no way for a re-bind to run
+   * twice and double every change on the subject.
+   */
   async subscribe(subject: string, handler: TransportHandler): Promise<TransportSubscription> {
-    this.#next += 1;
-    const id = this.#next;
-    const wanted: Wanted = { subject, handler, live: undefined };
-    this.#wanted.set(id, wanted);
-    try {
-      const connection = await this.#ensure();
-      // The dial this may have triggered already re-bound everything it found registered, this
-      // one included — binding again here would double every delivery on the subject.
-      wanted.live ??= await this.#bind(connection, wanted);
-    } catch (error) {
-      this.#wanted.delete(id);
-      throw error;
-    }
-    return {
-      subject,
-      unsubscribe: () => {
-        this.#wanted.delete(id);
-        void wanted.live?.unsubscribe().catch((error: unknown) => this.#report(error, subject));
-        wanted.live = undefined;
-      },
-    };
+    const client = await this.#ensure();
+    // Same seam as `publish`: a permissions violation on the subject is refused here, not later.
+    const live = this.#translating(`subscribe to ${subject}`, () =>
+      client.subscribe(subject, (message) => {
+        try {
+          handler(decoder.decode(message.payload), message.subject);
+        } catch (error) {
+          this.#report(error, message.subject);
+        }
+      }),
+    );
+    return { subject, unsubscribe: () => live.unsubscribe() };
   }
 
   async close(): Promise<void> {
     this.#closed = true;
-    this.#wanted.clear();
-    const connection = this.#connection;
-    this.#connection = undefined;
-    await connection?.close();
-  }
-
-  #bind(connection: NatsConnection, wanted: Wanted): Promise<NatsSubscription> {
-    return connection.subscribe(wanted.subject, (message) => {
-      try {
-        wanted.handler(decoder.decode(message.payload), message.subject);
-      } catch (error) {
-        this.#report(error, message.subject);
-      }
-    });
+    const client = this.#client;
+    this.#client = undefined;
+    await client?.close();
   }
 
-  #ensure(): Promise<NatsConnection> {
+  /**
+   * One dial, shared by every caller that races it. A client that has already been handed out is
+   * reused whatever its state: while it is reconnecting the library is re-establishing that same
+   * connection and its subscriptions, and a second dial alongside it would double every delivery.
+   * A budget that ran out is a readiness failure, not a reason to start an unbounded retry here.
+   */
+  #ensure(): Promise<NatsClient> {
     if (this.#closed) {
       return Promise.reject(
         new TransportUnavailableError({ transport: this.name, reason: 'transport is closed' }),
       );
     }
-    const current = this.#connection;
-    if (current !== undefined && !current.closed) return Promise.resolve(current);
+    const current = this.#client;
+    if (current !== undefined) return Promise.resolve(current);
     this.#dialing ??= this.#dial().finally(() => {
       this.#dialing = undefined;
     });
     return this.#dialing;
   }
 
-  /** Retry is bounded: a bus that is down for longer than the budget is a readiness failure. */
-  async #dial(): Promise<NatsConnection> {
-    for (let attempt = 0; ; attempt += 1) {
-      try {
-        return await this.#establish();
-      } catch (error) {
-        // A protocol mismatch answers the same on every attempt — a server too old for per-message
-        // TTL stays too old — so retrying only delays the one report that names the fix.
-        const fatal = isUltimateError(error) && error.code === 'X_TRANSPORT_PROTOCOL';
-        if (fatal || this.#closed || attempt >= this.#attempts) {
-          throw isUltimateError(error)
-            ? error
-            : new TransportUnavailableError({
-                transport: this.name,
-                reason: `${this.#target.host}:${this.#target.port} — ${String(error)}`,
-              });
-        }
-        await this.#sleep(backoffDelay(attempt, this.#backoff, this.#rng));
-      }
-    }
-  }
-
   /**
-   * One attempt, published only once it is whole. A connection parked in `#connection` before its
-   * bucket and its subscriptions are up answers `connected` for a dial that rejected, keeps its
-   * `onClose` — which then clears the connection that replaced it — and leaves half a rebind
-   * behind, so the next dial binds the same subject a second time and every change arrives twice.
-   * A failed attempt therefore takes its own socket down with it rather than leaking one per retry.
+   * One attempt, published only once it is whole. A client parked in `#client` before its bucket is
+   * up answers `connected` for a dial that rejected, and the next caller then writes presence into
+   * a bucket that does not exist. A failed attempt therefore closes its own connection rather than
+   * leaking one per retry.
    */
-  async #establish(): Promise<NatsConnection> {
-    const connection = await this.#open();
+  async #dial(): Promise<NatsClient> {
+    const client = await this.#connect({
+      url: this.#options.url,
+      name: 'ultimate',
+      maxReconnectAttempts: this.#attempts,
+      // The library retries; the spread is ours, so a cluster restart does not bring every node
+      // back on the same millisecond.
+      reconnectDelay: () => backoffDelay(this.#retries++, this.#backoff, this.#rng),
+      onError: (error) => this.#report(error, this.name),
+      onReconnect: () => this.#recovered(),
+    });
     try {
-      await ensureKvBucket(connection, this.#options.bucket, this.#options.presenceTtlMs ?? 30_000);
-      for (const wanted of this.#wanted.values())
-        wanted.live = await this.#bind(connection, wanted);
-      // `close()` can land while an attempt is in flight, and it only closes what it can see:
-      // publishing now would leave a socket open that nothing will ever close again.
+      await this.#ensureBucket(client);
+      // `close()` can land while a dial is in flight, and it only closes what it can see:
+      // publishing now would leave a connection open that nothing will ever close again.
       if (this.#closed) {
         throw new TransportUnavailableError({
           transport: this.name,
@@ -185,55 +160,51 @@ export class NatsTransport implements Transport {
         });
       }
     } catch (error) {
-      for (const wanted of this.#wanted.values()) wanted.live = undefined;
-      await connection.close();
+      await client.close();
       throw error;
     }
-    this.#connection = connection;
-    this.#losses = 0;
-    return connection;
+    this.#client = client;
+    this.#retries = 0;
+    return client;
   }
 
-  async #open(): Promise<NatsConnection> {
-    const stream = await (this.#options.open ?? bunNatsStream)(this.#target);
-    // The connection names itself in its own `onClose` so a drop can be matched against the live
-    // one. It goes through a holder rather than a `const`, because a buffered `-ERR` closes the
-    // session from inside `open()`, while a `const` binding would still be in its dead zone.
-    const held: { connection: NatsConnection | undefined } = { connection: undefined };
-    held.connection = await NatsConnection.open({
-      stream,
-      target: this.#target,
-      name: 'ultimate',
-      rng: this.#options.rng,
-      onClose: (error) => this.#lost(error, held.connection),
-      onError: (error) => this.#report(error, this.name),
-    });
-    return held.connection;
+  #ensureBucket(client: NatsClient): Promise<void> {
+    return ensureKvBucket(
+      client,
+      this.#options.bucket,
+      this.#options.presenceTtlMs ?? DEFAULT_PRESENCE_TTL_MS,
+    );
   }
 
   /**
-   * A lost connection re-dials on its own rather than waiting for the next publish: a `sync` node
-   * whose subscriptions are down is silently delivering nothing, which is worse than an error.
+   * A reconnect may have landed on a different cluster — a restarted single node, or a failover to
+   * one that never held this bucket. The subscriptions came back with the client; the bucket is the
+   * one thing the library knows nothing about, so it is re-asserted here. It is idempotent.
    */
-  #lost(error: unknown, connection: NatsConnection | undefined): void {
-    // Only the live connection may declare a loss. One abandoned mid-dial drops on its own clock,
-    // and without this it would clear the subscriptions — and the reconnect budget — of whichever
-    // connection replaced it, then report a failure the transport had already recovered from.
-    if (connection === undefined || this.#connection !== connection) return;
-    this.#connection = undefined;
-    for (const wanted of this.#wanted.values()) wanted.live = undefined;
-    this.#report(error, this.name);
-    if (this.#closed || this.#wanted.size === 0) return;
-    this.#losses += 1;
-    if (this.#losses > this.#attempts) return;
-    void this.#recover();
+  #recovered(): void {
+    this.#retries = 0;
+    const client = this.#client;
+    if (client === undefined) return;
+    void this.#ensureBucket(client).catch((error: unknown) => this.#report(error, this.name));
   }
 
-  async #recover(): Promise<void> {
-    // Backoff first: a server that accepts and immediately drops must not become a hot loop.
-    await this.#sleep(backoffDelay(this.#losses - 1, this.#backoff, this.#rng));
-    if (this.#closed || this.connected) return;
-    await this.#ensure().catch((error: unknown) => this.#report(error, this.name));
+  /**
+   * One call into the client, with its refusal translated. An `UltimateError` passes through — the
+   * port raises its own for a closed client, and re-wrapping would bury the code a caller branches
+   * on — while anything else becomes `X_TRANSPORT_UNAVAILABLE` carrying the library's own words as
+   * evidence. Never a bare `Error` out of this file: a raw `NatsError` has no code, no `fix:` and
+   * nothing an operator can act on, which is the whole reason the port is here.
+   */
+  #translating<T>(what: string, call: () => T): T {
+    try {
+      return call();
+    } catch (error) {
+      if (isUltimateError(error)) throw error;
+      throw new TransportUnavailableError({
+        transport: this.name,
+        reason: `${what} was refused: ${renderThrowable(error)}`,
+      });
+    }
   }
 
   /**

package/src/offline-queue.ts

@@ -1,11 +1,15 @@
-// Tier 3: the durable mutation queue. Two invariants, both enforced here rather than documented:
+// Tier 3: the durable mutation queue. Three invariants, all enforced here rather than documented:
 //
 //   1. **Order.** Mutations drain in client sequence order and stop at the first failure. A mutator
 //      that assumed `like` ran before `unlike` must never see them swapped.
 //   2. **Dedupe.** The idempotency key is the identity of the intent. Re-enqueueing a key that is
 //      already queued (double click, replay after a crash) collapses onto the existing entry and
 //      never gets a new sequence number.
+//   3. **Only the server removes a mutation.** A `send` that returned proves the frame was handed
+//      to a socket and nothing more, so a drained mutation is `inflight` — not `acked` — until an
+//      `ack`/`fail` frame settles it, or a lost connection returns it to the queue.
 
+import { renderThrowable, stringField } from '@ultimat3/core';
 import type { JsonValue } from './json';
 import { type Frame, PROTOCOL_VERSION, type WireError } from './sync-protocol';
 
@@ -50,6 +54,7 @@ export class MemoryQueueStore implements QueueStore {
 export interface DrainReport {
   readonly sent: number;
   readonly collapsed: number;
+  /** Still to send. Not the queue depth: a sent mutation is unacknowledged, never unsent. */
   readonly remaining: number;
   readonly stoppedAt: string | null;
 }
@@ -61,6 +66,14 @@ export class OfflineQueue {
   #mutations: QueuedMutation[] = [];
   #nextSeq = 1;
   #collapsed = 0;
+  /** The drain lane: one pass at a time, in call order. See `drain`. */
+  #draining: Promise<DrainReport> | null = null;
+  /**
+   * Which connection the current pass is draining into. The lane orders passes against each other
+   * but `requeueInflight` is not a pass — it is a socket death, and it cannot reach into one that
+   * is parked inside `send`. Bumped by every loss so a pass that resumes afterwards claims nothing.
+   */
+  #epoch = 0;
 
   private constructor(store: QueueStore, state: QueueState) {
     this.#store = store;
@@ -89,7 +102,10 @@ export class OfflineQueue {
     return this.#mutations.find((mutation) => mutation.key === key);
   }
 
-  /** Sorted by sequence. This is the only order anything downstream is allowed to use. */
+  /**
+   * Everything the server has not settled yet, sorted by sequence — this is the only order
+   * anything downstream is allowed to use, and the count a UI renders as "unsynced".
+   */
   pending(): readonly QueuedMutation[] {
     return this.#mutations
       .filter((mutation) => mutation.status === 'pending' || mutation.status === 'inflight')
@@ -107,10 +123,16 @@ export class OfflineQueue {
     at?: number;
   }): Promise<QueuedMutation> {
     const existing = this.find(args.key);
-    if (existing) {
+    if (existing && existing.status !== 'failed') {
       this.#collapsed += 1;
       return existing;
     }
+    // A terminally failed entry is a decision the server already made about this key, kept for the
+    // UI — collapsing onto it makes an explicit idempotency key unusable for the rest of the
+    // session, because nothing ever retries a denial. Re-issuing one is a NEW intent, so the old
+    // entry is dropped and this one takes a new sequence at the back of the queue.
+    if (existing)
+      this.#mutations = this.#mutations.filter((candidate) => candidate.key !== args.key);
     const mutation: QueuedMutation = {
       key: args.key,
       seq: this.#nextSeq,
@@ -130,31 +152,51 @@ export class OfflineQueue {
   /**
    * Drains in sequence order and stops at the first failure. Continuing past a failure is how a
    * sync engine reorders a user's intent — so it does not continue.
+   *
+   * **One pass at a time, chained rather than joined.** Two passes overlapping read the same entry
+   * as sendable and put the same key on the wire twice — with the same seq, and the node dedupes
+   * nothing — and a pass that started later could pass a mutation the pass in front of it has not
+   * reached yet, which is the ordering guarantee above, gone. Chained rather than joined because a
+   * caller that enqueued after the running pass began must still see its own mutation sent: it
+   * gets a pass BEHIND that one, not that one's promise. The chain hangs off a settled shadow, so
+   * one pass that rejected does not reject every pass behind it.
    */
   async drain(send: MutationSender): Promise<DrainReport> {
-    let sent = 0;
-    for (const mutation of this.pending()) {
-      mutation.status = 'inflight';
-      mutation.attempts += 1;
-      try {
-        await send(mutation);
-        mutation.status = 'acked';
-        mutation.error = null;
-        sent += 1;
-      } catch (error) {
-        mutation.status = 'pending';
-        mutation.error = toQueueError(error);
-        await this.#persist();
-        return {
-          sent,
-          collapsed: this.#collapsed,
-          remaining: this.pending().length,
-          stoppedAt: mutation.key,
-        };
-      }
+    const ahead = this.#draining?.then(
+      () => undefined,
+      () => undefined,
+    );
+    const pass = (ahead ?? Promise.resolve()).then(() => this.#pass(send));
+    this.#draining = pass;
+    try {
+      return await pass;
+    } finally {
+      // Cleared only by the last pass in the chain, so the next drain starts fresh instead of
+      // queueing behind a promise that settled a lifetime ago.
+      if (this.#draining === pass) this.#draining = null;
     }
-    await this.#persist();
-    return { sent, collapsed: this.#collapsed, remaining: this.pending().length, stoppedAt: null };
+  }
+
+  /**
+   * A lost connection: everything handed to the dead socket goes back to `pending`, because a
+   * `send` that returned is not an acknowledgement and those frames may never have left the tab.
+   * At least once by construction — the idempotency key is what makes the resend safe.
+   *
+   * The epoch is bumped BEFORE the scan, not after: a pass parked at `await send(p1)` on the socket
+   * that just died resumes into this same turn and would otherwise mark p2 and p3 `inflight` for a
+   * connection that is gone. `#sendable` excludes `inflight`, so the next drain skips them, no ack
+   * will ever arrive, and the writes are lost — which is exactly what invariant 3 forbids.
+   */
+  async requeueInflight(): Promise<number> {
+    this.#epoch += 1;
+    let returned = 0;
+    for (const mutation of this.#mutations) {
+      if (mutation.status !== 'inflight') continue;
+      mutation.status = 'pending';
+      returned += 1;
+    }
+    if (returned > 0) await this.#persist();
+    return returned;
   }
 
   /** Server acknowledged: the mutation leaves the queue and its rebase entry can be committed. */
@@ -175,13 +217,82 @@ export class OfflineQueue {
     await this.#persist();
   }
 
+  /** Never sent on this connection. `inflight` is excluded: it is already on a socket. */
+  #sendable(): readonly QueuedMutation[] {
+    return this.#mutations
+      .filter((mutation) => mutation.status === 'pending')
+      .sort((a, b) => a.seq - b.seq);
+  }
+
+  /** One drain pass. Never called concurrently with itself — `drain` owns that. */
+  async #pass(send: MutationSender): Promise<DrainReport> {
+    const epoch = this.#epoch;
+    const sendable = this.#sendable();
+    // Nothing to do: a pass chained behind one that already sent everything must not rewrite the
+    // durable state for the privilege of reporting zero.
+    if (sendable.length === 0) {
+      return { sent: 0, collapsed: this.#collapsed, remaining: 0, stoppedAt: null };
+    }
+    let sent = 0;
+    for (const mutation of sendable) {
+      // The connection this pass was draining into is gone, and `requeueInflight` has already
+      // handed back what was on it. Everything left stays `pending` for the pass the next
+      // connection arms — claiming it here would strand it on a socket that cannot answer.
+      if (epoch !== this.#epoch) {
+        return {
+          sent,
+          collapsed: this.#collapsed,
+          remaining: this.#sendable().length,
+          stoppedAt: mutation.key,
+        };
+      }
+      mutation.status = 'inflight';
+      mutation.attempts += 1;
+      try {
+        await send(mutation);
+        // Stays `inflight`. `send` resolving means the frame reached a socket — a browser
+        // `WebSocket.send` on a CLOSING socket discards it and returns normally — so calling that
+        // an ack drops the mutation on exactly the socket death this queue exists to survive.
+        // Only `ack`/`fail` (the server) or `requeueInflight` (a lost connection) moves it on.
+        mutation.error = null;
+        sent += 1;
+      } catch (error) {
+        mutation.status = 'pending';
+        mutation.error = toQueueError(error);
+        await this.#persist();
+        return {
+          sent,
+          collapsed: this.#collapsed,
+          remaining: this.#sendable().length,
+          stoppedAt: mutation.key,
+        };
+      }
+    }
+    await this.#persist();
+    return {
+      sent,
+      collapsed: this.#collapsed,
+      remaining: this.#sendable().length,
+      stoppedAt: null,
+    };
+  }
+
   async clear(): Promise<void> {
     this.#mutations = [];
     await this.#persist();
   }
 
+  /**
+   * A snapshot, never the live entries. `save` is a durable write — OPFS, IndexedDB — and it is
+   * allowed to await before it reads. Handed the array itself, a store that resolves after the next
+   * pass has moved on persists a status that was never true when it was called; `inflight` is the
+   * one a reload cannot recover from, because `#sendable` skips it and no ack is coming.
+   */
   async #persist(): Promise<void> {
-    await this.#store.save({ mutations: this.#mutations, nextSeq: this.#nextSeq });
+    await this.#store.save({
+      mutations: this.#mutations.map((mutation) => ({ ...mutation })),
+      nextSeq: this.#nextSeq,
+    });
   }
 }
 
@@ -197,10 +308,15 @@ export function mutateFrame(mutation: QueuedMutation): Frame {
 }
 
 function toQueueError(error: unknown): WireError {
-  const shape = error as { code?: unknown; cause?: unknown; fix?: unknown } | null;
   return {
-    code: typeof shape?.code === 'string' ? shape.code : 'X_TRANSPORT_UNAVAILABLE',
-    cause: typeof shape?.cause === 'string' ? shape.cause : String(error),
-    fix: typeof shape?.fix === 'string' ? shape.fix : 'the queue retries on the next reconnect',
+    // `stringField`, not `shape?.code`: the sender is a transport the app supplied, so the probe
+    // for "did it throw a coded error" is itself a property read on an app value. A getter that
+    // throws escaped `drain`'s catch through the probe rather than the render — the same contract
+    // break one line earlier than the one the comment below records.
+    code: stringField(error, 'code') ?? 'X_TRANSPORT_UNAVAILABLE',
+    // Whatever the sender threw. `String()` here escaped `drain`'s own catch, so the queue's
+    // stop-at-the-first-failure contract broke on the failure it exists to record.
+    cause: stringField(error, 'cause') ?? renderThrowable(error),
+    fix: stringField(error, 'fix') ?? 'the queue retries on the next reconnect',
   };
 }