serverless-ircd 0.8.0 → 0.9.0

package/tools/load-test/tests/client.test.ts

@@ -1,7 +1,8 @@
+import { EventEmitter } from 'node:events';
 import { type LocalServer, startLocalServer } from '@serverless-ircd/local-cli/dist/server.js';
-import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
 import { WebSocketServer } from 'ws';
-import { IrcLoadClient } from '../src/client';
+import { IrcLoadClient, type WebSocketCtor } from '../src/client';
 import { resolveConfig } from '../src/config';
 
 /**
@@ -210,3 +211,258 @@ function startDroppingWsServer(): Promise<{ port: number; close: () => Promise<v
     wss.once('error', onError);
   });
 }
+
+// ---------------------------------------------------------------------------
+// Failure-path coverage via an injectable fake WebSocket.
+//
+// The client accepts a `WebSocketCtor` dependency (client.ts) so the lifecycle
+// can be driven against a scriptable fake. The four tests below exercise the
+// branches that are impractical to reach through a real socket: connect
+// timeout (socket never opens), join timeout, privmsg timeout, and a socket
+// `error` event fanning out to pending waiters mid-wait.
+// ---------------------------------------------------------------------------
+
+/** A reply the fake fires when the client sends a matching line. */
+type FakeHandler = {
+  match: RegExp;
+  action: { kind: 'messages'; lines: string[] } | { kind: 'error'; error: unknown };
+};
+
+/** Module-level fake controller state (reset per test in beforeEach). */
+let fakeAutoOpen = true;
+let fakeHandlers: FakeHandler[] = [];
+let fakeReadyState: number | undefined;
+let fakeErrorOnClose = false;
+let lastFake: FakeSocket | undefined;
+
+/**
+ * Minimal WebSocket stand-in. Emits `open` on the next microtask (so the
+ * client's `once('open')` listener is attached first), and on `send()` fires
+ * any scripted reply for the sent line. `emit('error', ...)` is used to drive
+ * the socket-error path.
+ */
+class FakeSocket extends EventEmitter {
+  readonly OPEN = 1;
+  readyState: number;
+  readonly sent: string[] = [];
+
+  constructor(_url: string, _protocols: string[]) {
+    super();
+    lastFake = this;
+    this.readyState = fakeReadyState ?? 1;
+    if (fakeAutoOpen) {
+      queueMicrotask(() => this.emit('open'));
+    }
+  }
+
+  send(line: string): void {
+    this.sent.push(line);
+    for (const h of fakeHandlers) {
+      if (h.match.test(line)) {
+        const action = h.action;
+        queueMicrotask(() => {
+          if (action.kind === 'messages') {
+            for (const text of action.lines) {
+              this.emit('message', Buffer.from(text, 'utf8'));
+            }
+          } else {
+            this.emit('error', action.error);
+          }
+        });
+      }
+    }
+  }
+
+  close(): void {
+    this.readyState = 3;
+    if (fakeErrorOnClose) {
+      this.emit('error', new Error('emitted on close'));
+    }
+  }
+}
+
+/**
+ * A WebSocketCtor whose constructor throws synchronously — drives the
+ * `this.ws === undefined` path in teardown.
+ */
+class ThrowingSocketCtor extends EventEmitter {
+  constructor(_url: string, _protocols: string[]) {
+    super();
+    throw new Error('constructor blew up');
+  }
+}
+
+describe('IrcLoadClient — failure paths (fake WebSocket)', () => {
+  beforeEach(() => {
+    fakeAutoOpen = true;
+    fakeHandlers = [];
+    fakeReadyState = undefined;
+    fakeErrorOnClose = false;
+    lastFake = undefined;
+  });
+
+  /** Resolves a config aimed at the fake, with short timeouts. */
+  function fakeCfg(
+    overrides: Parameters<typeof resolveConfig>[0] = {},
+  ): ReturnType<typeof resolveConfig> {
+    return resolveConfig({
+      target: 'ws://fake.local/',
+      channel: '#test',
+      nickPrefix: 'bot',
+      messagesPerClient: 0,
+      connectTimeoutMs: 1000,
+      registerTimeoutMs: 100,
+      ...overrides,
+    });
+  }
+
+  it('fails at connect when the socket never opens (connect timeout)', async () => {
+    fakeAutoOpen = false;
+    const client = new IrcLoadClient({
+      id: 0,
+      config: fakeCfg({ connectTimeoutMs: 50 }),
+      WebSocketCtor: FakeSocket as unknown as WebSocketCtor,
+    });
+    const result = await client.run();
+    expect(result.ok).toBe(false);
+    expect(result.failedPhase).toBe('connect');
+    expect(result.error).toMatch(/connect timeout/i);
+  });
+
+  it('fails at join when the server never replies with 366', async () => {
+    // Registration completes (001 sent in reply to NICK); JOIN gets no 366
+    // so the join waiter times out. The reply bundles a blank line and a
+    // non-prefixed PING line alongside the 001 to also cover the empty-line
+    // skip (onMessage) and the non-':' prefix arm (numericOf).
+    fakeHandlers = [
+      {
+        match: /^NICK /u,
+        action: {
+          kind: 'messages',
+          lines: ['\r\nPING :keepalive\r\n:srv 001 bot0 :Welcome'],
+        },
+      },
+    ];
+    const client = new IrcLoadClient({
+      id: 0,
+      config: fakeCfg({ echoMessage: false }),
+      WebSocketCtor: FakeSocket as unknown as WebSocketCtor,
+    });
+    const result = await client.run();
+    expect(result.ok).toBe(false);
+    expect(result.failedPhase).toBe('join');
+    expect(result.samples.register.length).toBe(1);
+    expect(lastFake?.sent.some((l) => l.startsWith('JOIN'))).toBe(true);
+  });
+
+  it('fails at privmsg when the echo never arrives', async () => {
+    // Registration + join succeed; the PRIVMSG echo never arrives so the
+    // privmsg waiter times out.
+    fakeHandlers = [
+      {
+        match: /^NICK /u,
+        action: { kind: 'messages', lines: [':srv 001 bot0 :Welcome'] },
+      },
+      {
+        match: /^JOIN /u,
+        action: { kind: 'messages', lines: [':srv 366 bot0 #test :End of NAMES'] },
+      },
+    ];
+    const client = new IrcLoadClient({
+      id: 0,
+      config: fakeCfg({ messagesPerClient: 1, echoMessage: false }),
+      WebSocketCtor: FakeSocket as unknown as WebSocketCtor,
+    });
+    const result = await client.run();
+    expect(result.ok).toBe(false);
+    expect(result.failedPhase).toBe('privmsg');
+    expect(result.samples.register.length).toBe(1);
+    expect(result.samples.join.length).toBe(1);
+    expect(lastFake?.sent.some((l) => l.startsWith('PRIVMSG'))).toBe(true);
+  });
+
+  it('fails via onError when the socket errors during a pending wait', async () => {
+    // The socket errors mid-registration: the `on('error')` handler fans the
+    // error out to the pending register waiter via failWaiters.
+    fakeHandlers = [
+      {
+        match: /^NICK /u,
+        action: { kind: 'error', error: new Error('socket boom') },
+      },
+    ];
+    const client = new IrcLoadClient({
+      id: 0,
+      config: fakeCfg({ echoMessage: false }),
+      WebSocketCtor: FakeSocket as unknown as WebSocketCtor,
+    });
+    const result = await client.run();
+    expect(result.ok).toBe(false);
+    expect(result.error).toBe('socket boom');
+    // connect succeeded before the error fired.
+    expect(result.samples.connect.length).toBe(1);
+  });
+
+  it('coerces a non-Error rejection to a string error message', async () => {
+    // Some transports emit non-Error values on 'error'. The client's failedAt
+    // helper must fall back to String(err) rather than crash.
+    fakeHandlers = [
+      {
+        match: /^NICK /u,
+        action: { kind: 'error', error: 'stringy failure' },
+      },
+    ];
+    const client = new IrcLoadClient({
+      id: 0,
+      config: fakeCfg({ echoMessage: false }),
+      WebSocketCtor: FakeSocket as unknown as WebSocketCtor,
+    });
+    const result = await client.run();
+    expect(result.ok).toBe(false);
+    expect(result.error).toBe('stringy failure');
+  });
+
+  it('skips send() when the socket is not in the OPEN state', async () => {
+    // The fake reports CLOSED even though it emits 'open', so the send()
+    // readyState guard is exercised and no lines reach the wire.
+    fakeReadyState = 3;
+    const client = new IrcLoadClient({
+      id: 0,
+      config: fakeCfg({ echoMessage: false }),
+      WebSocketCtor: FakeSocket as unknown as WebSocketCtor,
+    });
+    const result = await client.run();
+    expect(result.ok).toBe(false);
+    expect(result.failedPhase).toBe('register');
+    expect(lastFake?.sent.length).toBe(0);
+  });
+
+  it('ignores a socket error that arrives after teardown', async () => {
+    // The fake emits 'error' from close(); by the time teardown calls close()
+    // the client is already settled, so onError's guard short-circuits.
+    fakeErrorOnClose = true;
+    const client = new IrcLoadClient({
+      id: 0,
+      config: fakeCfg({ echoMessage: false }),
+      WebSocketCtor: FakeSocket as unknown as WebSocketCtor,
+    });
+    // register will time out (no 001), then teardown → close() → error is
+    // swallowed by the settled guard.
+    const result = await client.run();
+    expect(result.ok).toBe(false);
+    expect(result.failedPhase).toBe('register');
+  });
+
+  it('handles a WebSocket constructor that throws synchronously', async () => {
+    // The constructor blowing up means this.ws is never assigned; teardown
+    // must skip the close path without crashing.
+    const client = new IrcLoadClient({
+      id: 0,
+      config: fakeCfg({ echoMessage: false }),
+      WebSocketCtor: ThrowingSocketCtor as unknown as WebSocketCtor,
+    });
+    const result = await client.run();
+    expect(result.ok).toBe(false);
+    expect(result.failedPhase).toBe('connect');
+    expect(result.error).toBe('constructor blew up');
+  });
+});

