serverless-ircd 0.1.0

package/apps/local-cli/src/main.ts

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * `apps/local-cli` entry point.
+ *
+ * Boots a local IRC server backed by the in-memory runtime. By default it
+ * binds TWO listeners on adjacent ports so the harness serves both use
+ * cases from a single command:
+ *
+ *   • a WebSocket listener (PLAN §3 — the serverless transport) on `--port`
+ *     for programmatic test fixtures,
+ *   • an RFC-style TCP listener on `--tcp-port` so real IRC clients
+ *     (WeeChat, HexChat, IRCCloud, …) can dial in directly.
+ *
+ * Both listeners share one runtime, so a TCP client and a WS client can
+ * see each other (cross-transport channel broadcast). Pass `--no-tcp` to
+ * run WebSocket-only; the WebSocket port / hostname / MOTD are tunable via
+ * flags (a fuller config-loader lands in a later ticket).
+ *
+ * Usage:
+ *   pnpm --filter local-cli start -- --port 6667 --tcp-port 6668 --host 127.0.0.1
+ *   pnpm --filter local-cli start -- --motd-file ./motd.txt
+ */
+
+import { loadMotdFile } from './motd-file.js';
+import { startLocalServer } from './server.js';
+
+interface CliArgs {
+  port: number;
+  hostname: string;
+  /** undefined when the TCP listener is disabled via `--no-tcp`. */
+  tcpPort: number | undefined;
+  /** undefined when --motd-file is not given; built-in default MOTD applies. */
+  motdFile: string | undefined;
+}
+
+const DEFAULT_PORT = 6667;
+
+function parseArgs(argv: string[]): CliArgs {
+  const out: CliArgs = {
+    port: DEFAULT_PORT,
+    hostname: '127.0.0.1',
+    tcpPort: undefined,
+    motdFile: undefined,
+  };
+  let tcpDisabled = false;
+  let tcpPortOverride: number | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    if (a === '--port' && next !== undefined) {
+      out.port = Number.parseInt(next, 10);
+      i++;
+    } else if (a === '--host' && next !== undefined) {
+      out.hostname = next;
+      i++;
+    } else if (a === '--tcp-port' && next !== undefined) {
+      tcpPortOverride = Number.parseInt(next, 10);
+      i++;
+    } else if (a === '--motd-file' && next !== undefined) {
+      out.motdFile = next;
+      i++;
+    } else if (a === '--no-tcp') {
+      tcpDisabled = true;
+    } else if (a === '--help' || a === '-h') {
+      process.stdout.write(
+        [
+          'Usage: local-cli --port <n> --host <addr> [--tcp-port <n> | --no-tcp] [--motd-file <path>]',
+          '',
+          'Options:',
+          '  --port <n>         WebSocket port to bind (default 6667).',
+          '  --host <addr>      Hostname / interface to bind (default 127.0.0.1).',
+          '  --tcp-port <n>     TCP port for RFC-style IRC clients. Defaults to',
+          '                     <port> + 1 (so 6668) unless --no-tcp is given.',
+          '  --no-tcp           Disable the TCP listener (WebSocket only).',
+          '  --motd-file <path> Read MOTD lines from this file (one per line).',
+          '                     Optional; overrides the built-in default MOTD.',
+          '  -h, --help         Show this help and exit.',
+          '',
+        ].join('\n'),
+      );
+      process.exit(0);
+    } else {
+      process.stderr.write(`unknown argument: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  if (!tcpDisabled) {
+    out.tcpPort = tcpPortOverride ?? out.port + 1;
+  }
+  return out;
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  // --motd-file is optional; missing-file errors throw synchronously with a
+  // motd-prefixed message, surfaced as a fatal by the outer catch.
+  const motdLines = args.motdFile !== undefined ? loadMotdFile(args.motdFile) : undefined;
+  const server = await startLocalServer({
+    port: args.port,
+    hostname: args.hostname,
+    tcpPort: args.tcpPort,
+    ...(motdLines !== undefined ? { motdLines } : {}),
+  });
+
+  process.stdout.write(
+    `${JSON.stringify({
+      ts: new Date().toISOString(),
+      level: 'info',
+      msg: 'local-cli listening',
+      wsUrl: `ws://${server.hostname}:${server.port}/`,
+      port: server.port,
+      tcpPort: server.tcpPort ?? null,
+      hostname: server.hostname,
+    })}\n`,
+  );
+  // Mentioned in --help; kept as a second line for human readers connecting
+  // WeeChat/HexChat/etc. to the TCP listener.
+  if (server.tcpPort !== undefined) {
+    process.stdout.write(
+      `    irc clients connect via TCP:  /connect ${server.hostname}/${server.tcpPort}\n`,
+    );
+  }
+
+  const shutdown = (signal: string): void => {
+    process.stdout.write(
+      `${JSON.stringify({ ts: new Date().toISOString(), level: 'info', msg: 'shutdown', signal })}\n`,
+    );
+    server
+      .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);
+});

package/apps/local-cli/src/motd-file.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * Parses the text contents of a MOTD file into the logical IRC MOTD lines
+ * the server should advertise.
+ *
+ * Framing rules mirror the local-cli TCP `LineScanner` (PLAN §9): both
+ * CRLF (`\r\n`) and bare LF (`\n`) terminate a line; the trailing CR of a
+ * CRLF pair is stripped, and a lone CR mid-text is treated as data. A
+ * single trailing newline does not synthesize a final empty line, but
+ * interior blank lines are preserved so ASCII-art MOTDs keep their shape.
+ *
+ * An empty (or all-newline) input yields an empty array, which the IRC
+ * `MOTD` reducer maps to `422 ERR_NOMOTD`.
+ */
+export function parseMotdFileContent(content: string): string[] {
+  if (content.length === 0) return [];
+  // Split on LF; strip a trailing CR from each piece (CRLF tolerance).
+  const pieces = content
+    .split('\n')
+    .map((line) => (line.length > 0 && line[line.length - 1] === '\r' ? line.slice(0, -1) : line));
+  // Drop the synthesized trailing empty element when the input ends with LF.
+  if (pieces[pieces.length - 1] === '') pieces.pop();
+  return pieces;
+}
+
+/**
+ * Reads a MOTD file from disk synchronously and returns its parsed lines.
+ *
+ * Synchronous I/O is intentional: `main.ts` resolves CLI args and any
+ * derived configuration (including the MOTD) before invoking
+ * `startLocalServer`. Failures (missing file, unreadable) are surfaced as
+ * an `Error` whose message mentions `motd` so the fatal handler in
+ * `main.ts` produces a recognisable diagnostic.
+ */
+export function loadMotdFile(path: string): string[] {
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`motd: cannot read --motd-file at ${path}: ${detail}`);
+  }
+  return parseMotdFileContent(raw);
+}

package/apps/local-cli/src/server.ts

@@ -0,0 +1,409 @@
+/**
+ * Local IRC server wiring.
+ *
+ * PLAN §2 + §3 (Phase 7 dual-transport) — the local CLI adapter is the
+ * manual-test harness and the e2e fixture target. It binds TWO listeners
+ * sharing one {@link InMemoryRuntime}:
+ *
+ *   • a `ws.WebSocketServer` on {@link StartServerOptions.port} — the
+ *     original WebSocket transport (one IRC message per text frame, or N
+ *     `\r\n`-joined messages per frame). Programmatic test clients use this.
+ *   • an optional `node:net` TCP server on {@link StartServerOptions.tcpPort}
+ *     — the RFC-style byte stream that real IRC clients (WeeChat, HexChat,
+ *     IRCCloud) speak. The TCP path uses {@link LineScanner} to reassemble
+ *     IRC lines across chunk boundaries.
+ *
+ * Both transports allocate a fresh {@link ConnectionState} per connection,
+ * attach a {@link ConnectionActor} running against the SAME shared runtime,
+ * and route inbound bytes → `actor.receiveTextFrame`. Because nick/channel
+ * state lives in the runtime, a TCP client and a WS client can see each
+ * other (cross-transport channel broadcast).
+ *
+ * This is `apps/local-cli` rather than `packages/` because the transport
+ * wiring is platform-specific: the CF and AWS adapters wire the same actor
+ * + runtime to Durable Object hibernation sockets and APIGW respectively.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { type Server, type Socket, createServer } from 'node:net';
+import { InMemoryRuntime } from '@serverless-ircd/in-memory-runtime';
+import {
+  type ChanName,
+  type ConnectionState,
+  type RawLine,
+  createConnection,
+} from '@serverless-ircd/irc-core';
+import { ConnectionActor } from '@serverless-ircd/irc-server';
+import { WebSocket, WebSocketServer } from 'ws';
+import { LineScanner } from './line-scanner.js';
+
+/** Default server config; `startLocalServer` accepts overrides. */
+export interface LocalServerConfig {
+  serverName?: string;
+  networkName?: string;
+  motdLines?: string[];
+  maxChannelsPerUser?: number;
+  maxTargetsPerCommand?: number;
+  maxListEntries?: number;
+  nickLen?: number;
+  channelLen?: number;
+  topicLen?: number;
+  quitMessage?: string;
+}
+
+export interface StartServerOptions extends LocalServerConfig {
+  port: number;
+  hostname?: string;
+  /**
+   * Optional TCP port. When provided, also starts an RFC-style TCP IRC
+   * listener that real IRC clients can dial directly. Use 0 for an
+   * ephemeral port (the actual port is exposed on the returned
+   * {@link LocalServer}). When omitted, only the WebSocket listener runs.
+   */
+  tcpPort?: number | undefined;
+}
+
+/** A running local IRC server. Call {@link close} to shut it down. */
+export interface LocalServer {
+  readonly port: number;
+  readonly hostname: string;
+  /**
+   * The actual TCP port, when {@link StartServerOptions.tcpPort} was
+   * provided; `undefined` when the TCP transport is disabled.
+   */
+  readonly tcpPort?: number | undefined;
+  readonly runtime: InMemoryRuntime;
+  close(): Promise<void>;
+  /**
+   * Test-only seam: live server-side WebSockets. Exposed so tests can
+   * synthesize socket-level events (`emit('error', ...)`) that are otherwise
+   * unreachable without a real protocol fault. Production code MUST NOT use.
+   */
+  readonly testSockets: ReadonlySet<WebSocket>;
+  /**
+   * Test-only seam: live server-side TCP sockets when the TCP listener is
+   * enabled; `undefined` otherwise. Same purpose as {@link testSockets}.
+   */
+  readonly testTcpSockets?: ReadonlySet<Socket> | undefined;
+}
+
+interface ConnectionBindings {
+  state: ConnectionState;
+  actor: ConnectionActor;
+}
+
+const DEFAULT_CONFIG: Required<LocalServerConfig> = {
+  serverName: 'irc.example.com',
+  networkName: 'ExampleNet',
+  motdLines: ['Welcome to the local-cli ServerlessIRCd instance.'],
+  maxChannelsPerUser: 30,
+  maxTargetsPerCommand: 10,
+  maxListEntries: 50,
+  nickLen: 30,
+  channelLen: 50,
+  topicLen: 390,
+  quitMessage: 'Client Quit',
+};
+
+/**
+ * Shared IdFactory. Hoisted to module scope so v8's function-coverage counts
+ * the three generators once at module load, not per-connection. No reducer in
+ * the current codebase actually invokes `batchId` / `nonce` / `sessionId`;
+ * they are forward-looking seams for SASL / BATCH / context-restoration
+ * tickets and are exercised by irc-core's own unit tests via test fakes.
+ *
+ * Exported so `apps/local-cli` can ship a focused unit test asserting each
+ * generator returns a fresh UUID-shaped string (defending against future
+ * refactorings that might collapse them into constant strings).
+ */
+export const DEFAULT_ID_FACTORY = {
+  batchId: () => randomUUID(),
+  nonce: () => randomUUID(),
+  sessionId: () => randomUUID(),
+};
+
+/**
+ * Starts a local IRC server. Resolves once BOTH the WebSocket listener and
+ * (if requested) the TCP listener are ready. Use port 0 to bind ephemeral
+ * ports (the actual ports are exposed on the returned {@link LocalServer}).
+ *
+ * If the TCP listener fails to bind after the WebSocket listener succeeded,
+ * the WebSocket listener is torn down before the promise rejects so callers
+ * don't leak a half-started server.
+ */
+export function startLocalServer(opts: StartServerOptions): Promise<LocalServer> {
+  const cfg: Required<LocalServerConfig> = { ...DEFAULT_CONFIG, ...stripUndefined(opts) };
+  const hostname = opts.hostname ?? '127.0.0.1';
+
+  const runtime = new InMemoryRuntime({ clock: { now: () => Date.now() } });
+
+  const wss = new WebSocketServer({ port: opts.port, host: hostname });
+  const wsConnections = new Map<WebSocket, ConnectionBindings>();
+
+  wss.on('connection', (ws) => {
+    const { state, actor } = attachConnection(runtime, cfg, {
+      sendText: (text) => {
+        if (ws.readyState === WebSocket.OPEN) ws.send(text);
+      },
+      closeTransport: () => ws.close(),
+    });
+    wsConnections.set(ws, { state, actor });
+
+    ws.on('message', (data) => {
+      const text = data.toString('utf8');
+      // Fire-and-forget: the actor's reducer pipeline is synchronous through
+      // to dispatch, and dispatch awaits each runtime call in order. Errors
+      // propagate to the catch here and are logged (never crash the server).
+      actor.receiveTextFrame(text).catch((err) => {
+        logError('actor failure', err);
+      });
+    });
+
+    // 'close' and 'error' both end in the same cleanup: drop the connection
+    // map entry and unregister the conn from the runtime so it stops
+    // receiving broadcasts.
+    const cleanup = (): void => {
+      wsConnections.delete(ws);
+      runtime.unregisterConnection(state.id);
+    };
+    ws.on('close', cleanup);
+    ws.on('error', (err) => {
+      logError('socket error', err);
+      cleanup();
+    });
+  });
+
+  return new Promise<LocalServer>((resolve, reject) => {
+    const onWsError = (err: Error): void => {
+      wss.removeListener('listening', onWsListening);
+      reject(err);
+    };
+    const onWsListening = (): void => {
+      wss.removeListener('error', onWsError);
+      const addr = wss.address();
+      // c8 ignore next 1 - defensive fallback for non-IP transports; with a
+      // TCP port `wss.address()` always returns an AddressInfo object.
+      const wsPort = typeof addr === 'object' && addr !== null ? addr.port : opts.port;
+
+      // If no TCP listener was requested, resolve immediately with just WS.
+      if (opts.tcpPort === undefined) {
+        finishResolve({ wsPort, tcpPort: undefined, tcpServer: undefined });
+        return;
+      }
+
+      // Spin up the TCP listener and wait for it to be ready. If it fails,
+      // tear down the WS server first so callers don't leak a half-started
+      // server.
+      const tcpConnections = new Map<Socket, ConnectionBindings>();
+      const tcpSockets = new Set<Socket>();
+      const tcpServer = createServer((socket) => {
+        tcpSockets.add(socket);
+        const scanner = new LineScanner();
+        const { state, actor } = attachConnection(runtime, cfg, {
+          sendText: (text) => {
+            if (socket.writable) socket.write(text);
+          },
+          closeTransport: () => {
+            // `destroy()` over `end()` so a half-closed peer can't hold the
+            // socket open past the actor's QUIT/disconnect decision. WS
+            // callers go through `ws.close()`; TCP callers go through here.
+            socket.destroy();
+          },
+        });
+        tcpConnections.set(socket, { state, actor });
+
+        socket.on('data', (chunk: Buffer) => {
+          for (const line of scanner.push(chunk)) {
+            if (line.length === 0) continue;
+            actor.receiveTextFrame(line).catch((err) => {
+              logError('actor failure', err);
+            });
+          }
+        });
+
+        const cleanup = (): void => {
+          tcpConnections.delete(socket);
+          tcpSockets.delete(socket);
+          runtime.unregisterConnection(state.id);
+        };
+        socket.on('close', cleanup);
+        socket.on('error', (err) => {
+          logError('tcp socket error', err);
+          cleanup();
+        });
+      });
+
+      tcpServer.once('error', (err) => {
+        // Tear down the WS server first; reject with the TCP error so the
+        // caller sees the actual bind failure.
+        teardownWss(wss, wsConnections).finally(() => reject(err));
+      });
+      tcpServer.once('listening', () => {
+        const tcpAddr = tcpServer.address();
+        // c8 ignore next 1 - defensive: a TCP listener always yields AddressInfo.
+        const tcpPort =
+          typeof tcpAddr === 'object' && tcpAddr !== null ? tcpAddr.port : opts.tcpPort;
+        finishResolve({ wsPort, tcpPort, tcpServer, tcpConnections, tcpSockets });
+      });
+      tcpServer.listen(opts.tcpPort, hostname);
+    };
+
+    const finishResolve = (args: {
+      wsPort: number;
+      tcpPort: number | undefined;
+      tcpServer: Server | undefined;
+      tcpConnections?: Map<Socket, ConnectionBindings>;
+      tcpSockets?: Set<Socket>;
+    }): void => {
+      const { wsPort, tcpPort, tcpServer, tcpConnections, tcpSockets } = args;
+      resolve({
+        port: wsPort,
+        tcpPort,
+        hostname,
+        runtime,
+        testSockets: wss.clients,
+        testTcpSockets: tcpSockets,
+        close: () =>
+          closeEverything({
+            wss,
+            wsConnections,
+            tcpServer,
+            tcpConnections,
+          }),
+      });
+    };
+
+    wss.once('listening', onWsListening);
+    wss.once('error', onWsError);
+  });
+}
+
+/**
+ * Allocates a fresh {@link ConnectionState} + {@link ConnectionActor} against
+ * the shared runtime, and registers the connection's send/disconnect
+ * transport callbacks. Used by both the WS and TCP listeners so they share
+ * identical actor lifecycle wiring — only the byte-moving callbacks differ.
+ */
+function attachConnection(
+  runtime: InMemoryRuntime,
+  cfg: Required<LocalServerConfig>,
+  transport: { sendText: (text: string) => void; closeTransport: () => void },
+): ConnectionBindings {
+  const id = randomUUID();
+  const state = createConnection({ id, connectedSince: Date.now() });
+
+  const actor = new ConnectionActor({
+    state,
+    runtime,
+    channels: runtime,
+    serverConfig: {
+      serverName: cfg.serverName,
+      networkName: cfg.networkName,
+      maxChannelsPerUser: cfg.maxChannelsPerUser,
+      maxTargetsPerCommand: cfg.maxTargetsPerCommand,
+      maxListEntries: cfg.maxListEntries,
+      nickLen: cfg.nickLen,
+      channelLen: cfg.channelLen,
+      topicLen: cfg.topicLen,
+      quitMessage: cfg.quitMessage,
+    },
+    clock: { now: () => Date.now() },
+    ids: DEFAULT_ID_FACTORY,
+    motd: { lines: () => cfg.motdLines },
+  });
+
+  runtime.registerConnection(state, {
+    send: (lines: RawLine[]) => {
+      const text = `${lines.map((l) => l.text).join('\r\n')}\r\n`;
+      transport.sendText(text);
+    },
+    disconnect: (reason?: string) => {
+      // If a reason was supplied, send the RFC-style ERROR notice before
+      // closing. (QUIT does not supply one; future paths like flood
+      // control will.)
+      if (reason !== undefined) {
+        transport.sendText(`ERROR :Closing link: (${reason})\r\n`);
+      }
+      transport.closeTransport();
+    },
+  });
+
+  return { state, actor };
+}
+
+/** Tears down the WS server and all live WS connections. */
+function teardownWss(
+  wss: WebSocketServer,
+  connections: Map<WebSocket, ConnectionBindings>,
+): Promise<void> {
+  for (const ws of connections.keys()) {
+    if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+      ws.close();
+    }
+  }
+  connections.clear();
+  return new Promise<void>((res) => {
+    wss.close(() => res());
+  });
+}
+
+/** Idempotent shutdown of every started listener and all live connections. */
+function closeEverything(args: {
+  wss: WebSocketServer;
+  wsConnections: Map<WebSocket, ConnectionBindings>;
+  tcpServer: Server | undefined;
+  tcpConnections?: Map<Socket, ConnectionBindings> | undefined;
+}): Promise<void> {
+  const { wss, wsConnections, tcpServer, tcpConnections } = args;
+
+  // Tear down WS connections + server first.
+  const wsClosed = teardownWss(wss, wsConnections);
+
+  // Tear down TCP connections + server in parallel (if enabled).
+  const tcpClosed =
+    tcpServer === undefined
+      ? Promise.resolve()
+      : new Promise<void>((res) => {
+          if (tcpConnections !== undefined) {
+            for (const socket of tcpConnections.keys()) {
+              // Defensive: reachable only if a socket was already destroyed
+              // (e.g. via a reducer-driven disconnect racing the close sweep)
+              // but hasn't yet been removed from `tcpConnections`. The cleanup
+              // handler always removes on 'close'/'error', so this branch is a
+              // no-op in steady state.
+              // c8 ignore next 1
+              if (!socket.destroyed) socket.destroy();
+            }
+            tcpConnections.clear();
+          }
+          tcpServer.close(() => res());
+        });
+
+  return Promise.all([wsClosed, tcpClosed]).then(() => undefined);
+}
+
+function stripUndefined<T extends object>(obj: T): Partial<T> {
+  const out: Partial<T> = {};
+  for (const key of Object.keys(obj) as Array<keyof T>) {
+    const v = obj[key];
+    if (v !== undefined) out[key] = v;
+  }
+  return out;
+}
+
+function logError(msg: string, err: unknown): void {
+  // Structured JSON per acceptance criteria.
+  const payload = { ts: new Date().toISOString(), level: 'error', msg, err: stringifyErr(err) };
+  // eslint-disable-next-line no-console
+  console.error(JSON.stringify(payload));
+}
+
+function stringifyErr(err: unknown): unknown {
+  if (err instanceof Error) {
+    return { name: err.name, message: err.message, stack: err.stack };
+  }
+  return err;
+}
+
+// Suppress "ChanName imported but unused" — kept for type re-export ergonomics.
+export type { ChanName, ConnectionState };