@ultimat3/realtime 1.2.0 → 2.0.0

package/src/nats-fake.ts

@@ -1,431 +1,476 @@
-// Single responsibility: an in-memory nats-server — core routing plus the slice of JetStream KV the
-// bus uses. Tests run under a sealed network, so this is the only way to prove multi-node fanout
-// without a broker; the live test against a real server is what proves this fake is not lying.
+// Single responsibility: an in-memory nats-server — core subject routing plus the slice of
+// JetStream KV the bus uses — implementing `NatsClient` directly. The `nats` library owns the wire
+// now, so the fake emulates the server one level above it: tests get a multi-node bus under a
+// sealed network, and the live test against a real server is what proves this fake is not lying.
 
 import { type Clock, systemClock } from '@ultimat3/core';
+import { TransportUnavailableError } from './errors';
 import { subjectMatches } from './fanout';
-import type { NatsHeaders } from './nats-protocol';
-import { parseHeaders } from './nats-protocol';
-import type { NatsStream } from './nats-socket';
+import type {
+  NatsClient,
+  NatsClientOptions,
+  NatsConnect,
+  NatsHeaders,
+  NatsMessage,
+  NatsMessageHandler,
+  NatsRequestManyOptions,
+  NatsRequestOptions,
+  NatsSubscription,
+} from './nats-client';
 
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
+const EMPTY = new Uint8Array(0);
+
+const DEFAULT_VERSION = '2.11.17';
+const DEFAULT_URL = 'nats://fake.test:4222';
+const DEFAULT_BATCH = 1_000;
+
+const STATUS_OK = 0;
+const STATUS_EOB = 204;
+const STATUS_NOT_FOUND = 404;
+
+const STREAM_INFO = '$JS.API.STREAM.INFO.';
+const STREAM_CREATE = '$JS.API.STREAM.CREATE.';
+const DIRECT_GET = '$JS.API.DIRECT.GET.';
+const KV_PREFIX = '$KV.';
+
+const NS_PER_MS = 1_000_000;
+const MS_PER_SECOND = 1_000;
 
 export interface FakeNatsOptions {
+  /** What `NatsClient.version` answers — the string `assertServerVersion` reads. */
   readonly version?: string;
-  readonly maxPayload?: number;
-  readonly tlsRequired?: boolean;
+  /** TTL and `max_age` are judged by this clock, so a test advances time instead of sleeping. */
   readonly clock?: Clock;
 }
 
 interface StoredMessage {
   readonly subject: string;
-  readonly payload: string;
+  readonly payload: Uint8Array;
+  /** The write's own headers, keys lowercased — a later read hands `KV-Operation` back from here. */
   readonly headers: ReadonlyMap<string, string>;
   readonly seq: number;
   readonly writtenAt: number;
   readonly expiresAt: number | undefined;
 }
 
-type ClientCommand =
-  | { readonly kind: 'connect' | 'ping' | 'pong' }
-  | { readonly kind: 'sub'; readonly subject: string; readonly sid: string }
-  | { readonly kind: 'unsub'; readonly sid: string }
-  | {
-      readonly kind: 'pub';
-      readonly subject: string;
-      readonly replyTo: string | undefined;
-      readonly headers: ReadonlyMap<string, string>;
-      readonly payload: string;
-    };
+interface StreamRecord {
+  readonly name: string;
+  readonly config: Record<string, unknown>;
+  readonly subjects: readonly string[];
+  /** `max_msgs_per_subject: 1` — a write replaces the subject's current message rather than logging. */
+  readonly history1: boolean;
+  /** `max_age`, as milliseconds: the whole-stream ceiling over every per-message TTL. */
+  readonly maxAgeMs: number | undefined;
+}
 
-const crlf = (text: string): Uint8Array => encoder.encode(`${text}\r\n`);
+/** What a client is allowed to ask of the broker it came from. Nothing else crosses the seam. */
+interface BrokerPort {
+  readonly version: string;
+  up(): boolean;
+  publish(subject: string, payload: Uint8Array): void;
+  request(subject: string, payload: Uint8Array, headers: NatsHeaders | undefined): NatsMessage;
+  requestMany(
+    subject: string,
+    payload: Uint8Array,
+    until: (message: NatsMessage) => boolean,
+  ): readonly NatsMessage[];
+  release(client: FakeNatsClient): void;
+}
 