package/tools/load-test/tests/config.test.ts

@@ -69,6 +69,35 @@ describe('resolveConfig — validation (fail-fast)', () => {
   it('throws when the channel does not start with #', () => {
     expect(() => resolveConfig({ target: 'ws://x/', channel: 'loadtest' })).toThrow(/channel/i);
   });
+
+  it('throws when connectTimeoutMs is non-positive', () => {
+    expect(() => resolveConfig({ target: 'ws://x/', connectTimeoutMs: 0 })).toThrow(
+      /connect timeout/i,
+    );
+  });
+
+  it('throws when registerTimeoutMs is non-positive', () => {
+    expect(() => resolveConfig({ target: 'ws://x/', registerTimeoutMs: -1 })).toThrow(
+      /register timeout/i,
+    );
+  });
+
+  it('throws when rampMs is negative', () => {
+    expect(() => resolveConfig({ target: 'ws://x/', rampMs: -5 })).toThrow(/ramp-ms/i);
+  });
+
+  it('throws when messageIntervalMs is negative', () => {
+    expect(() => resolveConfig({ target: 'ws://x/', messageIntervalMs: -1 })).toThrow(
+      /message interval/i,
+    );
+  });
+});
+
+describe('resolveConfig — reportPath propagation', () => {
+  it('sets reportPath when provided', () => {
+    const cfg = resolveConfig({ target: 'ws://x/', reportPath: './out/report.md' });
+    expect(cfg.reportPath).toBe('./out/report.md');
+  });
 });
 
 describe('parseArgs — CLI flag parsing', () => {
@@ -107,6 +136,16 @@ describe('parseArgs — CLI flag parsing', () => {
     expect(() => parseArgs(['--target', 'ws://x/', '--bogus', '1'])).toThrow(/unknown argument/i);
   });
 
+  it('skips sparse (hole) entries in the argv array', () => {
+    // A hole at index 0 exercises the `a === undefined` guard in the parse
+    // loop; the remaining flags still resolve to a valid config.
+    const sparse: string[] = [];
+    sparse[1] = '--target';
+    sparse[2] = 'ws://x/';
+    const cfg = parseArgs(sparse);
+    expect(cfg.target).toBe('ws://x/');
+  });
+
   it('throws when --target is absent and no positional is given', () => {
     expect(() => parseArgs([])).toThrow(/target/i);
   });

package/tools/load-test/tests/harness.test.ts

@@ -81,6 +81,27 @@ describe('runLoadTest — aggregation', () => {
     const md = generateReport(run);
     expect(md).toContain('Latency');
   });
+
+  it('invokes onProgress as each client completes', async () => {
+    const calls: Array<{ done: number; total: number }> = [];
+    const factory = () => ({
+      run: async () =>
+        ({
+          id: 0,
+          ok: true,
+          samples: { connect: [1], register: [], join: [], privmsg: [] },
+        }) as ClientResult,
+    });
+    const run = await runLoadTest(cfg({ connections: 4, connectConcurrency: 2 }), {
+      clientFactory: factory,
+      onProgress: (done, total) => calls.push({ done, total }),
+    });
+    expect(run.summary.totalClients).toBe(4);
+    // Monotonic done counter, one call per client, total stays constant.
+    expect(calls.length).toBe(4);
+    expect(calls.every((c) => c.total === 4)).toBe(true);
+    expect(calls.map((c) => c.done)).toEqual([1, 2, 3, 4]);
+  });
 });
 
 describe('runLoadTest — concurrency cap', () => {

package/tools/load-test/tests/metrics.test.ts

@@ -59,6 +59,13 @@ describe('percentile (nearest-rank)', () => {
   it('throws for a percentile above 100 (programming error)', () => {
     expect(() => percentile([1, 2, 3], 101)).toThrow(/percentile/i);
   });
+
+  it('returns 0 for a NaN percentile (slips the range guard, hits the defensive fallback)', () => {
+    // NaN < 0 and NaN > 100 are both false, so NaN passes the range check.
+    // It then makes the index NaN, so sorted[NaN] is undefined and the
+    // `?? 0` fallback returns 0 rather than NaN.
+    expect(percentile([1, 2, 3], Number.NaN)).toBe(0);
+  });
 });
 
 describe('summarizePhase', () => {

package/tools/tcp-ws-forwarder/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/tcp-ws-forwarder",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": true,
   "description": "Local TCP to ws/wss forwarder so standard IRC clients can reach the WebSocket-only ServerlessIRCd transport",
   "license": "BSD-3-Clause",

package/tools/tcp-ws-forwarder/tests/close-error.test.ts

@@ -0,0 +1,40 @@
+import type { Socket } from 'node:net';
+import { describe, expect, it, vi } from 'vitest';
+
+/**
+ * Dedicated coverage for the `server.close` error-rejection branch in
+ * forwarder close() (forwarder.ts:135): `server.close((err) => err ?
+ * reject(err) : resolve())`. Under normal operation the callback never
+ * surfaces an error, so the truthy branch is unreachable without a stub.
+ *
+ * This file mocks `node:net` so the forwarder's TCP listener gets a server
+ * whose `close` invokes its callback with a synthetic Error. The mock is
+ * file-scoped (vi.mock), leaving the real-socket integration suite in
+ * forwarder.test.ts untouched.
+ */
+
+vi.mock('node:net', async (importActual) => {
+  const actual = await importActual<typeof import('node:net')>();
+  const wrappedCreateServer = (connectionListener?: (socket: Socket) => void) => {
+    const server = actual.createServer(connectionListener);
+    const realClose = server.close.bind(server);
+    // Drive the real shutdown so the listener is actually torn down, but
+    // surface a synthetic error to the callback to exercise the
+    // error-rejection branch.
+    server.close = ((cb?: (err?: Error | null) => void) => {
+      realClose(() => cb?.(new Error('synthetic server.close failure')));
+      return server;
+    }) as unknown as typeof server.close;
+    return server;
+  };
+  return { ...actual, createServer: wrappedCreateServer as unknown as typeof actual.createServer };
+});
+
+const { startForwarder } = await import('../src/forwarder');
+
+describe('forwarder close() — server.close error branch', () => {
+  it('rejects when server.close surfaces an error to its callback', async () => {
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: 'ws://127.0.0.1:1/' });
+    await expect(fwd.close()).rejects.toThrow('synthetic server.close failure');
+  });
+});

package/tools/tcp-ws-forwarder/tests/defensive-branches.test.ts

@@ -0,0 +1,78 @@
+import { EventEmitter } from 'node:events';
+import type { Socket } from 'node:net';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+/**
+ * Coverage for two defensive branches in forwarder.ts that cannot be reached
+ * through real sockets:
+ *   - line 148: `server.address()` always returns an AddressInfo after the
+ *     'listening' event fires, so the `opts.listenPort` ternary fallback is
+ *     never taken in practice.
+ *   - line 184: a connected server-side socket always carries remoteAddress/
+ *     remotePort, so the `?? '?'` remote-label fallbacks are never taken.
+ *
+ * Both are exercised here by mocking `node:net` so the forwarder's TCP server
+ * reports a null address and its connection listener is captured, allowing a
+ * synthetic address-less socket to be fed in. The mock is file-scoped
+ * (vi.mock); the real-socket integration suite in forwarder.test.ts is
+ * untouched.
+ */
+
+const state = vi.hoisted(() => ({
+  captured: undefined as ((socket: Socket) => void) | undefined,
+}));
+
+vi.mock('node:net', async (importActual) => {
+  const actual = await importActual<typeof import('node:net')>();
+  const wrappedCreateServer = (connectionListener?: (socket: Socket) => void) => {
+    state.captured = connectionListener;
+    const server = actual.createServer(connectionListener);
+    // Force the defensive AddressInfo fallback (forwarder.ts:148).
+    server.address = (() => null) as typeof server.address;
+    return server;
+  };
+  return {
+    ...actual,
+    createServer: wrappedCreateServer as unknown as typeof actual.createServer,
+  };
+});
+
+const { startForwarder } = await import('../src/forwarder');
+
+const openForwarders: { close(): Promise<void> }[] = [];
+afterEach(async () => {
+  for (const f of openForwarders.splice(0)) {
+    await f.close().catch(() => undefined);
+  }
+});
+
+describe('forwarder — defensive branches unreachable via real sockets', () => {
+  it('falls back to opts.listenPort when server.address() yields no AddressInfo', async () => {
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: 'ws://127.0.0.1:1/' });
+    openForwarders.push(fwd);
+    // server.address() returns null → the ternary takes its false branch and
+    // the reported port is the requested opts.listenPort (0), not a real
+    // ephemeral port.
+    expect(fwd.listenPort).toBe(0);
+  });
+
+  it('builds the remote label with "?" placeholders for an address-less socket', async () => {
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: 'ws://127.0.0.1:1/' });
+    openForwarders.push(fwd);
+
+    // Synthesize an incoming connection on a socket with no remote address/
+    // port; bridgeConnection must build the `?:?` label (forwarder.ts:184)
+    // and register the bridge without throwing.
+    const fakeSocket = new EventEmitter();
+    Object.assign(fakeSocket, {
+      remoteAddress: undefined,
+      remotePort: undefined,
+      destroy: () => undefined,
+    });
+    const listener = state.captured;
+    if (listener === undefined) throw new Error('connection listener was not captured');
+    listener(fakeSocket as unknown as Socket);
+
+    expect([...fwd.testSockets]).toContain(fakeSocket);
+  });
+});

