@ultimat3/realtime 1.0.0

package/src/nats-kv.ts

@@ -0,0 +1,157 @@
+// Single responsibility: `TransportSet` over a JetStream KV bucket — the shared, TTL'd keyed sets
+// presence lives in. A member is one KV key, so a node that dies stops heartbeating and its members
+// expire on the server's own clock; nothing has to be cleaned up by whoever notices the loss.
+
+import type { Clock } from '@ultimat3/core';
+import type { TransportSet, TransportSetEntry } from './fanout';
+import type { NatsConnection } from './nats-connection';
+import { kvGet, kvLast, kvWrite } from './nats-jetstream';
+
+/** Per-message TTL is expressed in whole seconds, and must never expire before the logical one. */
+const TTL_GRACE_SECONDS = 1;
+
+/**
+ * A presence key and a member id are user data — a topic name carries dots, a socket id can carry
+ * anything — and a subject token may not. base64url over UTF-8 bytes is reversible and lands inside
+ * both the subject grammar and the KV key charset, so no name has to be rejected for its spelling.
+ */
+export function encodeToken(text: string): string {
+  const bytes = new TextEncoder().encode(text);
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}
+
+export function decodeToken(token: string): string {
+  const padded = token.replaceAll('-', '+').replaceAll('_', '/');
+  const binary = atob(padded.padEnd(padded.length + ((4 - (padded.length % 4)) % 4), '='));
+  return new TextDecoder().decode(Uint8Array.from(binary, (character) => character.charCodeAt(0)));
+}
+
+interface StoredValue {
+  /** The caller's opaque value. */
+  readonly v: string;
+  /** The TTL it was written with, so expiry can be recomputed from the server's write time. */
+  readonly t: number;
+}
+
+const parseStored = (raw: string): StoredValue | undefined => {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null) return undefined;
+    const shape = parsed as { v?: unknown; t?: unknown };
+    if (typeof shape.v !== 'string' || typeof shape.t !== 'number') return undefined;
+    return { v: shape.v, t: shape.t };
+  } catch {
+    return undefined;
+  }
+};
+
+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>;
+  readonly bucket: string;
+  /** Only the fallback when a reply carries no server timestamp; the server's clock is the truth. */
+  readonly clock: Clock;
+}
+
+/** Presence's shared state. One KV key per `<set>.<member>`, one JetStream ack per write. */
+export class NatsKvSet implements TransportSet {
+  readonly #options: NatsKvSetOptions;
+
+  constructor(options: NatsKvSetOptions) {
+    this.#options = options;
+  }
+
+  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(),
+      this.#options.bucket,
+      this.#key(key, member),
+      JSON.stringify(stored),
+      ttlHeader(ttlMs),
+    );
+  }
+
+  /** `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(),
+      this.#options.bucket,
+      this.#key(key, member),
+    );
+    if (record === undefined || record.operation !== undefined) return false;
+    const stored = parseStored(record.value);
+    if (stored === undefined) return false;
+    if (this.#expiresAt(record.writtenAt, stored.t) <= this.#now()) return false;
+    await this.put(key, member, stored.v, ttlMs);
+    return true;
+  }
+
+  /**
+   * A tombstone rather than a stream delete: the bucket denies deletes so history cannot be
+   * rewritten, and the marker carries the shortest legal TTL so it clears itself straight after.
+   */
+  async drop(key: string, member: string): Promise<void> {
+    await kvWrite(
+      await this.#options.connection(),
+      this.#options.bucket,
+      this.#key(key, member),
+      '',
+      new Map([
+        ['KV-Operation', 'DEL'],
+        ['Nats-TTL', String(TTL_GRACE_SECONDS)],
+      ]),
+    );
+  }
+
+  async entries(key: string): Promise<readonly TransportSetEntry[]> {
+    const records = await kvLast(
+      await this.#options.connection(),
+      this.#options.bucket,
+      `${encodeToken(key)}.*`,
+    );
+    const now = this.#now();
+    const live: TransportSetEntry[] = [];
+    for (const record of records) {
+      if (record.operation !== undefined) continue;
+      const stored = parseStored(record.value);
+      const member = this.#member(record.key);
+      if (stored === undefined || member === undefined) continue;
+      const expiresAt = this.#expiresAt(record.writtenAt, stored.t);
+      if (expiresAt > now) live.push({ member, value: stored.v, expiresAt });
+    }
+    return live;
+  }
+
+  #key(key: string, member: string): string {
+    return `${encodeToken(key)}.${encodeToken(member)}`;
+  }
+
+  /**
+   * Token `[1]` is the member — `#key` writes exactly two, because `encodeToken` emits no dot.
+   * A key this class did not write is skipped rather than read: the bucket may hold anything, and
+   * one foreign key must not take the whole presence listing down with it.
+   */
+  #member(kvKey: string): string | undefined {
+    const token = kvKey.split('.')[1];
+    if (token === undefined) return undefined;
+    try {
+      return decodeToken(token);
+    } catch {
+      return undefined;
+    }
+  }
+
+  #expiresAt(writtenAt: number | undefined, ttlMs: number): number {
+    return (writtenAt ?? this.#now()) + ttlMs;
+  }
+
+  #now(): number {
+    return this.#options.clock.now().getTime();
+  }
+}

