@ultimat3/realtime 1.0.0

package/src/nats-fake.ts

@@ -0,0 +1,431 @@
+// 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.
+
+import { type Clock, systemClock } from '@ultimat3/core';
+import { subjectMatches } from './fanout';
+import type { NatsHeaders } from './nats-protocol';
+import { parseHeaders } from './nats-protocol';
+import type { NatsStream } from './nats-socket';
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export interface FakeNatsOptions {
+  readonly version?: string;
+  readonly maxPayload?: number;
+  readonly tlsRequired?: boolean;
+  readonly clock?: Clock;
+}
+
+interface StoredMessage {
+  readonly subject: string;
+  readonly payload: string;
+  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;
+    };
+
+const crlf = (text: string): Uint8Array => encoder.encode(`${text}\r\n`);
+
+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 msgFrame = (
+  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`);
+};
+
+const CR = 0x0d;
+const LF = 0x0a;
+
+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;
+};
+
+/**
+ * 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;
+    }
+  }
+
+  /** 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>() };
+    return {
+      kind: 'pub',
+      subject: args[1] ?? '',
+      replyTo: hasReply ? args[2] : undefined,
+      headers: parsed.headers,
+      payload: decoder.decode(body.subarray(headerBytes)),
+    };
+  }
+}
+
+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;
+}
+
+/** 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;
+  readonly #clock: Clock;
+  #seq = 0;
+  #creates = 0;
+
+  constructor(options: FakeNatsOptions = {}) {
+    this.#options = options;
+    this.#clock = options.clock ?? systemClock;
+  }
+
+  get connections(): number {
+    return [...this.#clients].filter((client) => client.open).length;
+  }
+
+  /**
+   * 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".
+   */
+  get streamCreates(): number {
+    return this.#creates;
+  }
+
+  /** 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);
+  }
+
+  /** 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;
+  }
+
+  /** 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);
+  }
+
+  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())}`));
+    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);
+        }
+      },
+      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(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);
+  }
+
+  #route(
+    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));
+      }
+    }
+  }
+
+  #reply(command: Extract<ClientCommand, { kind: 'pub' }>, body: unknown): void {
+    if (command.replyTo === undefined) return;
+    this.#route(command.replyTo, JSON.stringify(body), undefined, undefined);
+  }
+
+  #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 });
+  }
+
+  #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);
+    }
+    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,
+    ]);
+  }
+
+  #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;
+    }
+    this.#reply(command, {
+      error: { code: 503, err_code: 0, description: `no responder for ${subject}` },
+    });
+  }
+
+  /** `…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;
+    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 (matched.length === 0) {
+      this.#route(reply, '', undefined, new Map(), '404 No Results');
+      return;
+    }
+    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');
+  }
+}
+
+/** One connected client stream against a fresh server — the one-liner most tests want. */
+export const fakeNatsStream = (server: FakeNatsServer): NatsStream => server.connect();

package/src/nats-jetstream.ts

