serverless-ircd 0.1.0 → 0.2.0

package/packages/aws-adapter/tests/config-loader.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Unit tests for `loadServerConfigFromLambdaEnv` and `buildLambdaConfigInput`.
+ *
+ * Pure-function tests; no DynamoDB / Lambda runtime needed.
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  type LambdaConfigEnv,
+  buildLambdaConfigInput,
+  loadServerConfigFromLambdaEnv,
+} from '../src/config-loader.js';
+
+describe('buildLambdaConfigInput', () => {
+  it('passes SERVER_NAME and NETWORK_NAME through', () => {
+    const out = buildLambdaConfigInput({ SERVER_NAME: 'irc.x', NETWORK_NAME: 'NetX' });
+    expect(out.serverName).toBe('irc.x');
+    expect(out.networkName).toBe('NetX');
+  });
+
+  it('splits MOTD on newlines into motdLines', () => {
+    const out = buildLambdaConfigInput({ MOTD: 'first\nsecond' });
+    expect(out.motdLines).toEqual(['first', 'second']);
+  });
+
+  it('omits motdLines when MOTD is empty', () => {
+    const out = buildLambdaConfigInput({ MOTD: '' });
+    expect('motdLines' in out).toBe(false);
+  });
+
+  it('omits motdLines when MOTD is undefined', () => {
+    const out = buildLambdaConfigInput({});
+    expect('motdLines' in out).toBe(false);
+  });
+
+  it('parses MAX_CLIENTS as int', () => {
+    expect(buildLambdaConfigInput({ MAX_CLIENTS: '42' }).maxClients).toBe(42);
+  });
+
+  it('passes CHANNEL_PREFIXES through', () => {
+    expect(buildLambdaConfigInput({ CHANNEL_PREFIXES: '#&' }).channelPrefixes).toBe('#&');
+  });
+
+  it('builds operCreds when OPER_USER alone is set', () => {
+    const out = buildLambdaConfigInput({ OPER_USER: 'alice' });
+    expect(out.operCreds).toEqual([{ user: 'alice', password: '' }]);
+  });
+
+  it('builds operCreds when OPER_PASSWORD alone is set', () => {
+    const out = buildLambdaConfigInput({ OPER_PASSWORD: 'pw' });
+    expect(out.operCreds).toEqual([{ user: '', password: 'pw' }]);
+  });
+
+  it('omits operCreds when neither OPER_* is set', () => {
+    expect('operCreds' in buildLambdaConfigInput({})).toBe(false);
+  });
+
+  it('parses all numeric knobs', () => {
+    const out = buildLambdaConfigInput({
+      MAX_CHANNELS_PER_USER: '5',
+      MAX_TARGETS_PER_COMMAND: '3',
+      NICK_LEN: '9',
+      CHANNEL_LEN: '12',
+      TOPIC_LEN: '100',
+      MAX_LIST_ENTRIES: '7',
+    });
+    expect(out.maxChannelsPerUser).toBe(5);
+    expect(out.maxTargetsPerCommand).toBe(3);
+    expect(out.nickLen).toBe(9);
+    expect(out.channelLen).toBe(12);
+    expect(out.topicLen).toBe(100);
+    expect(out.maxListEntries).toBe(7);
+  });
+
+  it('passes QUIT_MESSAGE through', () => {
+    expect(buildLambdaConfigInput({ QUIT_MESSAGE: 'bye' }).quitMessage).toBe('bye');
+  });
+});
+
+describe('loadServerConfigFromLambdaEnv', () => {
+  it('parses a minimal valid env', () => {
+    const env: LambdaConfigEnv = { SERVER_NAME: 'irc.test', NETWORK_NAME: 'TestNet' };
+    const cfg = loadServerConfigFromLambdaEnv(env);
+    expect(cfg.serverName).toBe('irc.test');
+    expect(cfg.networkName).toBe('TestNet');
+  });
+
+  it('applies schema defaults for unspecified numeric knobs', () => {
+    const cfg = loadServerConfigFromLambdaEnv({ SERVER_NAME: 's', NETWORK_NAME: 'n' });
+    expect(typeof cfg.maxClients).toBe('number');
+    expect(typeof cfg.nickLen).toBe('number');
+  });
+
+  it('throws when SERVER_NAME is missing', () => {
+    expect(() => loadServerConfigFromLambdaEnv({})).toThrow();
+  });
+
+  it('round-trips MOTD lines into ParsedServerConfig', () => {
+    const cfg = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      MOTD: 'a\nb',
+    });
+    expect(cfg.motdLines).toEqual(['a', 'b']);
+  });
+
+  it('round-trips the CDK default MOTD (newline-joined) into exactly two motdLines', () => {
+    const cdkDefaultMotd =
+      'Welcome to the ServerlessIRCd deployment.\nThis server runs on AWS Lambda.';
+    const cfg = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      MOTD: cdkDefaultMotd,
+    });
+    expect(cfg.motdLines).toHaveLength(2);
+    expect(cfg.motdLines).toEqual([
+      'Welcome to the ServerlessIRCd deployment.',
+      'This server runs on AWS Lambda.',
+    ]);
+  });
+
+  it('treats a comma as part of a line, not a line delimiter', () => {
+    const cfg = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      MOTD: 'first line, still first line',
+    });
+    expect(cfg.motdLines).toEqual(['first line, still first line']);
+    expect(cfg.motdLines).toHaveLength(1);
+  });
+
+  it('honours CHANNEL_PREFIXES override', () => {
+    const cfg = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      CHANNEL_PREFIXES: '&',
+    });
+    expect(cfg.channelPrefixes).toBe('&');
+  });
+
+  it('honours MAX_CLIENTS override', () => {
+    const cfg = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      MAX_CLIENTS: '5000',
+    });
+    expect(cfg.maxClients).toBe(5000);
+  });
+
+  it('honours QUIT_MESSAGE override', () => {
+    const cfg = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      QUIT_MESSAGE: 'goodbye',
+    });
+    expect(cfg.quitMessage).toBe('goodbye');
+  });
+});

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