package/src/nats-protocol.ts

@@ -0,0 +1,222 @@
+// Single responsibility: the NATS client protocol codec — pure encode/decode of the text
+// protocol nats-server speaks on port 4222. No sockets, no timers, no randomness: chunks of
+// bytes in, whole operations out, so the socket layer can be tested with no network at all.
+
+import { TransportProtocolError } from './errors';
+
+const decoder = new TextDecoder();
+const CR = 0x0d;
+const LF = 0x0a;
+
+/** A single declared payload is bounded so a corrupt byte count cannot allocate the machine. */
+const MAX_PAYLOAD_BYTES = 64 * 1024 * 1024;
+
+const protocolError = (stage: 'read' | 'headers', detail: string): TransportProtocolError =>
+  new TransportProtocolError({ transport: 'nats', stage, detail });
+const missingArg = (label: string): never => {
+  throw protocolError('read', `missing ${label}`);
+};
+
+export interface NatsServerInfo {
+  readonly serverId: string;
+  readonly version: string;
+  readonly maxPayload: number;
+  readonly tlsRequired: boolean;
+  readonly tlsAvailable: boolean;
+  readonly authRequired: boolean;
+  readonly headers: boolean;
+  readonly nonce: string | undefined;
+}
+export type NatsHeaders = ReadonlyMap<string, string>;
+export interface NatsMessage {
+  readonly subject: string;
+  readonly sid: string;
+  readonly replyTo: string | undefined;
+  readonly payload: Uint8Array;
+  readonly headers: NatsHeaders;
+  /** From `NATS/1.0 <code> <description>`; `undefined` on a plain MSG or a status-less header. */
+  readonly status: number | undefined;
+  readonly description: string | undefined;
+}
+export type NatsOperation =
+  | { readonly kind: 'info'; readonly info: NatsServerInfo }
+  | { readonly kind: 'msg'; readonly message: NatsMessage }
+  | { readonly kind: 'ping' }
+  | { readonly kind: 'pong' }
+  | { readonly kind: 'ok' }
+  | { readonly kind: 'err'; readonly detail: string };
+
+const EMPTY_HEADERS: NatsHeaders = new Map<string, string>();
+const indexOfCrlf = (bytes: Uint8Array, from: number): number => {
+  for (let i = from; i < bytes.length - 1; i += 1) {
+    if (bytes[i] === CR && bytes[i + 1] === LF) return i;
+  }
+  return -1;
+};
+export const concatBytes = (...parts: readonly Uint8Array[]): Uint8Array => {
+  const total = parts.reduce((sum, part) => sum + part.length, 0);
+  const joined = new Uint8Array(total);
+  let at = 0;
+  for (const part of parts) {
+    joined.set(part, at);
+    at += part.length;
+  }
+  return joined;
+};
+const splitArgs = (text: string): string[] =>
+  text.split(/[ \t]+/).filter((part) => part.length > 0);
+const parseByteCount = (text: string | undefined): number => {
+  if (text === undefined || !/^\d+$/.test(text)) {
+    throw protocolError('read', `expected a byte count, got "${text ?? ''}"`);
+  }
+  return Number(text);
+};
+
+const parseInfo = (json: string): NatsServerInfo => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    throw protocolError('read', `INFO json did not parse: "${json}"`);
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw protocolError('read', `INFO json was not an object: "${json}"`);
+  }
+  const info = parsed as Record<string, unknown>;
+  return {
+    serverId: typeof info['server_id'] === 'string' ? info['server_id'] : '',
+    version: typeof info['version'] === 'string' ? info['version'] : '',
+    maxPayload: typeof info['max_payload'] === 'number' ? info['max_payload'] : 1_048_576,
+    tlsRequired: info['tls_required'] === true,
+    tlsAvailable: info['tls_available'] === true,
+    authRequired: info['auth_required'] === true,
+    headers: info['headers'] === true,
+    nonce: typeof info['nonce'] === 'string' ? info['nonce'] : undefined,
+  };
+};
+
+/** Parses an HMSG/HPUB header block: `NATS/1.0[ <code> <description>]\r\nKey: Value\r\n...\r\n\r\n`. */
+export function parseHeaders(bytes: Uint8Array): {
+  readonly headers: ReadonlyMap<string, string>;
+  readonly status: number | undefined;
+  readonly description: string | undefined;
+} {
+  const lines = decoder.decode(bytes).split('\r\n');
+  const first = lines[0] ?? '';
+  if (!first.startsWith('NATS/1.0')) {
+    throw protocolError('headers', `header block did not start with NATS/1.0: "${first}"`);
+  }
+  const statusPart = first.slice('NATS/1.0'.length).trim();
+  let status: number | undefined;
+  let description: string | undefined;
+  if (statusPart.length > 0) {
+    const spaceAt = statusPart.search(/\s/);
+    const code = spaceAt < 0 ? statusPart : statusPart.slice(0, spaceAt);
+    if (!/^\d{3}$/.test(code)) {
+      throw protocolError('headers', `status code was not 3 digits: "${code}"`);
+    }
+    status = Number(code);
+    description = spaceAt < 0 ? '' : statusPart.slice(spaceAt + 1).trim();
+  }
+  const headers = new Map<string, string>();
+  for (const line of lines.slice(1)) {
+    if (line.length === 0) continue;
+    const colonAt = line.indexOf(':');
+    if (colonAt < 0) continue;
+    headers.set(line.slice(0, colonAt).trim().toLowerCase(), line.slice(colonAt + 1).trim());
+  }
+  return { headers, status, description };
+}
+
+/** Chunks in, whole operations out. A TCP read boundary lands anywhere. */
+export class NatsProtocolParser {
+  #buffer: Uint8Array = new Uint8Array(0);
+
+  push(chunk: Uint8Array): void {
+    this.#buffer = this.#buffer.length === 0 ? chunk : concatBytes(this.#buffer, chunk);
+  }
+
+  /** Bytes read but not yet consumed — what a partial frame is holding. */
+  get buffered(): number {
+    return this.#buffer.length;
+  }
+
+  /** The next complete operation, or `undefined` when more bytes are needed. */
+  next(): NatsOperation | undefined {
+    const buffer = this.#buffer;
+    const lineEnd = indexOfCrlf(buffer, 0);
+    if (lineEnd < 0) return undefined;
+    const line = decoder.decode(buffer.subarray(0, lineEnd));
+    const spaceAt = line.search(/[ \t]/);
+    const verb = (spaceAt < 0 ? line : line.slice(0, spaceAt)).toUpperCase();
+    const rest = spaceAt < 0 ? '' : line.slice(spaceAt + 1).trim();
+    if (verb === 'MSG' || verb === 'HMSG') {
+      return this.#takeMessage(lineEnd, rest, verb === 'HMSG');
+    }
+    this.#buffer = buffer.subarray(lineEnd + 2);
+    switch (verb) {
+      case 'INFO':
+        return { kind: 'info', info: parseInfo(rest) };
+      case 'PING':
+        return { kind: 'ping' };
+      case 'PONG':
+        return { kind: 'pong' };
+      case '+OK':
+        return { kind: 'ok' };
+      case '-ERR': {
+        const trimmed = rest.trim();
+        const quoted = trimmed.length >= 2 && trimmed.startsWith("'") && trimmed.endsWith("'");
+        return { kind: 'err', detail: quoted ? trimmed.slice(1, -1) : trimmed };
+      }
+      default:
+        throw protocolError('read', `unknown verb "${verb}"`);
+    }
+  }
+
+  #takeMessage(lineEnd: number, rest: string, headered: boolean): NatsOperation | undefined {
+    const buffer = this.#buffer;
+    const args = splitArgs(rest);
+    const minArgs = headered ? 4 : 3;
+    const maxArgs = headered ? 5 : 4;
+    if (args.length !== minArgs && args.length !== maxArgs) {
+      const verb = headered ? 'HMSG' : 'MSG';
+      throw protocolError('read', `${verb} wants ${minArgs} or ${maxArgs} args, got "${rest}"`);
+    }
+    const hasReply = args.length === maxArgs;
+    const subject = args[0] ?? missingArg('subject');
+    const sid = args[1] ?? missingArg('sid');
+    const replyTo = hasReply ? (args[2] ?? missingArg('reply-to')) : undefined;
+    const headerBytes = headered ? parseByteCount(args[hasReply ? 3 : 2]) : 0;
+    const totalBytes = parseByteCount(args[args.length - 1]);
+    if (headered && totalBytes < headerBytes) {
+      throw protocolError('read', `HMSG total ${totalBytes} is smaller than header ${headerBytes}`);
+    }
+    if (totalBytes > MAX_PAYLOAD_BYTES) {
+      throw protocolError('read', `payload of ${totalBytes} bytes exceeds ${MAX_PAYLOAD_BYTES}`);
+    }
+    const payloadStart = lineEnd + 2;
+    const headerEnd = payloadStart + headerBytes;
+    const payloadEnd = payloadStart + totalBytes;
+    const end = payloadEnd + 2;
+    if (buffer.length < end) return undefined;
+    if (buffer[payloadEnd] !== CR || buffer[payloadEnd + 1] !== LF) {
+      throw protocolError('read', `payload was not followed by CRLF at offset ${payloadEnd}`);
+    }
+    const { headers, status, description } = headered
+      ? parseHeaders(buffer.subarray(payloadStart, headerEnd))
+      : { headers: EMPTY_HEADERS, status: undefined, description: undefined };
+    this.#buffer = buffer.subarray(end);
+    return {
+      kind: 'msg',
+      message: {
+        subject,
+        sid,
+        replyTo,
+        payload: buffer.subarray(headerEnd, payloadEnd),
+        headers,
+        status,
+        description,
+      },
+    };
+  }
+}

