serverless-ircd 0.1.0 → 0.2.0

package/apps/aws-stack/scripts/smoke.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * CI smoke e2e for a deployed AWS API Gateway WebSocket stack.
+ *
+ * Replays the same CONNECT → REGISTER → JOIN → PRIVMSG → QUIT flow as the
+ * cf-worker smoke script, but against a live deployed API Gateway WebSocket
+ * endpoint. Exits non-zero on any failure so the GitHub Actions deploy job
+ * fails the build.
+ *
+ * Usage:
+ *   node scripts/smoke.mjs --url wss://abc123.execute-api.us-east-1.amazonaws.com/prod
+ *
+ * Defaults to `ws://localhost:8787` so the same script works against a local
+ * sam-local / localstack dev session.
+ *
+ * Dependencies: only the `ws` WebSocket client (a transitive dev dep). The
+ * script is plain Node ESM — no TypeScript transform needed in CI.
+ */
+
+import { WebSocket } from 'ws';
+import { DEFAULT_SMOKE_URL, numericEquals, parseArgs, waitForPredicate } from './smoke-helpers.mjs';
+
+const POLL_MS = 50;
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+let parsed;
+try {
+  parsed = parseArgs(process.argv.slice(2));
+} catch (err) {
+  process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(2);
+}
+
+if (parsed.help) {
+  process.stdout.write(
+    [
+      'Usage: node scripts/smoke.mjs --url wss://<api-gateway-websocket-url>',
+      '',
+      'Options:',
+      '  --url <ws-url>   WebSocket URL of the deployed stack.',
+      '                   Defaults to ws://localhost:8787 (local dev).',
+      '  -h, --help       Show this help.',
+      '',
+    ].join('\n'),
+  );
+  process.exit(0);
+}
+
+const url = parsed.url ?? DEFAULT_SMOKE_URL;
+
+runSmoke().catch((err) => {
+  process.stderr.write(
+    `${JSON.stringify({
+      ts: new Date().toISOString(),
+      level: 'error',
+      msg: 'aws-stack smoke e2e failed',
+      url,
+      error: err instanceof Error ? err.message : String(err),
+    })}\n`,
+  );
+  process.exit(1);
+});
+
+async function runSmoke() {
+  const ws = await openSocket(url);
+  const received = [];
+
+  ws.on('message', (data) => {
+    const text = data.toString();
+    for (const line of text.split('\r\n')) {
+      if (line.length > 0) received.push(line);
+    }
+  });
+
+  const waitForNumeric = (code, timeoutMs = DEFAULT_TIMEOUT_MS) =>
+    waitForPredicate(
+      (line) => numericEquals(line, code),
+      `numeric ${code}`,
+      received,
+      timeoutMs,
+      POLL_MS,
+    );
+  const waitForLine = (predicate, label, timeoutMs = DEFAULT_TIMEOUT_MS) =>
+    waitForPredicate(predicate, label, received, timeoutMs, POLL_MS);
+
+  // REGISTER
+  ws.send('NICK smoke\r\n');
+  ws.send('USER smoke 0 * :Smoke Test\r\n');
+  await waitForNumeric('001', DEFAULT_TIMEOUT_MS);
+  await waitForNumeric('376', DEFAULT_TIMEOUT_MS);
+
+  // JOIN
+  ws.send('JOIN #smoke\r\n');
+  await waitForLine((l) => l.includes('JOIN') && l.includes('#smoke'), 'JOIN echo');
+  await waitForNumeric('353', DEFAULT_TIMEOUT_MS);
+  await waitForNumeric('366', DEFAULT_TIMEOUT_MS);
+
+  // PRIVMSG (no echo expected — echo-message is opt-in via CAP)
+  ws.send('PRIVMSG #smoke :hello from ci\r\n');
+
+  // QUIT — expect the server to close the socket
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, DEFAULT_TIMEOUT_MS);
+    ws.once('close', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+    ws.once('error', (err) => {
+      clearTimeout(timer);
+      reject(new Error(`socket error during QUIT: ${err.message}`));
+    });
+    ws.send('QUIT :smoke test complete\r\n');
+  });
+
+  ws.close();
+  process.stdout.write(
+    `${JSON.stringify({
+      ts: new Date().toISOString(),
+      level: 'info',
+      msg: 'aws-stack smoke e2e passed',
+      url,
+    })}\n`,
+  );
+}
+
+function openSocket(targetUrl) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(targetUrl);
+    const timer = setTimeout(() => {
+      ws.terminate();
+      reject(new Error(`connect timeout: ${targetUrl}`));
+    }, DEFAULT_TIMEOUT_MS);
+    ws.once('open', () => {
+      clearTimeout(timer);
+      resolve(ws);
+    });
+    ws.once('error', (err) => {
+      clearTimeout(timer);
+      reject(new Error(`connect failed: ${err.message}`));
+    });
+  });
+}

