@ultimat3/realtime 1.2.0 → 3.0.0

package/src/nats-jetstream.ts

@@ -3,8 +3,7 @@
 // built from a validated bucket name, because a stream name goes straight into a request subject.
 
 import { TransportProtocolError, TransportUnavailableError } from './errors';
-import type { NatsConnection } from './nats-connection';
-import type { NatsHeaders, NatsMessage } from './nats-protocol';
+import type { NatsClient, NatsHeaders, NatsMessage } from './nats-client';
 
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
@@ -91,22 +90,22 @@ const errorOf = (body: Record<string, unknown>): JsError | undefined => {
 
 /** One JetStream API call. The API always answers with json, and reports failure inside it. */
 export async function jsRequest(
-  connection: NatsConnection,
+  client: NatsClient,
   subject: string,
   body: unknown,
 ): Promise<{ readonly data: Record<string, unknown>; readonly error: JsError | undefined }> {
-  const reply = await connection.request(subject, encoder.encode(JSON.stringify(body ?? {})));
+  const reply = await client.request(subject, encoder.encode(JSON.stringify(body ?? {})));
   const data = asObject(reply, subject);
   return { data, error: errorOf(data) };
 }
 
 /** `jsRequest`, but a JetStream error is thrown rather than returned. */
 export async function jsCall(
-  connection: NatsConnection,
+  client: NatsClient,
   subject: string,
   body: unknown,
 ): Promise<Record<string, unknown>> {
-  const { data, error } = await jsRequest(connection, subject, body);
+  const { data, error } = await jsRequest(client, subject, body);
   if (error === undefined) return data;
   throw new TransportUnavailableError({
     transport: 'nats',
@@ -122,14 +121,14 @@ export const kvSubject = (bucket: string, key: string): string => `$KV.${bucket}
  * rather than in an ops runbook is what lets `x dev` and a fresh cluster boot the same way.
  */
 export async function ensureKvBucket(
-  connection: NatsConnection,
+  client: NatsClient,
   bucket: string,
   ttlMs: number,
 ): Promise<void> {
   assertBucket(bucket);
-  assertServerVersion(connection.info.version);
+  assertServerVersion(client.version);
   const stream = kvStream(bucket);
-  const info = await jsRequest(connection, `$JS.API.STREAM.INFO.${stream}`, {});
+  const info = await jsRequest(client, `$JS.API.STREAM.INFO.${stream}`, {});
   if (info.error === undefined) return;
   if (info.error.code !== STATUS_NOT_FOUND) {
     throw new TransportUnavailableError({
@@ -137,7 +136,7 @@ export async function ensureKvBucket(
       reason: `could not read stream ${stream}: ${info.error.description}`,
     });
   }
-  await jsCall(connection, `$JS.API.STREAM.CREATE.${stream}`, {
+  await jsCall(client, `$JS.API.STREAM.CREATE.${stream}`, {
     name: stream,
     subjects: [`$KV.${bucket}.>`],
     // History of one: presence is a current value, never a log. `discard: new` keeps a full
@@ -157,26 +156,26 @@ export async function ensureKvBucket(
 }
 
 const recordOf = (message: NatsMessage, bucket: string): KvRecord | undefined => {
-  const subject = message.headers.get('nats-subject');
+  const subject = message.header('Nats-Subject');
   if (subject === undefined) return undefined;
-  const stamp = message.headers.get('nats-time-stamp');
+  const stamp = message.header('Nats-Time-Stamp');
   const writtenAt = stamp === undefined ? undefined : Date.parse(stamp);
   return {
     key: subject.slice(`$KV.${bucket}.`.length),
     value: decoder.decode(message.payload),
     writtenAt: writtenAt === undefined || Number.isNaN(writtenAt) ? undefined : writtenAt,
-    operation: message.headers.get('kv-operation'),
+    operation: message.header('KV-Operation'),
   };
 };
 
 /** The current value for one key, or `undefined` when the server has none. */
 export async function kvGet(
-  connection: NatsConnection,
+  client: NatsClient,
   bucket: string,
   key: string,
 ): Promise<KvRecord | undefined> {
   const subject = `$JS.API.DIRECT.GET.${kvStream(bucket)}.${kvSubject(bucket, key)}`;
-  const reply = await connection.request(subject, new Uint8Array(0));
+  const reply = await client.request(subject, new Uint8Array(0));
   if (reply.status === STATUS_NOT_FOUND) return undefined;
   return recordOf(reply, bucket);
 }
@@ -186,19 +185,21 @@ export async function kvGet(
  * messages and then an empty `204 EOB`; a prefix nobody has written answers `404` and nothing else.
  */
 export async function kvLast(
-  connection: NatsConnection,
+  client: NatsClient,
   bucket: string,
   filter: string,
   batch = 1_000,
 ): Promise<readonly KvRecord[]> {
   const subject = `$JS.API.DIRECT.GET.${kvStream(bucket)}`;
   const body = { multi_last: [kvSubject(bucket, filter)], batch };
-  const replies = await connection.requestMany(subject, encoder.encode(JSON.stringify(body)), {
+  const replies = await client.requestMany(subject, encoder.encode(JSON.stringify(body)), {
     until: (message) => message.status === STATUS_EOB || message.status === STATUS_NOT_FOUND,
   });
   const records: KvRecord[] = [];
   for (const reply of replies) {
-    if (reply.status !== undefined) continue;
+    // A status on a batch reply is a marker, never a value — the terminator is filtered by `until`,
+    // and anything else the server slips in (a `408` heartbeat) carries no message to read.
+    if (reply.status !== 0) continue;
     const record = recordOf(reply, bucket);
     if (record) records.push(record);
   }
@@ -207,14 +208,14 @@ export async function kvLast(
 
 /** A KV write is a publish that waits for JetStream's ack — a lost put must not read as stored. */
 export async function kvWrite(
-  connection: NatsConnection,
+  client: NatsClient,
   bucket: string,
   key: string,
   value: string,
   headers: NatsHeaders,
 ): Promise<void> {
   const subject = kvSubject(bucket, key);
-  const reply = await connection.request(subject, encoder.encode(value), { headers });
+  const reply = await client.request(subject, encoder.encode(value), { headers });
   const body = asObject(reply, subject);
   const error = errorOf(body);
   if (error !== undefined) {

package/src/nats-kv.ts

@@ -4,7 +4,7 @@
 
 import type { Clock } from '@ultimat3/core';
 import type { TransportSet, TransportSetEntry } from './fanout';
-import type { NatsConnection } from './nats-connection';
+import type { NatsClient } from './nats-client';
 import { kvGet, kvLast, kvWrite } from './nats-jetstream';
 
 /** Per-message TTL is expressed in whole seconds, and must never expire before the logical one. */
@@ -51,8 +51,8 @@ const ttlHeader = (ttlMs: number): ReadonlyMap<string, string> =>
   new Map([['Nats-TTL', String(Math.ceil(ttlMs / 1_000) + TTL_GRACE_SECONDS)]]);
 
 export interface NatsKvSetOptions {
-  /** The live connection. Awaited per call, because the transport replaces it on a reconnect. */
-  readonly connection: () => Promise<NatsConnection>;
+  /** The live client. Awaited per call: the transport dials lazily and re-dials after a loss. */
+  readonly client: () => Promise<NatsClient>;
   readonly bucket: string;
   /** Only the fallback when a reply carries no server timestamp; the server's clock is the truth. */
   readonly clock: Clock;
@@ -69,7 +69,7 @@ export class NatsKvSet implements TransportSet {
   async put(key: string, member: string, value: string, ttlMs: number): Promise<void> {
     const stored: StoredValue = { v: value, t: ttlMs };
     await kvWrite(
-      await this.#options.connection(),
+      await this.#options.client(),
       this.#options.bucket,
       this.#key(key, member),
       JSON.stringify(stored),
@@ -80,7 +80,7 @@ export class NatsKvSet implements TransportSet {
   /** `false` when the member had already expired: the caller must re-`put`, which is a re-join. */
   async touch(key: string, member: string, ttlMs: number): Promise<boolean> {
     const record = await kvGet(
-      await this.#options.connection(),
+      await this.#options.client(),
       this.#options.bucket,
       this.#key(key, member),
     );
@@ -98,7 +98,7 @@ export class NatsKvSet implements TransportSet {
    */
   async drop(key: string, member: string): Promise<void> {
     await kvWrite(
-      await this.#options.connection(),
+      await this.#options.client(),
       this.#options.bucket,
       this.#key(key, member),
       '',
@@ -111,7 +111,7 @@ export class NatsKvSet implements TransportSet {
 
   async entries(key: string): Promise<readonly TransportSetEntry[]> {
     const records = await kvLast(
-      await this.#options.connection(),
+      await this.#options.client(),
       this.#options.bucket,
       `${encodeToken(key)}.*`,
     );

package/src/nats-lib-client.ts

@@ -0,0 +1,210 @@
+// Single responsibility: the one adapter from the `nats` client to this package's port. It is the
+// only file in the repo that imports `nats` — everything else speaks `NatsClient`, so the wire, the
+// reconnect and the TLS upgrade are the library's and stay replaceable.
+//
+// WHERE FAILURES ARE TRANSLATED, and it is deliberately not all here. This file coded the calls
+// that have no synchronous caller frame to catch them: `request`, `requestMany`, the dial, and the
+// background `#watch` that is the only place a lost connection is announced. `publish` and
+// `subscribe` are synchronous and stay raw — `NatsTransport.#translating` codes them, because
+// `NatsTransportOptions.connect` is a PUBLIC injection seam: translating in this class would cover
+// the one client the repo ships and leave every app-supplied one uncovered, and translating in both
+// places would be two answers to one event. `unsubscribe()` is wrapped nowhere on purpose — it is
+// synchronous, returns `void`, and its throw reaches the caller rather than being swallowed.
+//
+// This header said "every failure leaves here as an `UltimateError`" until 2026-08, which a reader
+// took as a guarantee it never was.
+
+import { connect, Events, headers, Match, type Msg, type MsgHdrs, type NatsConnection } from 'nats';
+import { TransportUnavailableError } from './errors';
+import {
+  DEFAULT_REQUEST_TIMEOUT_MS,
+  type NatsClient,
+  type NatsClientOptions,
+  type NatsHeaders,
+  type NatsMessage,
+  type NatsMessageHandler,
+  type NatsRequestManyOptions,
+  type NatsRequestOptions,
+  type NatsSubscription,
+  type NatsTarget,
+  parseNatsUrl,
+} from './nats-client';
+
+/** A message that has already left the library: the port's shape, read lazily off the headers. */
+const messageOf = (message: Msg): NatsMessage => ({
+  subject: message.subject,
+  payload: message.data,
+  status: message.headers?.code ?? 0,
+  // `MsgHdrs.get` answers '' for a header the server never sent, and every header this package
+  // reads is meaningless when empty — so one absent answer, rather than two.
+  header: (name: string): string | undefined => {
+    const value = message.headers?.get(name, Match.IgnoreCase);
+    return value === undefined || value === '' ? undefined : value;
+  },
+});
+
+const headersOf = (map: NatsHeaders | undefined): MsgHdrs | undefined => {
+  if (map === undefined || map.size === 0) return undefined;
+  const built = headers();
+  for (const [name, value] of map) built.set(name, value);
+  return built;
+};
+
+const unavailable = (target: NatsTarget, reason: string): TransportUnavailableError =>
+  new TransportUnavailableError({
+    transport: 'nats',
+    // The URL is never echoed back — it carries the credentials.
+    reason: `${target.host}:${target.port} — ${reason}`,
+  });
+
+const describe = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+class LibNatsClient implements NatsClient {
+  readonly #connection: NatsConnection;
+  readonly #target: NatsTarget;
+  readonly #timeoutMs: number;
+  readonly #report: (error: unknown) => void;
+  #connected = true;
+
+  constructor(connection: NatsConnection, target: NatsTarget, options: NatsClientOptions) {
+    this.#connection = connection;
+    this.#target = target;
+    this.#timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    this.#report = options.onError ?? ((): void => undefined);
+    void this.#watch(options);
+  }
+
+  get version(): string {
+    return this.#connection.info?.version ?? '';
+  }
+
+  get connected(): boolean {
+    return this.#connected && !this.#connection.isClosed();
+  }
+
+  publish(subject: string, payload: Uint8Array): void {
+    this.#connection.publish(subject, payload);
+  }
+
+  subscribe(subject: string, handler: NatsMessageHandler): NatsSubscription {
+    const subscription = this.#connection.subscribe(subject, {
+      // A callback rather than the async iterator: the iterator queues, and a `sync` node that
+      // falls behind on one subject must drop nothing silently into a growing buffer.
+      callback: (error, message) => {
+        // A subscription's own failure — a permissions violation on the subject is the common one —
+        // arrives here and nowhere else. Dropping it is a node delivering nothing, silently.
+        if (error !== null) this.#report(unavailable(this.#target, `${subject}: ${error.message}`));
+        else handler(messageOf(message));
+      },
+    });
+    return { unsubscribe: () => subscription.unsubscribe() };
+  }
+
+  async request(
+    subject: string,
+    payload: Uint8Array,
+    options: NatsRequestOptions = {},
+  ): Promise<NatsMessage> {
+    const built = headersOf(options.headers);
+    try {
+      const reply = await this.#connection.request(subject, payload, {
+        timeout: this.#timeoutMs,
+        ...(built === undefined ? {} : { headers: built }),
+      });
+      return messageOf(reply);
+    } catch (error) {
+      throw unavailable(this.#target, `${subject} did not answer: ${describe(error)}`);
+    }
+  }
+
+  /**
+   * A batch read ends on a message the caller recognises — a `204` end-of-batch or a `404` for a
+   * prefix nobody has written. Breaking the loop is what releases the library's inbox subscription,
+   * so the terminator is never collected and never awaited past.
+   */
+  async requestMany(
+    subject: string,
+    payload: Uint8Array,
+    options: NatsRequestManyOptions,
+  ): Promise<readonly NatsMessage[]> {
+    const collected: NatsMessage[] = [];
+    try {
+      const replies = await this.#connection.requestMany(subject, payload, {
+        maxWait: this.#timeoutMs,
+      });
+      for await (const reply of replies) {
+        const message = messageOf(reply);
+        if (options.until(message)) break;
+        collected.push(message);
+      }
+    } catch (error) {
+      throw unavailable(this.#target, `${subject} did not answer: ${describe(error)}`);
+    }
+    return collected;
+  }
+
+  async close(): Promise<void> {
+    this.#connected = false;
+    await this.#connection.close();
+  }
+
+  /**
+   * The library's own status stream is the only place a background loss is announced. Nothing
+   * awaits it, so it can neither throw nor end the process: a drop reports and flips `connected`,
+   * a reconnect flips it back and tells the transport its cluster may be a new one.
+   */
+  async #watch(options: NatsClientOptions): Promise<void> {
+    const report = options.onError ?? ((): void => undefined);
+    try {
+      for await (const status of this.#connection.status()) {
+        if (status.type === Events.Disconnect) {
+          this.#connected = false;
+          report(unavailable(this.#target, 'the connection dropped'));
+        } else if (status.type === Events.Reconnect) {
+          this.#connected = true;
+          options.onReconnect?.();
+        } else if (status.type === Events.Error) {
+          report(unavailable(this.#target, `the server reported ${String(status.data)}`));
+        }
+      }
+      // The iterator ends when the connection is done: either `close()` or a reconnect budget spent.
+      this.#connected = false;
+      const failure = await this.#connection.closed();
+      if (failure !== undefined) report(unavailable(this.#target, describe(failure)));
+    } catch (error) {
+      this.#connected = false;
+      report(unavailable(this.#target, describe(error)));
+    }
+  }
+}
+
+/**
+ * The production `NatsConnect`. The first dial retries on the same budget as a later loss
+ * (`waitOnFirstConnect`), so a `sync` container that raced the bus into readiness recovers on its
+ * own — and a budget that runs out rejects here rather than leaving a half-live connection behind.
+ */
+export const openNatsClient = async (options: NatsClientOptions): Promise<NatsClient> => {
+  const target = parseNatsUrl(options.url);
+  try {
+    const connection = await connect({
+      servers: [`${target.host}:${target.port}`],
+      name: options.name ?? 'ultimate',
+      waitOnFirstConnect: true,
+      ...(options.maxReconnectAttempts === undefined
+        ? {}
+        : { maxReconnectAttempts: options.maxReconnectAttempts }),
+      ...(options.reconnectDelay === undefined
+        ? {}
+        : { reconnectDelayHandler: options.reconnectDelay }),
+      // The scheme is the only thing that can demand TLS before the server's INFO is read.
+      ...(target.tls ? { tls: {} } : {}),
+      ...(target.user === undefined ? {} : { user: target.user }),
+      ...(target.pass === undefined ? {} : { pass: target.pass }),
+      ...(target.token === undefined ? {} : { token: target.token }),
+    });
+    return new LibNatsClient(connection, target, options);
+  } catch (error) {
+    throw unavailable(target, describe(error));
+  }
+};