@ultimat3/realtime 1.0.0

package/src/pg-socket.ts

@@ -0,0 +1,265 @@
+// Single responsibility: the one production `PgStream`, over `Bun.connect` — plus the URL parsing
+// and the SSLRequest handshake that has to happen before the first protocol byte. Bun pushes bytes
+// at handlers while the connection pulls messages, so a queue sits between them.
+
+import { ReplicationFailedError, ReplicationProtocolError } from './errors';
+import { type PgStream, sslRequest } from './pg-wire';
+
+/** Structural view of Bun's socket, declared here so the contract does not need bun-types. */
+export interface SocketLike {
+  write(data: Uint8Array): number;
+  end(): void;
+  upgradeTLS(options: {
+    readonly tls: { readonly serverName: string; readonly rejectUnauthorized?: boolean };
+    readonly socket: SocketHandlers;
+  }): readonly SocketLike[];
+}
+
+export interface SocketHandlers {
+  data(socket: SocketLike, data: Uint8Array): void;
+  close(): void;
+  end(): void;
+  drain(): void;
+  error(socket: SocketLike, error: Error): void;
+}
+
+export interface BunConnect {
+  connect(options: {
+    readonly hostname: string;
+    readonly port: number;
+    readonly socket: SocketHandlers;
+  }): Promise<SocketLike>;
+}
+
+/** `disable` never offers TLS, `prefer` accepts a refusal, `require` treats one as a failure. */
+export type SslMode = 'disable' | 'prefer' | 'require';
+
+export interface PgTarget {
+  readonly host: string;
+  readonly port: number;
+  readonly database: string;
+  readonly user: string;
+  readonly password: string | undefined;
+  readonly ssl: SslMode;
+}
+
+const SSL_MODES = new Set<string>(['disable', 'prefer', 'require']);
+
+/** `postgres://user:pass@host:5432/db?sslmode=require`. The one place a connection URL is read. */
+export function parsePgUrl(url: string): PgTarget {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new ReplicationFailedError({
+      stage: 'connect',
+      detail: `"${url}" is not a connection URL`,
+      fix: 'set DATABASE_URL to postgres://user:password@host:5432/database',
+    });
+  }
+  if (parsed.protocol !== 'postgres:' && parsed.protocol !== 'postgresql:') {
+    throw new ReplicationFailedError({
+      stage: 'connect',
+      detail: `the connection URL uses "${parsed.protocol}" rather than postgres:`,
+      fix: 'set DATABASE_URL to postgres://user:password@host:5432/database',
+    });
+  }
+  const mode = parsed.searchParams.get('sslmode') ?? 'prefer';
+  if (!SSL_MODES.has(mode)) {
+    throw new ReplicationFailedError({
+      stage: 'connect',
+      detail: `sslmode=${mode} is not one of disable, prefer, require`,
+      fix: 'use ?sslmode=require for a managed database, ?sslmode=disable for a local one',
+    });
+  }
+  const database = decodeURIComponent(parsed.pathname.replace(/^\//, ''));
+  return {
+    host: parsed.hostname,
+    port: parsed.port === '' ? 5432 : Number.parseInt(parsed.port, 10),
+    database: database === '' ? 'postgres' : database,
+    user: decodeURIComponent(parsed.username) || 'postgres',
+    password: parsed.password === '' ? undefined : decodeURIComponent(parsed.password),
+    ssl: mode as SslMode,
+  };
+}
+
+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);
+    // One slot, one waiter: overwriting it would abandon the first promise unsettled forever, so
+    // the single-consumer rule is refused here rather than written down and hoped for.
+    if (this.#waiting !== undefined) {
+      return Promise.reject(
+        new ReplicationProtocolError({
+          stage: 'read',
+          detail: 'a second read() arrived while one was already parked on this stream',
+          fix: 'read this stream from one place only — PgConnection owns it for the whole session',
+        }),
+      );
+    }
+    return new Promise((resolve, reject) => {
+      this.#waiting = { resolve, reject };
+    });
+  }
+
+  #take(): Waiter | undefined {
+    const waiter = this.#waiting;
+    this.#waiting = undefined;
+    return waiter;
+  }
+}
+
+export const bunPgStream = (target: PgTarget): Promise<PgStream> =>
+  pgStreamOver(Bun as unknown as BunConnect, target);
+
+/**
+ * `bunPgStream` with the runtime handed in. TLS is negotiated in-band: postgres answers the
+ * 8-byte SSLRequest with a single `S` or `N` **before** any framed message exists, so it has to
+ * happen here rather than in the message layer.
+ */
+export async function pgStreamOver(runtime: BunConnect, target: PgTarget): Promise<PgStream> {
+  const queue = new ChunkQueue();
+  let draining: (() => void) | undefined;
+
+  /**
+   * 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, not retained: Bun promises nothing about the chunk's contents — or that it is even
+    // the same buffer — once the handler returns, and this one outlives it in the queue.
+    data: (_socket, data) => queue.push(data.slice()),
+    close: died,
+    end: died,
+    drain: () => {
+      const resume = draining;
+      draining = undefined;
+      resume?.();
+    },
+    error: (_socket, error) =>
+      queue.fail(
+        new ReplicationFailedError({
+          stage: 'connect',
+          detail: error.message,
+          fix: `open the route to ${target.host}:${target.port}, then: x doctor db`,
+        }),
+      ),
+  };
+
+  let socket = await runtime.connect({
+    hostname: target.host,
+    port: target.port,
+    socket: handlers,
+  });
+
+  const flush = 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 ReplicationFailedError({
+          stage: 'write',
+          detail: `the socket refused a ${rest.length}-byte write`,
+          fix: 'the replicator reconnects on its own; confirm the host is up with: x doctor db',
+        });
+      }
+      if (written > 0) rest = rest.subarray(written);
+      await new Promise<void>((resolve) => {
+        draining = resolve;
+      });
+    }
+  };
+
+  if (target.ssl !== 'disable') {
+    await flush(sslRequest());
+    const answer = (await queue.read()) ?? new Uint8Array(0);
+    const verdict = answer[0];
+    if (verdict === undefined) {
+      throw new ReplicationFailedError({
+        stage: 'ssl',
+        detail: 'the server closed the connection instead of answering the TLS request',
+        fix: `use ?sslmode=disable if ${target.host} does not speak TLS`,
+      });
+    }
+    if (verdict === 0x53) {
+      // The answer is exactly one byte: anything after it was written before the handshake and
+      // would be read as ciphertext, so it is a wrong peer rather than an early arrival.
+      if (answer.length > 1) {
+        throw new ReplicationProtocolError({
+          stage: 'ssl',
+          detail: `the server sent ${answer.length - 1} bytes after accepting TLS`,
+          fix: 'point the replication URL at postgres itself — a proxy answers like this',
+        });
+      }
+      // 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 upgraded = socket.upgradeTLS({ tls: { serverName: target.host }, socket: handlers })[1];
+      if (upgraded === undefined) {
+        throw new ReplicationFailedError({
+          stage: 'ssl',
+          detail: 'the runtime returned no TLS socket for the upgrade',
+          fix: 'bun upgrade   # in-band TLS needs bun >= 1.3',
+        });
+      }
+      socket = upgraded;
+    } else if (target.ssl === 'require') {
+      throw new ReplicationFailedError({
+        stage: 'ssl',
+        detail: 'the server refused TLS but sslmode=require was asked for',
+        fix: `enable ssl on ${target.host}, or use ?sslmode=prefer to accept a cleartext session`,
+      });
+    }
+  }
+
+  return {
+    read: () => queue.read(),
+    write: flush,
+    close: () => socket.end(),
+  };
+}

package/src/pg-wire.ts

@@ -0,0 +1,192 @@
+// Single responsibility: the Postgres v3 message frame — reassemble the length-prefixed backend
+// messages out of whatever chunk sizes the socket hands us, and build the frontend ones. Nothing
+// here knows what a replication slot is; that is `pg-connection.ts`. Nothing here owns a socket;
+// the byte pipe is injected, so the whole protocol runs in a test with no network.
+
+import { ReplicationFailedError, ReplicationProtocolError } from './errors';
+import { ByteReader, ByteWriter } from './pg-bytes';
+
+/** The byte pipe a connection runs over. `pg-socket.ts` implements it over `Bun.connect`. */
+export interface PgStream {
+  /** The next chunk the server sent, or `undefined` once it closed the connection. */
+  read(): Promise<Uint8Array | undefined>;
+  write(bytes: Uint8Array): Promise<void>;
+  close(): void;
+}
+
+export interface PgMessage {
+  /** The one-byte type code, as its ASCII character. */
+  readonly tag: string;
+  readonly body: Uint8Array;
+}
+
+/** Protocol 3.0, as an Int32 — the number the startup packet leads with instead of a tag. */
+export const PROTOCOL_3_0 = 196_608;
+
+/** The magic number that asks for TLS before the startup packet. */
+export const SSL_REQUEST_CODE = 80_877_103;
+
+/** A single message is bounded so a corrupt length cannot make us allocate the machine. */
+const MAX_MESSAGE_BYTES = 64 * 1024 * 1024;
+
+/**
+ * Chunks in, whole messages out. A TCP read boundary lands anywhere — halfway through a length
+ * prefix, halfway through a 4MB `CopyData` — so the buffer is the only place that knows how many
+ * bytes are still missing, and every other module gets to assume a complete frame.
+ */
+export class MessageReader {
+  readonly #stream: PgStream;
+  #buffer: Uint8Array = new Uint8Array(0);
+
+  constructor(stream: PgStream) {
+    this.#stream = stream;
+  }
+
+  /** Bytes already read but not yet consumed — what a reconnect would have to replay. */
+  get buffered(): number {
+    return this.#buffer.length;
+  }
+
+  /** The next complete message, or `undefined` at a clean EOF. */
+  async next(): Promise<PgMessage | undefined> {
+    for (;;) {
+      const framed = this.#take();
+      if (framed !== undefined) return framed;
+      const chunk = await this.#stream.read();
+      if (chunk === undefined) {
+        if (this.#buffer.length === 0) return undefined;
+        throw new ReplicationProtocolError({
+          stage: 'read',
+          detail: `the connection closed with ${this.#buffer.length} bytes of a partial message`,
+          fix: 'x doctor db — the backend was terminated mid-message; the server log names the reason',
+        });
+      }
+      this.#append(chunk);
+    }
+  }
+
+  #append(chunk: Uint8Array): void {
+    if (this.#buffer.length === 0) {
+      this.#buffer = chunk;
+      return;
+    }
+    const joined = new Uint8Array(this.#buffer.length + chunk.length);
+    joined.set(this.#buffer, 0);
+    joined.set(chunk, this.#buffer.length);
+    this.#buffer = joined;
+  }
+
+  /** A message is `tag` + Int32 length that counts itself but not the tag. */
+  #take(): PgMessage | undefined {
+    const buffer = this.#buffer;
+    if (buffer.length < 5) return undefined;
+    const length = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength).getInt32(
+      1,
+      false,
+    );
+    if (length < 4 || length > MAX_MESSAGE_BYTES) {
+      throw new ReplicationProtocolError({
+        stage: 'read',
+        detail: `a message declared a length of ${length} bytes`,
+        fix: 'point the replication URL at postgres itself — a proxy or a TLS port frames like this',
+      });
+    }
+    const total = length + 1;
+    if (buffer.length < total) return undefined;
+    const message: PgMessage = {
+      tag: String.fromCharCode(buffer[0] ?? 0),
+      body: buffer.subarray(5, total),
+    };
+    this.#buffer = buffer.subarray(total);
+    return message;
+  }
+}
+
+/** `tag` + Int32 length + body — the shape of every frontend message except the startup packet. */
+export const frame = (tag: string, body: Uint8Array): Uint8Array =>
+  new ByteWriter(body.length + 5)
+    .uint8(tag.charCodeAt(0))
+    .int32(body.length + 4)
+    .raw(body)
+    .finish();
+
+/** The startup packet carries no tag: Int32 length, Int32 version, then `key\0value\0`…`\0`. */
+export const startupMessage = (parameters: Readonly<Record<string, string>>): Uint8Array => {
+  const body = new ByteWriter(128).int32(PROTOCOL_3_0);
+  for (const [key, value] of Object.entries(parameters)) body.cstring(key).cstring(value);
+  const payload = body.uint8(0).finish();
+  return new ByteWriter(payload.length + 4)
+    .int32(payload.length + 4)
+    .raw(payload)
+    .finish();
+};
+
+/** Asks the server whether it will speak TLS. Same no-tag shape as the startup packet. */
+export const sslRequest = (): Uint8Array =>
+  new ByteWriter(8).int32(8).int32(SSL_REQUEST_CODE).finish();
+
+export const passwordMessage = (password: string): Uint8Array =>
+  frame('p', new ByteWriter(password.length + 1).cstring(password).finish());
+
+/** SASLInitialResponse: the mechanism we picked, then the length-prefixed first client message. */
+export const saslInitialResponse = (mechanism: string, initial: Uint8Array): Uint8Array =>
+  frame(
+    'p',
+    new ByteWriter(mechanism.length + initial.length + 8)
+      .cstring(mechanism)
+      .int32(initial.length)
+      .raw(initial)
+      .finish(),
+  );
+
+export const saslResponse = (payload: Uint8Array): Uint8Array => frame('p', payload);
+
+export const queryMessage = (sql: string): Uint8Array =>
+  frame('Q', new ByteWriter(sql.length + 1).cstring(sql).finish());
+
+export const terminateMessage = (): Uint8Array => frame('X', new Uint8Array(0));
+
+export const copyDoneMessage = (): Uint8Array => frame('c', new Uint8Array(0));
+
+/**
+ * `ErrorResponse` and `NoticeResponse` share a body: `field-code` + String, until a zero byte.
+ * `C` is the SQLSTATE, `M` the message, `S` the severity — the three we ever act on.
+ */
+export const responseFields = (body: Uint8Array): Readonly<Record<string, string>> => {
+  const reader = new ByteReader(body, 'error');
+  const fields: Record<string, string> = {};
+  while (reader.remaining > 0) {
+    const code = reader.tag();
+    // The list ends with a bare zero byte rather than another field code.
+    if (code === '\0') break;
+    fields[code] = reader.cstring();
+  }
+  return fields;
+};
+
+/** One line an operator can act on: `28P01 invalid password for user "x"`. */
+export const describeFields = (fields: Readonly<Record<string, string>>): string =>
+  [fields['C'], fields['M'] ?? 'the server reported no message', fields['D'], fields['H']]
+    .filter((part): part is string => part !== undefined && part !== '')
+    .join(' — ');
+
+/** SQLSTATEs worth their own fix line, because the operator's next command differs for each. */
+const FIXES: Readonly<Record<string, string>> = {
+  '28P01': 'correct the password in the replication URL — the server refused the credentials',
+  '28000': 'add a `host replication <user> <cidr> scram-sha-256` line to pg_hba.conf and reload',
+  '42501': 'grant the role REPLICATION: ALTER ROLE <user> WITH REPLICATION',
+  '55006': 'another replicator holds the slot — exactly one replicator per database, by design',
+  '42704': 'x db replication init — the publication or the slot does not exist yet',
+  '0A000': 'set wal_level = logical in postgresql.conf and restart the server',
+};
+
+/** An `ErrorResponse` becomes the one error class whose `fix` names the command to run. */
+export const serverError = (stage: string, body: Uint8Array): ReplicationFailedError => {
+  const fields = responseFields(body);
+  const code = fields['C'] ?? '';
+  return new ReplicationFailedError({
+    stage,
+    detail: describeFields(fields),
+    fix: FIXES[code] ?? 'x doctor db — the postgres message above names the object to change',
+  });
+};