@@ -0,0 +1,226 @@
+// Single responsibility: the JetStream API calls the bus needs — the KV bucket's stream, and the
+// direct reads that answer "what is under this prefix" in one round trip. Every subject here is
+// 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';
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** Batch direct get and per-message TTL both landed in 2.11; without them there is no KV presence. */
+const MIN_SERVER = { major: 2, minor: 11 } as const;
+
+/** Interpolated into a stream name and a subject, so this regex is a security boundary. */
+const BUCKET = /^[a-zA-Z0-9_-]+$/;
+
+const STATUS_NOT_FOUND = 404;
+const STATUS_EOB = 204;
+
+export interface JsError {
+  readonly code: number;
+  readonly errCode: number;
+  readonly description: string;
+}
+
+/** One direct-get hit: the KV key, its bytes, and when the server wrote it. */
+export interface KvRecord {
+  readonly key: string;
+  readonly value: string;
+  /** The server's own write time — the one clock every node agrees on. */
+  readonly writtenAt: number | undefined;
+  /** `DEL`/`PURGE` marks a tombstone; a live value has none. */
+  readonly operation: string | undefined;
+}
+
+export function assertBucket(bucket: string): void {
+  if (!BUCKET.test(bucket)) {
+    throw new TransportProtocolError({
+      transport: 'nats',
+      stage: 'bucket',
+      detail: `"${bucket}" is not a bucket name: letters, digits, "-" and "_" only`,
+      fix: 'set NATS_KV_BUCKET to a name matching [a-zA-Z0-9_-]+, then restart',
+    });
+  }
+}
+
+/** `2.11.17` → `{ major: 2, minor: 11 }`. A version we cannot read is treated as too old. */
+export function assertServerVersion(version: string): void {
+  const [major = 0, minor = 0] = version.split('.').map((part) => Number.parseInt(part, 10) || 0);
+  if (major > MIN_SERVER.major || (major === MIN_SERVER.major && minor >= MIN_SERVER.minor)) return;
+  throw new TransportProtocolError({
+    transport: 'nats',
+    stage: 'jetstream',
+    detail: `nats-server ${version || '<unknown>'} is older than ${MIN_SERVER.major}.${MIN_SERVER.minor}, which is where batch direct get and per-message TTL landed`,
+    fix: `run nats:${MIN_SERVER.major}.${MIN_SERVER.minor}-alpine or newer with JetStream enabled (\`nats-server -js\`)`,
+  });
+}
+
+const asObject = (message: NatsMessage, subject: string): Record<string, unknown> => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoder.decode(message.payload));
+  } catch {
+    throw new TransportProtocolError({
+      transport: 'nats',
+      stage: 'jetstream',
+      detail: `${subject} answered with something that is not json`,
+    });
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new TransportProtocolError({
+      transport: 'nats',
+      stage: 'jetstream',
+      detail: `${subject} answered with a ${Array.isArray(parsed) ? 'list' : typeof parsed}`,
+    });
+  }
+  return parsed as Record<string, unknown>;
+};
+
+const errorOf = (body: Record<string, unknown>): JsError | undefined => {
+  const raw = body['error'];
+  if (typeof raw !== 'object' || raw === null) return undefined;
+  const fields = raw as Record<string, unknown>;
+  return {
+    code: typeof fields['code'] === 'number' ? fields['code'] : 0,
+    errCode: typeof fields['err_code'] === 'number' ? fields['err_code'] : 0,
+    description: typeof fields['description'] === 'string' ? fields['description'] : 'unknown',
+  };
+};
+
+/** One JetStream API call. The API always answers with json, and reports failure inside it. */
+export async function jsRequest(
+  connection: NatsConnection,
+  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 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,
+  subject: string,
+  body: unknown,
+): Promise<Record<string, unknown>> {
+  const { data, error } = await jsRequest(connection, subject, body);
+  if (error === undefined) return data;
+  throw new TransportUnavailableError({
+    transport: 'nats',
+    reason: `${subject} failed: ${error.description} (code ${error.code}/${error.errCode})`,
+  });
+}
+
+export const kvStream = (bucket: string): string => `KV_${bucket}`;
+export const kvSubject = (bucket: string, key: string): string => `$KV.${bucket}.${key}`;
+
+/**
+ * Create the bucket's stream when it is missing, and leave an existing one alone. Doing it here
+ * 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,
+  bucket: string,
+  ttlMs: number,
+): Promise<void> {
+  assertBucket(bucket);
+  assertServerVersion(connection.info.version);
+  const stream = kvStream(bucket);
+  const info = await jsRequest(connection, `$JS.API.STREAM.INFO.${stream}`, {});
+  if (info.error === undefined) return;
+  if (info.error.code !== STATUS_NOT_FOUND) {
+    throw new TransportUnavailableError({
+      transport: 'nats',
+      reason: `could not read stream ${stream}: ${info.error.description}`,
+    });
+  }
+  await jsCall(connection, `$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
+    // bucket from silently dropping the oldest member instead of refusing the newest write.
+    max_msgs_per_subject: 1,
+    discard: 'new',
+    deny_delete: true,
+    allow_direct: true,
+    allow_rollup_hdrs: true,
+    allow_msg_ttl: true,
+    // A whole-stream ceiling as well as the per-message TTL: a node that dies mid-put must not be
+    // able to leave a member behind forever, whatever happens to its heartbeats.
+    max_age: Math.max(ttlMs, 60_000) * 1_000_000,
+    storage: 'file',
+    num_replicas: 1,
+  });
+}
+
+const recordOf = (message: NatsMessage, bucket: string): KvRecord | undefined => {
+  const subject = message.headers.get('nats-subject');
+  if (subject === undefined) return undefined;
+  const stamp = message.headers.get('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'),
+  };
+};
+
+/** The current value for one key, or `undefined` when the server has none. */
+export async function kvGet(
+  connection: NatsConnection,
+  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));
+  if (reply.status === STATUS_NOT_FOUND) return undefined;
+  return recordOf(reply, bucket);
+}
+
+/**
+ * Every current value under a wildcard, in one request. A batch direct read answers with the
+ * messages and then an empty `204 EOB`; a prefix nobody has written answers `404` and nothing else.
+ */
+export async function kvLast(
+  connection: NatsConnection,
+  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)), {
+    until: (message) => message.status === STATUS_EOB || message.status === STATUS_NOT_FOUND,
+  });
+  const records: KvRecord[] = [];
+  for (const reply of replies) {
+    if (reply.status !== undefined) continue;
+    const record = recordOf(reply, bucket);
+    if (record) records.push(record);
+  }
+  return records;
+}
+
+/** 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,
+  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 body = asObject(reply, subject);
+  const error = errorOf(body);
+  if (error !== undefined) {
+    throw new TransportUnavailableError({
+      transport: 'nats',
+      reason: `${subject} was not stored: ${error.description} (code ${error.code})`,
+    });
+  }
+}