serverless-ircd 0.5.0 → 0.7.0

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

@@ -0,0 +1,351 @@
+/**
+ * Synthetic IRC load-test client.
+ *
+ * One {@link IrcLoadClient} drives a single WebSocket connection through
+ * the full IRC lifecycle the harness cares about:
+ *
+ *   1. **connect** — WebSocket handshake (`open` event).
+ *   2. **register** — `CAP LS` → (optional `CAP REQ :echo-message`) →
+ *      `NICK`/`USER` → `CAP END`, measured until the server sends `001`.
+ *   3. **join** — `JOIN #chan`, measured until `366` (end of NAMES).
+ *   4. **privmsg** — N × `PRIVMSG #chan :body`, each measured until the
+ *      `echo-message` self-echo arrives (so each message yields one
+ *      round-trip sample).
+ *
+ * The client is transport-agnostic: it only needs a `ws://` / `wss://`
+ * target. {@link IrcLoadClient.run} resolves to a {@link ClientResult}
+ * carrying the per-phase latency samples and, on failure, the phase +
+ * reason (drop attribution). It never throws — failures become
+ * `ok: false` results so the harness can aggregate them into the drop
+ * rate without try/catch per client.
+ */
+
+import { WebSocket } from 'ws';
+import type { LoadTestConfig } from './config.js';
+import type { ClientResult, PhaseName } from './metrics.js';
+
+/** WebSocket constructor type, accepted as an injectable dependency. */
+export type WebSocketCtor = typeof WebSocket;
+
+/** Options accepted by {@link IrcLoadClient}. */
+export interface IrcLoadClientOptions {
+  /** 0-based client index; also disambiguates the nick and message bodies. */
+  id: number;
+  /** Resolved load-test config. */
+  config: LoadTestConfig;
+  /**
+   * Injectable WebSocket constructor. Defaults to the real `ws.WebSocket`;
+   * tests substitute it to drive the lifecycle against fakes. The real
+   * harness always uses the default.
+   */
+  WebSocketCtor?: WebSocketCtor;
+}
+
+/** IRCv3 WebSocket subprotocols offered when dialing (matches the forwarder). */
+const WS_SUBPROTOCOLS = ['binary.ircv3.net', 'text.ircv3.net'] as const;
+
+/** A pending line-waiter registered with `waitForLine`. */
+interface LineWaiter {
+  predicate: (line: string) => boolean;
+  resolve: (line: string) => void;
+  reject: (err: Error) => void;
+  phase: PhaseName;
+  label: string;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * One synthetic IRC client. Construct one per desired connection and
+ * `await client.run()`; the client closes its own socket on completion
+ * (success or failure).
+ */
+export class IrcLoadClient {
+  private readonly id: number;
+  private readonly config: LoadTestConfig;
+  private readonly WebSocketCtor: WebSocketCtor;
+  private ws!: WebSocket;
+  private readonly samples: Record<PhaseName, number[]> = {
+    connect: [],
+    register: [],
+    join: [],
+    privmsg: [],
+  };
+  private readonly waiters: LineWaiter[] = [];
+  /** Set true once we have started tearing down so close/error are idempotent. */
+  private settled = false;
+
+  constructor(opts: IrcLoadClientOptions) {
+    this.id = opts.id;
+    this.config = opts.config;
+    this.WebSocketCtor = opts.WebSocketCtor ?? WebSocket;
+  }
+
+  /** The nick this client registers with (`<nickPrefix><id>`). */
+  get nick(): string {
+    return `${this.config.nickPrefix}${this.id}`;
+  }
+
+  /**
+   * Runs the full lifecycle, resolving to a {@link ClientResult}. Never
+   * rejects — every failure path is captured as `ok: false` with the
+   * phase and reason populated, so the caller can aggregate uniformly.
+   */
+  async run(): Promise<ClientResult> {
+    const failedAt = (phase: PhaseName, err: unknown): ClientResult => ({
+      id: this.id,
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+      failedPhase: phase,
+      samples: this.samples,
+    });
+
+    try {
+      await this.connect();
+      try {
+        await this.register();
+      } catch (err) {
+        return failedAt('register', err);
+      }
+      try {
+        await this.join();
+      } catch (err) {
+        return failedAt('join', err);
+      }
+      if (this.config.messagesPerClient > 0) {
+        try {
+          await this.chat();
+        } catch (err) {
+          return failedAt('privmsg', err);
+        }
+      }
+      return { id: this.id, ok: true, samples: this.samples };
+    } catch (err) {
+      // Only connect-phase failures land here (register/join/chat are
+      // caught above so a later-phase drop keeps its earlier samples).
+      return failedAt('connect', err);
+    } finally {
+      this.teardown();
+    }
+  }
+
+  /** Phase 1: open the WebSocket and record the handshake latency. */
+  private connect(): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const t0 = Date.now();
+      this.ws = new this.WebSocketCtor(this.config.target, [...WS_SUBPROTOCOLS]);
+      const timer = setTimeout(() => {
+        if (!this.settled) {
+          this.failWaiters(new Error(`connect timeout (${this.config.connectTimeoutMs}ms)`));
+          reject(new Error(`connect timeout (${this.config.connectTimeoutMs}ms)`));
+        }
+      }, this.config.connectTimeoutMs);
+
+      this.ws.once('open', () => {
+        clearTimeout(timer);
+        this.samples.connect.push(Date.now() - t0);
+        // Route inbound frames. Attached here (not in the ctor) so a
+        // pre-open error doesn't race a message handler against the reject.
+        this.ws.on('message', (data) => this.onMessage(wsFrameToText(data)));
+        this.ws.once('close', () => this.onClose());
+        this.ws.on('error', (err) => this.onError(err));
+        resolve();
+      });
+      this.ws.once('error', (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+    });
+  }
+
+  /**
+   * Phase 2: negotiate caps + register. Measures from the first
+   * registration byte sent to the `001` welcome numeric.
+   */
+  private async register(): Promise<void> {
+    const t0 = Date.now();
+    if (this.config.echoMessage) {
+      this.send('CAP LS');
+      await this.waitForLine(
+        (l) => l.includes(' CAP * LS :'),
+        'register',
+        'CAP LS reply',
+        this.config.registerTimeoutMs,
+      );
+      this.send('CAP REQ :echo-message');
+      await this.waitForLine(
+        (l) => l.includes(' CAP * ACK :echo-message'),
+        'register',
+        'CAP ACK echo-message',
+        this.config.registerTimeoutMs,
+      );
+    }
+    this.send(`NICK ${this.nick}`);
+    this.send(`USER ${this.nick} 0 * :${this.nick}`);
+    if (this.config.echoMessage) {
+      this.send('CAP END');
+    }
+    await this.waitForLine(
+      (l) => numericOf(l) === '001',
+      'register',
+      '001 welcome',
+      this.config.registerTimeoutMs,
+    );
+    this.samples.register.push(Date.now() - t0);
+  }
+
+  /** Phase 3: JOIN the configured channel, measured until `366`. */
+  private async join(): Promise<void> {
+    const t0 = Date.now();
+    this.send(`JOIN ${this.config.channel}`);
+    await this.waitForLine(
+      (l) => numericOf(l) === '366' && l.includes(this.config.channel),
+      'join',
+      '366 end of NAMES',
+      this.config.registerTimeoutMs,
+    );
+    this.samples.join.push(Date.now() - t0);
+  }
+
+  /**
+   * Phase 4: send N PRIVMSGs and measure each echo round-trip. The body
+   * is unique per (client, message) so the echo match never collides
+   * with another client's broadcast in the shared channel.
+   */
+  private async chat(): Promise<void> {
+    for (let i = 0; i < this.config.messagesPerClient; i++) {
+      const body = `msg-${this.id}-${i}`;
+      const t0 = Date.now();
+      this.send(`PRIVMSG ${this.config.channel} :${body}`);
+      await this.waitForLine(
+        (l) => l.includes('PRIVMSG') && l.includes(this.config.channel) && l.includes(body),
+        'privmsg',
+        `echo for ${body}`,
+        this.config.registerTimeoutMs,
+      );
+      this.samples.privmsg.push(Date.now() - t0);
+      if (i < this.config.messagesPerClient - 1 && this.config.messageIntervalMs > 0) {
+        await delay(this.config.messageIntervalMs);
+      }
+    }
+  }
+
+  /** Sends one bare IRC line as a single WebSocket text frame. */
+  private send(line: string): void {
+    // One message per frame, no trailing CR-LF — the canonical IRCv3 WS
+    // convention the server's ConnectionActor expects. The server is
+    // tolerant of CRLF too, but bare is the wire-spec form.
+    if (this.ws.readyState === this.ws.OPEN) {
+      this.ws.send(line);
+    }
+  }
+
+  /** Splits an inbound WS frame into IRC lines and dispatches to waiters. */
+  private onMessage(text: string): void {
+    for (const line of text.split(/\r?\n/u)) {
+      if (line.length === 0) continue;
+      // Dispatch to the first matching waiter (FIFO preserves phase order).
+      const idx = this.waiters.findIndex((w) => w.predicate(line));
+      if (idx >= 0) {
+        const waiter = this.waiters[idx];
+        if (waiter !== undefined) {
+          this.waiters.splice(idx, 1);
+          clearTimeout(waiter.timer);
+          waiter.resolve(line);
+        }
+      }
+    }
+  }
+
+  /** Connection closed unexpectedly: fail every pending waiter. */
+  private onClose(): void {
+    if (this.settled) return;
+    this.failWaiters(new Error('connection closed by server'));
+  }
+
+  /** Underlying socket error: fail every pending waiter (once). */
+  private onError(err: Error): void {
+    if (this.settled) return;
+    this.failWaiters(err);
+  }
+
+  /**
+   * Resolves the next line matching `predicate` within `timeoutMs`, else
+   * rejects with a timeout error tagged with `label`. The `phase` is
+   * recorded on the waiter purely so a close-during-wait error can be
+   * attributed; the harness reads the failed phase off the outer catch.
+   */
+  private waitForLine(
+    predicate: (line: string) => boolean,
+    phase: PhaseName,
+    label: string,
+    timeoutMs: number,
+  ): Promise<string> {
+    return new Promise<string>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        const idx = this.waiters.findIndex((w) => w.resolve === resolve);
+        if (idx >= 0) this.waiters.splice(idx, 1);
+        reject(new Error(`timed out waiting for ${label} (${timeoutMs}ms)`));
+      }, timeoutMs);
+      this.waiters.push({ predicate, resolve, reject, phase, label, timer });
+    });
+  }
+
+  /** Fails every pending waiter (used on close/error/teardown). */
+  private failWaiters(err: Error): void {
+    const pending = this.waiters.splice(0, this.waiters.length);
+    for (const w of pending) {
+      clearTimeout(w.timer);
+      w.reject(err);
+    }
+  }
+
+  /** Idempotently closes the socket and drains waiters. */
+  private teardown(): void {
+    if (this.settled) return;
+    this.settled = true;
+    this.failWaiters(new Error('client teardown'));
+    try {
+      if (this.ws !== undefined) {
+        // QUIT is best-effort; ignore ready-state edge cases at teardown.
+        if (this.ws.readyState === this.ws.OPEN) {
+          this.ws.send(`QUIT :load-test client ${this.id}`);
+        }
+        this.ws.close();
+      }
+    } catch {
+      // c8 ignore next 1 - defensive: teardown must never throw back
+      // through run()'s finally; a half-closed socket emitting on close()
+      // is the only way to reach here.
+    }
+  }
+}
+
+/**
+ * Normalises a `ws` message payload to a UTF-8 string. Exported so the
+ * `Buffer[]` / `ArrayBuffer` / `Uint8Array` variants — which `ws` only
+ * emits under non-default `binaryType` / fragmentation settings — can be
+ * unit-tested without contriving real socket conditions. Mirrors the
+ * forwarder's `toBuffer` contract.
+ */
+export function wsFrameToText(data: unknown): string {
+  if (typeof data === 'string') return data;
+  if (Array.isArray(data)) {
+    return Buffer.concat(data as ReadonlyArray<Buffer>).toString('utf8');
+  }
+  if (Buffer.isBuffer(data)) return data.toString('utf8');
+  if (data instanceof ArrayBuffer) return Buffer.from(data).toString('utf8');
+  return Buffer.from(data as Uint8Array).toString('utf8');
+}
+
+/** Extracts the IRC numeric (3-digit command) from a line, or `undefined`. */
+function numericOf(line: string): string | undefined {
+  const parts = line.split(' ');
+  const start = parts[0]?.startsWith(':') ? 1 : 0;
+  const candidate = parts[start];
+  return candidate !== undefined && /^\d{3}$/u.test(candidate) ? candidate : undefined;
+}
+
+/** Resolves after `ms` milliseconds. */
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

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

