serverless-ircd 0.1.0 → 0.2.0

package/packages/aws-adapter/tests/aws-harness.ts

@@ -0,0 +1,408 @@
+/**
+ * AwsHarness — implements the {@link IrcHarnessFactory} port from
+ * `@serverless-ircd/irc-test-support` against the DynamoDB-backed
+ * {@link AwsRuntime}.
+ *
+ * Each {@link AwsHarness} instance:
+ *   1. Generates a unique table-name prefix (so parallel test runs share
+ *      one DynamoDB Local instance without colliding).
+ *   2. Creates five physical tables against `process.env.DYNAMO_ENDPOINT`.
+ *   3. Constructs a single `LocalPostToConnection` test double shared by
+ *      every spawned runtime so cross-connection sends route in-process.
+ *   4. `spawnClient` mints a connection id, persists a Connections row,
+ *      builds an `AwsRuntime` + `ConnectionActor` + `AwsChannelAccess`,
+ *      and registers the new client's sink with the shared management
+ *      double so other connections can postToConnection to it.
+ *   5. `close()` deletes the five tables and clears every client.
+ *
+ * Mirrors `cf-adapter/tests/integration/in-memory-harness.ts` plus the
+ * cross-process send plumbing from `cf-adapter/tests/cf-harness.ts`.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
+import {
+  type ChanName,
+  type ChannelState,
+  type Clock,
+  type ConnId,
+  type ConnectionState,
+  type RawLine,
+  SequentialIdFactory,
+  StaticMotdProvider,
+  SystemClock,
+  createConnection,
+} from '@serverless-ircd/irc-core';
+import { type ActorChannelAccess, ConnectionActor } from '@serverless-ircd/irc-server';
+import type {
+  ClientHarness,
+  IrcHarness,
+  IrcHarnessFactory,
+  SpawnClientOptions,
+} from '@serverless-ircd/irc-test-support';
+import { HARNESS_MOTD_LINES, HARNESS_SERVER_CONFIG } from '@serverless-ircd/irc-test-support';
+import { AwsRuntime, type AwsRuntimeHandlers, type PostToConnection } from '../src/aws-runtime.js';
+import { TABLE_DEFS } from '../src/cdk-table-defs.js';
+import { createDynamoDocumentClient } from '../src/dynamo.js';
+import type { TablesConfig } from '../src/tables.js';
+
+const POLL_MS = 10;
+const DEFAULT_TIMEOUT_MS = 2000;
+
+const endpoint = process.env.DYNAMO_ENDPOINT;
+
+/**
+ * Factory entry — appends to a suite's FACTORIES array to opt the scenarios
+ * into the AWS matrix. Returns a no-op factory when DynamoDB Local is
+ * unavailable so `describe.skipIf` short-circuits before any test runs.
+ */
+export const awsHarnessFactory: IrcHarnessFactory = Object.freeze({
+  name: 'aws',
+  async create() {
+    return new AwsHarness();
+  },
+});
+
+interface TrackedClient {
+  client: AwsClientHandle;
+  actor: ConnectionActor;
+  state: ConnectionState;
+  channelAccess: AwsChannelAccess;
+}
+
+/** Per-test DynamoDB-backed harness. */
+export class AwsHarness implements IrcHarness {
+  private readonly prefix: string;
+  private readonly tables: TablesConfig;
+  private readonly client: ReturnType<typeof createDynamoDocumentClient>;
+  private readonly mgmt = new LocalPostToConnection();
+  private readonly clock: Clock = SystemClock;
+  private readonly ids = new SequentialIdFactory();
+  private readonly motd = new StaticMotdProvider(HARNESS_MOTD_LINES);
+  private readonly tracked = new Map<ConnId, TrackedClient>();
+  private nextId = 0;
+  private closed = false;
+
+  constructor() {
+    if (endpoint === undefined) {
+      throw new Error('DYNAMO_ENDPOINT missing — global-setup did not run');
+    }
+    this.prefix = `t${randomUUID()}-`;
+    this.tables = {
+      Connections: `${this.prefix}Connections`,
+      ChannelMeta: `${this.prefix}ChannelMeta`,
+      ChannelMembers: `${this.prefix}ChannelMembers`,
+      Nicks: `${this.prefix}Nicks`,
+      Accounts: `${this.prefix}Accounts`,
+    };
+    this.client = createDynamoDocumentClient({ endpoint });
+  }
+
+  async spawnClient(opts?: SpawnClientOptions): Promise<ClientHarness> {
+    if (this.closed) throw new Error('spawnClient called on a closed harness');
+    if (this.tracked.size === 0) {
+      // First spawn triggers table creation so an unused harness (e.g. one
+      // that hit a thrown assertion before spawnClient) doesn't leak tables.
+      await this.createTables();
+    }
+    const id = opts?.id ?? `c${this.nextId++}`;
+    if (this.tracked.has(id)) {
+      throw new Error(`duplicate client id: ${id}`);
+    }
+
+    const state = createConnection({ id, connectedSince: this.clock.now() });
+    const clientHandle = new AwsClientHandle(id);
+
+    // Wire the management double so other clients can send to this one.
+    this.mgmt.register(id, (data) => {
+      for (const line of data.split('\r\n')) {
+        if (line.length > 0) clientHandle.pushReceived(line);
+      }
+    });
+
+    const handlers: AwsRuntimeHandlers = {
+      // Self-send: route directly into received (APIGW would echo back to
+      // the open socket — the test doubles that with a local sink).
+      send: (lines: RawLine[]) => {
+        for (const l of lines) clientHandle.pushReceived(l.text);
+      },
+      disconnect: () => {
+        // Lambda cannot close its own WebSocket from inside the handler
+        // (the `$disconnect` route fires when APIGW observes the close).
+        // For test purposes we mark the client as disconnected.
+        clientHandle.markDisconnected();
+      },
+      snapshot: () => state,
+    };
+
+    const runtime = new AwsRuntime({
+      dynamo: this.client,
+      tables: this.tables,
+      connId: id,
+      handlers,
+      managementApi: this.mgmt,
+      clock: this.clock,
+    });
+    await runtime.persistConnectionState(state);
+
+    const channelAccess = new AwsChannelAccess(runtime, this.clock.now());
+
+    const actor = new ConnectionActor({
+      state,
+      runtime,
+      channels: channelAccess,
+      serverConfig: HARNESS_SERVER_CONFIG,
+      clock: this.clock,
+      ids: this.ids,
+      motd: this.motd,
+    });
+    clientHandle.bindActor(actor);
+
+    this.tracked.set(id, { client: clientHandle, actor, state, channelAccess });
+
+    if (opts?.nick !== undefined) {
+      await clientHandle.send(`NICK ${opts.nick}`);
+      await clientHandle.send(`USER ${opts.nick} 0 * :${opts.nick}`);
+      await clientHandle.waitForNumeric('001', DEFAULT_TIMEOUT_MS);
+    }
+    return clientHandle;
+  }
+
+  async clientByNick(nick: string): Promise<ClientHarness | undefined> {
+    // Build a transient runtime just for the lookup. Every runtime reads
+    // from the same DynamoDB tables, so a no-op one suffices.
+    const probe = new AwsRuntime({
+      dynamo: this.client,
+      tables: this.tables,
+      connId: '__lookup__',
+      handlers: {
+        send: () => {},
+        disconnect: () => {},
+        snapshot: () => undefined,
+      },
+      managementApi: this.mgmt,
+      clock: this.clock,
+    });
+    const found = await probe.lookupNick(nick);
+    if (found === null) return undefined;
+    return this.tracked.get(found)?.client;
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    // Best-effort QUIT on every client so peers see PART/QUIT broadcasts.
+    for (const { client } of this.tracked.values()) {
+      try {
+        await client.send('QUIT :client closed');
+      } catch {
+        // Ignore — the actor swallows teardown errors.
+      }
+    }
+    this.tracked.clear();
+    await this.deleteTables();
+  }
+
+  private async createTables(): Promise<void> {
+    for (const [logical, props] of Object.entries(TABLE_DEFS)) {
+      const pkName = props.partitionKey?.name;
+      const skName = props.sortKey?.name;
+      if (pkName === undefined) throw new Error(`table ${logical} missing partitionKey`);
+      const attributeDefinitions: Array<{ AttributeName: string; AttributeType: 'S' }> = [
+        { AttributeName: pkName, AttributeType: 'S' },
+      ];
+      const keySchema: Array<{ AttributeName: string; KeyType: 'HASH' | 'RANGE' }> = [
+        { AttributeName: pkName, KeyType: 'HASH' },
+      ];
+      if (skName !== undefined) {
+        attributeDefinitions.push({ AttributeName: skName, AttributeType: 'S' });
+        keySchema.push({ AttributeName: skName, KeyType: 'RANGE' });
+      }
+      await this.client.send(
+        new CreateTableCommand({
+          TableName: `${this.prefix}${logical}`,
+          AttributeDefinitions: attributeDefinitions,
+          KeySchema: keySchema,
+          BillingMode: 'PAY_PER_REQUEST',
+        }),
+      );
+    }
+  }
+
+  private async deleteTables(): Promise<void> {
+    for (const logical of Object.keys(TABLE_DEFS)) {
+      try {
+        await this.client.send(new DeleteTableCommand({ TableName: `${this.prefix}${logical}` }));
+      } catch {
+        // Idempotent — table may not exist if createTables threw.
+      }
+    }
+  }
+}
+
+/**
+ * Per-connection actor channel access.
+ *
+ * The actor's reducers mutate a local {@link ChannelState} and emit
+ * `ApplyChannelDelta` effects that the runtime forwards to DynamoDB.
+ * For commands that *read* channel state (NAMES, KICK, PART), the
+ * actor calls `refreshChannel(name)` first — we fetch the authoritative
+ * snapshot via {@link AwsRuntime.getChannelSnapshot} and rebuild the
+ * local cache so the reducer sees the current roster.
+ *
+ * Mirrors `cf-adapter/src/connection-do.ts`'s `PassthroughChannelAccess`.
+ */
+class AwsChannelAccess implements ActorChannelAccess {
+  private readonly cache = new Map<string, ChannelState>();
+  constructor(
+    private readonly runtime: AwsRuntime,
+    private readonly now: number,
+  ) {}
+
+  getOrCreateChannel(name: ChanName): ChannelState {
+    const key = name.toLowerCase();
+    const existing = this.cache.get(key);
+    if (existing !== undefined) return existing;
+    const created: ChannelState = {
+      name,
+      nameLower: key,
+      modes: {
+        inviteOnly: false,
+        topicLock: false,
+        noExternal: false,
+        moderated: false,
+        secret: false,
+        private: false,
+      },
+      banMasks: new Set<string>(),
+      members: new Map(),
+      pendingInvites: new Set<string>(),
+      createdAt: this.now,
+    };
+    this.cache.set(key, created);
+    return created;
+  }
+
+  async refreshChannel(name: ChanName): Promise<void> {
+    const key = name.toLowerCase();
+    const snap = await this.runtime.getChannelSnapshot(name);
+    if (snap === null) return;
+    // Don't clobber the cache if the snapshot is empty (the channel
+    // was never created authoritative); let the reducer lazily seed.
+    if (snap.members.size === 0) {
+      // Still preserve modes/topic from meta even without members.
+      const existing = this.cache.get(key);
+      if (existing !== undefined) {
+        existing.modes = { ...snap.modes };
+        existing.banMasks = new Set(snap.banMasks);
+        existing.pendingInvites = new Set(snap.pendingInvites);
+        if (snap.topic !== undefined) existing.topic = snap.topic;
+      }
+      return;
+    }
+    const rebuilt: ChannelState = {
+      name,
+      nameLower: key,
+      modes: { ...snap.modes },
+      banMasks: new Set(snap.banMasks),
+      members: new Map(snap.members),
+      pendingInvites: new Set(snap.pendingInvites),
+      createdAt: snap.createdAt,
+    };
+    if (snap.topic !== undefined) rebuilt.topic = snap.topic;
+    this.cache.set(key, rebuilt);
+  }
+}
+
+/** Aws-backed {@link ClientHarness}. */
+class AwsClientHandle implements ClientHarness {
+  readonly received: string[] = [];
+  private actor: ConnectionActor | undefined;
+  private closed = false;
+  private disconnected = false;
+
+  constructor(readonly id: ConnId) {}
+
+  bindActor(actor: ConnectionActor): void {
+    this.actor = actor;
+  }
+
+  markDisconnected(): void {
+    this.disconnected = true;
+  }
+
+  pushReceived(text: string): void {
+    if (this.disconnected) return;
+    this.received.push(text);
+  }
+
+  async send(line: string): Promise<void> {
+    if (this.actor === undefined) {
+      throw new Error(`client ${this.id} has no bound actor`);
+    }
+    if (this.closed) return;
+    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;
+    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;
+    if (this.actor !== undefined) {
+      try {
+        await this.actor.receiveTextFrame('QUIT :client closed\r\n');
+      } catch {
+        // Swallow — teardown errors are non-fatal.
+      }
+    }
+  }
+}
+
+/**
+ * Test double for `ApiGatewayManagementApi`. Routes `postToConnection`
+ * calls to the registered sink for `ConnectionId`.
+ */
+class LocalPostToConnection implements PostToConnection {
+  private readonly sinks = new Map<string, (data: string) => void>();
+  register(connId: string, sink: (data: string) => void): void {
+    this.sinks.set(connId, sink);
+  }
+  async postToConnection(input: { ConnectionId: string; Data: string }): Promise<unknown> {
+    const sink = this.sinks.get(input.ConnectionId);
+    if (sink !== undefined) sink(input.Data);
+    return {};
+  }
+}
+
+function numericEquals(line: string, code: string): boolean {
+  const parts = line.split(' ');
+  const start = parts[0]?.startsWith(':') ? 1 : 0;
+  const candidate = parts[start];
+  return candidate === code;
+}

package/packages/aws-adapter/tests/aws-integration.test.ts

@@ -0,0 +1,17 @@
+/**
+ * Parametrized IRC scenarios against the AWS runtime.
+ *
+ * Registers the {@link awsHarnessFactory} against the shared scenario
+ * suite from `@serverless-ircd/irc-test-support`. Each scenario builds
+ * a fresh {@link AwsHarness} which mints uniquely-prefixed DynamoDB
+ * tables against the global-setup's endpoint.
+ *
+ * Gated on `process.env.DDB_AVAILABLE`: the suite is skipped when
+ * DynamoDB Local cannot be booted (no Docker, no Java). When available,
+ * every scenario MUST pass — that is the 040 acceptance criterion.
+ */
+
+import { runIrcScenarios } from '@serverless-ircd/irc-test-support';
+import { awsHarnessFactory } from './aws-harness.js';
+
+runIrcScenarios([awsHarnessFactory]);