package/src/nats-socket.ts

@@ -0,0 +1,236 @@
+// Single responsibility: the one production `NatsStream`, over `Bun.connect` — plus the URL
+// parsing. NATS sends its INFO line in cleartext before any TLS decision, so the upgrade is a
+// method the caller invokes after reading it, never a handshake negotiated here at connect time.
+
+import { TransportUnavailableError } from './errors';
+import type { BunConnect, SocketHandlers, SocketLike } from './pg-socket';
+
+export interface NatsTarget {
+  readonly host: string;
+  readonly port: number; // default 4222
+  /** `tls://` demands TLS; `nats://` still upgrades when the server's INFO says it is required. */
+  readonly tls: boolean;
+  readonly user: string | undefined;
+  readonly pass: string | undefined;
+  /** `nats://token@host` — NATS' single-credential form, mutually exclusive with user/pass. */
+  readonly token: string | undefined;
+}
+
+const DEFAULT_PORT = 4222;
+
+/** `nats://user:pass@host:4222`. The one place a bus URL is read. */
+export function parseNatsUrl(url: string): NatsTarget {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new TransportUnavailableError({
+      transport: 'nats',
+      reason: `"${url}" is not a connection URL`,
+    });
+  }
+  if (parsed.protocol !== 'nats:' && parsed.protocol !== 'tls:') {
+    throw new TransportUnavailableError({
+      transport: 'nats',
+      reason: `the connection URL uses "${parsed.protocol}" rather than nats: or tls:`,
+    });
+  }
+  if (parsed.hostname === '') {
+    throw new TransportUnavailableError({
+      transport: 'nats',
+      reason: `"${url}" has no host`,
+    });
+  }
+  const hasUser = parsed.username !== '';
+  const hasPass = parsed.password !== '';
+  // A password with no user matches neither credential form, and dropping it silently connects
+  // anonymously — the failure then surfaces as the server's own 'Authorization Violation', which
+  // names nothing about the URL. The URL itself is never echoed back: it holds the secret.
+  if (!hasUser && hasPass) {
+    throw new TransportUnavailableError({
+      transport: 'nats',
+      reason: `the connection URL for ${parsed.hostname} carries a password with no user`,
+      fix: 'set the URL to nats://<user>:<pass>@host:4222, or the bare-token form nats://<token>@host:4222',
+    });
+  }
+  const user = hasUser ? decodeURIComponent(parsed.username) : undefined;
+  const pass = hasPass ? decodeURIComponent(parsed.password) : undefined;
+  return {
+    host: parsed.hostname,
+    port: parsed.port === '' ? DEFAULT_PORT : Number.parseInt(parsed.port, 10),
+    tls: parsed.protocol === 'tls:',
+    // A username with no password is NATS' bare-token form; a password makes it user/pass instead.
+    user: hasUser && hasPass ? user : undefined,
+    pass: hasUser && hasPass ? pass : undefined,
+    token: hasUser && !hasPass ? user : undefined,
+  };
+}
+
+/** The byte pipe a NATS connection runs over. Mirrors `PgStream`, plus the late TLS upgrade. */
+export interface NatsStream {
+  /** The next chunk the server sent, or `undefined` once it closed the connection. */
+  read(): Promise<Uint8Array | undefined>;
+  write(bytes: Uint8Array): Promise<void>;
+  /** In-band TLS. Must be called before any byte other than the server's INFO is exchanged. */
+  upgradeTls(): void;
+  close(): void;
+}
+
+interface Waiter {
+  readonly resolve: (chunk: Uint8Array | undefined) => void;
+  readonly reject: (error: Error) => void;
+}
+
+/** Chunks the socket pushed, handed out one `read()` at a time — EOF and socket errors included. */
+class ChunkQueue {
+  readonly #chunks: Uint8Array[] = [];
+  #waiting: Waiter | undefined;
+  #ended = false;
+  #failure: Error | undefined;
+
+  push(chunk: Uint8Array): void {
+    const waiter = this.#take();
+    if (waiter === undefined) {
+      this.#chunks.push(chunk);
+      return;
+    }
+    waiter.resolve(chunk);
+  }
+
+  /** EOF. A reader parked on `read()` is released rather than left hanging forever. */
+  end(): void {
+    this.#ended = true;
+    this.#take()?.resolve(undefined);
+  }
+
+  fail(error: Error): void {
+    this.#failure = error;
+    this.#ended = true;
+    this.#take()?.reject(error);
+  }
+
+  read(): Promise<Uint8Array | undefined> {
+    const next = this.#chunks.shift();
+    if (next !== undefined) return Promise.resolve(next);
+    if (this.#failure !== undefined) return Promise.reject(this.#failure);
+    if (this.#ended) return Promise.resolve(undefined);
+    if (this.#waiting !== undefined) {
+      // One reader drives this queue — the handshake, then the session's single read loop.
+      // Overwriting the parked waiter would strand it: nothing left would ever settle its promise,
+      // so the caller hangs with no error and no deadline. Refusing the second reader names it.
+      return Promise.reject(
+        new TransportUnavailableError({
+          transport: 'nats',
+          reason: 'a second read() started while one was already parked on this stream',
+          fix: 'read a NatsStream from one place only: one stream feeds exactly one read loop',
+        }),
+      );
+    }
+    return new Promise((resolve, reject) => {
+      this.#waiting = { resolve, reject };
+    });
+  }
+
+  #take(): Waiter | undefined {
+    const waiter = this.#waiting;
+    this.#waiting = undefined;
+    return waiter;
+  }
+}
+
+export const bunNatsStream = (target: NatsTarget): Promise<NatsStream> =>
+  natsStreamOver(Bun as unknown as BunConnect, target);
+
+/** `bunNatsStream` with the runtime handed in, so the whole path runs in a test with no network. */
+export async function natsStreamOver(runtime: BunConnect, target: NatsTarget): Promise<NatsStream> {
+  const queue = new ChunkQueue();
+  let draining: (() => void) | undefined;
+  let upgraded = false;
+
+  /**
+   * A write parked for `drain` can never get one from a socket that is gone, so it is released
+   * here; it then fails on the next `write` rather than burning a whole deadline first. The read
+   * side ends cleanly because an EOF that matters is already an error one layer up.
+   */
+  const died = (): void => {
+    const resume = draining;
+    draining = undefined;
+    resume?.();
+    queue.end();
+  };
+
+  const handlers: SocketHandlers = {
+    // Copied before it is queued or handed on: Bun owns that buffer and gives no guarantee its
+    // contents survive the handler returning, while a queued chunk is read a whole tick later.
+    data: (_socket, data) => queue.push(data.slice()),
+    close: died,
+    end: died,
+    drain: () => {
+      const resume = draining;
+      draining = undefined;
+      resume?.();
+    },
+    error: (_socket, error) =>
+      queue.fail(
+        new TransportUnavailableError({
+          transport: 'nats',
+          reason: `${target.host}:${target.port} — ${error.message}`,
+        }),
+      ),
+  };
+
+  let socket: SocketLike = await runtime.connect({
+    hostname: target.host,
+    port: target.port,
+    socket: handlers,
+  });
+
+  const write = async (bytes: Uint8Array): Promise<void> => {
+    let rest = bytes;
+    while (rest.length > 0) {
+      const written = socket.write(rest);
+      if (written >= rest.length) return;
+      // A negative count is a refusal, not backpressure: no `drain` follows a dead socket, so
+      // waiting for one would park this write forever.
+      if (written < 0) {
+        throw new TransportUnavailableError({
+          transport: 'nats',
+          reason: `the socket refused a ${rest.length}-byte write to ${target.host}:${target.port}`,
+        });
+      }
+      if (written > 0) rest = rest.subarray(written);
+      await new Promise<void>((resolve) => {
+        draining = resolve;
+      });
+    }
+  };
+
+  return {
+    read: () => queue.read(),
+    write,
+    upgradeTls: () => {
+      // Marked before the attempt, not after: a failed upgrade still leaves the raw socket in an
+      // indeterminate TLS-negotiation state, so a retry is refused rather than risking a second
+      // ClientHello on top of the first.
+      if (upgraded) {
+        throw new TransportUnavailableError({
+          transport: 'nats',
+          reason: `upgradeTls() was already called for ${target.host}:${target.port}`,
+        });
+      }
+      upgraded = true;
+      // Bun hands back `[raw, tls]`; every later read and write goes through the second one, and
+      // the handlers are re-registered because the upgraded socket is a different object.
+      const next = socket.upgradeTLS({ tls: { serverName: target.host }, socket: handlers })[1];
+      if (next === undefined) {
+        throw new TransportUnavailableError({
+          transport: 'nats',
+          reason: `the runtime returned no TLS socket for the upgrade to ${target.host}:${target.port}`,
+          fix: 'bun upgrade   # in-band TLS needs bun >= 1.3',
+        });
+      }
+      socket = next;
+    },
+    close: () => socket.end(),
+  };
+}