serverless-ircd 0.1.0

package/tools/tcp-ws-forwarder/src/forwarder.ts

@@ -0,0 +1,244 @@
+/**
+ * TCP → ws/wss forwarder.
+ *
+ * The ServerlessIRCd v1 transport is WebSocket-only (PLAN §3): real IRC
+ * clients speak a line-oriented TCP byte stream, so a standard client
+ * cannot dial a deployed worker directly. This forwarder is the local
+ * bridge: it accepts an IRC TCP connection on `127.0.0.1:<port>` and, for
+ * each TCP socket, opens one WebSocket to the configured `ws://` / `wss://`
+ * target and pumps bytes both ways.
+ *
+ *   IRC client  ──TCP──▶  forwarder  ──WS──▶  ServerlessIRCd endpoint
+ *   IRC client  ◀─TCP──  forwarder  ◀─WS──  ServerlessIRCd endpoint
+ *
+ * Framing:
+ *   • TCP→WS: the TCP byte stream is reassembled into IRC lines with the
+ *     byte-accurate {@link LineScanner} (tolerant of CRLF and bare LF per
+ *     PLAN §9). Each complete line is sent as one bare WebSocket text frame
+ *     — the canonical "one message per frame" convention the server's
+ *     `ConnectionActor` expects.
+ *   • WS→TCP: each inbound WS frame is split on line terminators and every
+ *     non-empty line is written back to the TCP socket with a trailing
+ *     CRLF, normalizing whatever framing the server used (single message,
+ *     `\r\n`-joined, or bare) into canonical IRC wire format.
+ *
+ * Lifetime: closing either side tears down the whole bridge. The forwarder
+ * itself is transport-agnostic and has no `@serverless-ircd/*` dependency.
+ */
+
+import { type Socket, createServer } from 'node:net';
+import { type RawData, WebSocket } from 'ws';
+import { LineScanner } from './line-scanner.js';
+
+/** Options accepted by {@link startForwarder}. */
+export interface StartForwarderOptions {
+  /** TCP port to listen on. Use 0 for an ephemeral port. */
+  listenPort: number;
+  /** Interface to bind. Defaults to `127.0.0.1` (loopback only). */
+  listenHost?: string;
+  /**
+   * Upstream WebSocket URL to bridge each TCP connection to. Must use the
+   * `ws:` or `wss:` scheme; otherwise `startForwarder` throws synchronously.
+   */
+  targetUrl: string;
+}
+
+/** A running forwarder. Call {@link Forwarder.close} to shut it down. */
+export interface Forwarder {
+  /** The bound TCP port (the actual port when `listenPort: 0` was requested). */
+  readonly listenPort: number;
+  /** The interface the TCP listener is bound to. */
+  readonly listenHost: string;
+  /** The normalized `ws://` / `wss://` URL each connection is bridged to. */
+  readonly targetUrl: string;
+  /** Closes the listener and every live bridge. Idempotent. */
+  close(): Promise<void>;
+  /**
+   * Test-only seam: live server-side TCP sockets. Exposed so tests can
+   * synthesize socket-level events (`emit('error', ...)`) that are otherwise
+   * unreachable without a real transport fault. Production code MUST NOT use.
+   */
+  readonly testSockets: ReadonlySet<Socket>;
+}
+
+/**
+ * Parses and validates the upstream target URL. Throws synchronously if the
+ * URL is unparseable or does not use the `ws:` / `wss:` scheme.
+ */
+export function parseTargetUrl(raw: string): URL {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`invalid target URL (expected ws:// or wss://): ${raw}`);
+  }
+  if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+    throw new Error(`target URL must use ws:// or wss:// (got ${url.protocol})`);
+  }
+  return url;
+}
+
+/**
+ * Starts the forwarder. Resolves once the TCP listener is ready. Throws
+ * synchronously for a bad `targetUrl`; the returned promise rejects if the
+ * requested port cannot be bound.
+ */
+export function startForwarder(opts: StartForwarderOptions): Promise<Forwarder> {
+  const target = parseTargetUrl(opts.targetUrl);
+  const listenHost = opts.listenHost ?? '127.0.0.1';
+  const targetHref = target.href;
+
+  const bridges = new Map<Socket, () => void>();
+  const sockets = new Set<Socket>();
+  let forwarderClosed = false;
+
+  const server = createServer((tcp) => {
+    sockets.add(tcp);
+    bridges.set(tcp, bridgeConnection(tcp, targetHref, bridges, sockets));
+  });
+
+  const close = (): Promise<void> => {
+    if (forwarderClosed) return Promise.resolve();
+    forwarderClosed = true;
+    const teardowns = [...bridges.values()];
+    bridges.clear();
+    for (const teardown of teardowns) teardown();
+    return new Promise<void>((resolve, reject) => {
+      server.close((err) => (err ? reject(err) : resolve()));
+    });
+  };
+
+  return new Promise<Forwarder>((resolve, reject) => {
+    const onError = (err: Error): void => {
+      server.removeListener('listening', onListening);
+      reject(err);
+    };
+    const onListening = (): void => {
+      server.removeListener('error', onError);
+      const addr = server.address();
+      // c8 ignore next 1 - defensive: a TCP listener always yields AddressInfo.
+      const port = typeof addr === 'object' && addr !== null ? addr.port : opts.listenPort;
+      resolve({
+        listenPort: port,
+        listenHost,
+        targetUrl: targetHref,
+        close,
+        testSockets: sockets,
+      });
+    };
+    server.once('listening', onListening);
+    server.once('error', onError);
+    server.listen(opts.listenPort, listenHost);
+  });
+}
+
+/**
+ * Wires one TCP socket to one fresh WebSocket. Returns a teardown closure
+ * that closes both ends idempotently; the caller registers it in `bridges`
+ * so {@link Forwarder.close} can sweep active connections.
+ */
+function bridgeConnection(
+  tcp: Socket,
+  targetHref: string,
+  bridges: Map<Socket, () => void>,
+  sockets: Set<Socket>,
+): () => void {
+  const ws = new WebSocket(targetHref);
+  const outgoing = new LineScanner();
+  const pending: string[] = [];
+  let wsReady = false;
+  let bridgeClosed = false;
+
+  const sendLine = (line: string): void => {
+    if (wsReady) ws.send(line);
+    else pending.push(line);
+  };
+
+  tcp.on('data', (chunk: Buffer) => {
+    for (const line of outgoing.push(chunk)) {
+      if (line.length > 0) sendLine(line);
+    }
+  });
+
+  ws.on('open', () => {
+    wsReady = true;
+    for (const line of pending) ws.send(line);
+    pending.length = 0;
+  });
+
+  ws.on('message', (data: RawData) => {
+    const text = toBuffer(data).toString('utf8');
+    for (const line of splitFrameLines(text)) {
+      if (line.length > 0) tcp.write(`${line}\r\n`);
+    }
+  });
+
+  const teardown = (): void => {
+    if (bridgeClosed) return;
+    bridgeClosed = true;
+    bridges.delete(tcp);
+    sockets.delete(tcp);
+    // ws.close() does not throw: on a CONNECTING socket it aborts the
+    // handshake and emits an 'error' event, which our handler suppresses
+    // via the `bridgeClosed` guard set above.
+    ws.close();
+    tcp.destroy();
+  };
+
+  tcp.on('close', teardown);
+  tcp.on('error', (err) => {
+    // Errors that arrive after we already tore this bridge down (e.g. an
+    // RST echoing our own `destroy()`) are expected — don't log them.
+    if (bridgeClosed) return;
+    logError('forwarder tcp socket error', err);
+    teardown();
+  });
+  ws.on('close', teardown);
+  ws.on('error', (err) => {
+    // Same suppression as above; also covers the benign "closed before the
+    // connection was established" event ws emits when we close() a socket
+    // that was still CONNECTING at shutdown time.
+    if (bridgeClosed) return;
+    logError('forwarder upstream ws error', err);
+    teardown();
+  });
+
+  return teardown;
+}
+
+/**
+ * Splits an inbound WebSocket text frame into IRC lines. Tolerates `\r\n`,
+ * bare `\n`, and missing trailing terminators. Mirrors the server-side
+ * framing in `ConnectionActor.splitFrameLines`. Exported so the framing
+ * edges (empty frame, joined frame) can be unit-tested in isolation.
+ */
+export function splitFrameLines(text: string): string[] {
+  if (text.length === 0) return [];
+  return text.split(/\r?\n/u);
+}
+
+/**
+ * Normalizes a `ws` `RawData` payload into a single UTF-8 `Buffer`. Exported
+ * so the `ArrayBuffer` / `Uint8Array` / `Buffer[]` variants — which ws only
+ * emits under non-default `binaryType` / fragmentation settings — can be
+ * unit-tested without contriving real socket conditions.
+ */
+export function toBuffer(data: RawData): Buffer {
+  if (Array.isArray(data)) return Buffer.concat(data);
+  if (Buffer.isBuffer(data)) return data;
+  if (data instanceof ArrayBuffer) return Buffer.from(data);
+  return Buffer.from(data as Uint8Array);
+}
+
+function logError(msg: string, err: unknown): void {
+  const payload = {
+    ts: new Date().toISOString(),
+    level: 'error',
+    msg,
+    err:
+      err instanceof Error
+        ? { name: err.name, message: err.message, stack: err.stack }
+        : String(err),
+  };
+  console.error(JSON.stringify(payload));
+}

