serverless-ircd 0.8.0 → 0.9.0

package/apps/cf-tcp-container/tests/container-server.test.ts

@@ -128,6 +128,58 @@ describe('container-server — lifecycle', () => {
   });
 });
 
+describe('container-server — option wiring (coverage matrix)', () => {
+  // Exercises the `opts.X ?? default` / `opts.X !== undefined ? ... : ...`
+  // branches in startContainerServer by starting the server with each optional
+  // knob set, so every "option provided" branch is taken at least once.
+
+  it('binds the default host when `host` is omitted', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      serverName: 'irc.defaulthost',
+      networkName: 'DefaultHostNet',
+    });
+    expect(srv.host).toBe('0.0.0.0');
+    // Connecting via 127.0.0.1 still reaches the 0.0.0.0 listener.
+    const c = new TcpClient('127.0.0.1', srv.port);
+    await c.opened();
+    await c.close();
+    await srv.close();
+  });
+
+  it('applies the default admission knobs when only maxConnectionsPerUser is set', async () => {
+    // Setting only maxConnectionsPerUser builds the admission config, so
+    // maxConnectionsPerIp and perIpConnectionRate fall back to their defaults.
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.admission',
+      networkName: 'AdmissionNet',
+      maxConnectionsPerUser: 5,
+    });
+    const c = new TcpClient('127.0.0.1', srv.port);
+    await c.opened();
+    await c.close();
+    await srv.close();
+  });
+
+  it('wires saslAccounts, serverPassword, and cloaking when provided', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.options',
+      networkName: 'OptionsNet',
+      serverPassword: 'secret',
+      cloaking: { enabled: true, secret: 'cloak-secret', cloakedSuffix: '.hidden' },
+      saslAccounts: [{ username: 'alice', password: 'pw' }],
+    });
+    const c = new TcpClient('127.0.0.1', srv.port);
+    await c.opened();
+    await c.close();
+    await srv.close();
+  });
+});
+
 describe('container-server — IRC flows over TCP', () => {
   let server: ContainerServer;
 
@@ -329,7 +381,6 @@ describe('container-server — snapshot error resilience', () => {
     const path = join(dir, 'corrupt.json');
     const { writeFile } = await import('node:fs/promises');
     await writeFile(path, '{ this is not valid json', 'utf8');
-
     const srv = await startContainerServer({
       port: 0,
       host: '127.0.0.1',
@@ -373,6 +424,61 @@ describe('container-server — snapshot error resilience', () => {
     expect(c.socket.destroyed).toBe(true);
     await rm(dir, { recursive: true, force: true });
   });
+
+  it('close() skips sockets that are already destroyed', async () => {
+    // Covers closeServer's `!socket.destroyed` false branch: a server-side
+    // socket destroyed in the same tick as close() is still in the sockets
+    // set (its 'close' cleanup is async) but already destroyed.
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.skip',
+      networkName: 'SkipNet',
+    });
+    const c = new TcpClient('127.0.0.1', srv.port);
+    await c.opened();
+    for (let i = 0; i < 50 && srv.testSockets.size === 0; i++) {
+      await new Promise((r) => setTimeout(r, 5));
+    }
+    const serverSideSocket = [...srv.testSockets][0];
+    if (serverSideSocket === undefined) throw new Error('no server-side socket');
+    // Destroy the server-side socket synchronously; its 'close' handler
+    // (which would remove it from the set) fires on a later tick.
+    serverSideSocket.destroy();
+    await expect(srv.close()).resolves.toBeUndefined();
+    await new Promise<void>((resolve) => c.socket.once('close', () => resolve()));
+  });
+
+  it('logs and resolves when the final snapshot save fails on close', async () => {
+    // Pointing persistencePath at an existing directory makes the boot-time
+    // load fail (EISDIR → caught → start fresh) AND the close-time save fail
+    // (writeFile on a directory → EISDIR → caught at the closeServer catch).
+    const dir = await mkdtemp(join(tmpdir(), 'sirc-finalfail-'));
+    const { mkdir } = await import('node:fs/promises');
+    const dirPath = join(dir, 'snap-target-dir');
+    await mkdir(dirPath);
+
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.finalfail',
+      networkName: 'FinalFailNet',
+      persistencePath: dirPath,
+      snapshotIntervalMs: 999_999,
+    });
+    const c = new TcpClient('127.0.0.1', srv.port);
+    await c.opened();
+    await c.send('NICK finalFail');
+    await c.send('USER finalFail 0 * :FinalFail');
+    await c.waitFor((l) => l.startsWith(':irc.finalfail 001 '), 2000);
+    // The server destroys live sockets on close; capture the close event first.
+    const closed = new Promise<void>((resolve) => c.socket.once('close', () => resolve()));
+    // close() must resolve (not reject) even though the final snapshot write
+    // throws — the error is logged and swallowed.
+    await expect(srv.close()).resolves.toBeUndefined();
+    await closed;
+    await rm(dir, { recursive: true, force: true });
+  });
 });
 
 describe('container-server — error paths', () => {
@@ -407,6 +513,95 @@ describe('container-server — error paths', () => {
     await srv.close();
   });
 
+  it('logs a non-Error rejection from the actor without crashing', async () => {
+    // logError's `err instanceof Error ? {...} : err` false branch is only
+    // reached when the caught value is NOT an Error instance.
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.nonerr',
+      networkName: 'NonErrNet',
+    });
+    const original = srv.runtime.send.bind(srv.runtime);
+    srv.runtime.send = async () => {
+      // eslint-disable-next-line no-throw-literal
+      throw { code: 'SYNTHETIC', detail: 'not an Error' };
+    };
+    const client = new TcpClient('127.0.0.1', srv.port);
+    await client.opened();
+    await client.send('NICK nonErrUser');
+    await client.send('USER nonErrUser 0 * :NonErr');
+    await client.send('PING :will-throw-non-error');
+    await new Promise((r) => setTimeout(r, 100));
+
+    srv.runtime.send = original;
+    const next = new TcpClient('127.0.0.1', srv.port);
+    await next.opened();
+    await next.send('NICK recover2');
+    await next.send('USER recover2 0 * :Recover2');
+    await next.waitFor((l) => l.startsWith(':irc.nonerr 001 '), 3000);
+    await next.close();
+    await client.close();
+    await srv.close();
+  });
+
+  it('disconnects a connection without an ERROR notice when no reason is supplied', async () => {
+    // Covers the disconnect callback's `reason === undefined` branch: no
+    // `ERROR :Closing link` line is sent, the transport is just closed.
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.noreason',
+      networkName: 'NoReasonNet',
+    });
+    const client = new TcpClient('127.0.0.1', srv.port);
+    await client.opened();
+    await client.send('NICK noReason');
+    await client.send('USER noReason 0 * :NoReason');
+    await client.waitFor((l) => l.startsWith(':irc.noreason 001 '), 2000);
+
+    const connId = await srv.runtime.lookupNick('noReason');
+    expect(connId).not.toBeNull();
+    const closed = new Promise<void>((resolve) => client.socket.once('close', () => resolve()));
+    await srv.runtime.disconnect(connId as string);
+    await closed;
+    // The client must NOT have received an `ERROR :Closing link` line.
+    expect(client.received.some((l) => l.startsWith('ERROR :Closing link:'))).toBe(false);
+    await srv.close();
+  });
+
+  it('skips writing when the server-side socket is no longer writable', async () => {
+    // Covers the sendText callback's `socket.writable` else branch: after the
+    // server-side socket is destroyed (writable=false) but before its 'close'
+    // handler removes the connection, a runtime send must skip the write.
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.unwritable',
+      networkName: 'UnwritableNet',
+    });
+    const client = new TcpClient('127.0.0.1', srv.port);
+    await client.opened();
+    await client.send('NICK unwritable');
+    await client.send('USER unwritable 0 * :Unwritable');
+    await client.waitFor((l) => l.startsWith(':irc.unwritable 001 '), 2000);
+    for (let i = 0; i < 50 && srv.testSockets.size === 0; i++) {
+      await new Promise((r) => setTimeout(r, 5));
+    }
+    const serverSideSocket = [...srv.testSockets][0];
+    if (serverSideSocket === undefined) throw new Error('no server-side socket');
+    const connId = (await srv.runtime.lookupNick('unwritable')) as string;
+    // Destroy the server-side socket: writable flips false synchronously,
+    // while the 'close' cleanup (which unregisters the connection) is queued.
+    serverSideSocket.destroy();
+    // The send resolves without writing because socket.writable is false.
+    await expect(
+      srv.runtime.send(connId, [{ text: ':irc.unwritable NOTICE unwritable :dropped' }]),
+    ).resolves.toBeUndefined();
+    await srv.close();
+    await new Promise<void>((resolve) => client.socket.once('close', () => resolve()));
+  });
+
   it('logs and recovers from a per-socket error', async () => {
     const srv = await startContainerServer({
       port: 0,
@@ -463,3 +658,56 @@ describe('container-server — error paths', () => {
     await rm(dir, { recursive: true, force: true });
   });
 });
+
+describe('container-server — draft/multiline BATCH to a nick target', () => {
+  // Driving a nick-target multi-line batch exercises the `batchId` and
+  // `nonce` id-factory seams in DEFAULT_ID_FACTORY (container-server lines
+  // 96/98), which are only invoked by closeMultilineBatchToNick.
+
+  /** Negotiates `batch` + `draft/multiline`, then registers the nick. */
+  async function registerMultilineCapable(srv: ContainerServer, nick: string): Promise<TcpClient> {
+    const c = new TcpClient('127.0.0.1', srv.port);
+    await c.opened();
+    await c.send('CAP LS 302');
+    await c.waitFor((l) => l.startsWith(':irc.ml CAP * LS :'), 2000);
+    await c.send('CAP REQ :batch draft/multiline');
+    await c.waitFor((l) => l.includes('CAP') && l.includes('ACK'), 2000);
+    await c.send('CAP END');
+    await c.send(`NICK ${nick}`);
+    await c.send(`USER ${nick} 0 * :${nick}`);
+    await c.waitFor((l) => l.startsWith(':irc.ml 001 '), 2000);
+    return c;
+  }
+
+  it('delivers a finalized nick-target batch and exercises batchId/nonce', async () => {
+    const srv = await startContainerServer({
+      port: 0,
+      host: '127.0.0.1',
+      serverName: 'irc.ml',
+      networkName: 'MLNet',
+    });
+    const alice = await registerMultilineCapable(srv, 'alice');
+    const bob = await registerMultilineCapable(srv, 'bob');
+
+    await alice.send('BATCH +m1 draft/multiline :bob');
+    await alice.send('PRIVMSG bob :line one');
+    await alice.send('PRIVMSG bob :line two');
+    await alice.send('BATCH -m1');
+
+    // Bob (also batch+draft/multiline capable) receives the replayed BATCH.
+    // The server allocates a fresh UUID batch id via the batchId() seam.
+    const open = await bob.waitFor(
+      (l) => /^BATCH \+[0-9a-f-]{36} draft\/multiline bob$/u.test(l),
+      3000,
+    );
+    const batchId = open?.match(/^BATCH \+([0-9a-f-]{36})/u)?.[1];
+    expect(batchId).toBeDefined();
+    await bob.waitFor((l) => l.includes(':alice!') && l.includes('PRIVMSG bob :line one'), 2000);
+    await bob.waitFor((l) => l.includes(':alice!') && l.includes('PRIVMSG bob :line two'), 2000);
+    await bob.waitFor((l) => l === `BATCH -${batchId}`, 2000);
+
+    await alice.close();
+    await bob.close();
+    await srv.close();
+  });
+});

package/apps/cf-tcp-container/tests/persistence.test.ts

@@ -143,6 +143,15 @@ describe('persistence — saveSnapshot / loadSnapshot file I/O', () => {
     expect(loaded).toBeNull();
   });
 
+  it('re-throws non-ENOENT read errors (e.g. EISDIR when the path is a directory)', async () => {
+    // Reading a directory produces EISDIR, which is NOT ENOENT, so
+    // loadSnapshot must propagate it instead of treating it as first-boot.
+    const { mkdir } = await import('node:fs/promises');
+    const subDir = join(dir, 'not-a-file-dir');
+    await mkdir(subDir);
+    await expect(loadSnapshot(subDir)).rejects.toThrow();
+  });
+
   it('overwrites a previous snapshot on re-save', async () => {
     const path = join(dir, 'overwrite.json');
     const rt1 = new InMemoryRuntime({ clock: { now: () => 0 } });

package/apps/cf-tcp-container/tests/tls-e2e.test.ts

@@ -1,4 +1,4 @@
-import { execFileSync } from 'node:child_process';
+import { execFile } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { type Socket, createConnection } from 'node:net';
@@ -10,9 +10,21 @@ import {
   connect as tlsConnect,
   createServer as tlsCreateServer,
 } from 'node:tls';
+import { promisify } from 'node:util';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import { type ContainerServer, startContainerServer } from '../src/container-server.js';
 
+const execFileAsync = promisify(execFile);
+
+/**
+ * Maximum wall-clock budget for a single `openssl` invocation. RSA-2048
+ * keygen finishes in well under a second on any modern CPU; if it hasn't
+ * returned by this point the binary is wedged (or the runner is so starved
+ * that the TLS e2e would be flaky anyway), so we skip the suite instead of
+ * stalling the test process.
+ */
+const OPENSSL_TIMEOUT_MS = 15_000;
+
 /**
  * Generates a self-signed TLS certificate for the test proxy using the
  * system `openssl` binary. This mirrors what Cloudflare Spectrum does in
@@ -26,7 +38,12 @@ async function generateSelfSignedCert(dir: string): Promise<{ key: string; cert:
   const keyPath = join(dir, 'key.pem');
   const certPath = join(dir, 'cert.pem');
   try {
-    execFileSync(
+    // Bound openssl: the previous `execFileSync` blocked the event loop,
+    // which defeated vitest's hook timer and let a stuck/missing binary
+    // hang the whole suite. The async call + `timeout` fails fast and
+    // yields control back to the runner; beforeAll swallows the throw and
+    // skips the suite (each test also guards on `cert === undefined`).
+    await execFileAsync(
       'openssl',
       [
         'req',
@@ -43,10 +60,12 @@ async function generateSelfSignedCert(dir: string): Promise<{ key: string; cert:
         '-subj',
         '/CN=localhost',
       ],
-      { stdio: 'pipe' },
+      { timeout: OPENSSL_TIMEOUT_MS },
     );
   } catch {
-    throw new Error('openssl not available — required to generate test TLS cert');
+    throw new Error(
+      `openssl unavailable or did not finish within ${OPENSSL_TIMEOUT_MS}ms — required to generate test TLS cert`,
+    );
   }
   const key = await readFile(keyPath, 'utf8');
   const cert = await readFile(certPath, 'utf8');
@@ -205,7 +224,7 @@ describe('container-server — TLS e2e via in-process proxy (Spectrum analogue)'
       originHost: '127.0.0.1',
       originPort: origin.port,
     });
-  });
+  }, 30_000);
 
   afterAll(async () => {
     if (proxy !== undefined) await proxy.close();

package/apps/cf-worker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-worker",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": true,
   "description": "Cloudflare Worker deploy glue: WebSocket edge entry point + DO bindings + wrangler pipeline",
   "license": "BSD-3-Clause",

package/apps/local-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/local-cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": true,
   "description": "Runnable WebSocket IRC server using the in-memory runtime; manual-test harness and e2e fixture target",
   "license": "BSD-3-Clause",

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

@@ -77,6 +77,7 @@ type ResolvedServerConfig = Omit<
   | 'perIpConnectionRate'
   | 'historyMaxPerChannel'
   | 'saslAccounts'
+  | 'operCreds'
 > &
   Pick<
     LocalServerConfig,
@@ -86,6 +87,7 @@ type ResolvedServerConfig = Omit<
     | 'maxConnectionsPerUser'
     | 'perIpConnectionRate'
     | 'saslAccounts'
+    | 'operCreds'
   >;
 
 /**
@@ -107,6 +109,7 @@ function serverConfigFromResolved(cfg: ResolvedServerConfig): ServerConfig {
     quitMessage: cfg.quitMessage,
     ...(cfg.serverPassword !== undefined ? { serverPassword: cfg.serverPassword } : {}),
     ...(cfg.cloaking !== undefined ? { cloaking: cfg.cloaking } : {}),
+    ...(cfg.operCreds !== undefined ? { operCreds: cfg.operCreds } : {}),
   };
 }
 
@@ -171,6 +174,14 @@ export interface LocalServerConfig {
    * disabled (`ctx.accounts` undefined → `904 ERR_SASLFAIL`).
    */
   saslAccounts?: Array<{ username: string; password: string }>;
+  /**
+   * IRC operator credentials consulted by the `OPER` reducer. When omitted
+   * (or empty) `OPER` receives `491 ERR_NOOPERHOST` and oper-only commands
+   * like `REHASH` are unreachable; supply a non-empty list to let a client
+   * oper up. Threaded straight through to the reducer-facing
+   * {@link ServerConfig} via the shared schema.
+   */
+  readonly operCreds?: Array<{ user: string; password: string }>;
 }
 
 export interface StartServerOptions extends LocalServerConfig {
@@ -235,6 +246,7 @@ const DEFAULT_CONFIG: Omit<
   | 'perIpConnectionRate'
   | 'historyMaxPerChannel'
   | 'saslAccounts'
+  | 'operCreds'
   | 'serverName'
   | 'networkName'
 > = {
@@ -303,6 +315,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
       ...(opts.quitMessage !== undefined ? { quitMessage: opts.quitMessage } : {}),
       ...(opts.saslAccounts !== undefined ? { saslAccounts: opts.saslAccounts } : {}),
       ...(opts.serverPassword !== undefined ? { serverPassword: opts.serverPassword } : {}),
+      ...(opts.operCreds !== undefined ? { operCreds: opts.operCreds } : {}),
     });
   } catch (err) {
     return Promise.reject(err);
@@ -332,6 +345,9 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     ...(opts.saslAccounts !== undefined && opts.saslAccounts.length > 0
       ? { saslAccounts: opts.saslAccounts }
       : {}),
+    ...(opts.operCreds !== undefined && opts.operCreds.length > 0
+      ? { operCreds: opts.operCreds }
+      : {}),
   };
   const hostname = opts.hostname ?? '127.0.0.1';
 
@@ -399,7 +415,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     // Admission gate: refuse the connection BEFORE we attach an actor / emit
     // any IRC state. Keeps per-IP / per-user counters authoritative and
     // avoids burning a nick or runtime slot on a denied client.
-    const ip = req.socket.remoteAddress ?? 'unknown';
+    const ip = peerHost(req.socket.remoteAddress);
     const decision = runtime.admitConnection(ip, undefined);
     if (!decision.ok) {
       ws.send(`ERROR :Closing link: (connection limit reached: ${decision.reason})\r\n`);
@@ -485,12 +501,15 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     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;
+      const wsPort = listenerPort(addr, opts.port);
+
+      // Capture the requested TCP port as a `const` so TS narrows it to
+      // `number` past the `undefined` early-return below (a property access
+      // like `opts.tcpPort` is not narrowed across the closure).
+      const requestedTcpPort = opts.tcpPort;
 
       // If no TCP listener was requested, resolve immediately with just WS.
-      if (opts.tcpPort === undefined) {
+      if (requestedTcpPort === undefined) {
         finishResolve({ wsPort, tcpPort: undefined, tcpServer: undefined });
         return;
       }
@@ -506,12 +525,13 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
 
         // Admission gate — same policy as the WS path: refuse before the
         // actor is attached so per-IP / per-user counters stay authoritative.
-        const ip = socket.remoteAddress ?? 'unknown';
+        const ip = peerHost(socket.remoteAddress);
         const decision = runtime.admitConnection(ip, undefined);
         if (!decision.ok) {
-          if (socket.writable) {
-            socket.write(`ERROR :Closing link: (connection limit reached: ${decision.reason})\r\n`);
-          }
+          safeSocketWrite(
+            socket,
+            `ERROR :Closing link: (connection limit reached: ${decision.reason})\r\n`,
+          );
           socket.destroy();
           tcpSockets.delete(socket);
           return;
@@ -521,7 +541,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
 
         const { state, actor } = attachConnection(runtime, cfg, messages, accounts, history, {
           sendText: (text) => {
-            if (socket.writable) socket.write(text);
+            safeSocketWrite(socket, text);
           },
           closeTransport: () => {
             // `destroy()` over `end()` so a half-closed peer can't hold the
@@ -562,12 +582,10 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
       });
       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;
+        const tcpPort = listenerPort(tcpAddr, requestedTcpPort);
         finishResolve({ wsPort, tcpPort, tcpServer, tcpConnections, tcpSockets });
       });
-      tcpServer.listen(opts.tcpPort, hostname);
+      tcpServer.listen(requestedTcpPort, hostname);
     };
 
     const finishResolve = (args: {
@@ -618,7 +636,12 @@ function attachConnection(
     sendText: (text: string) => void;
     closeTransport: () => void;
     admissionRecordId?: string;
-    sourceHost?: string;
+    /**
+     * Transport-visible source host recorded on the connection state (cloak
+     * input / visible host). Both transports always supply the peer IP, so
+     * this is required rather than optional.
+     */
+    sourceHost: string;
     /**
      * Negotiated IRCv3 WebSocket frame mode for this connection. Spec modes
      * (`spec-text` / `spec-binary`) switch outbound delivery to one WS
@@ -639,9 +662,7 @@ function attachConnection(
   const state = createConnection({ id, connectedSince: Date.now() });
   // Record the transport-visible source host up front. Used as the cloak
   // input when cloaking is enabled, and as the visible host otherwise.
-  if (transport.sourceHost !== undefined) {
-    state.host = transport.sourceHost;
-  }
+  state.host = transport.sourceHost;
 
   // Per-connection logger: every record the actor emits
   // carries this connection's id so the local-cli log stream can be
@@ -731,29 +752,71 @@ function closeEverything(args: {
   // Tear down WS connections + server first.
   const wsClosed = teardownWss(wss, wsConnections);
 
-  // Tear down TCP connections + server in parallel (if enabled).
+  // Tear down TCP connections + server in parallel (if enabled). Both are
+  // captured together (a TCP-disabled server has neither), so the guard is a
+  // single expression covering both the disabled and enabled cases.
   const tcpClosed =
-    tcpServer === undefined
+    tcpServer === undefined || tcpConnections === 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();
+          for (const socket of tcpConnections.keys()) {
+            // Idempotent: a socket already torn down by a reducer-driven
+            // disconnect racing the close sweep is skipped.
+            safeDestroy(socket);
           }
+          tcpConnections.clear();
           tcpServer.close(() => res());
         });
 
   return Promise.all([wsClosed, tcpClosed]).then(() => undefined);
 }
 
+/**
+ * Resolves the visible peer IP for a freshly-accepted socket, falling back to
+ * `'unknown'` when the transport exposes no remote address (e.g. a socket
+ * already torn down at upgrade time). Extracted as a pure helper so the
+ * fallback arm is unit-testable in isolation — the live WS/TCP paths always
+ * observe a concrete `remoteAddress`, so the `'unknown'` arm is unreachable
+ * through the integration suite.
+ */
+export function peerHost(remoteAddress: string | undefined): string {
+  return remoteAddress ?? 'unknown';
+}
+
+/**
+ * Reads the bound port from a listener's `address()` result, falling back to
+ * the requested port for non-IP transports (named-pipe / unix-socket) which
+ * local-cli never binds but the `node:net` typing permits. Pure helper so the
+ * fallback arm is unit-testable; the live listeners always bind IP.
+ */
+export function listenerPort(addr: { port: number } | string | null, fallback: number): number {
+  return typeof addr === 'object' && addr !== null ? addr.port : fallback;
+}
+
+/**
+ * Writes `data` to `socket` only while it is still writable, silently
+ * skipping a destroyed / non-writable socket. Extracted so the non-writable
+ * arm is unit-testable with a fake — the live WS/TCP send paths always
+ * observe a writable transport, and the TCP admission-deny write races a
+ * socket that a peer RST may already have torn down.
+ */
+export function safeSocketWrite(
+  socket: { writable: boolean; write: (data: string) => void },
+  data: string,
+): void {
+  if (socket.writable) socket.write(data);
+}
+
+/**
+ * Destroys `socket` unless it is already destroyed (idempotent teardown).
+ * Extracted so the already-destroyed arm is unit-testable with a fake — the
+ * race that produces an already-destroyed socket still present in the
+ * connection map is not deterministically reproducible in the suite.
+ */
+export function safeDestroy(socket: { destroyed: boolean; destroy(): void }): void {
+  if (!socket.destroyed) socket.destroy();
+}
+
 function logError(msg: string, err: unknown): void {
   // Structured JSON per acceptance criteria.
   const payload = { ts: new Date().toISOString(), level: 'error', msg, err: stringifyErr(err) };