package/tools/tcp-ws-forwarder/tests/forwarder.test.ts

@@ -735,3 +735,54 @@ describe('forwarder — logging', () => {
     infoSpy.mockRestore();
   });
 });
+
+describe('forwarder — empty-line drop (TCP→WS guard)', () => {
+  it('drops a bare-CRLF empty line and forwards only the next non-empty line', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+
+    // A bare CRLF yields an empty line from the LineScanner; the
+    // `line.length > 0` guard drops it, so only the subsequent real line is
+    // bridged as a single WS frame.
+    client.sendRaw('\r\n');
+    client.send('PING :after-empty');
+
+    const ws = await target.waitForConnection();
+    await new Promise<void>((res) => ws.once('message', () => res()));
+    expect(target.frames).toEqual(['PING :after-empty']);
+  });
+});
+
+describe('forwarder — post-teardown error suppression', () => {
+  it('suppresses a tcp socket error arriving after the bridge has torn down', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+    await target.waitForConnection();
+
+    const serverSide = [...fwd.testSockets][0];
+    if (serverSide === undefined) throw new Error('no server-side socket');
+
+    // Tearing the bridge down arms the `bridgeClosed` guard; a tcp error
+    // arriving afterwards (e.g. an RST echoing our own destroy()) is
+    // expected and must be silently suppressed.
+    await fwd.close();
+
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    serverSide.emit('error', new Error('post-teardown noise'));
+    await new Promise((r) => setImmediate(r));
+    expect(errSpy).not.toHaveBeenCalled();
+    errSpy.mockRestore();
+  });
+});