-const headerBlock = (headers: NatsHeaders, status?: string): string => {
-  let block = `NATS/1.0${status === undefined ? '' : ` ${status}`}\r\n`;
-  for (const [key, value] of headers) block += `${key}: ${value}\r\n`;
-  return `${block}\r\n`;
+const lowercased = (headers: NatsHeaders | undefined): ReadonlyMap<string, string> => {
+  const map = new Map<string, string>();
+  for (const [name, value] of headers ?? []) map.set(name.toLowerCase(), value);
+  return map;
 };
 
-const msgFrame = (
+/** `headers` must already be lowercase-keyed: `header()` is case-insensitive by lowering the ask. */
+const message = (
   subject: string,
-  sid: string,
-  replyTo: string | undefined,
-  payload: string,
-  headers: NatsHeaders | undefined,
-  status?: string,
-): Uint8Array => {
-  const body = encoder.encode(payload);
-  const reply = replyTo === undefined ? '' : ` ${replyTo}`;
-  if (headers === undefined && status === undefined) {
-    const control = `MSG ${subject} ${sid}${reply} ${body.length}\r\n`;
-    return encoder.encode(`${control}${payload}\r\n`);
-  }
-  const block = headerBlock(headers ?? new Map(), status);
-  const blockBytes = encoder.encode(block).length;
-  const control = `HMSG ${subject} ${sid}${reply} ${blockBytes} ${blockBytes + body.length}\r\n`;
-  return encoder.encode(`${control}${block}${payload}\r\n`);
+  payload: Uint8Array,
+  status: number,
+  headers: ReadonlyMap<string, string>,
+): NatsMessage => ({
+  subject,
+  payload,
+  status,
+  header: (name: string) => headers.get(name.toLowerCase()),
+});
+
+const json = (subject: string, body: unknown): NatsMessage =>
+  message(subject, encoder.encode(JSON.stringify(body)), STATUS_OK, new Map());
+
+const unavailable = (reason: string): TransportUnavailableError =>
+  new TransportUnavailableError({ transport: 'nats', reason });
+
+/** A request body is always json here; anything unreadable is treated as `{}`, as the server does. */
+const bodyOf = (payload: Uint8Array): Record<string, unknown> => {
+  const text = decoder.decode(payload);
+  if (text === '') return {};
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return {};
+    return parsed as Record<string, unknown>;
+  } catch {
+    return {};
+  }
 };
 
-const CR = 0x0d;
-const LF = 0x0a;
+const stringList = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];
+
+const numberOr = (value: unknown, fallback: number): number =>
+  typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+
+/** One simulated node's connection. Not exported: callers only ever see it as a `NatsClient`. */
+class FakeNatsClient implements NatsClient {
+  readonly #broker: BrokerPort;
+  readonly #options: NatsClientOptions;
+  readonly #subscriptions = new Set<{
+    readonly pattern: string;
+    readonly handler: NatsMessageHandler;
+  }>();
+  #closed = false;
+  #dropped: boolean;
+
+  constructor(broker: BrokerPort, options: NatsClientOptions) {
+    this.#broker = broker;
+    this.#options = options;
+    this.#dropped = !broker.up();
+  }
 
-const concat = (left: Uint8Array, right: Uint8Array): Uint8Array => {
-  const merged = new Uint8Array(left.length + right.length);
-  merged.set(left);
-  merged.set(right, left.length);
-  return merged;
-};
+  get version(): string {
+    return this.#broker.version;
+  }
 
