serverless-ircd 0.1.0 → 0.3.0

package/packages/aws-adapter/tests/global-setup.ts

@@ -0,0 +1,301 @@
+/**
+ * Vitest `globalSetup` — boots a DynamoDB Local instance once per test run
+ * and exposes its endpoint via `process.env.DYNAMO_ENDPOINT`.
+ *
+ * Strategy (in priority order):
+ *
+ *   1. **testcontainers** — preferred, matches CI. Spins up the canonical
+ *      `amazon/dynamodb-local` Docker image. Requires Docker.
+ *   2. **DynamoDB Local ZIP + Java** — development fallback for hosts
+ *      with Java (e.g. dev laptops without Docker Desktop). Downloads
+ *      the official AWS ZIP once into a per-user cache dir, runs it
+ *      with `-inMemory` so per-run state is isolated by port.
+ *   3. **Skip** — sets `process.env.DDB_AVAILABLE = '0'`; integration
+ *      tests gate themselves on this via `describe.skipIf`.
+ *
+ * The skip path keeps the suite green in environments that legitimately
+ * can't run DynamoDB Local (no Docker, no Java). The acceptance criterion
+ * is "all 31 scenarios pass when DDB is available", not "every dev box
+ * runs them".
+ */
+
+import { execSync, spawn } from 'node:child_process';
+import { exec as execCb } from 'node:child_process';
+import { createWriteStream, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { type RequestOptions, request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { type Server, createServer } from 'node:net';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+const execAsync = promisify(execCb);
+
+const DDB_LOCAL_IMAGE = 'amazon/dynamodb-local:2.5.3';
+/** Official AWS-hosted DynamoDB Local distribution (ZIP). */
+const DDB_LOCAL_ZIP_URL =
+  'https://s3.us-west-2.amazonaws.com/dynamodb-local/dynamodb_local_latest.zip';
+const CACHE_DIR = join(homedir(), '.cache', 'serverless-ircd', 'ddb-local');
+const MARKER_PATH = join(CACHE_DIR, '.installed');
+const JAR_PATH = join(CACHE_DIR, 'DynamoDBLocal.jar');
+const LIB_PATH = join(CACHE_DIR, 'DynamoDBLocal_lib');
+
+/** Idle health-check loop interval (ms). */
+const HEALTH_INTERVAL_MS = 200;
+/** Cap on how long we wait for DynamoDB Local to answer ListTables. */
+const HEALTH_TIMEOUT_MS = 20_000;
+
+interface DdbHandle {
+  endpoint: string;
+  stop: () => Promise<void>;
+}
+
+export default async function globalSetup(): Promise<(() => Promise<void>) | undefined> {
+  // Strategy 1: testcontainers (Docker).
+  try {
+    const handle = await tryTestcontainers();
+    if (handle !== null) {
+      process.env.DDB_AVAILABLE = '1';
+      process.env.DYNAMO_ENDPOINT = handle.endpoint;
+      console.warn(`[aws-adapter global-setup] DynamoDB Local via Docker at ${handle.endpoint}`);
+      return async () => {
+        await handle.stop();
+      };
+    }
+  } catch (err: unknown) {
+    console.warn('[aws-adapter global-setup] testcontainers unavailable:', renderErr(err));
+  }
+
+  // Strategy 2: local ZIP + Java.
+  try {
+    const handle = await tryZip();
+    if (handle !== null) {
+      process.env.DDB_AVAILABLE = '1';
+      process.env.DYNAMO_ENDPOINT = handle.endpoint;
+      console.warn(`[aws-adapter global-setup] DynamoDB Local via Java ZIP at ${handle.endpoint}`);
+      return async () => {
+        await handle.stop();
+      };
+    }
+  } catch (err: unknown) {
+    console.warn('[aws-adapter global-setup] ZIP fallback unavailable:', renderErr(err));
+  }
+
+  // Strategy 3: skip.
+  console.warn(
+    '[aws-adapter global-setup] No DynamoDB Local backend available (need Docker or Java). ' +
+      'Integration tests will be skipped.',
+  );
+  process.env.DDB_AVAILABLE = '0';
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Strategy 1: testcontainers
+// ---------------------------------------------------------------------------
+
+async function tryTestcontainers(): Promise<DdbHandle | null> {
+  let mod: typeof import('testcontainers') | undefined;
+  try {
+    mod = await import('testcontainers');
+  } catch {
+    return null;
+  }
+  const container = await new mod.GenericContainer(DDB_LOCAL_IMAGE)
+    .withExposedPorts(8000)
+    .withWaitStrategy(mod.Wait.forLogMessage(/Started ScriptEnvironment/u, 2))
+    .start();
+  const port = container.getMappedPort(8000);
+  const host = container.getHost();
+  const endpoint = `http://${host}:${port}`;
+  await waitForHealthy(endpoint);
+  return {
+    endpoint,
+    stop: async () => {
+      await container.stop();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Strategy 2: DynamoDB Local ZIP + Java
+// ---------------------------------------------------------------------------
+
+async function tryZip(): Promise<DdbHandle | null> {
+  // Find any Java on PATH; the official ZIP's bundled version works with
+  // Java 8+, so we don't need a specific major version.
+  const javaBin = which('java');
+  if (javaBin === null) return null;
+  await ensureZipInstalled();
+  const port = await pickFreePort();
+  const endpoint = `http://localhost:${port}`;
+  const child = spawn(
+    javaBin,
+    [`-Djava.library.path=${LIB_PATH}`, '-jar', JAR_PATH, '-port', String(port), '-inMemory'],
+    { stdio: 'ignore', detached: false, cwd: CACHE_DIR },
+  );
+  const crashed = new Promise<void>((resolve) => {
+    child.on('exit', () => resolve());
+  });
+  try {
+    await waitForHealthy(endpoint);
+  } catch (err) {
+    child.kill('SIGKILL');
+    throw err;
+  }
+  return {
+    endpoint,
+    stop: async () => {
+      child.kill('SIGTERM');
+      await Promise.race([crashed, new Promise<void>((resolve) => setTimeout(resolve, 1500))]);
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        // Already gone.
+      }
+    },
+  };
+}
+
+async function ensureZipInstalled(): Promise<void> {
+  if (existsSync(MARKER_PATH) && existsSync(JAR_PATH) && existsSync(LIB_PATH)) return;
+  mkdirSync(CACHE_DIR, { recursive: true });
+  const zipPath = join(CACHE_DIR, 'dynamodb_local.zip');
+  await downloadFile(DDB_LOCAL_ZIP_URL, zipPath);
+  // `unzip` ships with macOS and most Linux distros; fall back to jar tooling
+  // if absent (the JAR can also extract ZIPs).
+  if (which('unzip') !== null) {
+    await execAsync(`unzip -q -o ${quote(zipPath)} -d ${quote(CACHE_DIR)}`);
+  } else {
+    // java -jar DynamoDBLocal.jar would explode on a non-DDB zip; use
+    // Python's zipfile as a portable fallback.
+    await execAsync(
+      `python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).extractall(sys.argv[2])" ${quote(zipPath)} ${quote(CACHE_DIR)}`,
+    );
+  }
+  // Marker write happens last so a partial extraction is detectable.
+  const { writeFileSync } = await import('node:fs');
+  writeFileSync(MARKER_PATH, new Date().toISOString());
+}
+
+function downloadFile(url: string, dest: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tmp = `${dest}.tmp`;
+    const file = createWriteStream(tmp);
+    const req = httpsRequest(url, (res) => {
+      if (res.statusCode !== 200) {
+        reject(new Error(`download failed: ${res.statusCode ?? '?'} for ${url}`));
+        return;
+      }
+      res.pipe(file);
+      file.on('finish', () => {
+        file.close(() => {
+          renameSync(tmp, dest);
+          resolve();
+        });
+      });
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+function pickFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv: Server = createServer();
+    srv.unref();
+    srv.on('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const addr = srv.address();
+      if (addr === null || typeof addr === 'string') {
+        reject(new Error('failed to pick free port'));
+        return;
+      }
+      const port = addr.port;
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Health check
+// ---------------------------------------------------------------------------
+
+async function waitForHealthy(endpoint: string): Promise<void> {
+  const deadline = Date.now() + HEALTH_TIMEOUT_MS;
+  let lastErr: unknown;
+  while (Date.now() < deadline) {
+    try {
+      await listTablesProbe(endpoint);
+      return;
+    } catch (err) {
+      lastErr = err;
+      await new Promise((r) => setTimeout(r, HEALTH_INTERVAL_MS));
+    }
+  }
+  throw new Error(
+    `DynamoDB Local at ${endpoint} did not become healthy in ${HEALTH_TIMEOUT_MS}ms: ${renderErr(
+      lastErr,
+    )}`,
+  );
+}
+
+function listTablesProbe(endpoint: string): Promise<void> {
+  // DynamoDB Local replies with `MissingAuthenticationToken` (status 400
+  // or 403 depending on version) when the server is *up* but the bare
+  // probe lacks a SigV4 signature. We treat any HTTP response as
+  // "healthy" — the SDK signs every real request.
+  return new Promise((resolve, reject) => {
+    const body = '{}';
+    const opts: RequestOptions = {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-amz-json-1.0',
+        'X-Amz-Target': 'DynamoDB_20120810.ListTables',
+        'Content-Length': Buffer.byteLength(body),
+      },
+    };
+    const req = httpRequest(`${endpoint}/`, opts, (res) => {
+      res.resume();
+      res.on('end', () => {
+        if (res.statusCode === undefined) {
+          reject(new Error('health probe: no status'));
+          return;
+        }
+        // 200 (signed) or 400/403 (auth errors indicating server is up).
+        resolve();
+      });
+    });
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Misc helpers
+// ---------------------------------------------------------------------------
+
+function which(bin: string): string | null {
+  const cmd = platform() === 'win32' ? `where ${bin}` : `command -v ${bin}`;
+  try {
+    const out = execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim();
+    return out.length > 0 ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+function quote(path: string): string {
+  // Minimal shell-quote for paths with spaces; fine for our use.
+  if (/\s/u.test(path)) return `"${path}"`;
+  return path;
+}
+
+function renderErr(err: unknown): string {
+  if (err === null || err === undefined) return '<no error>';
+  if (err instanceof Error) return `${err.name}: ${err.message}`;
+  return String(err);
+}

package/packages/aws-adapter/tests/gone-exception.test.ts

@@ -0,0 +1,271 @@
+/**
+ * Verifies that a `GoneException` raised during cross-connection `send`
+ * triggers {@link cleanupConnection}, which deletes:
+ *   - the dead connection's row in Connections,
+ *   - its nick (if any) in Nicks,
+ *   - its memberships in ChannelMembers.
+ *
+ * Tested by injecting a mock `PostToConnection` that throws once.
+ */
+
+import { GoneException } from '@aws-sdk/client-apigatewaymanagementapi';
+import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
+import { PutCommand } from '@aws-sdk/lib-dynamodb';
+import {
+  DEFAULT_SERVER_CONFIG,
+  type Nick,
+  type ParsedServerConfig,
+  createConnection,
+} from '@serverless-ircd/irc-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { AwsRuntime, type PostToConnection, cleanupConnection } from '../src/aws-runtime.js';
+import { TABLE_DEFS } from '../src/cdk-table-defs.js';
+import { createDynamoDocumentClient } from '../src/dynamo.js';
+import { marshalChannelMember, marshalConnection, marshalNick } from '../src/serialize.js';
+import type { TablesConfig } from '../src/tables.js';
+
+const available = process.env.DDB_AVAILABLE === '1';
+const endpoint = process.env.DYNAMO_ENDPOINT;
+
+const SERVER_CONFIG: ParsedServerConfig = {
+  ...DEFAULT_SERVER_CONFIG,
+  serverName: 'irc.example.com',
+  networkName: 'ExampleNet',
+  motdLines: [],
+};
+
+interface Fixture {
+  tables: TablesConfig;
+  client: ReturnType<typeof createDynamoDocumentClient>;
+  cleanup: () => Promise<void>;
+}
+
+let fx: Fixture | null;
+
+async function makeFixture(): Promise<Fixture> {
+  if (endpoint === undefined) throw new Error('DYNAMO_ENDPOINT missing');
+  const prefix = `g${Date.now()}-${Math.floor(Math.random() * 1e6)}-`;
+  const tables = Object.fromEntries(
+    Object.keys(TABLE_DEFS).map((name) => [name, `${prefix}${name}`]),
+  ) as TablesConfig;
+  const client = createDynamoDocumentClient({ endpoint });
+  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 client.send(
+      new CreateTableCommand({
+        TableName: `${prefix}${logical}`,
+        AttributeDefinitions: attributeDefinitions,
+        KeySchema: keySchema,
+        BillingMode: 'PAY_PER_REQUEST',
+      }),
+    );
+  }
+  return {
+    tables,
+    client,
+    cleanup: async () => {
+      for (const logical of Object.keys(TABLE_DEFS)) {
+        try {
+          await client.send(new DeleteTableCommand({ TableName: `${prefix}${logical}` }));
+        } catch {
+          // best-effort
+        }
+      }
+    },
+  };
+}
+
+/** Seed a connection with a nick + a channel membership directly in Dynamo. */
+async function seedConnection(
+  client: ReturnType<typeof createDynamoDocumentClient>,
+  tables: TablesConfig,
+  connId: string,
+  nick: string,
+  channel: string,
+): Promise<void> {
+  const now = Date.now();
+  const state = createConnection({ id: connId, connectedSince: now });
+  state.registration = 'registered';
+  state.nick = nick as Nick;
+  state.user = nick;
+  state.host = 'x';
+  state.realname = nick;
+  state.joinedChannels = new Set([channel as never]);
+  state.lastSeen = now;
+  await client.send(
+    new PutCommand({ TableName: tables.Connections, Item: marshalConnection(state, now) }),
+  );
+  await client.send(
+    new PutCommand({
+      TableName: tables.Nicks,
+      Item: marshalNick(nick as Nick, connId, now),
+    }),
+  );
+  await client.send(
+    new PutCommand({
+      TableName: tables.ChannelMembers,
+      Item: marshalChannelMember(channel, {
+        conn: connId,
+        nick: nick as Nick,
+        op: false,
+        voice: false,
+      }),
+    }),
+  );
+}
+
+describe.skipIf(!available)('GoneException cleanup', () => {
+  beforeEach(async () => {
+    fx = await makeFixture();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+    fx = null;
+  });
+
+  it('send() to a gone connection triggers cleanupConnection and deletes Connections/Nicks/Members rows', async () => {
+    await seedConnection(fx!.client, fx!.tables, 'gone', 'bob', '#room');
+
+    // A self-connection runtime that tries to `send` to 'gone'.
+    const mgmt: PostToConnection = {
+      async postToConnection() {
+        throw new GoneException({
+          $metadata: {},
+          message: 'Gone',
+        });
+      },
+    };
+
+    const runtime = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: 'self',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: mgmt,
+    });
+
+    await runtime.send('gone', [{ text: ':self PRIVMSG bob :hi' } as never]);
+
+    const probe = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: '__probe__',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: null,
+    });
+    expect(await probe.getConnectionInfo('gone')).toBeNull();
+    expect(await probe.lookupNick('bob' as Nick)).toBeNull();
+    const members = await probe.getChannelConnections('#room' as never);
+    expect(members.size).toBe(0);
+  });
+
+  it('send() to a non-gone error rethrows', async () => {
+    await seedConnection(fx!.client, fx!.tables, 'present', 'carol', '#room');
+    const mgmt: PostToConnection = {
+      async postToConnection() {
+        throw new Error('network down');
+      },
+    };
+    const runtime = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: 'self',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: mgmt,
+    });
+    await expect(
+      runtime.send('present', [{ text: ':self PRIVMSG carol :hi' } as never]),
+    ).rejects.toThrow('network down');
+    // The target row should NOT have been cleaned up.
+    const probe = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: '__probe__',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: null,
+    });
+    expect(await probe.getConnectionInfo('present')).not.toBeNull();
+  });
+
+  it('cleanupConnection is idempotent when called twice', async () => {
+    await seedConnection(fx!.client, fx!.tables, 'gone2', 'dave', '#room');
+    await cleanupConnection(fx!.client, fx!.tables, 'gone2', null);
+    await cleanupConnection(fx!.client, fx!.tables, 'gone2', null);
+    const probe = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: '__probe__',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: null,
+    });
+    expect(await probe.getConnectionInfo('gone2')).toBeNull();
+  });
+
+  it('cleanupConnection is safe when the connection row is missing', async () => {
+    await expect(
+      cleanupConnection(fx!.client, fx!.tables, 'never-existed', null),
+    ).resolves.toBeUndefined();
+  });
+
+  it('broadcast() skips and cleans up gone members', async () => {
+    await seedConnection(fx!.client, fx!.tables, 'gone3', 'eve', '#room');
+    const mgmt: PostToConnection = {
+      async postToConnection() {
+        throw new GoneException({ $metadata: {}, message: 'Gone' });
+      },
+    };
+    const runtime = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: 'self',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: mgmt,
+    });
+    // `broadcast` iterates ChannelMembers and skips `except`.
+    await runtime.broadcast('#room' as never, [{ text: ':self PRIVMSG #room :hi' } as never]);
+    const probe = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: '__probe__',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: null,
+    });
+    expect(await probe.lookupNick('eve' as Nick)).toBeNull();
+  });
+
+  it('send() with managementApi=null is a silent no-op (no throw, no cleanup)', async () => {
+    await seedConnection(fx!.client, fx!.tables, 'present2', 'frank', '#room');
+    const runtime = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: 'self',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: null,
+    });
+    await runtime.send('present2', [{ text: ':self PRIVMSG frank :hi' } as never]);
+    const probe = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: '__probe__',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: null,
+    });
+    expect(await probe.getConnectionInfo('present2')).not.toBeNull();
+  });
+
+  it('static SERVER_CONFIG is valid (sanity)', () => {
+    expect(SERVER_CONFIG.serverName).toBe('irc.example.com');
+  });
+});