serverless-ircd 0.1.0

package/apps/local-cli/tests/tcp.test.ts

@@ -0,0 +1,358 @@
+import { EventEmitter } from 'node:events';
+import { type Socket, createConnection } from 'node:net';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { WebSocket } from 'ws';
+import { type LocalServer, startLocalServer } from '../src/server';
+
+/**
+ * Minimal IRC-over-TCP test client. Mirrors the WS `TestClient` in
+ * `e2e.test.ts` but speaks the RFC-style TCP byte stream: writes lines
+ * with a trailing CRLF, parses inbound bytes into IRC lines (tolerant of
+ * CRLF and bare LF, matching the server's `LineScanner`).
+ */
+class TcpTestClient extends EventEmitter {
+  readonly socket: Socket;
+  readonly received: string[] = [];
+
+  constructor(host: string, port: number) {
+    super();
+    this.socket = createConnection({ host, port });
+    this.socket.setEncoding('utf8');
+    this.socket.on('data', (text: string) => {
+      for (const line of text.split(/\r?\n/u)) {
+        if (line.length > 0) {
+          this.received.push(line);
+          this.emit('line', line);
+        }
+      }
+    });
+  }
+
+  /** Resolves once the TCP connection is established. */
+  opened(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.socket.readyState === 'open') resolve();
+      else {
+        this.socket.once('connect', () => resolve());
+        this.socket.once('error', reject);
+      }
+    });
+  }
+
+  /** Writes one IRC line with a trailing CRLF. */
+  send(line: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.socket.write(`${line}\r\n`, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  /** Raw write — used by framing tests that need to emit partial lines. */
+  writeRaw(chunk: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.socket.write(chunk, 'utf8', (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  /** Waits until a received line matches `predicate` (substring/predicate). */
+  waitFor(predicate: (line: string) => boolean, timeoutMs = 1000): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error(`timeout waiting for line; received: ${JSON.stringify(this.received)}`));
+      }, timeoutMs);
+      const check = (line: string): void => {
+        if (predicate(line)) {
+          clearTimeout(timeout);
+          this.off('line', check);
+          resolve(line);
+        }
+      };
+      for (const line of this.received) {
+        if (predicate(line)) {
+          clearTimeout(timeout);
+          resolve(line);
+          return;
+        }
+      }
+      this.on('line', check);
+    });
+  }
+
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      this.socket.once('close', () => resolve());
+      this.socket.end();
+    });
+  }
+
+  /** Force-closes the underlying socket without a FIN handshake. */
+  destroy(): void {
+    this.socket.destroy();
+  }
+}
+
+describe('local-cli TCP transport — startLocalServer tcpPort option', () => {
+  it('exposes tcpPort and testTcpSockets when tcpPort is provided', async () => {
+    const srv = await startLocalServer({ port: 0, tcpPort: 0, hostname: '127.0.0.1' });
+    expect(srv.tcpPort).toBeGreaterThan(0);
+    expect(srv.testTcpSockets).toBeDefined();
+    expect(srv.testTcpSockets?.size).toBe(0);
+    await srv.close();
+  });
+
+  it('omits tcpPort / testTcpSockets when tcpPort is not provided', async () => {
+    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    expect(srv.tcpPort).toBeUndefined();
+    expect(srv.testTcpSockets).toBeUndefined();
+    await srv.close();
+  });
+
+  it('rejects when the TCP port is already in use', async () => {
+    const first = await startLocalServer({ port: 0, tcpPort: 0, hostname: '127.0.0.1' });
+    await expect(
+      startLocalServer({ port: 0, tcpPort: first.tcpPort, hostname: '127.0.0.1' }),
+    ).rejects.toThrow();
+    await first.close();
+  });
+});
+
+describe('local-cli TCP transport — IRC flows', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({ port: 0, tcpPort: 0, hostname: '127.0.0.1' });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('accepts a TCP connection on the tcpPort', async () => {
+    const client = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    await client.opened();
+    expect(server.testTcpSockets?.size).toBe(1);
+    await client.close();
+  });
+
+  it('completes register → join → privmsg over TCP', async () => {
+    const alice = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    const bob = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    await alice.opened();
+    await bob.opened();
+
+    await alice.send('NICK alice');
+    await alice.send('USER alice 0 * :Alice');
+    await alice.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    await bob.send('NICK bob');
+    await bob.send('USER bob 0 * :Bob');
+    await bob.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    await alice.send('JOIN #tcp-e2e');
+    await alice.waitFor((l) => l.includes('JOIN #tcp-e2e'));
+    await bob.send('JOIN #tcp-e2e');
+    await bob.waitFor((l) => l.includes('JOIN #tcp-e2e'));
+
+    await alice.send('PRIVMSG #tcp-e2e :over tcp');
+    await bob.waitFor((l) => l.includes('PRIVMSG #tcp-e2e :over tcp'));
+
+    await alice.close();
+    await bob.close();
+  });
+
+  it('routes PING → PONG over TCP', async () => {
+    const client = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    await client.opened();
+    await client.send('NICK pingUser');
+    await client.send('USER pingUser 0 * :Ping');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    await client.send('PING :tcp-tok');
+    await client.waitFor((l) => l === 'PONG :tcp-tok');
+    await client.close();
+  });
+
+  it('reassembles a single IRC message split across two TCP writes', async () => {
+    const client = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    await client.opened();
+    await client.send('NICK splitter');
+    await client.send('USER splitter 0 * :Splitter');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    // Split a PING line mid-token across two writes. The server's LineScanner
+    // must buffer the partial line and emit one PONG when the terminator lands.
+    await client.writeRaw('PING :split');
+    await client.writeRaw('ted-tok\r\n');
+    await client.waitFor((l) => l === 'PONG :splitted-tok');
+    await client.close();
+  });
+
+  it('processes multiple IRC lines delivered in a single TCP write', async () => {
+    const client = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    await client.opened();
+    // NICK and USER bundled into one write, CRLF-separated.
+    await client.writeRaw('NICK bundler\r\nUSER bundler 0 * :Bundler\r\n');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 bundler'));
+    await client.close();
+  });
+
+  it('cleans up the runtime connection on abrupt TCP socket termination', async () => {
+    const client = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    await client.opened();
+    await client.send('NICK termUser');
+    await client.send('USER termUser 0 * :Term');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    const connId = await server.runtime.lookupNick('termUser');
+    expect(connId).not.toBeNull();
+    expect(server.runtime.hasConnection(connId as string)).toBe(true);
+
+    client.destroy();
+    // Give the server a tick to process the 'close' / 'error' handler.
+    await new Promise((r) => setTimeout(r, 100));
+    expect(server.runtime.hasConnection(connId as string)).toBe(false);
+  });
+
+  it('delivers an ERROR notice over TCP when a reducer supplies a disconnect reason', async () => {
+    const client = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    await client.opened();
+    await client.send('NICK reasonUser');
+    await client.send('USER reasonUser 0 * :Reason');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    // Synthesize a flood-control / oper-kill style disconnect with a reason.
+    const connId = await server.runtime.lookupNick('reasonUser');
+    expect(connId).not.toBeNull();
+    const wait = client.waitFor((l) => l.startsWith('ERROR :Closing link:'));
+    await server.runtime.disconnect(connId as string, 'Excess Flood');
+    await expect(wait).resolves.toContain('Excess Flood');
+    await client.close();
+  });
+
+  it('logs an actor failure on the TCP path without crashing the server', async () => {
+    const original = server.runtime.send.bind(server.runtime);
+    server.runtime.send = async () => {
+      throw new Error('synthetic tcp send failure');
+    };
+    const client = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    await client.opened();
+    await client.send('NICK tcpErr');
+    await client.send('USER tcpErr 0 * :TcpErr');
+    // PING triggers a Send → synthetic throw → actor catch → logError.
+    await client.send('PING :will-throw');
+    await new Promise((r) => setTimeout(r, 50));
+
+    server.runtime.send = original;
+    // Server should still serve new TCP connections.
+    const next = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    await next.opened();
+    await next.send('NICK tcpRecover');
+    await next.send('USER tcpRecover 0 * :TcpRecover');
+    await next.waitFor((l) => l.startsWith(':irc.example.com 001 '), 2000);
+    await next.close();
+    await client.close();
+  });
+});
+
+describe('local-cli TCP × WS cross-transport interop', () => {
+  it('delivers a TCP PRIVMSG to a WS client in the same channel', async () => {
+    const srv = await startLocalServer({ port: 0, tcpPort: 0, hostname: '127.0.0.1' });
+
+    // WS side.
+    const wsClient = new WebSocket(`ws://127.0.0.1:${srv.port}/`);
+    const wsReceived: string[] = [];
+    const wsOpened = new Promise<void>((resolve, reject) => {
+      wsClient.once('open', () => resolve());
+      wsClient.once('error', reject);
+    });
+    wsClient.on('message', (data) => {
+      for (const line of data.toString('utf8').split(/\r?\n/u)) {
+        if (line.length > 0) wsReceived.push(line);
+      }
+    });
+    await wsOpened;
+
+    const wsSend = (line: string): void => {
+      wsClient.send(`${line}\r\n`);
+    };
+    const wsWaitFor = async (
+      predicate: (l: string) => boolean,
+      timeoutMs = 1000,
+    ): Promise<string> => {
+      const start = Date.now();
+      while (Date.now() - start < timeoutMs) {
+        for (const l of wsReceived) if (predicate(l)) return l;
+        await new Promise((r) => setTimeout(r, 10));
+      }
+      throw new Error(`timeout; received: ${JSON.stringify(wsReceived)}`);
+    };
+
+    wsSend('NICK wsUser');
+    wsSend('USER wsUser 0 * :WS');
+    await wsWaitFor((l) => l.startsWith(':irc.example.com 001 '));
+    wsSend('JOIN #interop');
+    await wsWaitFor((l) => l.includes('JOIN #interop'));
+
+    // TCP side.
+    const tcp = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
+    await tcp.opened();
+    await tcp.send('NICK tcpUser');
+    await tcp.send('USER tcpUser 0 * :TCP');
+    await tcp.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await tcp.send('JOIN #interop');
+    await tcp.waitFor((l) => l.includes('JOIN #interop'));
+
+    await tcp.send('PRIVMSG #interop :hello from tcp');
+    await wsWaitFor((l) => l.includes('PRIVMSG #interop :hello from tcp'));
+
+    await tcp.close();
+    await new Promise<void>((resolve) => {
+      wsClient.once('close', () => resolve());
+      wsClient.close();
+    });
+    await srv.close();
+  });
+});
+
+describe('local-cli TCP transport — shutdown', () => {
+  it('close() tears down the TCP server and live TCP sockets', async () => {
+    const srv = await startLocalServer({ port: 0, tcpPort: 0, hostname: '127.0.0.1' });
+    const client = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
+    await client.opened();
+    // Closing the server destroys the server-side socket; the client side
+    // observes the close via its own 'close' event.
+    const closed = new Promise<void>((resolve) => client.socket.once('close', () => resolve()));
+    await srv.close();
+    await closed;
+    expect(client.socket.destroyed).toBe(true);
+  });
+
+  it('close() is a no-op for TCP when tcpPort was never enabled', async () => {
+    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    await expect(srv.close()).resolves.toBeUndefined();
+  });
+
+  it('logs and recovers from a per-TCP-socket error without crashing the server', async () => {
+    const srv = await startLocalServer({ port: 0, tcpPort: 0, hostname: '127.0.0.1' });
+    const client = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
+    await client.opened();
+    // Wait for the server-side 'connection' handler to register the socket
+    // in `testTcpSockets` (it fires on a later tick than the client's
+    // 'connect' event).
+    const sockets = srv.testTcpSockets as Set<Socket>;
+    for (let i = 0; i < 50 && sockets.size === 0; i++) {
+      await new Promise((r) => setTimeout(r, 5));
+    }
+    expect(sockets.size).toBe(1);
+    const serverSideSocket = [...sockets][0];
+    if (serverSideSocket === undefined) throw new Error('no server-side TCP socket');
+    serverSideSocket.emit('error', new Error('synthetic tcp socket failure'));
+    // Give the server a tick to process the handler.
+    await new Promise((r) => setImmediate(r));
+    // Server should still serve new TCP connections.
+    const next = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
+    await next.opened();
+    await next.close();
+    await client.close();
+    await srv.close();
+  });
+});