package/tools/tcp-ws-forwarder/tests/logger.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { ConsoleLogger, LogLevel, parseLogLevel } from '../src/logger';
 
 /**
@@ -134,3 +134,33 @@ describe('ConsoleLogger — output shape', () => {
     expect(JSON.parse(lines.error[0] as string).msg).toBe('e');
   });
 });
+
+describe('ConsoleLogger — global console sinks', () => {
+  it('routes a warn record to the global console.warn sink when no sinks are injected', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const log = new ConsoleLogger(undefined, LogLevel.Warn);
+    log.warn('global sink warn', { k: 'v' });
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const rec = JSON.parse(String(warnSpy.mock.calls[0]?.[0] ?? '{}'));
+    expect(rec.msg).toBe('global sink warn');
+    warnSpy.mockRestore();
+  });
+
+  it('falls back to no-op drop-sinks when globalThis.console is undefined', () => {
+    const original = globalThis.console;
+    (globalThis as { console?: Console | undefined }).console = undefined;
+    try {
+      // globalConsoleSinks() takes the `console === undefined` branch and
+      // returns drop-sinks; every level must swallow without throwing.
+      const log = new ConsoleLogger(undefined, LogLevel.Debug);
+      expect(() => {
+        log.debug('d');
+        log.info('i');
+        log.warn('w');
+        log.error('e');
+      }).not.toThrow();
+    } finally {
+      (globalThis as { console?: Console | undefined }).console = original;
+    }
+  });
+});