serverless-ircd 0.1.0

package/packages/cf-adapter/tests/integration/in-memory-harness.ts

@@ -0,0 +1,242 @@
+/**
+ * In-memory {@link IrcHarness} implementation.
+ *
+ * Wires {@link InMemoryRuntime} + {@link ConnectionActor} into the
+ * harness seam. Each {@link InMemoryHarness} instance is hermetic: fresh
+ * `Map`s, fresh clock, fresh id counter. Tests construct one per `it(...)`
+ * via {@link inMemoryHarnessFactory} and dispose with {@link close}.
+ *
+ * Because the in-memory runtime's send/broadcast/disconnect handlers are
+ * synchronous, by the time `await client.send(line)` resolves every side
+ * effect on every other client's `received` array has already landed.
+ * {@link InMemoryClientHarness.waitForLine} still polls on a short timer
+ * so test code can race `await Promise.all([a.waitForLine(...), b.send(...)])`
+ * without depending on that synchrony — keeps the same scenario code honest
+ * when it runs against the genuinely-async CF / AWS runtimes.
+ */
+
+import { InMemoryRuntime } from '@serverless-ircd/in-memory-runtime';
+import {
+  type ConnId,
+  FakeClock,
+  type RawLine,
+  SequentialIdFactory,
+  StaticMotdProvider,
+  createConnection,
+} from '@serverless-ircd/irc-core';
+import { ConnectionActor } from '@serverless-ircd/irc-server';
+import type {
+  ClientHarness,
+  IrcHarness,
+  IrcHarnessFactory,
+  SpawnClientOptions,
+} from './harness.js';
+
+/** Default tick for the polling waitFor* implementations (ms). */
+const POLL_MS = 10;
+
+/** Default timeout for waitFor* implementations (ms). */
+const DEFAULT_TIMEOUT_MS = 1000;
+
+/** Shared server config used by the harness. Hard-coded — tests assert on it. */
+export const HARNESS_SERVER_CONFIG = {
+  serverName: 'irc.example.com',
+  networkName: 'ExampleNet',
+  maxChannelsPerUser: 30,
+  maxTargetsPerCommand: 10,
+  maxListEntries: 50,
+  nickLen: 30,
+  channelLen: 50,
+  topicLen: 390,
+  quitMessage: 'Client Quit',
+} as const;
+
+/**
+ * Default MOTD lines exposed to every spawned client. The welcome block
+ * always emits the placeholder 375/372/376 numerics; an explicit `MOTD`
+ * command after registration reads these lines via the {@link MotdProvider}
+ * port. Tests assert against this content (scenario: MOTD).
+ */
+const HARNESS_MOTD_LINES = [
+  'Welcome to the ServerlessIRCd integration-test harness.',
+  'All scenarios run parametrized over the IrcRuntime factory matrix.',
+];
+
+/**
+ * Factory entry for the in-memory runtime. Append this to a suite's
+ * FACTORIES array to opt the scenarios into the in-memory matrix.
+ */
+export const inMemoryHarnessFactory: IrcHarnessFactory = Object.freeze({
+  name: 'in-memory',
+  async create() {
+    return new InMemoryHarness();
+  },
+});
+
+interface TrackedClient {
+  harness: InMemoryClientHarness;
+  disconnect: () => void;
+}
+
+export class InMemoryHarness implements IrcHarness {
+  private readonly clock = new FakeClock(0);
+  private readonly runtime = new InMemoryRuntime({ clock: this.clock });
+  private readonly ids = new SequentialIdFactory();
+  private readonly motd = new StaticMotdProvider(HARNESS_MOTD_LINES);
+  private readonly clients = new Map<ConnId, TrackedClient>();
+  private nextId = 0;
+  private closed = false;
+
+  async spawnClient(opts?: SpawnClientOptions): Promise<ClientHarness> {
+    if (this.closed) throw new Error('spawnClient called on a closed harness');
+    const id = opts?.id ?? `c${this.nextId++}`;
+    if (this.clients.has(id)) {
+      throw new Error(`duplicate client id: ${id}`);
+    }
+    const state = createConnection({ id, connectedSince: this.clock.now() });
+
+    const client = new InMemoryClientHarness(id);
+    let disconnected = false;
+    const disconnect = () => {
+      if (disconnected) return;
+      disconnected = true;
+      this.runtime.unregisterConnection(id);
+    };
+
+    this.runtime.registerConnection(state, {
+      send: (lines: RawLine[]) => {
+        for (const l of lines) client.pushReceived(l.text);
+      },
+      disconnect: () => disconnect(),
+    });
+
+    const actor = new ConnectionActor({
+      state,
+      runtime: this.runtime,
+      channels: this.runtime,
+      serverConfig: HARNESS_SERVER_CONFIG,
+      clock: this.clock,
+      ids: this.ids,
+      motd: this.motd,
+    });
+    client.bindActor(actor);
+
+    this.clients.set(id, { harness: client, disconnect });
+
+    if (opts?.nick !== undefined) {
+      await client.send(`NICK ${opts.nick}`);
+      await client.send(`USER ${opts.nick} 0 * :${opts.nick}`);
+      // Welcome fires synchronously through the in-memory runtime's
+      // send handler; by the time send() resolves, the 001 is in
+      // received[]. Await it (with a small timeout safety net) so the
+      // caller can rely on a registered client on return.
+      await client.waitForNumeric('001', DEFAULT_TIMEOUT_MS);
+    }
+    return client;
+  }
+
+  async clientByNick(nick: string): Promise<ClientHarness | undefined> {
+    const connId = await this.runtime.lookupNick(nick);
+    if (connId === null) return undefined;
+    return this.clients.get(connId)?.harness;
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    for (const { disconnect } of this.clients.values()) disconnect();
+    this.clients.clear();
+  }
+}
+
+/**
+ * Per-connection harness. The actor is bound post-construction via
+ * {@link bindActor} so the constructor can register itself with the
+ * runtime before the actor is wired up (the runtime's `send` handler
+ * closes over `client.pushReceived`).
+ */
+class InMemoryClientHarness implements ClientHarness {
+  readonly received: string[] = [];
+  private actor: ConnectionActor | undefined;
+  private closed = false;
+
+  constructor(readonly id: ConnId) {}
+
+  /** Late-bound by the harness once the runtime is registered. */
+  bindActor(actor: ConnectionActor): void {
+    this.actor = actor;
+  }
+
+  pushReceived(text: string): void {
+    this.received.push(text);
+  }
+
+  async send(line: string): Promise<void> {
+    /* istanbul ignore next -- defensive: bindActor is called by the
+       harness before the client is returned, so the unbound-actor branch
+       is unreachable through the public API. */
+    if (this.actor === undefined) {
+      throw new Error(`client ${this.id} has no bound actor`);
+    }
+    await this.actor.receiveTextFrame(`${line}\r\n`);
+  }
+
+  async waitForLine(
+    predicate: (line: string) => boolean,
+    timeoutMs: number = DEFAULT_TIMEOUT_MS,
+  ): Promise<string> {
+    const deadline = Date.now() + timeoutMs;
+    // Scan already-received lines first.
+    for (const line of this.received) {
+      if (predicate(line)) return line;
+    }
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, POLL_MS));
+      for (const line of this.received) {
+        if (predicate(line)) return line;
+      }
+    }
+    throw new Error(
+      `waitForLine timed out after ${timeoutMs}ms; received: ${JSON.stringify(this.received)}`,
+    );
+  }
+
+  async waitForNumeric(
+    code: number | string,
+    timeoutMs: number = DEFAULT_TIMEOUT_MS,
+  ): Promise<string> {
+    const want = typeof code === 'number' ? code.toString().padStart(3, '0') : code;
+    return this.waitForLine((l) => numericEquals(l, want), timeoutMs);
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    // Best-effort QUIT so peers see the part broadcast; the runtime's
+    // disconnect handler is wired by the harness to unregister.
+    if (this.actor !== undefined) {
+      try {
+        await this.actor.receiveTextFrame('QUIT :client closed\r\n');
+        /* istanbul ignore next -- defensive: receiveTextFrame swallows
+           every error internally; the catch is purely a teardown safety
+           net for catastrophic runtime failures. */
+      } catch {
+        // no-op
+      }
+    }
+  }
+}
+
+/**
+ * Returns true iff the second whitespace-delimited token of `line` is
+ * `code` (after the optional `:server` prefix). Matches both
+ * `:irc.example.com 001 nick ...` and the bare `PONG :tok` form (which
+ * has no numeric and therefore does not match).
+ */
+function numericEquals(line: string, code: string): boolean {
+  const parts = line.split(' ');
+  // Skip the optional `:prefix` token.
+  const start = parts[0]?.startsWith(':') ? 1 : 0;
+  const candidate = parts[start];
+  return candidate === code;
+}