package/apps/local-cli/tsconfig.build.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "tsBuildInfoFile": "./.tsbuildinfo",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "tests", "**/*.test.ts"],
+  "references": [
+    { "path": "../../packages/irc-core/tsconfig.build.json" },
+    { "path": "../../packages/irc-server/tsconfig.build.json" },
+    { "path": "../../packages/in-memory-runtime/tsconfig.build.json" }
+  ]
+}

package/apps/local-cli/tsconfig.test.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node"],
+    "composite": false
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"],
+  "exclude": ["dist"],
+  "references": [
+    { "path": "../../packages/irc-core/tsconfig.build.json" },
+    { "path": "../../packages/irc-server/tsconfig.build.json" },
+    { "path": "../../packages/in-memory-runtime/tsconfig.build.json" }
+  ]
+}

package/apps/local-cli/vitest.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      all: false,
+      include: ['src/**/*.ts'],
+      // `main.ts` is CLI glue (argv parsing, signal handlers); exercised
+      // manually by `pnpm start`. PLAN §1 requires ≥90% on core packages
+      // and 100% on protocol/reducers; this dev harness targets 90%.
+      exclude: ['src/main.ts'],
+      reporter: ['text', 'html', 'json-summary'],
+      thresholds: {
+        lines: 90,
+        functions: 90,
+        branches: 80,
+        statements: 90,
+      },
+    },
+  },
+});

