serverless-ircd 0.5.0 → 0.7.0

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

@@ -0,0 +1,212 @@
+import { type LocalServer, startLocalServer } from '@serverless-ircd/local-cli/dist/server.js';
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { WebSocketServer } from 'ws';
+import { IrcLoadClient } from '../src/client';
+import { resolveConfig } from '../src/config';
+
+/**
+ * The synthetic IRC client is exercised against a real in-process IRC
+ * server (`startLocalServer` from local-cli, the project's e2e fixture
+ * target) so the lifecycle — CAP → NICK/USER → CAP END → 001 → JOIN →
+ * 366 → PRIVMSG echo — is faithful to what the load-test harness will
+ * drive against a deployed platform.
+ */
+describe('IrcLoadClient', () => {
+  let irc: LocalServer;
+  let target: string;
+
+  beforeAll(async () => {
+    irc = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.load-test.local',
+      networkName: 'LoadTestNet',
+    });
+    target = `ws://127.0.0.1:${irc.port}/`;
+  });
+
+  afterEach(async () => {
+    // Best-effort: a fresh runtime per test keeps nick/channel state clean.
+    // local-cli's LocalServer has no per-test reset hook; we rely on unique
+    // nicks per test instead (see `cfg()` below).
+  });
+
+  afterAll(async () => {
+    await irc.close();
+  });
+
+  /** Builds a tiny config against the live IRC server with a unique nick. */
+  function cfg(
+    overrides: Parameters<typeof resolveConfig>[0] = {},
+  ): ReturnType<typeof resolveConfig> {
+    return resolveConfig({
+      target,
+      channel: `#load-${Math.random().toString(36).slice(2, 8)}`,
+      nickPrefix: 'load',
+      messagesPerClient: 0,
+      connectTimeoutMs: 2000,
+      registerTimeoutMs: 2000,
+      ...overrides,
+    });
+  }
+
+  it('completes the full lifecycle (connect/register/join) with messagesPerClient=0', async () => {
+    const client = new IrcLoadClient({ id: 1, config: cfg({ messagesPerClient: 0 }) });
+    const result = await client.run();
+    expect(result.ok).toBe(true);
+    expect(result.samples.connect.length).toBe(1);
+    expect(result.samples.register.length).toBe(1);
+    expect(result.samples.join.length).toBe(1);
+    expect(result.samples.privmsg.length).toBe(0);
+    // Latencies are real and positive for a reached phase.
+    expect(result.samples.connect[0]).toBeGreaterThanOrEqual(0);
+    expect(result.samples.register[0]).toBeGreaterThan(0);
+  });
+
+  it('measures a per-message echo latency when echo-message is negotiated', async () => {
+    const client = new IrcLoadClient({
+      id: 2,
+      config: cfg({ messagesPerClient: 3, messageIntervalMs: 0 }),
+    });
+    const result = await client.run();
+    expect(result.ok).toBe(true);
+    expect(result.samples.privmsg.length).toBe(3);
+    for (const lat of result.samples.privmsg) {
+      expect(lat).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  it('reports ok=false with failedPhase=connect against a non-listening port', async () => {
+    // Pick an unused high port by binding+closing to free its number.
+    const client = new IrcLoadClient({
+      id: 3,
+      config: resolveConfig({
+        target: 'ws://127.0.0.1:9/', // port 9 (discard) — refused on most hosts
+        connectTimeoutMs: 1000,
+        registerTimeoutMs: 1000,
+        channel: '#x',
+        messagesPerClient: 0,
+      }),
+    });
+    const result = await client.run();
+    expect(result.ok).toBe(false);
+    expect(result.failedPhase).toBe('connect');
+    expect(result.error).toBeDefined();
+  });
+
+  it('reports ok=false with failedPhase=register against a silent server', async () => {
+    // A WS server that accepts the handshake but never speaks IRC → the
+    // client's wait for 001 must time out at the register phase.
+    const silent = await startSilentWsServer();
+    try {
+      const client = new IrcLoadClient({
+        id: 4,
+        config: resolveConfig({
+          target: `ws://127.0.0.1:${silent.port}/`,
+          connectTimeoutMs: 1000,
+          registerTimeoutMs: 250,
+          channel: '#x',
+          messagesPerClient: 0,
+        }),
+      });
+      const result = await client.run();
+      expect(result.ok).toBe(false);
+      expect(result.failedPhase).toBe('register');
+      // connect succeeded, so a connect sample is present.
+      expect(result.samples.connect.length).toBe(1);
+    } finally {
+      await silent.close();
+    }
+  });
+
+  it('reports ok=false with failedPhase=register when the server closes mid-handshake', async () => {
+    // A WS server that accepts the handshake then immediately closes → the
+    // client's pending register waiter is rejected via the close handler
+    // (exercises failWaiters with a live waiter, not a timeout).
+    const dropping = await startDroppingWsServer();
+    try {
+      const client = new IrcLoadClient({
+        id: 5,
+        config: resolveConfig({
+          target: `ws://127.0.0.1:${dropping.port}/`,
+          connectTimeoutMs: 1000,
+          registerTimeoutMs: 2000,
+          channel: '#x',
+          messagesPerClient: 0,
+        }),
+      });
+      const result = await client.run();
+      expect(result.ok).toBe(false);
+      expect(result.failedPhase).toBe('register');
+      expect(result.samples.connect.length).toBe(1);
+    } finally {
+      await dropping.close();
+    }
+  });
+
+  it('paces PRIVMSGs by messageIntervalMs (>0 path)', async () => {
+    const client = new IrcLoadClient({
+      id: 6,
+      config: cfg({ messagesPerClient: 2, messageIntervalMs: 20 }),
+    });
+    const result = await client.run();
+    expect(result.ok).toBe(true);
+    expect(result.samples.privmsg.length).toBe(2);
+  });
+});
+
+/** A minimal WS server that completes the handshake but sends nothing. */
+function startSilentWsServer(): Promise<{ port: number; close: () => Promise<void> }> {
+  return new Promise((resolve, reject) => {
+    const wss = new WebSocketServer({ port: 0 });
+    const onError = (err: Error): void => {
+      wss.close();
+      reject(err);
+    };
+    wss.once('listening', () => {
+      wss.removeListener('error', onError);
+      const addr = wss.address();
+      const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+      resolve({
+        port,
+        close: () =>
+          new Promise<void>((res) => {
+            wss.close(() => res());
+          }),
+      });
+    });
+    wss.once('error', onError);
+  });
+}
+
+/**
+ * A WS server that accepts a connection then immediately closes it, so the
+ * client's pending register waiter is rejected via the close handler
+ * rather than a timeout.
+ */
+function startDroppingWsServer(): Promise<{ port: number; close: () => Promise<void> }> {
+  return new Promise((resolve, reject) => {
+    const wss = new WebSocketServer({ port: 0 });
+    const onError = (err: Error): void => {
+      wss.close();
+      reject(err);
+    };
+    wss.on('connection', (sock) => {
+      // Drop immediately; simulate a server that tears down mid-handshake.
+      sock.close();
+    });
+    wss.once('listening', () => {
+      wss.removeListener('error', onError);
+      const addr = wss.address();
+      const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+      resolve({
+        port,
+        close: () =>
+          new Promise<void>((res) => {
+            wss.close(() => res());
+          }),
+      });
+    });
+    wss.once('error', onError);
+  });
+}

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

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest';
+import { type LoadTestConfig, parseArgs, resolveConfig } from '../src/config';
+
+/**
+ * The config module owns defaulting + validation for a load-test run. It is
+ * the fail-fast gate: a malformed target URL or a nonsensical concurrency
+ * value throws here, before the harness opens a single socket.
+ */
+describe('resolveConfig — defaults', () => {
+  it('applies documented defaults when only the target is supplied', () => {
+    const cfg = resolveConfig({ target: 'ws://127.0.0.1:6667/' });
+    expect(cfg.target).toBe('ws://127.0.0.1:6667/');
+    expect(cfg.connections).toBeGreaterThan(0);
+    expect(cfg.channel.startsWith('#')).toBe(true);
+    expect(cfg.messagesPerClient).toBeGreaterThanOrEqual(0);
+    expect(cfg.connectConcurrency).toBeGreaterThanOrEqual(1);
+    expect(cfg.connectTimeoutMs).toBeGreaterThan(0);
+    expect(cfg.registerTimeoutMs).toBeGreaterThan(0);
+    expect(cfg.rampMs).toBeGreaterThanOrEqual(0);
+    expect(cfg.messageIntervalMs).toBeGreaterThanOrEqual(0);
+  });
+
+  it('respects explicit overrides over defaults', () => {
+    const cfg = resolveConfig({
+      target: 'wss://irc.example.com/',
+      connections: 25000,
+      channel: '#perf',
+      messagesPerClient: 7,
+      messageIntervalMs: 50,
+      rampMs: 30_000,
+      connectConcurrency: 500,
+    });
+    expect(cfg.connections).toBe(25000);
+    expect(cfg.channel).toBe('#perf');
+    expect(cfg.messagesPerClient).toBe(7);
+    expect(cfg.messageIntervalMs).toBe(50);
+    expect(cfg.rampMs).toBe(30_000);
+    expect(cfg.connectConcurrency).toBe(500);
+  });
+});
+
+describe('resolveConfig — validation (fail-fast)', () => {
+  it('throws when the target is missing entirely', () => {
+    expect(() => resolveConfig({})).toThrow(/target/i);
+  });
+
+  it('throws for a non-ws scheme', () => {
+    expect(() => resolveConfig({ target: 'http://example.com/' })).toThrow(/ws:\/\/|wss:\/\//);
+  });
+
+  it('throws for an unparseable target URL', () => {
+    expect(() => resolveConfig({ target: 'not a url' })).toThrow(/target/i);
+  });
+
+  it('throws when connections < 1', () => {
+    expect(() => resolveConfig({ target: 'ws://x/', connections: 0 })).toThrow(/connections/i);
+  });
+
+  it('throws when connectConcurrency < 1', () => {
+    expect(() => resolveConfig({ target: 'ws://x/', connectConcurrency: 0 })).toThrow(
+      /concurrency/i,
+    );
+  });
+
+  it('throws when messagesPerClient is negative', () => {
+    expect(() => resolveConfig({ target: 'ws://x/', messagesPerClient: -1 })).toThrow(/messages/i);
+  });
+
+  it('throws when the channel does not start with #', () => {
+    expect(() => resolveConfig({ target: 'ws://x/', channel: 'loadtest' })).toThrow(/channel/i);
+  });
+});
+
+describe('parseArgs — CLI flag parsing', () => {
+  it('parses the full flag set into a resolved config', () => {
+    const cfg = parseArgs([
+      '--target',
+      'wss://irc.staging.example.com/',
+      '--connections',
+      '10000',
+      '--channel',
+      '#loadtest',
+      '--messages',
+      '3',
+      '--ramp-ms',
+      '60000',
+      '--concurrency',
+      '200',
+      '--platform',
+      'cf-staging',
+    ]);
+    expect(cfg.target).toBe('wss://irc.staging.example.com/');
+    expect(cfg.connections).toBe(10000);
+    expect(cfg.channel).toBe('#loadtest');
+    expect(cfg.messagesPerClient).toBe(3);
+    expect(cfg.rampMs).toBe(60_000);
+    expect(cfg.connectConcurrency).toBe(200);
+    expect(cfg.platform).toBe('cf-staging');
+  });
+
+  it('allows a bare positional target URL', () => {
+    const cfg = parseArgs(['ws://localhost:8787/']);
+    expect(cfg.target).toBe('ws://localhost:8787/');
+  });
+
+  it('throws on an unknown flag', () => {
+    expect(() => parseArgs(['--target', 'ws://x/', '--bogus', '1'])).toThrow(/unknown argument/i);
+  });
+
+  it('throws when --target is absent and no positional is given', () => {
+    expect(() => parseArgs([])).toThrow(/target/i);
+  });
+
+  it('throws on a non-numeric --connections', () => {
+    expect(() => parseArgs(['--target', 'ws://x/', '--connections', 'lots'])).toThrow();
+  });
+
+  it('disables echo-message with --no-echo-message', () => {
+    const cfg = parseArgs(['ws://x/', '--messages', '3', '--no-echo-message']);
+    expect(cfg.echoMessage).toBe(false);
+  });
+
+  it('throws when a string flag has no following value', () => {
+    expect(() => parseArgs(['--target'])).toThrow(/requires a value/i);
+  });
+
+  it('throws when a numeric flag has no following value', () => {
+    expect(() => parseArgs(['ws://x/', '--connections'])).toThrow(/requires a value/i);
+  });
+
+  it('echo-message defaults on when --messages > 0 and off when 0', () => {
+    expect(parseArgs(['ws://x/', '--messages', '2']).echoMessage).toBe(true);
+    expect(parseArgs(['ws://x/', '--messages', '0']).echoMessage).toBe(false);
+  });
+
+  it('emits a typed LoadTestConfig (compile-time shape check)', () => {
+    const cfg: LoadTestConfig = parseArgs(['ws://127.0.0.1:6667/']);
+    // Touch every field so a rename/refactor breaks this test loudly.
+    expect(typeof cfg.target).toBe('string');
+    expect(typeof cfg.platform).toBe('string');
+    expect(typeof cfg.connections).toBe('number');
+    expect(typeof cfg.rampMs).toBe('number');
+    expect(typeof cfg.connectConcurrency).toBe('number');
+    expect(typeof cfg.connectTimeoutMs).toBe('number');
+    expect(typeof cfg.registerTimeoutMs).toBe('number');
+    expect(typeof cfg.channel).toBe('string');
+    expect(typeof cfg.nickPrefix).toBe('string');
+    expect(typeof cfg.messagesPerClient).toBe('number');
+    expect(typeof cfg.messageIntervalMs).toBe('number');
+    expect(typeof cfg.echoMessage).toBe('boolean');
+  });
+});

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

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { wsFrameToText } from '../src/client';
+
+/**
+ * Pure unit tests for the ws payload normaliser. The `Buffer[]` /
+ * `ArrayBuffer` / `Uint8Array` variants only appear under non-default
+ * `binaryType` / fragmentation settings, so they are pinned here in
+ * isolation rather than through real sockets. Mirrors the forwarder's
+ * `toBuffer` contract.
+ */
+describe('wsFrameToText', () => {
+  it('returns a string payload unchanged', () => {
+    expect(wsFrameToText(':srv 001 nick :Hi')).toBe(':srv 001 nick :Hi');
+  });
+
+  it('decodes a Buffer payload as UTF-8', () => {
+    expect(wsFrameToText(Buffer.from('hello', 'utf8'))).toBe('hello');
+  });
+
+  it('concatenates a Buffer[] payload', () => {
+    expect(wsFrameToText([Buffer.from('foo', 'utf8'), Buffer.from('bar', 'utf8')])).toBe('foobar');
+  });
+
+  it('wraps an ArrayBuffer payload', () => {
+    const src = new ArrayBuffer(3);
+    new Uint8Array(src).set([0x41, 0x42, 0x43]); // 'ABC'
+    expect(wsFrameToText(src)).toBe('ABC');
+  });
+
+  it('copies a Uint8Array payload', () => {
+    expect(wsFrameToText(new Uint8Array([0x41, 0x42, 0x43]))).toBe('ABC');
+  });
+
+  it('preserves multi-byte UTF-8 across the Buffer path', () => {
+    expect(wsFrameToText(Buffer.from('café', 'utf8'))).toBe('café');
+  });
+});

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

@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'vitest';
+import { resolveConfig } from '../src/config';
+import { type SyntheticClient, runLoadTest } from '../src/harness';
+import type { ClientResult } from '../src/metrics';
+import { generateReport } from '../src/report';
+
+/**
+ * The harness is the orchestrator: it spawns N synthetic clients under a
+ * concurrency cap, ramps them over a window, and aggregates their results.
+ *
+ * The smoke test against the real in-process IRC server is the ticket's
+ * explicit acceptance criterion ("load test script completes without
+ * crashing"); the fake-factory tests pin the concurrency cap, ramp, and
+ * aggregation math without touching real sockets.
+ */
+function cfg(
+  overrides: Parameters<typeof resolveConfig>[0] = {},
+): ReturnType<typeof resolveConfig> {
+  return resolveConfig({
+    target: 'ws://127.0.0.1:1/',
+    connections: 10,
+    connectConcurrency: 3,
+    rampMs: 0,
+    messagesPerClient: 0,
+    channel: '#loadtest',
+    // Short timeouts so a fake that never resolves still completes quickly.
+    connectTimeoutMs: 100,
+    registerTimeoutMs: 100,
+    ...overrides,
+  });
+}
+
+/** Builds a fake client factory whose clients resolve to scripted results. */
+function scriptedFactory(results: ClientResult[]): (opts: unknown) => SyntheticClient {
+  let i = 0;
+  return () => {
+    const idx = i++;
+    const result = results[idx % results.length] ?? {
+      id: idx,
+      ok: true,
+      samples: { connect: [1], register: [], join: [], privmsg: [] },
+    };
+    return {
+      run: async () => ({ ...result, id: idx }),
+    };
+  };
+}
+
+describe('runLoadTest — aggregation', () => {
+  it('collects every client result into the summary', async () => {
+    const results: ClientResult[] = [
+      { id: 0, ok: true, samples: { connect: [10], register: [20], join: [5], privmsg: [] } },
+      { id: 1, ok: true, samples: { connect: [12], register: [25], join: [6], privmsg: [] } },
+      {
+        id: 2,
+        ok: false,
+        error: 'register timeout',
+        failedPhase: 'register',
+        samples: { connect: [9], register: [], join: [], privmsg: [] },
+      },
+    ];
+    const run = await runLoadTest(cfg({ connections: 3 }), {
+      clientFactory: scriptedFactory(results),
+    });
+    expect(run.summary.totalClients).toBe(3);
+    expect(run.summary.succeeded).toBe(2);
+    expect(run.summary.failed).toBe(1);
+    expect(run.summary.dropRate).toBeCloseTo(1 / 3, 5);
+    expect(run.summary.phases.connect.count).toBe(3);
+    expect(run.summary.phases.register.count).toBe(2);
+  });
+
+  it('returns a LoadTestRun carrying config + timing + a renderable report', async () => {
+    const run = await runLoadTest(cfg({ connections: 2 }), {
+      clientFactory: scriptedFactory([
+        { id: 0, ok: true, samples: { connect: [10], register: [20], join: [5], privmsg: [] } },
+      ]),
+    });
+    expect(run.config.connections).toBe(2);
+    expect(run.durationMs).toBeGreaterThanOrEqual(0);
+    const md = generateReport(run);
+    expect(md).toContain('Latency');
+  });
+});
+
+describe('runLoadTest — concurrency cap', () => {
+  it('never exceeds connectConcurrency simultaneous in-flight clients', async () => {
+    const tracker = new ConcurrencyTracker();
+    const factory = () => ({
+      run: () =>
+        tracker.run(async () => {
+          const samples = { connect: [1], register: [], join: [], privmsg: [] };
+          return { id: 0, ok: true, samples } as ClientResult;
+        }),
+    });
+    const run = await runLoadTest(cfg({ connections: 20, connectConcurrency: 4 }), {
+      clientFactory: factory,
+    });
+    expect(run.summary.totalClients).toBe(20);
+    expect(tracker.maxObserved).toBeLessThanOrEqual(4);
+    expect(tracker.maxObserved).toBeGreaterThanOrEqual(1);
+  });
+});
+
+describe('runLoadTest — ramp', () => {
+  it('spreads client launches across the ramp window', async () => {
+    const starts: number[] = [];
+    const t0 = Date.now();
+    const factory = () => ({
+      run: async () => {
+        starts.push(Date.now() - t0);
+        // a tiny yield so the event loop can interleave launches
+        await Promise.resolve();
+        return {
+          id: 0,
+          ok: true,
+          samples: { connect: [1], register: [], join: [], privmsg: [] },
+        } as ClientResult;
+      },
+    });
+    // 5 clients, ramp 200ms → launches should spread ~50ms apart. With
+    // concurrency 5 they all queue immediately but each launch is delayed
+    // by its ramp share, so the last launch should land well after the first.
+    await runLoadTest(cfg({ connections: 5, connectConcurrency: 5, rampMs: 200 }), {
+      clientFactory: factory,
+    });
+    starts.sort((a, b) => a - b);
+    const first = starts[0] ?? 0;
+    const last = starts[4] ?? 0;
+    const spread = last - first;
+    expect(spread).toBeGreaterThanOrEqual(150);
+  });
+
+  it('completes instantly when rampMs=0 (burst)', async () => {
+    const factory = () => ({
+      run: async () =>
+        ({
+          id: 0,
+          ok: true,
+          samples: { connect: [1], register: [], join: [], privmsg: [] },
+        }) as ClientResult,
+    });
+    const t0 = Date.now();
+    await runLoadTest(cfg({ connections: 10, connectConcurrency: 10, rampMs: 0 }), {
+      clientFactory: factory,
+    });
+    expect(Date.now() - t0).toBeLessThan(500);
+  });
+});
+
+/** Tracks the high-water mark of concurrently in-flight fake clients. */
+class ConcurrencyTracker {
+  active = 0;
+  maxObserved = 0;
+
+  async run<T>(fn: () => Promise<T>): Promise<T> {
+    this.active++;
+    if (this.active > this.maxObserved) this.maxObserved = this.active;
+    try {
+      return await fn();
+    } finally {
+      this.active--;
+    }
+  }
+}