serverless-ircd 0.8.0 → 0.9.0

package/apps/local-cli/tests/config-resolution.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Coverage for `startLocalServer`'s config-resolution branches:
+ *   - the conditional spreads that pass optional CLI knobs through to the
+ *     shared schema (each knob's "defined" arm — exercised only when the
+ *     caller explicitly supplies the value);
+ *   - the admission-config `?? DEFAULT_*` fallbacks (exercised only when
+ *     admission is enabled without the corresponding cap/rate).
+ *
+ * Starting a server (and closing it) is enough to drive the resolution — no
+ * client connection is required.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { startLocalServer } from '../src/server';
+
+describe('startLocalServer — threads explicit config knobs to the schema', () => {
+  it('accepts every optional limit/knob override and starts cleanly', async () => {
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'cfg.example.com',
+      networkName: 'CfgNet',
+      motdLines: ['explicit motd line'],
+      maxChannelsPerUser: 7,
+      maxTargetsPerCommand: 3,
+      maxListEntries: 11,
+      nickLen: 20,
+      channelLen: 40,
+      topicLen: 200,
+      quitMessage: 'explicit quit',
+    });
+    expect(srv.port).toBeGreaterThan(0);
+    await srv.close();
+  });
+});
+
+describe('startLocalServer — admission defaults', () => {
+  it('falls back to the per-IP / per-user defaults when only the rate limit is set', async () => {
+    // Admission enabled, but maxConnectionsPerIp / maxConnectionsPerUser are
+    // left undefined → the `?? DEFAULT_*` arms apply.
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'rate.example.com',
+      networkName: 'RateNet',
+      perIpConnectionRate: { max: 5, windowMs: 60_000 },
+    });
+    expect(srv.port).toBeGreaterThan(0);
+    await srv.close();
+  });
+
+  it('falls back to the per-IP cap and rate defaults when only per-user cap is set', async () => {
+    // Admission enabled, but maxConnectionsPerIp / perIpConnectionRate are
+    // left undefined → both `?? DEFAULT_*` arms apply.
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'user.example.com',
+      networkName: 'UserNet',
+      maxConnectionsPerUser: 3,
+    });
+    expect(srv.port).toBeGreaterThan(0);
+    await srv.close();
+  });
+});

package/apps/local-cli/tests/motd-file-non-error.test.ts