package/biome.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "ignore": [
+      "**/dist/**",
+      "**/coverage/**",
+      "**/node_modules/**",
+      "**/.turbo/**",
+      "pnpm-lock.yaml"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100,
+    "lineEnding": "lf"
+  },
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "style": {
+        "useImportType": "error",
+        "useExportType": "error",
+        "noNonNullAssertion": "warn"
+      },
+      "suspicious": {
+        "noExplicitAny": "error"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "jsxQuoteStyle": "double",
+      "semicolons": "always",
+      "trailingCommas": "all",
+      "arrowParentheses": "always",
+      "bracketSpacing": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "serverless-ircd",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Serverless IRC daemon with a platform-agnostic core and Cloudflare Workers + AWS adapters",
+  "license": "BSD-3-Clause",
+  "packageManager": "pnpm@9.15.9",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "turbo run build",
+    "typecheck": "turbo run typecheck",
+    "test": "turbo run test",
+    "test:watch": "turbo run test:watch",
+    "coverage": "turbo run coverage",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "clean": "turbo run clean && rimraf node_modules",
+    "deploy:cf:staging": "pnpm --filter @serverless-ircd/cf-worker deploy:staging",
+    "deploy:cf:prod": "pnpm --filter @serverless-ircd/cf-worker deploy:prod",
+    "smoke:cf:staging": "pnpm --filter @serverless-ircd/cf-worker smoke:staging"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "fast-check": "^3.19.0",
+    "rimraf": "^6.0.0",
+    "turbo": "^2.0.0",
+    "typescript": "^5.6.0",
+    "vite": "^7.3.0",
+    "vitest": "^4.1.0"
+  }
+}

package/packages/cf-adapter/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@serverless-ircd/cf-adapter",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Cloudflare Workers adapter: Durable Objects (ConnectionDO, RegistryDO, ChannelDO) and CfRuntime implementing IrcRuntime",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "clean": "rimraf dist coverage .tsbuildinfo .turbo"
+  },
+  "files": ["dist", "src", "README.md"],
+  "dependencies": {
+    "@serverless-ircd/irc-core": "workspace:*",
+    "@serverless-ircd/irc-server": "workspace:*"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "0.18.6",
+    "@cloudflare/workers-types": "^5.20260714.1",
+    "@serverless-ircd/in-memory-runtime": "workspace:*",
+    "@vitest/coverage-v8": "^4.1.0",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.0"
+  }
+}