@@ -0,0 +1,57 @@
+/**
+ * Unit tests for `createDynamoDocumentClient`.
+ *
+ * The factory is intentionally tiny; these tests exercise every branch
+ * (with/without endpoint, with/without region, env fallback) without
+ * actually sending a command.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { createDynamoDocumentClient } from '../src/dynamo.js';
+
+describe('createDynamoDocumentClient', () => {
+  it('builds a client with an explicit endpoint', () => {
+    const c = createDynamoDocumentClient({ endpoint: 'http://localhost:8000' });
+    expect(c).toBeDefined();
+    expect(typeof c.send).toBe('function');
+  });
+
+  it('builds a client with explicit endpoint + region', () => {
+    const c = createDynamoDocumentClient({
+      endpoint: 'http://localhost:8000',
+      region: 'us-west-2',
+    });
+    expect(c).toBeDefined();
+  });
+
+  it('builds a client with region only (no endpoint)', () => {
+    const c = createDynamoDocumentClient({ region: 'eu-west-1' });
+    expect(c).toBeDefined();
+  });
+
+  it('falls back to AWS_REGION env when neither arg is supplied', () => {
+    const prev = process.env.AWS_REGION;
+    process.env.AWS_REGION = 'ap-southeast-2';
+    try {
+      const c = createDynamoDocumentClient({});
+      expect(c).toBeDefined();
+    } finally {
+      if (prev === undefined) {
+        Reflect.deleteProperty(process.env, 'AWS_REGION');
+      } else {
+        process.env.AWS_REGION = prev;
+      }
+    }
+  });
+
+  it('falls back to us-east-1 when nothing is supplied', () => {
+    const prev = process.env.AWS_REGION;
+    Reflect.deleteProperty(process.env, 'AWS_REGION');
+    try {
+      const c = createDynamoDocumentClient({});
+      expect(c).toBeDefined();
+    } finally {
+      if (prev !== undefined) process.env.AWS_REGION = prev;
+    }
+  });
+});

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);
+}