package/packages/cf-adapter/tests/integration/index.ts

@@ -0,0 +1,17 @@
+/**
+ * In-tree parametrized IRC scenario suite (folded in from the former
+ * `@serverless-ircd/integration-tests` workspace package).
+ *
+ * Each runtime (in-memory now; CF via `../cf-harness.ts`; AWS in Phase 4)
+ * ships one {@link IrcHarnessFactory}; the scenario tests run against
+ * every registered factory.
+ */
+
+export type {
+  ClientHarness,
+  IrcHarness,
+  IrcHarnessFactory,
+  SpawnClientOptions,
+} from './harness.js';
+export { inMemoryHarnessFactory, HARNESS_SERVER_CONFIG } from './in-memory-harness.js';
+export { runIrcScenarios } from './scenarios.js';

package/packages/cf-adapter/tests/integration/scenarios.test.ts

@@ -0,0 +1,20 @@
+/**
+ * Parametrized IRC scenarios — 032.
+ *
+ * The scenario bodies live in `src/scenarios.ts` (now re-exported as
+ * `runIrcScenarios`) so adapter packages can register their own
+ * {@link IrcHarnessFactory} against the exact same suite under their
+ * native vitest configuration (CF runs in `workerd`, AWS runs in node
+ * with dynamodb-local, etc.). This file is the in-memory entry point —
+ * it registers only {@link inMemoryHarnessFactory}.
+ *
+ * Adding a runtime to the in-memory suite = appending one entry to the
+ * `FACTORIES` array (acceptance criterion: "adding a new runtime
+ * requires only registering a factory").
+ */
+
+import { inMemoryHarnessFactory } from './in-memory-harness.js';
+import { runIrcScenarios } from './scenarios.js';
+
+/** The runtime matrix. Adding a runtime = appending one entry here. */
+runIrcScenarios([inMemoryHarnessFactory]);