@@ -0,0 +1,29 @@
+/**
+ * Isolated coverage for {@link loadMotdFile}'s non-Error throw wrap
+ * (motd-file.ts:41 — the `String(err)` branch). The rest of the motd-file
+ * suite exercises real `node:fs` I/O against a temp dir; this file
+ * `vi.mock`s `node:fs` so `readFileSync` rejects with a value that is NOT
+ * an `Error`, driving the `err instanceof Error ? ... : String(err)` ternary
+ * down its non-Error path. Lives in its own file so the mock never leaks
+ * into the real-I/O tests.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('node:fs', () => ({
+  // Throw a non-Error value so the catch wraps it via `String(err)`.
+  readFileSync: () => {
+    throw 'boom-non-error';
+  },
+}));
+
+// Imported AFTER `vi.mock` is established (vitest hoists the mock).
+import { loadMotdFile } from '../src/motd-file';
+
+describe('loadMotdFile — wraps a non-Error throw via String()', () => {
+  it('rethrows a descriptive Error whose detail is String(<thrown value>)', () => {
+    expect(() => loadMotdFile('/irrelevant/motd.txt')).toThrowError(
+      /motd: cannot read --motd-file at .*: boom-non-error/u,
+    );
+  });
+});

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

@@ -0,0 +1,147 @@
+/**
+ * oper `REHASH` end-to-end through the local CLI.
+ *
+ * Drives the `configLoader` closure bound at server.ts:358 — the REHASH
+ * reload source. An oper's `REHASH` re-invokes that closure (via the runtime's
+ * `reloadConfig`) and swaps the live ServerConfig; the actor emits
+ * `382 RPL_REHASHING` on success. A non-oper receives `481 ERR_NOPRIVILEGES`
+ * and no reload is attempted.
+ *
+ * Oper credentials are threaded through the local CLI's `operCreds` option
+ * (the shared schema already accepted them; `startLocalServer` now wires them
+ * to the reducer-facing ServerConfig).
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { WebSocket } from 'ws';
+import { type LocalServer, startLocalServer } from '../src/server';
+
+class IrcClient {
+  readonly ws: WebSocket;
+  readonly received: string[] = [];
+
+  constructor(url: string) {
+    this.ws = new WebSocket(url);
+    this.ws.on('message', (data) => {
+      const text = data.toString('utf8');
+      for (const line of text.split(/\r?\n/u)) {
+        if (line.length > 0) this.received.push(line);
+      }
+    });
+  }
+
+  opened(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.ws.readyState === WebSocket.OPEN) resolve();
+      else {
+        this.ws.once('open', () => resolve());
+        this.ws.once('error', reject);
+      }
+    });
+  }
+
+  send(line: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ws.send(`${line}\r\n`, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  waitFor(predicate: (line: string) => boolean, timeoutMs = 1_000): Promise<string> {
+    const check = (line: string): boolean => predicate(line);
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(
+        () => reject(new Error(`timeout; received: ${JSON.stringify(this.received)}`)),
+        timeoutMs,
+      );
+      const onLine = (line: string): void => {
+        if (check(line)) {
+          clearTimeout(timeout);
+          this.ws.off('message', onMessage);
+          resolve(line);
+        }
+      };
+      const onMessage = (data: { toString: (enc: string) => string }): void => {
+        for (const line of data.toString('utf8').split(/\r?\n/u)) {
+          if (line.length > 0) onLine(line);
+        }
+      };
+      for (const line of this.received) {
+        if (check(line)) {
+          clearTimeout(timeout);
+          resolve(line);
+          return;
+        }
+      }
+      this.ws.on('message', onMessage);
+    });
+  }
+
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      this.ws.once('close', () => resolve());
+      this.ws.close();
+    });
+  }
+}
+
+describe('local-cli e2e — oper REHASH re-invokes the bound configLoader', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'rehash.example.com',
+      networkName: 'RehashNet',
+      operCreds: [{ user: 'admin', password: 's3cret' }],
+    });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('grants oper then reloads config on REHASH (382 RPL_REHASHING, no error)', async () => {
+    const client = new IrcClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('NICK oper1');
+    await client.send('USER oper1 0 * :Oper');
+    await client.waitFor((l) => l.startsWith(':rehash.example.com 001 '));
+
+    // Oper up so the REHASH oper gate passes.
+    await client.send('OPER admin s3cret');
+    const operUp = await client.waitFor((l) => l.includes(' 381 '));
+    expect(operUp).toContain('You are now an IRC operator');
+
+    // REHASH — the actor re-invokes the runtime's reloadConfig, which calls
+    // the configLoader closure (server.ts:358). A clean `382` (no `failed`)
+    // proves the reload succeeded.
+    await client.send('REHASH');
+    const rehashLine = await client.waitFor((l) => l.includes(' 382 '), 2_000);
+    expect(rehashLine).toContain('Rehashing from');
+    expect(rehashLine).not.toContain('failed');
+
+    await client.close();
+  });
+
+  it('rejects REHASH from a non-oper with 481 ERR_NOPRIVILEGES (no reload)', async () => {
+    const client = new IrcClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('NICK peon');
+    await client.send('USER peon 0 * :Peon');
+    await client.waitFor((l) => l.startsWith(':rehash.example.com 001 '));
+
+    await client.send('REHASH');
+    const denied = await client.waitFor((l) => l.includes(' 481 '));
+    expect(denied).toContain('Permission Denied');
+    await client.close();
+  });
+
+  it('directly exercises the configLoader closure via runtime.reloadConfig()', async () => {
+    // Independent of the actor path: the closure bound at server.ts:358 must
+    // return the live ServerConfig the actor was bootstrapped with.
+    const reloaded = await server.runtime.reloadConfig();
+    expect(reloaded.serverName).toBe('rehash.example.com');
+    expect(reloaded.networkName).toBe('RehashNet');
+  });
+});

package/apps/local-cli/tests/server-helpers.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Unit tests for the small transport/adapter helpers extracted from
+ * `server.ts` as test seams. These wrap the genuinely-unreachable defensive
+ * branches (peer-IP fallback, listener-port fallback, write-to-unwritable,
+ * destroy-already-destroyed) so each branch is deterministically exercisable
+ * with a fake — the live WS/TCP integration paths only ever observe the
+ * non-defensive arm.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { listenerPort, peerHost, safeDestroy, safeSocketWrite } from '../src/server';
+
+describe('peerHost', () => {
+  it('returns the remote address when present', () => {
+    expect(peerHost('203.0.113.7')).toBe('203.0.113.7');
+  });
+
+  it("falls back to 'unknown' when no remote address is exposed", () => {
+    expect(peerHost(undefined)).toBe('unknown');
+  });
+});
+
+describe('listenerPort', () => {
+  it('reads the port from an AddressInfo-shaped object', () => {
+    expect(listenerPort({ port: 6667 }, 0)).toBe(6667);
+  });
+
+  it('falls back when the address is a non-IP transport (string)', () => {
+    expect(listenerPort('/run/irc.sock', 7000)).toBe(7000);
+  });
+
+  it('falls back when the address is null', () => {
+    expect(listenerPort(null, 7000)).toBe(7000);
+  });
+});
+
+describe('safeSocketWrite', () => {
+  it('writes when the socket is writable', () => {
+    const write = vi.fn();
+    safeSocketWrite({ writable: true, write }, 'PONG :tok');
+    expect(write).toHaveBeenCalledWith('PONG :tok');
+  });
+
+  it('is a silent no-op when the socket is no longer writable', () => {
+    const write = vi.fn();
+    safeSocketWrite({ writable: false, write }, 'PONG :tok');
+    expect(write).not.toHaveBeenCalled();
+  });
+});
+
+describe('safeDestroy', () => {
+  it('destroys a live socket', () => {
+    const destroy = vi.fn();
+    safeDestroy({ destroyed: false, destroy });
+    expect(destroy).toHaveBeenCalledTimes(1);
+  });
+
+  it('is idempotent — skips a socket that is already destroyed', () => {
+    const destroy = vi.fn();
+    safeDestroy({ destroyed: true, destroy });
+    expect(destroy).not.toHaveBeenCalled();
+  });
+});

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

@@ -215,6 +215,24 @@ describe('local-cli TCP transport — IRC flows', () => {
     await client.close();
   });
 
+  it('skips an empty line delivered over TCP without dispatching it', async () => {
+    // The LineScanner yields an empty string for a bare CRLF; the data
+    // handler's `if (line.length === 0) continue` must skip it without
+    // feeding an empty IRC line to the actor (server.ts:539).
+    const client = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    await client.opened();
+    await client.send('NICK blanker');
+    await client.send('USER blanker 0 * :Blanker');
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
+
+    // A bare CRLF (blank line) followed by a valid PING: the blank line is
+    // ignored and the PING still resolves to a PONG.
+    await client.writeRaw('\r\n');
+    await client.send('PING :after-blank');
+    await client.waitFor((l) => l === 'PONG :after-blank');
+    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();
@@ -367,6 +385,31 @@ describe('local-cli TCP transport — shutdown', () => {
     expect(client.socket.destroyed).toBe(true);
   });
 
+  it('close() destroys a still-live registered TCP connection via the close sweep', async () => {
+    // Registering the client (awaiting 001) guarantees the server-side
+    // connection handler has run and the socket is in `tcpConnections`, so
+    // `close()` deterministically enters the close sweep (server.ts:765) and
+    // destroys the live socket. (Connecting without registering races the
+    // handler under coverage instrumentation.)
+    const srv = await startLocalServer({
+      port: 0,
+      tcpPort: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
+    const client = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
+    await client.opened();
+    await client.send('NICK sweepUser');
+    await client.send('USER sweepUser 0 * :Sweep');
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
+
+    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,
@@ -408,3 +451,49 @@ describe('local-cli TCP transport — shutdown', () => {
     await srv.close();
   });
 });
+
+describe('local-cli TCP transport — admission gate', () => {
+  it('emits ERROR :Closing link and destroys the socket when admitConnection denies', async () => {
+    // Tight per-IP cap with a permissive rate limit so only the per-IP
+    // simultaneous-connection gate refuses the second connection.
+    const srv = await startLocalServer({
+      port: 0,
+      tcpPort: 0,
+      hostname: '127.0.0.1',
+      serverName: 'admit.example.com',
+      networkName: 'AdmitNet',
+      maxConnectionsPerIp: 1,
+      maxConnectionsPerUser: 1_000,
+      perIpConnectionRate: { max: 1_000, windowMs: 60_000 },
+    });
+
+    try {
+      // First connection fills the per-IP cap (maxConnectionsPerIp: 1).
+      const first = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
+      await first.opened();
+
+      // Second connection from the same IP is denied at the TCP admission
+      // gate BEFORE an actor is attached. The server writes the RFC-style
+      // ERROR notice then destroys the socket (server.ts 511-517).
+      const rejected = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
+      const errorLine = await rejected.waitFor((l) => l.startsWith('ERROR :Closing link'), 2_000);
+      expect(errorLine).toContain('connection limit reached');
+      expect(errorLine).toContain('max_connections_per_ip');
+
+      // The server destroys the socket after the ERROR notice.
+      await new Promise<void>((resolve) => {
+        if (rejected.socket.destroyed) resolve();
+        else rejected.socket.once('close', () => resolve());
+      });
+      expect(rejected.socket.destroyed).toBe(true);
+
+      // The denied socket is removed from the server's tracked set so the
+      // runtime admission counters don't leak it.
+      expect(srv.testTcpSockets?.has(rejected.socket)).toBe(false);
+
+      await first.close();
+    } finally {
+      await srv.close();
+    }
+  });
+});

package/apps/local-cli/tests/ws-subprotocol.test.ts

@@ -171,6 +171,20 @@ describe('local-cli IRCv3 WebSocket subprotocol', () => {
     await client.close();
   });
 
+  it('falls back to legacy framing when only unsupported protocols are offered', async () => {
+    // `selectSubprotocol` returns undefined for an all-unsupported offer, so
+    // `handleProtocols` returns false and the ws library completes the
+    // handshake with no negotiated subprotocol. Exercises the
+    // `?? false` fallback in handleProtocols. The offering client then
+    // aborts ("Server sent no subprotocol"), which is expected — the
+    // server-side branch is what this covers.
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, ['chat']);
+    client.ws.on('error', () => {
+      // Expected: server returned no subprotocol for an all-unsupported offer.
+    });
+    await expect(client.opened()).rejects.toThrow(/no subprotocol/iu);
+  });
+
   it('completes registration with one IRC message per WebSocket message (text mode)', async () => {
     const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
     await client.opened();
@@ -260,3 +274,81 @@ describe('local-cli IRCv3 WebSocket subprotocol', () => {
     });
   }
 });
+
+describe('local-cli WebSocket — transport seams', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'seam.example.com',
+      networkName: 'SeamNet',
+    });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('logs a spec-mode actor failure without crashing the server', async () => {
+    // Register normally first so the connection has a nick, then swap the
+    // runtime send to throw — the next inbound message's dispatch rejects
+    // inside receiveTextFrame and the spec-mode `.catch` (server.ts:453)
+    // routes it to logError instead of crashing the server.
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    await client.send('NICK specErr');
+    await client.send('USER specErr 0 * :Spec Err');
+    await client.waitFor((l) => l.startsWith(':seam.example.com 001 '));
+
+    const original = server.runtime.send.bind(server.runtime);
+    server.runtime.send = async () => {
+      throw new Error('synthetic spec send failure');
+    };
+    try {
+      // PING dispatches a Send effect → synthetic throw → actor catch.
+      await client.send('PING :will-throw');
+      await new Promise((r) => setTimeout(r, 60));
+    } finally {
+      server.runtime.send = original;
+    }
+
+    // The server must still serve fresh spec-mode connections.
+    const next = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await next.opened();
+    await next.send('NICK specRecover');
+    await next.send('USER specRecover 0 * :Spec Recover');
+    await next.waitFor((l) => l.startsWith(':seam.example.com 001 '), 2_000);
+    await next.close();
+    await client.close();
+  });
+
+  it('drops an outbound send to a WebSocket that is no longer OPEN', async () => {
+    // Register, then transition the server-side ws to CLOSING. The runtime
+    // still tracks the connection until the 'close' event fires on a later
+    // tick, so a synchronous dispatch hits the `ws.readyState !== OPEN`
+    // guard and returns before calling ws.send (server.ts:423).
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    await client.send('NICK dropSend');
+    await client.send('USER dropSend 0 * :Drop');
+    await client.waitFor((l) => l.startsWith(':seam.example.com 001 '));
+
+    const connId = await server.runtime.lookupNick('dropSend');
+    expect(connId).not.toBeNull();
+    const serverWs = [...server.testSockets].find((ws) => ws.readyState === WebSocket.OPEN);
+    expect(serverWs).toBeDefined();
+    serverWs?.close();
+    // Synchronous dispatch before the 'close' cleanup runs: the send handler
+    // must observe readyState !== OPEN and no-op without throwing.
+    await expect(
+      server.runtime.send(connId as string, [{ text: ':seam NOTICE dropSend :dropped' }]),
+    ).resolves.toBeUndefined();
+
+    await new Promise<void>((resolve) => {
+      client.ws.once('close', () => resolve());
+      client.ws.close();
+    });
+  });
+});