package/tools/tcp-ws-forwarder/src/line-scanner.ts

@@ -0,0 +1,55 @@
+/**
+ * Byte-accurate line scanner for the forwarder's TCP→WS direction.
+ *
+ * TCP is a byte stream, not a message stream: a single `data` chunk may
+ * contain several IRC lines, a partial line, or a line split across two
+ * chunks. The {@link LineScanner} accumulates raw `Buffer` chunks and emits
+ * each complete line as a decoded UTF-8 string the moment it sees a line
+ * terminator. Decoding happens only on whole lines, so a multi-byte UTF-8
+ * sequence split across two TCP chunks is never corrupted.
+ *
+ * Line endings are tolerated per PLAN §9 transport rules: both CRLF
+ * (`\r\n`) and bare LF (`\n`) terminate a line; a lone CR in the middle of
+ * text is treated as data. The trailing `\r` of a CRLF pair is stripped
+ * before the line is returned.
+ */
+export class LineScanner {
+  private carry: Buffer = Buffer.alloc(0);
+
+  /**
+   * Feeds a chunk of TCP bytes. Returns the complete lines found in this
+   * chunk (joined with any leftover carry from prior chunks), in order,
+   * with terminators removed. Any trailing unterminated bytes are retained
+   * internally for the next call.
+   */
+  push(chunk: Buffer): string[] {
+    const buf = Buffer.concat([this.carry, chunk]);
+    const lines: string[] = [];
+    let start = 0;
+    let nl = buf.indexOf(0x0a, start);
+    while (nl !== -1) {
+      let end = nl;
+      if (end > start && buf[end - 1] === 0x0d) {
+        end--;
+      }
+      lines.push(buf.toString('utf8', start, end));
+      start = nl + 1;
+      nl = buf.indexOf(0x0a, start);
+    }
+    this.carry = buf.subarray(start);
+    return lines;
+  }
+
+  /**
+   * Returns any unterminated tail still buffered (lossless), then clears
+   * the carry. The forwarder does NOT call this on TCP close — an IRC line
+   * without a terminator is a protocol violation and is dropped — but the
+   * method is exposed for completeness and tested directly.
+   */
+  flush(): string[] {
+    if (this.carry.length === 0) return [];
+    const rest = this.carry.toString('utf8');
+    this.carry = Buffer.alloc(0);
+    return [rest];
+  }
+}