package/apps/aws-stack/src/aws-stack.ts

@@ -0,0 +1,263 @@
+/**
+ * `apps/aws-stack` CDK stack — the AWS substrate for ServerlessIRCd (PLAN §6.2).
+ *
+ *   • 5 DynamoDB tables sourced from `@serverless-ircd/aws-adapter/cdk-table-defs`
+ *     (Connections, ChannelMeta, ChannelMembers, Nicks, Accounts).
+ *   • ONE Node 20 `NodejsFunction` bundling the AWS Lambda handler
+ *     (`$connect` / `$disconnect` / `$default` dispatched on
+ *     `event.requestContext.routeKey`).
+ *   • ONE Node 20 `NodejsFunction` for the gone-connection sweeper
+ *     (`sweeperHandler`), invoked on a fixed EventBridge schedule.
+ *   • API Gateway v2 WebSocket API + auto-deploying `prod` stage.
+ *   • Least-privilege IAM: scoped DynamoDB data-plane grants per table +
+ *     `execute-api:ManageConnections` scoped to this API's stage connections.
+ */
+
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { TABLE_DEFS } from '@serverless-ircd/aws-adapter/cdk-table-defs';
+import { CfnOutput, Duration, RemovalPolicy, Stack, type StackProps } from 'aws-cdk-lib';
+import { WebSocketApi, WebSocketStage } from 'aws-cdk-lib/aws-apigatewayv2';
+import { WebSocketLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
+import { Table } from 'aws-cdk-lib/aws-dynamodb';
+import { Rule, Schedule } from 'aws-cdk-lib/aws-events';
+import { LambdaFunction } from 'aws-cdk-lib/aws-events-targets';
+import { Runtime } from 'aws-cdk-lib/aws-lambda';
+import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
+import type { Construct } from 'constructs';
+
+/** Stage name served by the auto-deploying WebSocket stage. */
+const STAGE_NAME = 'prod';
+
+/** Fixed rate for the gone-connection sweeper (matches the architecture doc). */
+const SWEEPER_SCHEDULE_RATE = Duration.minutes(5);
+
+/**
+ * Fixed rate for the idle / PING checker. One minute is the finest
+ * granularity EventBridge `rate(...)` expressions support, which
+ * matches the default `DEFAULT_PING_INTERVAL_MS` (60 s).
+ */
+const PING_CHECKER_SCHEDULE_RATE = Duration.minutes(1);
+
+/**
+ * Environment assumed when {@link IrcStackProps.environmentName} is
+ * omitted. Keeps the existing deploy pipeline green without requiring
+ * callers to pass the flag.
+ */
+const DEFAULT_ENVIRONMENT_NAME = 'staging';
+
+/** Default server identity, used when the corresponding prop is omitted. */
+const DEFAULT_SERVER_NAME = 'irc.example.com';
+const DEFAULT_NETWORK_NAME = 'ExampleNet';
+const DEFAULT_MOTD_LINES = [
+  'Welcome to the ServerlessIRCd deployment.',
+  'This server runs on AWS Lambda.',
+] as const;
+
+const HERE = fileURLToPath(new URL('.', import.meta.url));
+
+/**
+ * Construct props for {@link IrcAwsStack}. Acts as the single
+ * configuration bag extended by deploy-time knobs (environment name,
+ * server identity, …) so the prop surface grows in one place.
+ */
+export interface IrcStackProps extends StackProps {
+  /**
+   * Logical deployment environment (e.g. `staging`, `production`).
+   *
+   * Prefixes every physical DynamoDB table name
+   * (`<Env><LogicalId>` — first letter capitalised, e.g.
+   * `StagingConnections`) and is intended to be folded into the
+   * CloudFormation stack id by the caller
+   * (`IrcAwsStack-<environmentName>`). Defaults to `staging`.
+   */
+  readonly environmentName?: string;
+
+  /**
+   * Server name advertised to clients (`SERVER_NAME` / the `001`
+   * welcome source). Defaults to `irc.example.com`.
+   */
+  readonly serverName?: string;
+
+  /**
+   * Network name advertised in `ISUPPORT` (`NETWORK`). Defaults to
+   * `ExampleNet`.
+   */
+  readonly networkName?: string;
+
+  /**
+   * Lines of the Message of the Day. Joined with `\n` so the Lambda
+   * config loader (`buildLambdaConfigInput`) round-trips them back into
+   * a `string[]` correctly. Defaults to a short two-line banner.
+   */
+  readonly motdLines?: string[];
+}
+
+export class IrcAwsStack extends Stack {
+  constructor(scope: Construct, id: string, props: IrcStackProps = {}) {
+    super(scope, id, props);
+
+    const environmentName = props.environmentName ?? DEFAULT_ENVIRONMENT_NAME;
+    const serverName = props.serverName ?? DEFAULT_SERVER_NAME;
+    const networkName = props.networkName ?? DEFAULT_NETWORK_NAME;
+    const motd = (props.motdLines ?? DEFAULT_MOTD_LINES).join('\n');
+
+    // Prefix every physical table name with the environment so parallel
+    // envs (staging + production) cannot collide in one account+region.
+    // The first letter is capitalised to compose cleanly with the
+    // PascalCase logical ids (`staging` → `StagingConnections`).
+    const tables = Object.fromEntries(
+      Object.entries(TABLE_DEFS).map(([logicalId, tableProps]) => {
+        const table = new Table(this, logicalId, {
+          ...tableProps,
+          tableName: prefixedTableName(environmentName, logicalId),
+          removalPolicy: RemovalPolicy.DESTROY,
+        });
+        return [logicalId, table];
+      }),
+    );
+
+    const handler = new NodejsFunction(this, 'IrcHandler', {
+      runtime: Runtime.NODEJS_20_X,
+      entry: handlerEntry(),
+      handler: 'handler',
+      bundling: {
+        // AWS SDK v3 is in the Lambda Node 20 runtime; exclude it so the
+        // bundle stays small. irc-core / irc-server are bundled because
+        // they are first-party.
+        externalModules: ['@aws-sdk/*'],
+      },
+    });
+
+    // Sweeper Lambda — same entry, different handler export. Shares the
+    // bundle (tree-shaken to the sweeper path by esbuild at synth time).
+    // Catches connections that vanished without APIGW emitting $disconnect;
+    // see packages/aws-adapter/src/handlers/sweeper.ts.
+    const sweeper = new NodejsFunction(this, 'IrcSweeper', {
+      runtime: Runtime.NODEJS_20_X,
+      entry: handlerEntry(),
+      handler: 'sweeperHandler',
+      bundling: {
+        externalModules: ['@aws-sdk/*'],
+      },
+    });
+
+    // Idle / PING checker Lambda — same entry, different handler export.
+    // Sends a server-initiated PING to idle connections and disconnects
+    // those that never answer; see
+    // packages/aws-adapter/src/handlers/ping-checker.ts. The Cloudflare
+    // adapter implements the equivalent flow inside `ConnectionDO.alarm()`.
+    const pingChecker = new NodejsFunction(this, 'IrcPingChecker', {
+      runtime: Runtime.NODEJS_20_X,
+      entry: handlerEntry(),
+      handler: 'pingCheckerHandler',
+      bundling: {
+        externalModules: ['@aws-sdk/*'],
+      },
+    });
+
+    for (const table of Object.values(tables)) {
+      table.grantReadWriteData(handler);
+      table.grantReadWriteData(sweeper);
+      table.grantReadWriteData(pingChecker);
+    }
+
+    const webSocketApi = new WebSocketApi(this, 'IrcWsApi', {
+      connectRouteOptions: {
+        integration: new WebSocketLambdaIntegration('ConnectIntegration', handler),
+      },
+      disconnectRouteOptions: {
+        integration: new WebSocketLambdaIntegration('DisconnectIntegration', handler),
+      },
+      defaultRouteOptions: {
+        integration: new WebSocketLambdaIntegration('DefaultIntegration', handler),
+      },
+    });
+
+    // The stage name is intentionally NOT suffixed with the environment:
+    // each environment is its own CloudFormation stack (and therefore its
+    // own WebSocket API), so `prod` in every env resolves to a distinct
+    // endpoint. Keeping a fixed stage keeps client connect URLs stable
+    // and identical in shape across environments.
+    const stage = new WebSocketStage(this, 'Stage', {
+      webSocketApi,
+      stageName: STAGE_NAME,
+      autoDeploy: true,
+    });
+
+    stage.grantManagementApiAccess(handler);
+    stage.grantManagementApiAccess(pingChecker);
+    handler.addEnvironment('MANAGEMENT_URL', stage.callbackUrl);
+    pingChecker.addEnvironment('MANAGEMENT_URL', stage.callbackUrl);
+
+    // Inject each table's physical name as an env var so every Lambda can
+    // construct a `TablesConfig` at cold start via `buildDepsFromEnv`. The
+    // env-var value is the environment-prefixed physical name (computed
+    // through the same helper as the Table construct so they match
+    // exactly), NOT a CloudFormation Ref — the runtime needs the literal
+    // per-env table name to target the correct table.
+    for (const logicalId of Object.keys(TABLE_DEFS)) {
+      const envName = `${logicalId.toUpperCase()}_TABLE`;
+      const physicalName = prefixedTableName(environmentName, logicalId);
+      handler.addEnvironment(envName, physicalName);
+      sweeper.addEnvironment(envName, physicalName);
+      pingChecker.addEnvironment(envName, physicalName);
+    }
+
+    // Server identity (consumed by the handler's config loader). Sourced
+    // from the single prop bag and injected into BOTH the handler and the
+    // ping checker — the ping checker needs SERVER_NAME / NETWORK_NAME /
+    // MOTD to build the same server-shaped config via the shared loader.
+    // The sweeper does not. MOTD is `\n`-joined so `buildLambdaConfigInput`
+    // splits it back into the expected `motdLines` array.
+    handler.addEnvironment('SERVER_NAME', serverName);
+    handler.addEnvironment('NETWORK_NAME', networkName);
+    handler.addEnvironment('MOTD', motd);
+    pingChecker.addEnvironment('SERVER_NAME', serverName);
+    pingChecker.addEnvironment('NETWORK_NAME', networkName);
+    pingChecker.addEnvironment('MOTD', motd);
+
+    // EventBridge schedule → sweeper Lambda. Fixed rate per the architecture
+    // doc; the sweeper is self-throttling (Scans + per-row cleanupConnection).
+    new Rule(this, 'SweeperSchedule', {
+      schedule: Schedule.rate(SWEEPER_SCHEDULE_RATE),
+      targets: [new LambdaFunction(sweeper)],
+    });
+
+    // EventBridge schedule → idle / PING checker Lambda. Fixed rate(1 minute)
+    // so an idle connection sees its first PING within one tick of the
+    // configured `DEFAULT_PING_INTERVAL_MS` (60 s).
+    new Rule(this, 'PingCheckerSchedule', {
+      schedule: Schedule.rate(PING_CHECKER_SCHEDULE_RATE),
+      targets: [new LambdaFunction(pingChecker)],
+    });
+
+    new CfnOutput(this, 'ConnectUrl', {
+      description: 'WebSocket connect endpoint clients dial (wss).',
+      value: stage.url,
+    });
+    new CfnOutput(this, 'ManagementUrl', {
+      description: 'HTTPS management endpoint for ApiGatewayManagementApi.postToConnection.',
+      value: stage.callbackUrl,
+    });
+  }
+}
+
+/**
+ * Absolute path to the Lambda handler entry (`packages/aws-adapter/src/handlers/index.ts`).
+ * Computed relative to this file so `cdk synth` works from any CWD.
+ */
+function handlerEntry(): string {
+  return resolve(HERE, '..', '..', '..', 'packages', 'aws-adapter', 'src', 'handlers', 'index.ts');
+}
+
+/**
+ * Builds the physical DynamoDB table name for a logical id under the
+ * given environment. Capitalises the environment's first letter so it
+ * composes cleanly with PascalCase logical ids
+ * (`staging` + `Connections` → `StagingConnections`).
+ */
+function prefixedTableName(environmentName: string, logicalId: string): string {
+  const cap = environmentName.charAt(0).toUpperCase() + environmentName.slice(1);
+  return `${cap}${logicalId}`;
+}

package/apps/aws-stack/src/tables.ts

@@ -0,0 +1,10 @@
+/**
+ * DynamoDB table schema definitions are owned by `@serverless-ircd/aws-adapter`
+ * so the runtime and the CDK stack share a single source of truth.
+ *
+ * Re-exported here for backwards compatibility with anything importing from
+ * `apps/aws-stack/src/tables.js`. New code should import directly from
+ * `@serverless-ircd/aws-adapter/cdk-table-defs`.
+ */
+
+export { TABLE_DEFS } from '@serverless-ircd/aws-adapter/cdk-table-defs';

package/apps/aws-stack/tests/localstack.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Localstack-backed deploy-time validation (gated).
+ *
+ * This is the "deploy contract" companion to `stack.test.ts`'s synth-time
+ * contract. It runs the real `cdklocal` CLI against a localstack container
+ * and asserts the synthesized template still contains all five tables —
+ * catching drift between the CDK constructs and what the localstack-aware
+ * synthesizer emits.
+ *
+ * Gated behind `LOCALSTACK=1` so it never runs in the default `pnpm test`
+ * (and therefore never blocks CI on a missing Docker daemon). See the
+ * package README for setup instructions.
+ */
+
+import { execSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+describe.skipIf(!process.env.LOCALSTACK)('localstack', () => {
+  it('synths five DynamoDB tables when run through cdklocal', () => {
+    const outDir = mkdtempSync(join(tmpdir(), 'aws-stack-localstack-'));
+    execSync(`cdklocal synth --output "${outDir}"`, {
+      cwd: PKG_ROOT,
+      env: { ...process.env, CDK_CONTEXT_JSON: '{}' },
+      stdio: ['ignore', 'ignore', 'pipe'],
+    });
+
+    const templateFile = readdirSync(outDir).find((f) => f.endsWith('.template.json'));
+    if (!templateFile) {
+      throw new Error('cdklocal produced no synthesized template');
+    }
+    const template = JSON.parse(readFileSync(join(outDir, templateFile), 'utf8')) as {
+      Resources?: Record<string, { Type: string }>;
+    };
+    const tables = Object.values(template.Resources ?? {}).filter(
+      (r) => r.Type === 'AWS::DynamoDB::Table',
+    );
+
+    expect(tables).toHaveLength(5);
+  }, 60_000);
+});

package/apps/aws-stack/tests/smoke-helpers.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Unit tests for the pure helpers backing the AWS staging smoke e2e
+ * (`scripts/smoke.mjs`). The helpers live in `scripts/smoke-helpers.mjs`
+ * (plain ESM, no TS transform) so they can run in CI without a build step;
+ * this file is the red→green driver — it imports them via a sibling
+ * declaration so the workspace typecheck still passes.
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  type ParseResult,
+  numericEquals,
+  parseArgs,
+  waitForPredicate,
+} from '../scripts/smoke-helpers.mjs';
+
+describe('numericEquals', () => {
+  it('matches a bare numeric line with no server prefix', () => {
+    expect(numericEquals('001 :Welcome to the network', '001')).toBe(true);
+  });
+
+  it('matches a numeric line carrying a :server prefix', () => {
+    expect(numericEquals(':irc.example.com 376 smoke :End of MOTD', '376')).toBe(true);
+  });
+
+  it('returns false when a different numeric occupies the command slot', () => {
+    expect(numericEquals(':irc.example.com 375 smoke :MOTD', '376')).toBe(false);
+  });
+
+  it('does not false-positive on a numeric embedded in the trailing text', () => {
+    expect(numericEquals(':nick PRIVMSG #chan :001 is not the command', '001')).toBe(false);
+  });
+});
+
+describe('parseArgs', () => {
+  it('defaults the url to localhost when no --url is supplied', () => {
+    expect(parseArgs([])).toStrictEqual<ParseResult>({ url: 'ws://localhost:8787', help: false });
+  });
+
+  it('reads the value following --url', () => {
+    expect(parseArgs(['--url', 'wss://irc.example.com/prod'])).toStrictEqual<ParseResult>({
+      url: 'wss://irc.example.com/prod',
+      help: false,
+    });
+  });
+
+  it('signals help for -h', () => {
+    expect(parseArgs(['-h']).help).toBe(true);
+  });
+
+  it('signals help for --help', () => {
+    expect(parseArgs(['--help']).help).toBe(true);
+  });
+
+  it('throws on an unknown argument', () => {
+    expect(() => parseArgs(['--bogus'])).toThrow(/unknown argument/);
+  });
+
+  it('throws when --url is given without a value', () => {
+    expect(() => parseArgs(['--url'])).toThrow(/--url/);
+  });
+
+  it('tolerates a leading -- options terminator (pnpm script passthrough)', () => {
+    // `pnpm smoke:aws:staging -- --url wss://x` forwards `['--', '--url', 'wss://x']`.
+    expect(parseArgs(['--', '--url', 'wss://irc.example.com/prod'])).toStrictEqual<ParseResult>({
+      url: 'wss://irc.example.com/prod',
+      help: false,
+    });
+  });
+});
+
+describe('waitForPredicate', () => {
+  it('resolves with the first received line that satisfies the predicate', async () => {
+    const received = [':srv 001 smoke :Welcome', ':srv 376 smoke :End of MOTD'];
+    const line = await waitForPredicate(
+      (l) => numericEquals(l, '376'),
+      'numeric 376',
+      received,
+      1000,
+      5,
+    );
+    expect(line).toBe(':srv 376 smoke :End of MOTD');
+  });
+
+  it('rejects with a message naming the label and dumping the received buffer on timeout', async () => {
+    const received = [':srv 001 smoke :Welcome'];
+    await expect(
+      waitForPredicate((l) => numericEquals(l, '376'), 'numeric 376', received, 20, 5),
+    ).rejects.toThrow(/timed out waiting for numeric 376/);
+  });
+
+  it('includes the received lines in the timeout error for diagnostics', async () => {
+    const received = [':srv 001 smoke :Welcome'];
+    await expect(
+      waitForPredicate((l) => numericEquals(l, '376'), 'numeric 376', received, 20, 5),
+    ).rejects.toThrow(/:srv 001 smoke :Welcome/);
+  });
+});