@@ -0,0 +1,313 @@
+/**
+ * Load-test configuration: defaulting, validation, and CLI parsing.
+ *
+ * This is the fail-fast gate for a run (PLAN §6). A malformed
+ * target URL or a nonsensical concurrency value throws here, before the
+ * harness opens a single socket. The parsing mirrors the
+ * `tcp-ws-forwarder` CLI convention (bare positional URL allowed, explicit
+ * `--flag value` pairs, readable error on unknown args).
+ */
+
+/** Fully-resolved configuration for a load-test run. Every field is set. */
+export interface LoadTestConfig {
+  /** Upstream `ws://` / `wss://` URL the synthetic clients dial. */
+  target: string;
+  /**
+   * Human-readable platform label baked into the report header (e.g.
+   * `cf-staging`, `aws-prod`). Defaults to `unknown`.
+   */
+  platform: string;
+  /** Total number of synthetic clients to open. */
+  connections: number;
+  /**
+   * Ramp-up window over which the connections are spread (ms). 0 means
+   * "open them as fast as `connectConcurrency` allows".
+   */
+  rampMs: number;
+  /** Max simultaneous in-flight WebSocket handshakes. */
+  connectConcurrency: number;
+  /** Per-connection timeout for the WebSocket `open` event (ms). */
+  connectTimeoutMs: number;
+  /** Per-connection timeout for registration (NICK/USER → `001`) (ms). */
+  registerTimeoutMs: number;
+  /** Channel every client joins after registering. Must start with `#`. */
+  channel: string;
+  /** Prefix for generated nicks (clients are named `<prefix><index>`). */
+  nickPrefix: string;
+  /** Number of PRIVMSG lines each client sends after joining. 0 = skip chat. */
+  messagesPerClient: number;
+  /** Delay between successive PRIVMSGs from one client (ms). */
+  messageIntervalMs: number;
+  /**
+   * Whether to negotiate the `echo-message` cap so each PRIVMSG echoes
+   * back to the sender (enables per-message round-trip latency). Defaults
+   * to `true` when `messagesPerClient > 0`.
+   */
+  echoMessage: boolean;
+  /** Optional path to write the rendered markdown report to. */
+  reportPath?: string;
+}
+
+/** Defaults applied by {@link resolveConfig} when a field is omitted. */
+export const DEFAULTS = {
+  platform: 'unknown',
+  connections: 1000,
+  rampMs: 0,
+  connectConcurrency: 100,
+  connectTimeoutMs: 10_000,
+  registerTimeoutMs: 15_000,
+  channel: '#loadtest',
+  nickPrefix: 'load',
+  messagesPerClient: 0,
+  messageIntervalMs: 100,
+} as const;
+
+/**
+ * Validates and resolves a partial config into a complete
+ * {@link LoadTestConfig}. Throws synchronously on any invalid value so the
+ * harness never starts a run with a broken configuration.
+ */
+export function resolveConfig(input: Partial<LoadTestConfig>): LoadTestConfig {
+  if (input.target === undefined) {
+    throw new Error('load-test: --target <ws|wss url> is required');
+  }
+  // URL validation: re-uses the same scheme rule as the forwarder so a
+  // typo (`http://`) fails loudly rather than producing a confusing ws error.
+  let url: URL;
+  try {
+    url = new URL(input.target);
+  } catch {
+    throw new Error(`load-test: invalid target URL (expected ws:// or wss://): ${input.target}`);
+  }
+  if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+    throw new Error(
+      `load-test: target URL must use ws:// or wss:// (got ${url.protocol}): ${input.target}`,
+    );
+  }
+
+  const connections = input.connections ?? DEFAULTS.connections;
+  if (!Number.isInteger(connections) || connections < 1) {
+    throw new Error(`load-test: --connections must be a positive integer (got ${connections})`);
+  }
+
+  const connectConcurrency = input.connectConcurrency ?? DEFAULTS.connectConcurrency;
+  if (!Number.isInteger(connectConcurrency) || connectConcurrency < 1) {
+    throw new Error(
+      `load-test: --concurrency must be a positive integer (got ${connectConcurrency})`,
+    );
+  }
+
+  const messagesPerClient = input.messagesPerClient ?? DEFAULTS.messagesPerClient;
+  if (!Number.isInteger(messagesPerClient) || messagesPerClient < 0) {
+    throw new Error(
+      `load-test: --messages must be a non-negative integer (got ${messagesPerClient})`,
+    );
+  }
+
+  const channel = input.channel ?? DEFAULTS.channel;
+  if (!channel.startsWith('#')) {
+    throw new Error(`load-test: --channel must start with '#' (got ${channel})`);
+  }
+
+  const connectTimeoutMs = input.connectTimeoutMs ?? DEFAULTS.connectTimeoutMs;
+  if (connectTimeoutMs <= 0) {
+    throw new Error(`load-test: connect timeout must be positive (got ${connectTimeoutMs})`);
+  }
+  const registerTimeoutMs = input.registerTimeoutMs ?? DEFAULTS.registerTimeoutMs;
+  if (registerTimeoutMs <= 0) {
+    throw new Error(`load-test: register timeout must be positive (got ${registerTimeoutMs})`);
+  }
+
+  const rampMs = input.rampMs ?? DEFAULTS.rampMs;
+  if (rampMs < 0) {
+    throw new Error(`load-test: --ramp-ms must be non-negative (got ${rampMs})`);
+  }
+  const messageIntervalMs = input.messageIntervalMs ?? DEFAULTS.messageIntervalMs;
+  if (messageIntervalMs < 0) {
+    throw new Error(`load-test: message interval must be non-negative (got ${messageIntervalMs})`);
+  }
+
+  // echo-message defaults on when the client is expected to chat; an
+  // explicit override always wins.
+  const echoMessage =
+    input.echoMessage ?? (messagesPerClient > 0 ? true : (input.echoMessage ?? false));
+
+  const cfg: LoadTestConfig = {
+    target: input.target,
+    platform: input.platform ?? DEFAULTS.platform,
+    connections,
+    rampMs,
+    connectConcurrency,
+    connectTimeoutMs,
+    registerTimeoutMs,
+    channel,
+    nickPrefix: input.nickPrefix ?? DEFAULTS.nickPrefix,
+    messagesPerClient,
+    messageIntervalMs,
+    echoMessage,
+  };
+  if (input.reportPath !== undefined) {
+    cfg.reportPath = input.reportPath;
+  }
+  return cfg;
+}
+
+/** Parsed CLI flags, prior to defaulting/validation. */
+type PartialConfig = Partial<LoadTestConfig>;
+
+/** A flag that takes a string value, mapped to its config key. */
+const STRING_FLAGS: Record<
+  string,
+  keyof Pick<LoadTestConfig, 'target' | 'channel' | 'nickPrefix' | 'platform' | 'reportPath'>
+> = {
+  '--target': 'target',
+  '--channel': 'channel',
+  '--nick-prefix': 'nickPrefix',
+  '--platform': 'platform',
+  '--report': 'reportPath',
+};
+
+/** A flag that takes an integer value, mapped to its config key. */
+const NUM_FLAGS: Record<
+  string,
+  keyof Pick<
+    LoadTestConfig,
+    | 'connections'
+    | 'connectConcurrency'
+    | 'rampMs'
+    | 'messagesPerClient'
+    | 'messageIntervalMs'
+    | 'connectTimeoutMs'
+    | 'registerTimeoutMs'
+  >
+> = {
+  '--connections': 'connections',
+  '--concurrency': 'connectConcurrency',
+  '--ramp-ms': 'rampMs',
+  '--messages': 'messagesPerClient',
+  '--message-interval-ms': 'messageIntervalMs',
+  '--connect-timeout-ms': 'connectTimeoutMs',
+  '--register-timeout-ms': 'registerTimeoutMs',
+};
+
+/** Sets one string-valued flag on the partial config (type-safe helper). */
+function setStringFlag(
+  out: PartialConfig,
+  key: keyof Pick<LoadTestConfig, 'target' | 'channel' | 'nickPrefix' | 'platform' | 'reportPath'>,
+  value: string,
+): void {
+  (out as Record<string, unknown>)[key] = value;
+}
+
+/** Sets one integer-valued flag on the partial config (type-safe helper). */
+function setNumFlag(
+  out: PartialConfig,
+  key: keyof Pick<
+    LoadTestConfig,
+    | 'connections'
+    | 'connectConcurrency'
+    | 'rampMs'
+    | 'messagesPerClient'
+    | 'messageIntervalMs'
+    | 'connectTimeoutMs'
+    | 'registerTimeoutMs'
+  >,
+  value: number,
+): void {
+  (out as Record<string, unknown>)[key] = value;
+}
+
+/**
+ * Parses an argv array (`process.argv.slice(2)` shape) into a validated
+ * {@link LoadTestConfig}. Recognised flags:
+ *
+ *   --target <url>         Upstream ws:// or wss:// URL (required).
+ *   --connections <n>      Total synthetic clients (default 1000).
+ *   --concurrency <n>      Max simultaneous handshakes (default 100).
+ *   --ramp-ms <n>          Ramp-up window in ms (default 0).
+ *   --channel <#name>      Channel to join (default #loadtest).
+ *   --nick-prefix <s>      Nick prefix (default load).
+ *   --messages <n>         PRIVMSGs per client (default 0).
+ *   --message-interval-ms <n>  Delay between PRIVMSGs (default 100).
+ *   --no-echo-message      Disable echo-message negotiation.
+ *   --connect-timeout-ms <n>   WebSocket open timeout (default 10000).
+ *   --register-timeout-ms <n>  Registration timeout (default 15000).
+ *   --platform <label>     Report header label (default unknown).
+ *   --report <path>        Write the markdown report to this path.
+ *   -h, --help             Show help and exit.
+ *
+ * A bare positional URL is accepted as the target.
+ */
+export function parseArgs(argv: string[]): LoadTestConfig {
+  const out: PartialConfig = {};
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === undefined) continue;
+    const next = argv[i + 1];
+
+    if (a === '--no-echo-message') {
+      out.echoMessage = false;
+      continue;
+    }
+
+    const stringKey = STRING_FLAGS[a];
+    if (stringKey !== undefined) {
+      if (next === undefined) {
+        throw new Error(`load-test: ${a} requires a value`);
+      }
+      setStringFlag(out, stringKey, next);
+      i++;
+      continue;
+    }
+    const numKey = NUM_FLAGS[a];
+    if (numKey !== undefined) {
+      if (next === undefined) {
+        throw new Error(`load-test: ${a} requires a value`);
+      }
+      const n = Number.parseInt(next, 10);
+      if (!Number.isFinite(n)) {
+        throw new Error(`load-test: ${a} expects an integer (got ${next})`);
+      }
+      setNumFlag(out, numKey, n);
+      i++;
+      continue;
+    }
+
+    // Bare positional URL: `load-test wss://host/`.
+    if (!a.startsWith('-') && out.target === undefined) {
+      out.target = a;
+      continue;
+    }
+
+    throw new Error(`load-test: unknown argument: ${a}`);
+  }
+
+  return resolveConfig(out);
+}
+
+export const HELP_TEXT = [
+  'Usage: load-test --target <ws|wss url> [options]',
+  '',
+  'Synthetic WebSocket IRC client farm (PLAN §6). Opens N',
+  'connections, registers (NICK/USER), joins a channel, and optionally',
+  'chats. Captures p50/p95/p99 latency per phase and the drop rate, then',
+  'prints a markdown report.',
+  '',
+  'Options:',
+  '  --target <url>             Upstream ws:// or wss:// URL (required).',
+  '  --connections <n>          Total synthetic clients (default 1000).',
+  '  --concurrency <n>          Max simultaneous handshakes (default 100).',
+  '  --ramp-ms <n>              Ramp-up window in ms (default 0).',
+  '  --channel <#name>          Channel to join (default #loadtest).',
+  '  --nick-prefix <s>          Nick prefix (default load).',
+  '  --messages <n>             PRIVMSGs per client (default 0 = skip chat).',
+  '  --message-interval-ms <n>  Delay between PRIVMSGs (default 100).',
+  '  --no-echo-message          Disable echo-message negotiation.',
+  '  --connect-timeout-ms <n>   WebSocket open timeout (default 10000).',
+  '  --register-timeout-ms <n>  Registration timeout (default 15000).',
+  '  --platform <label>         Report header label (default unknown).',
+  '  --report <path>            Write the markdown report to this path.',
+  '  -h, --help                 Show this help and exit.',
+  '',
+].join('\n');