package/tools/tcp-ws-forwarder/src/main.ts

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * `tools/tcp-ws-forwarder` entry point.
+ *
+ * v1 of ServerlessIRCd is WebSocket-only, so a standard TCP IRC client
+ * (WeeChat, HexChat, irssi, …) cannot dial a deployed worker directly.
+ * This tool runs a local bridge: it listens on a TCP port and forwards
+ * every connection to a `ws://` / `wss://` endpoint, framing bytes into
+ * IRC lines in both directions.
+ *
+ * Usage:
+ *   tcp-ws-forwarder --target wss://irc.example.com/ [options]
+ *
+ *   --target <url>        Upstream ws:// or wss:// URL (required).
+ *   --listen-port <n>     TCP port to listen on (default 6667).
+ *   --listen-host <addr>  Interface to bind (default 127.0.0.1).
+ *   -h, --help            Show this help and exit.
+ *
+ * Point your IRC client at 127.0.0.1:<listen-port> and it will appear as
+ * a direct connection to the WebSocket endpoint.
+ */
+
+import { startForwarder } from './forwarder.js';
+
+interface CliArgs {
+  target: string | undefined;
+  listenPort: number;
+  listenHost: string;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const out: CliArgs = { target: undefined, listenPort: 6667, listenHost: '127.0.0.1' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === undefined) continue;
+    const next = argv[i + 1];
+    if (a === '--target' && next !== undefined) {
+      out.target = next;
+      i++;
+    } else if (a === '--listen-port' && next !== undefined) {
+      out.listenPort = Number.parseInt(next, 10);
+      i++;
+    } else if (a === '--listen-host' && next !== undefined) {
+      out.listenHost = next;
+      i++;
+    } else if (a === '--help' || a === '-h') {
+      process.stdout.write(
+        [
+          'Usage: tcp-ws-forwarder --target <ws|wss url> [options]',
+          '',
+          'Options:',
+          '  --target <url>        Upstream ws:// or wss:// URL (required).',
+          '  --listen-port <n>     TCP port to listen on (default 6667).',
+          '  --listen-host <addr>  Interface to bind (default 127.0.0.1).',
+          '  -h, --help            Show this help and exit.',
+          '',
+        ].join('\n'),
+      );
+      process.exit(0);
+    } else if (next === undefined && !a.startsWith('-') && out.target === undefined) {
+      // Allow a bare positional URL: tcp-ws-forwarder wss://host/
+      out.target = a;
+    } else {
+      process.stderr.write(`unknown argument: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return out;
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.target === undefined) {
+    process.stderr.write('error: --target <ws|wss url> is required\n');
+    process.exit(2);
+  }
+
+  const forwarder = await startForwarder({
+    listenPort: args.listenPort,
+    listenHost: args.listenHost,
+    targetUrl: args.target,
+  });
+  process.stdout.write(
+    `${JSON.stringify({
+      ts: new Date().toISOString(),
+      level: 'info',
+      msg: 'tcp-ws-forwarder listening',
+      listen: `${forwarder.listenHost}:${forwarder.listenPort}`,
+      target: forwarder.targetUrl,
+    })}\n`,
+  );
+
+  const shutdown = (signal: string): void => {
+    process.stdout.write(
+      `${JSON.stringify({ ts: new Date().toISOString(), level: 'info', msg: 'shutdown', signal })}\n`,
+    );
+    forwarder
+      .close()
+      .then(() => process.exit(0))
+      .catch((err) => {
+        process.stderr.write(`shutdown error: ${String(err)}\n`);
+        process.exit(1);
+      });
+  };
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
+
+main().catch((err) => {
+  process.stderr.write(
+    `fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`,
+  );
+  process.exit(1);
+});