-/**
- * Chunks the client wrote, turned into whole commands. The mirror of `NatsProtocolParser`, and
- * buffered in bytes for the same reason it is: a control line counts bytes, a string counts UTF-16
- * code units, and any multi-byte character makes the two disagree — the payload is then sliced
- * short and every command behind it is misread. Decoding per chunk is the same bug twice over,
- * because a character split across two writes decodes to U+FFFD.
- */
-class ClientCommandReader {
-  #buffer: Uint8Array = new Uint8Array(0);
-
-  push(chunk: Uint8Array): void {
-    this.#buffer = this.#buffer.length === 0 ? chunk : concat(this.#buffer, chunk);
-  }
-
-  next(): ClientCommand | undefined {
-    const lineEnd = this.#lineEnd();
-    if (lineEnd < 0) return undefined;
-    const line = decoder.decode(this.#buffer.subarray(0, lineEnd));
-    const args = line.split(/[ \t]+/).filter((part) => part.length > 0);
-    const verb = (args[0] ?? '').toUpperCase();
-    if (verb === 'PUB' || verb === 'HPUB') return this.#takePub(lineEnd, args, verb === 'HPUB');
-    this.#buffer = this.#buffer.subarray(lineEnd + 2);
-    switch (verb) {
-      case 'CONNECT':
-        return { kind: 'connect' };
-      case 'PING':
-        return { kind: 'ping' };
-      case 'PONG':
-        return { kind: 'pong' };
-      case 'SUB':
-        // `SUB <subject> [queue] <sid>` — the sid is always last.
-        return { kind: 'sub', subject: args[1] ?? '', sid: args[args.length - 1] ?? '' };
-      case 'UNSUB':
-        return { kind: 'unsub', sid: args[1] ?? '' };
-      default:
-        return undefined;
-    }
+  get connected(): boolean {
+    return !this.#closed && !this.#dropped;
   }
 
-  /** Only the head of the buffer is ever a control line: a payload is consumed whole with it. */
-  #lineEnd(): number {
-    for (let index = 0; index + 1 < this.#buffer.length; index += 1) {
-      if (this.#buffer[index] === CR && this.#buffer[index + 1] === LF) return index;
-    }
-    return -1;
-  }
-
-  #takePub(lineEnd: number, args: readonly string[], headered: boolean): ClientCommand | undefined {
-    const counts = headered ? 2 : 1;
-    const hasReply = args.length === 2 + counts + 1;
-    const total = Number(args[args.length - 1] ?? '0');
-    const headerBytes = headered ? Number(args[args.length - 2] ?? '0') : 0;
-    const start = lineEnd + 2;
-    if (this.#buffer.length < start + total + 2) return undefined;
-    const body = this.#buffer.subarray(start, start + total);
-    this.#buffer = this.#buffer.subarray(start + total + 2);
-    const parsed = headered
-      ? parseHeaders(body.subarray(0, headerBytes))
-      : { headers: new Map<string, string>() };
+  publish(subject: string, payload: Uint8Array): void {
+    this.#assertOpen();
+    // A publish into a dropped connection is lost, exactly as a real disconnect loses it.
+    if (this.#dropped) return;
+    this.#broker.publish(subject, payload);
+  }
+
+  subscribe(subject: string, handler: NatsMessageHandler): NatsSubscription {
+    this.#assertOpen();
+    // The subscription is held across a drop: re-establishing it is what the library is bought for.
+    const entry = { pattern: subject, handler };
+    this.#subscriptions.add(entry);
     return {
-      kind: 'pub',
-      subject: args[1] ?? '',
-      replyTo: hasReply ? args[2] : undefined,
-      headers: parsed.headers,
-      payload: decoder.decode(body.subarray(headerBytes)),
+      unsubscribe: () => {
+        this.#subscriptions.delete(entry);
+      },
     };
   }
-}
 
-interface FakeClient {
-  readonly reader: ClientCommandReader;
-  readonly subscriptions: Map<string, string>;
-  readonly push: (bytes: Uint8Array) => void;
-  /** EOF for a reader parked on `read()` — a dropped client must never leave one hanging. */
-  readonly end: () => void;
-  open: boolean;
+  async request(
+    subject: string,
+    payload: Uint8Array,
+    options?: NatsRequestOptions,
+  ): Promise<NatsMessage> {
+    this.#assertOpen();
+    this.#assertLive();
+    return this.#broker.request(subject, payload, options?.headers);
+  }
+
+  async requestMany(
+    subject: string,
+    payload: Uint8Array,
+    options: NatsRequestManyOptions,
+  ): Promise<readonly NatsMessage[]> {
+    this.#assertOpen();
+    this.#assertLive();
+    return this.#broker.requestMany(subject, payload, options.until);
+  }
+
+  async close(): Promise<void> {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#subscriptions.clear();
+    this.#broker.release(this);
+  }
+
+  deliver(delivered: NatsMessage): void {
+    if (!this.connected) return;
+    for (const entry of [...this.#subscriptions]) {
+      if (!subjectMatches(entry.pattern, delivered.subject)) continue;
+      try {
+        entry.handler(delivered);
+      } catch (error) {
+        // A subscriber that throws is the subscriber's problem, never the publisher's.
+        this.#options.onError?.(error);
+      }
+    }
+  }
+
+  markDropped(error: unknown): void {
+    if (this.#closed || this.#dropped) return;
+    this.#dropped = true;
+    this.#options.onError?.(error);
+  }
+
+  markRestored(): void {
+    if (this.#closed || !this.#dropped) return;
+    this.#dropped = false;
+    this.#options.onReconnect?.();
+  }
+
+  get closed(): boolean {
+    return this.#closed;
+  }
+
+  #assertOpen(): void {
+    if (this.#closed) throw unavailable('the client is closed');
+  }
+
+  /** A request has an answer to wait for, so a dropped connection fails it rather than losing it. */
+  #assertLive(): void {
+    if (this.#dropped) throw unavailable('the connection dropped');
+  }
 }
 
-/** An in-memory nats-server. `connect()` hands back a `NatsStream` wired straight to it. */
-export class FakeNatsServer {
-  readonly #clients = new Set<FakeClient>();
-  readonly #streams = new Map<string, Record<string, unknown>>();
-  readonly #messages = new Map<string, StoredMessage>();
-  readonly #options: FakeNatsOptions;
+/** An in-memory nats-server: core subject routing plus the slice of JetStream KV the bus uses. */
+export class FakeNatsBroker {
   readonly #clock: Clock;
+  readonly #version: string;
+  readonly #clients = new Set<FakeNatsClient>();
+  readonly #streams = new Map<string, StreamRecord>();
+  readonly #failures: { readonly needle: string; remaining: number }[] = [];
+  #messages: StoredMessage[] = [];
   #seq = 0;
-  #creates = 0;
+  #up = true;
+
+  /** Refuse the next dial: `fakeNatsConnect` rejects while this is true. */
+  offline = false;
 
   constructor(options: FakeNatsOptions = {}) {
-    this.#options = options;
     this.#clock = options.clock ?? systemClock;
+    this.#version = options.version ?? DEFAULT_VERSION;
+  }
+
+  /** One client per simulated node. Every client on one broker sees every other's publishes. */
+  client(options: NatsClientOptions = { url: DEFAULT_URL }): NatsClient {
+    const client = new FakeNatsClient(this.#port(), options);
+    this.#clients.add(client);
+    return client;
   }
 
-  get connections(): number {
-    return [...this.#clients].filter((client) => client.open).length;
+  get clients(): readonly NatsClient[] {
+    return [...this.#clients];
+  }
+
+  /** Streams currently declared — so a test asserts bucket creation rather than inferring it. */
+  get streams(): readonly string[] {
+    return [...this.#streams.keys()];
+  }
+
+  /** The config body a create declared, verbatim — a bucket's history, direct reads, TTL, max_age. */
+  streamConfig(stream: string): Record<string, unknown> | undefined {
+    return this.#streams.get(stream)?.config;
   }
 
   /**
-   * STREAM.CREATE calls answered. A bucket that already exists must be left alone, and nothing
-   * else the client can observe distinguishes "created again" from "found and kept".
+   * The node came back with nothing in it: every stream and every message is gone, and the clients
+   * are untouched. That is the state a bucket-asserting reconnect has to survive.
    */
-  get streamCreates(): number {
-    return this.#creates;
+  forget(): void {
+    this.#streams.clear();
+    this.#messages = [];
+    this.#seq = 0;
   }
 
-  /** The config a stream was created with, so a bucket test asserts it rather than infers it. */
-  streamConfig(stream: string): Readonly<Record<string, unknown>> | undefined {
-    return this.#streams.get(stream);
+  /** The connection dropped underneath every client. */
+  drop(reason = 'the bus went away'): void {
+    this.#up = false;
+    for (const client of this.#clients) client.markDropped(unavailable(reason));
   }
 
-  /** Every current KV value, tombstones excluded — the assertion surface for a presence test. */
-  get stored(): ReadonlyMap<string, string> {
-    const live = new Map<string, string>();
-    for (const message of this.#live()) live.set(message.subject, message.payload);
-    return live;
+  /** The library got it back. */
+  restore(): void {
+    this.#up = true;
+    for (const client of this.#clients) client.markRestored();
   }
 
-  /** A bus restart: every connection drops, and the client is expected to re-establish its subs. */
-  dropAll(): void {
-    for (const client of [...this.#clients]) this.#drop(client);
+  /** The next `count` requests whose subject contains `needle` fail as an unreachable bus would. */
+  fail(needle: string, count = 1): void {
+    this.#failures.push({ needle, remaining: count });
   }
 
-  connect(): NatsStream {
-    const queue: Uint8Array[] = [];
-    let waiting: ((chunk: Uint8Array | undefined) => void) | undefined;
-    const client: FakeClient = {
-      reader: new ClientCommandReader(),
-      subscriptions: new Map(),
-      open: true,
-      push: (bytes) => {
-        const waiter = waiting;
-        waiting = undefined;
-        if (waiter) waiter(bytes);
-        else queue.push(bytes);
-      },
-      end: () => {
-        const waiter = waiting;
-        waiting = undefined;
-        waiter?.(undefined);
-      },
-    };
-    this.#clients.add(client);
-    client.push(crlf(`INFO ${JSON.stringify(this.#info())}`));
+  #port(): BrokerPort {
     return {
-      read: () =>
-        new Promise((resolve) => {
-          const next = queue.shift();
-          if (next !== undefined) resolve(next);
-          else if (!client.open) resolve(undefined);
-          else waiting = resolve;
-        }),
-      write: async (bytes) => {
-        if (!client.open) return;
-        client.reader.push(bytes);
-        for (;;) {
-          const command = client.reader.next();
-          if (command === undefined) return;
-          this.#handle(client, command);
-        }
+      version: this.#version,
+      up: () => this.#up,
+      publish: (subject, payload) => this.#publish(subject, payload),
+      request: (subject, payload, headers) => this.#request(subject, payload, headers),
+      requestMany: (subject, payload, until) => this.#requestMany(subject, payload, until),
+      release: (client) => {
+        this.#clients.delete(client);
       },
-      upgradeTls: () => undefined,
-      close: () => this.#drop(client),
-    };
-  }
-
-  #info(): Record<string, unknown> {
-    return {
-      server_id: 'FAKE',
-      version: this.#options.version ?? '2.11.0',
-      max_payload: this.#options.maxPayload ?? 1_048_576,
-      headers: true,
-      proto: 1,
-      ...(this.#options.tlsRequired === true ? { tls_required: true } : {}),
     };
   }
 
-  #drop(client: FakeClient): void {
-    if (!client.open) return;
-    client.open = false;
-    client.subscriptions.clear();
-    this.#clients.delete(client);
-    client.end();
-  }
-
-  #handle(client: FakeClient, command: ClientCommand): void {
-    switch (command.kind) {
-      case 'connect':
-      case 'pong':
-        return;
-      case 'ping':
-        client.push(crlf('PONG'));
-        return;
-      case 'sub':
-        client.subscriptions.set(command.sid, command.subject);
-        return;
-      case 'unsub':
-        client.subscriptions.delete(command.sid);
-        return;
-      case 'pub':
-        this.#publish(command);
+  #publish(subject: string, payload: Uint8Array): void {
+    const delivered = message(subject, payload, STATUS_OK, new Map());
+    for (const client of [...this.#clients]) {
+      if (client.closed) continue;
+      client.deliver(delivered);
     }
   }
 
-  #publish(command: Extract<ClientCommand, { kind: 'pub' }>): void {
-    if (command.subject.startsWith('$JS.API.')) {
-      this.#jetStream(command);
-      return;
-    }
-    if (command.subject.startsWith('$KV.')) {
-      this.#store(command);
-      return;
-    }
-    this.#route(command.subject, command.payload, command.replyTo, undefined);
+  #request(subject: string, payload: Uint8Array, headers: NatsHeaders | undefined): NatsMessage {
+    this.#maybeFail(subject);
+    if (subject.startsWith(STREAM_INFO)) return this.#streamInfo(subject);
+    if (subject.startsWith(STREAM_CREATE)) return this.#streamCreate(subject, payload);
+    if (subject.startsWith(DIRECT_GET)) return this.#directGet(subject);
+    if (subject.startsWith(KV_PREFIX)) return this.#store(subject, payload, headers);
+    throw unavailable(`no responders for ${subject}`);
   }
 
-  #route(
+  #requestMany(
     subject: string,
-    payload: string,
-    replyTo: string | undefined,
-    headers: NatsHeaders | undefined,
-    status?: string,
-  ): void {
-    for (const client of this.#clients) {
-      if (!client.open) continue;
-      for (const [sid, pattern] of client.subscriptions) {
-        if (!subjectMatches(pattern, subject)) continue;
-        client.push(msgFrame(subject, sid, replyTo, payload, headers, status));
-      }
+    payload: Uint8Array,
+    until: (candidate: NatsMessage) => boolean,
+  ): readonly NatsMessage[] {
+    this.#maybeFail(subject);
+    const body = bodyOf(payload);
+    const filters = subject.startsWith(DIRECT_GET) ? stringList(body['multi_last']) : [];
+    if (filters.length === 0) throw unavailable(`no responders for ${subject}`);
+    const batch = numberOr(body['batch'], DEFAULT_BATCH);
+    const matched = this.#current()
+      .filter((stored) => filters.some((filter) => subjectMatches(filter, stored.subject)))
+      .slice(0, batch);
+    const replies = matched.map((stored) => this.#replyFor(stored));
+    // A batch always terminates: `204 EOB` behind results, `404` when the filter matched nothing.
+    replies.push(
+      message(subject, EMPTY, matched.length > 0 ? STATUS_EOB : STATUS_NOT_FOUND, new Map()),
+    );
+    const collected: NatsMessage[] = [];
+    for (const reply of replies) {
+      if (until(reply)) break;
+      collected.push(reply);
     }
+    return collected;
   }
 
-  #reply(command: Extract<ClientCommand, { kind: 'pub' }>, body: unknown): void {
-    if (command.replyTo === undefined) return;
-    this.#route(command.replyTo, JSON.stringify(body), undefined, undefined);
+  #maybeFail(subject: string): void {
+    const failure = this.#failures.find((entry) => subject.includes(entry.needle));
+    if (failure === undefined) return;
+    failure.remaining -= 1;
+    if (failure.remaining <= 0) this.#failures.splice(this.#failures.indexOf(failure), 1);
+    throw unavailable(`${subject} was refused`);
   }
 
-  #store(command: Extract<ClientCommand, { kind: 'pub' }>): void {
-    this.#seq += 1;
-    const ttl = Number(command.headers.get('nats-ttl') ?? '0');
-    const now = this.#clock.now().getTime();
-    this.#messages.set(command.subject, {
-      subject: command.subject,
-      payload: command.payload,
-      headers: command.headers,
-      seq: this.#seq,
-      writtenAt: now,
-      expiresAt: ttl > 0 ? now + ttl * 1_000 : undefined,
-    });
-    this.#reply(command, { stream: 'KV', seq: this.#seq });
+  #streamInfo(subject: string): NatsMessage {
+    const name = subject.slice(STREAM_INFO.length);
+    const stream = this.#streams.get(name);
+    return json(
+      subject,
+      stream === undefined
+        ? { error: { code: STATUS_NOT_FOUND, err_code: 10_059, description: 'stream not found' } }
+        : { config: { name } },
+    );
   }
 
-  #live(): readonly StoredMessage[] {
-    const now = this.#clock.now().getTime();
-    const live: StoredMessage[] = [];
-    for (const message of this.#messages.values()) {
-      if (message.expiresAt !== undefined && message.expiresAt <= now) {
-        this.#messages.delete(message.subject);
-        continue;
-      }
-      if (message.headers.get('kv-operation') === undefined) live.push(message);
+  #streamCreate(subject: string, payload: Uint8Array): NatsMessage {
+    const name = subject.slice(STREAM_CREATE.length);
+    const config = bodyOf(payload);
+    const subjects = stringList(config['subjects']);
+    const existing = this.#streams.get(name);
+    // Same name, different subjects is the one create a server refuses outright.
+    if (existing !== undefined && existing.subjects.join(' ') !== subjects.join(' ')) {
+      return json(subject, {
+        error: { code: 400, err_code: 10_065, description: 'stream name already in use' },
+      });
     }
-    return live;
-  }
-
-  #headersFor(message: StoredMessage, extra: readonly (readonly [string, string])[]): NatsHeaders {
-    return new Map<string, string>([
-      ['Nats-Stream', 'KV'],
-      ['Nats-Subject', message.subject],
-      ['Nats-Sequence', String(message.seq)],
-      ['Nats-Time-Stamp', new Date(message.writtenAt).toISOString()],
-      ...(message.headers.get('kv-operation') === undefined
-        ? []
-        : ([['KV-Operation', message.headers.get('kv-operation') ?? '']] as const)),
-      ...extra,
-    ]);
+    const maxAge = numberOr(config['max_age'], 0);
+    this.#streams.set(name, {
+      name,
+      config,
+      subjects,
+      history1: config['max_msgs_per_subject'] === 1,
+      maxAgeMs: maxAge > 0 ? maxAge / NS_PER_MS : undefined,
+    });
+    return json(subject, { config: { name } });
   }
 
-  #jetStream(command: Extract<ClientCommand, { kind: 'pub' }>): void {
-    const subject = command.subject;
-    if (subject.startsWith('$JS.API.STREAM.INFO.')) {
-      const name = subject.slice('$JS.API.STREAM.INFO.'.length);
-      const config = this.#streams.get(name);
-      this.#reply(
-        command,
-        config === undefined
-          ? { error: { code: 404, err_code: 10_059, description: 'stream not found' } }
-          : { config },
-      );
-      return;
-    }
-    if (subject.startsWith('$JS.API.STREAM.CREATE.')) {
-      const name = subject.slice('$JS.API.STREAM.CREATE.'.length);
-      const config: unknown = JSON.parse(command.payload || '{}');
-      this.#creates += 1;
-      this.#streams.set(name, config as Record<string, unknown>);
-      this.#reply(command, { config });
-      return;
-    }
-    if (subject.startsWith('$JS.API.DIRECT.GET.')) {
-      this.#directGet(command, subject.slice('$JS.API.DIRECT.GET.'.length));
-      return;
+  /** A KV write: a publish that waits for JetStream's ack, so an unstored put never reads as one. */
+  #store(subject: string, payload: Uint8Array, headers: NatsHeaders | undefined): NatsMessage {
+    const stream = this.#streamFor(subject);
+    if (stream === undefined) {
+      return json(subject, { error: { code: 503, description: 'no responders' } });
     }
-    this.#reply(command, {
-      error: { code: 503, err_code: 0, description: `no responder for ${subject}` },
+    const written = lowercased(headers);
+    const now = this.#clock.now().getTime();
+    const ttlSeconds = Number.parseInt(written.get('nats-ttl') ?? '', 10);
+    const perMessage =
+      Number.isNaN(ttlSeconds) || ttlSeconds <= 0 ? undefined : now + ttlSeconds * MS_PER_SECOND;
+    const ceiling = stream.maxAgeMs === undefined ? undefined : now + stream.maxAgeMs;
+    const limits = [perMessage, ceiling].filter((at): at is number => at !== undefined);
+    this.#seq += 1;
+    if (stream.history1) this.#messages = this.#messages.filter((m) => m.subject !== subject);
+    this.#messages.push({
+      subject,
+      payload,
+      headers: written,
+      seq: this.#seq,
+      writtenAt: now,
+      expiresAt: limits.length === 0 ? undefined : Math.min(...limits),
     });
+    return json(subject, { stream: stream.name, seq: this.#seq });
   }
 
-  /** `…GET.<stream>.<subject>` is one key; `…GET.<stream>` with a `multi_last` body is a batch. */
-  #directGet(command: Extract<ClientCommand, { kind: 'pub' }>, tail: string): void {
-    const reply = command.replyTo;
-    if (reply === undefined) return;
+  /** `…GET.<stream>.<subject>` is one exact key; the batch form goes through `requestMany`. */
+  #directGet(subject: string): NatsMessage {
+    const tail = subject.slice(DIRECT_GET.length);
     const dot = tail.indexOf('.');
-    if (dot >= 0) {
-      const wanted = tail.slice(dot + 1);
-      const found = this.#live().find((message) => message.subject === wanted);
-      const stale = this.#messages.get(wanted);
-      if (found === undefined && stale === undefined) {
-        this.#route(reply, '', undefined, new Map(), '404 Message Not Found');
-        return;
-      }
-      const message = found ?? stale;
-      if (message === undefined) return;
-      this.#route(reply, message.payload, undefined, this.#headersFor(message, []));
-      return;
-    }
-    const body: unknown = JSON.parse(command.payload || '{}');
-    const filters = (body as { multi_last?: unknown }).multi_last;
-    const patterns = Array.isArray(filters) ? filters.filter((f) => typeof f === 'string') : [];
-    const matched = [...this.#messages.values()].filter(
-      (message) =>
-        patterns.some((pattern) => subjectMatches(pattern, message.subject)) &&
-        !(message.expiresAt !== undefined && message.expiresAt <= this.#clock.now().getTime()),
+    if (dot < 0) throw unavailable(`no responders for ${subject}`);
+    const wanted = tail.slice(dot + 1);
+    const found = this.#current().findLast((stored) => stored.subject === wanted);
+    if (found === undefined) return message(subject, EMPTY, STATUS_NOT_FOUND, new Map());
+    return this.#replyFor(found);
+  }
+
+  #replyFor(stored: StoredMessage): NatsMessage {
+    const operation = stored.headers.get('kv-operation');
+    const headers = new Map<string, string>([
+      ['nats-subject', stored.subject],
+      ['nats-sequence', String(stored.seq)],
+      // The server's own write time, in the one format `Date.parse` round-trips.
+      ['nats-time-stamp', new Date(stored.writtenAt).toISOString()],
+    ]);
+    if (operation !== undefined) headers.set('kv-operation', operation);
+    return message(stored.subject, stored.payload, STATUS_OK, headers);
+  }
+
+  /** Every unexpired message, in write order, one per subject: expiry is judged, never swept. */
+  #current(): readonly StoredMessage[] {
+    const now = this.#clock.now().getTime();
+    this.#messages = this.#messages.filter(
+      (stored) => stored.expiresAt === undefined || stored.expiresAt > now,
     );
-    if (matched.length === 0) {
-      this.#route(reply, '', undefined, new Map(), '404 No Results');
-      return;
+    const latest = new Map<string, StoredMessage>();
+    for (const stored of this.#messages) latest.set(stored.subject, stored);
+    return [...latest.values()];
+  }
+
+  #streamFor(subject: string): StreamRecord | undefined {
+    for (const stream of this.#streams.values()) {
+      if (stream.subjects.some((pattern) => subjectMatches(pattern, subject))) return stream;
     }
-    matched.forEach((message, index) => {
-      const pending = String(matched.length - index - 1);
-      this.#route(
-        reply,
-        message.payload,
-        undefined,
-        this.#headersFor(message, [['Nats-Num-Pending', pending]]),
-      );
-    });
-    this.#route(reply, '', undefined, new Map([['Nats-Num-Pending', '0']]), '204 EOB');
+    return undefined;
   }
 }
 
-/** One connected client stream against a fresh server — the one-liner most tests want. */
-export const fakeNatsStream = (server: FakeNatsServer): NatsStream => server.connect();
+/** The `NatsConnect` a test injects in place of the real client. */
+export const fakeNatsConnect =
+  (broker: FakeNatsBroker): NatsConnect =>
+  async (options: NatsClientOptions): Promise<NatsClient> => {
+    if (broker.offline) {
+      throw unavailable(`${options.url} refused the connection`);
+    }
+    return broker.client(options);
+  };