serverless-ircd 0.3.0 → 0.5.0

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

@@ -1,10 +1,10 @@
 /**
  * Synth-time assertions for the `apps/aws-stack` CDK stack.
  *
- * These are the primary red→green tests for the infrastructure ticket:
+ * These are the primary red→green tests for the infrastructure stack:
  * they assert the exact CloudFormation shape that `cdk synth` must
  * produce — five DynamoDB tables with the PLAN §4 schema, a single
- * Node 20 Lambda wired to all three WebSocket routes, the API Gateway
+ * Node 24 Lambda wired to all three WebSocket routes, the API Gateway
  * v2 WebSocket API, the two stack outputs, and a least-privilege guard
  * that no IAM policy grants `Resource: '*'` or `Action: '*'`.
  *
@@ -149,6 +149,52 @@ describe('IrcAwsStack — API Gateway v2 WebSocket API', () => {
     const { template } = makeTemplate();
     template.resourceCountIs('AWS::ApiGatewayV2::Route', 3);
   });
+
+  it('enables the $connect route to return a response (route response selection)', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::Route', {
+      RouteKey: '$connect',
+      RouteResponseSelectionExpression: '$default',
+    });
+  });
+
+  it('creates a $connect route response so the upgrade can carry a response', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::RouteResponse', {
+      RouteResponseKey: '$default',
+    });
+  });
+});
+
+describe('IrcAwsStack — IRCv3 WebSocket subprotocol echo', () => {
+  it('attaches an integration response on the $connect route mapping Sec-WebSocket-Protocol', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::IntegrationResponse', {
+      ResponseParameters: {
+        'method.response.header.Sec-WebSocket-Protocol':
+          'integration.response.header.Sec-WebSocket-Protocol',
+      },
+    });
+  });
+
+  it('binds the subprotocol integration response to the $connect integration', () => {
+    const { template, stack } = makeTemplate();
+    const responses = template.findResources('AWS::ApiGatewayV2::IntegrationResponse');
+    // Exactly one integration response is configured (the $connect subprotocol echo).
+    expect(Object.keys(responses)).toHaveLength(1);
+    // The IntegrationId Ref must resolve to a CfnIntegration under the $connect route.
+    const stackName = stack.stackName;
+    void stackName;
+    const cfnIntegrations = template.findResources('AWS::ApiGatewayV2::Integration');
+    expect(Object.keys(cfnIntegrations).length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('uses the $default integration response key', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::IntegrationResponse', {
+      IntegrationResponseKey: '$default',
+    });
+  });
 });
 
 describe('IrcAwsStack — Lambda', () => {
@@ -157,10 +203,10 @@ describe('IrcAwsStack — Lambda', () => {
     template.resourceCountIs('AWS::Lambda::Function', 3);
   });
 
-  it('targets the Node 20 runtime for every function', () => {
+  it('targets the Node 24 runtime for every function', () => {
     const { template } = makeTemplate();
     template.allResourcesProperties('AWS::Lambda::Function', {
-      Runtime: 'nodejs20.x',
+      Runtime: 'nodejs24.x',
     });
   });
 });
@@ -462,3 +508,98 @@ describe('IrcAwsStack — server identity props (configurable deploy identity)',
     ).toBeUndefined();
   });
 });
+
+describe('IrcAwsStack — TCP+TLS NLB adapter', () => {
+  /** Makes a template WITH the tcpTlsDomainName prop (enables the NLB path). */
+  function makeTcpTemplate(domainName = 'irc.example.com'): {
+    app: App;
+    stack: Stack;
+    template: Template;
+  } {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', {
+      environmentName: 'staging',
+      tcpTlsDomainName: domainName,
+    });
+    const template = Template.fromStack(stack);
+    return { app, stack, template };
+  }
+
+  describe('when tcpTlsDomainName is omitted (default)', () => {
+    it('creates no Network Load Balancer', () => {
+      const { template } = makeTemplate();
+      template.resourceCountIs('AWS::ElasticLoadBalancingV2::LoadBalancer', 0);
+    });
+
+    it('creates no ACM certificate', () => {
+      const { template } = makeTemplate();
+      template.resourceCountIs('AWS::CertificateManager::Certificate', 0);
+    });
+
+    it('still creates exactly three Lambda functions', () => {
+      const { template } = makeTemplate();
+      template.resourceCountIs('AWS::Lambda::Function', 3);
+    });
+  });
+
+  describe('when tcpTlsDomainName is provided', () => {
+    it('creates a Network Load Balancer', () => {
+      const { template } = makeTcpTemplate();
+      template.resourceCountIs('AWS::ElasticLoadBalancingV2::LoadBalancer', 1);
+    });
+
+    it('creates an ACM certificate for the provided domain', () => {
+      const { template } = makeTcpTemplate('irc.my.net');
+      template.hasResourceProperties('AWS::CertificateManager::Certificate', {
+        DomainName: 'irc.my.net',
+      });
+    });
+
+    it('creates a TLS listener on port 6697', () => {
+      const { template } = makeTcpTemplate();
+      template.hasResourceProperties('AWS::ElasticLoadBalancingV2::Listener', {
+        Port: 6697,
+        Protocol: 'TLS',
+      });
+    });
+
+    it('creates a target group with Lambda as the target type', () => {
+      const { template } = makeTcpTemplate();
+      template.hasResourceProperties('AWS::ElasticLoadBalancingV2::TargetGroup', {
+        TargetType: 'lambda',
+      });
+    });
+
+    it('creates a fourth Lambda function for the NLB streaming handler', () => {
+      const { template } = makeTcpTemplate();
+      template.resourceCountIs('AWS::Lambda::Function', 4);
+    });
+
+    it('targets the Node 24 runtime for the NLB handler Lambda', () => {
+      const { template } = makeTcpTemplate();
+      template.allResourcesProperties('AWS::Lambda::Function', {
+        Runtime: 'nodejs24.x',
+      });
+    });
+
+    it('grants the NLB permission to invoke the handler Lambda', () => {
+      const { template } = makeTcpTemplate();
+      template.hasResourceProperties('AWS::Lambda::Permission', {
+        Principal: 'elasticloadbalancing.amazonaws.com',
+      });
+    });
+
+    it('still creates the wss WebSocket API (both transports coexist)', () => {
+      const { template } = makeTcpTemplate();
+      template.hasResourceProperties('AWS::ApiGatewayV2::Api', {
+        ProtocolType: 'WEBSOCKET',
+      });
+    });
+
+    it('emits a TcpConnectUrl output pointing at the NLB DNS', () => {
+      const { template } = makeTcpTemplate();
+      const outputs = template.toJSON().Outputs ?? {};
+      expect(outputs).toHaveProperty('TcpConnectUrl');
+    });
+  });
+});

package/apps/cf-tcp-container/Dockerfile

@@ -0,0 +1,69 @@
+# Cloudflare Container / Docker image for the ServerlessIRCd TCP origin.
+#
+# Spectrum terminates TLS at the edge and forwards plaintext TCP to this
+# container. The container runs the IRC core (ConnectionActor +
+# InMemoryRuntime) over the TcpByteStreamTransport seam on port 6667.
+#
+# Build context: the repository root (monorepo). The container needs the
+# irc-core, irc-server, and in-memory-runtime packages.
+#
+#   docker build -f apps/cf-tcp-container/Dockerfile -t sirc-tcp-origin .
+#   docker run -p 6667:6667 -e SERVER_NAME=irc.example.com sirc-tcp-origin
+#
+# For Cloudflare Containers deployment, the same image is referenced from
+# wrangler.toml.
+
+FROM node:24-slim AS builder
+
+WORKDIR /app
+
+# Install pnpm.
+RUN corepack enable && corepack prepare pnpm@11.17.0 --activate
+
+# Copy workspace config + lockfile first for layer caching.
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY tsconfig.base.json ./
+
+# Copy all workspace packages needed for the build.
+COPY packages/irc-core/ packages/irc-core/
+COPY packages/irc-server/ packages/irc-server/
+COPY packages/in-memory-runtime/ packages/in-memory-runtime/
+COPY apps/cf-tcp-container/ apps/cf-tcp-container/
+
+# Install dependencies and build.
+RUN pnpm install --frozen-lockfile
+RUN pnpm --filter '@serverless-ircd/irc-core' build && \
+    pnpm --filter '@serverless-ircd/irc-server' build && \
+    pnpm --filter '@serverless-ircd/in-memory-runtime' build && \
+    pnpm --filter '@serverless-ircd/cf-tcp-container' build
+
+# --- Runtime stage ---
+FROM node:24-slim AS runtime
+
+WORKDIR /app
+
+# Copy built artifacts + package manifests (for workspace resolution).
+COPY --from=builder /app/package.json /app/pnpm-workspace.yaml ./
+COPY --from=builder /app/packages/irc-core/package.json packages/irc-core/
+COPY --from=builder /app/packages/irc-core/dist/ packages/irc-core/dist/
+COPY --from=builder /app/packages/irc-server/package.json packages/irc-server/
+COPY --from=builder /app/packages/irc-server/dist/ packages/irc-server/dist/
+COPY --from=builder /app/packages/in-memory-runtime/package.json packages/in-memory-runtime/
+COPY --from=builder /app/packages/in-memory-runtime/dist/ packages/in-memory-runtime/dist/
+COPY --from=builder /app/apps/cf-tcp-container/package.json apps/cf-tcp-container/
+COPY --from=builder /app/apps/cf-tcp-container/dist/ apps/cf-tcp-container/dist/
+
+# Production install (only the workspace deps, no devDependencies).
+RUN corepack enable && corepack prepare pnpm@11.17.0 --activate && \
+    pnpm install --frozen-lockfile --prod
+
+# Persistence volume: Spectrum-origin channel state survives restarts.
+VOLUME ["/data"]
+
+EXPOSE 6667
+
+ENV TCP_PORT=6667
+ENV TCP_HOST=0.0.0.0
+ENV PERSISTENCE_PATH=/data/state.json
+
+CMD ["node", "--enable-source-maps", "apps/cf-tcp-container/dist/main.js"]

package/apps/cf-tcp-container/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@serverless-ircd/cf-tcp-container",
+  "version": "0.5.0",
+  "private": true,
+  "description": "Cloudflare Container TCP origin for the irc+tls :6697 transport — Spectrum terminates TLS at the edge, this container runs the IRC core over plaintext TCP",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "main": "./dist/main.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "start": "node --enable-source-maps ./dist/main.js",
+    "deploy:staging": "wrangler deploy --env staging",
+    "deploy:prod": "wrangler deploy",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "clean": "rimraf dist coverage .tsbuildinfo .turbo"
+  },
+  "dependencies": {
+    "@serverless-ircd/in-memory-runtime": "workspace:*",
+    "@serverless-ircd/irc-core": "workspace:*",
+    "@serverless-ircd/irc-server": "workspace:*"
+  },
+  "devDependencies": {
+    "@cloudflare/containers": "^0.1.0",
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.0",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.0",
+    "wrangler": "4.112.0"
+  }
+}

package/apps/cf-tcp-container/src/config-loader.ts

@@ -0,0 +1,145 @@
+/**
+ * CF TCP container config loader.
+ *
+ * Adapts platform-native env vars (Cloudflare Container runtime env or
+ * Docker/Kubernetes env) into the shared `ServerConfigSchema` from
+ * `irc-core`, plus a handful of container-specific knobs (TCP port/host,
+ * persistence path, snapshot interval).
+ *
+ * Mirrors `packages/cf-adapter/src/config-loader.ts` in shape — both
+ * adapters consume the same `ServerConfigSchema`; only the env-mapping
+ * and the extra container knobs differ.
+ */
+
+import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc-core';
+
+/**
+ * The env vars this loader reads. Every field is a string (the platform
+ * env shape); numeric fields are coerced inside {@link loadContainerConfig}.
+ */
+export interface ContainerConfigEnv {
+  SERVER_NAME?: string;
+  NETWORK_NAME?: string;
+  SERVER_VERSION?: string;
+  CREATED_AT?: string;
+  MOTD_LINES?: string;
+  MAX_CLIENTS?: string;
+  CHANNEL_PREFIXES?: string;
+  OPER_USER?: string;
+  OPER_PASSWORD?: string;
+  MAX_CHANNELS_PER_USER?: string;
+  MAX_TARGETS_PER_COMMAND?: string;
+  NICK_LEN?: string;
+  CHANNEL_LEN?: string;
+  TOPIC_LEN?: string;
+  MAX_LIST_ENTRIES?: string;
+  QUIT_MESSAGE?: string;
+  SASL_ACCOUNTS?: string;
+  /** Container-specific: plaintext TCP port Spectrum forwards to. */
+  TCP_PORT?: string;
+  /** Container-specific: bind address (default 0.0.0.0 for Spectrum origin). */
+  TCP_HOST?: string;
+  /** Container-specific: path to the persistence snapshot file. */
+  PERSISTENCE_PATH?: string;
+  /** Container-specific: auto-snapshot interval in milliseconds. */
+  SNAPSHOT_INTERVAL_MS?: string;
+}
+
+/** Fully-resolved container config: IRC server config + container knobs. */
+export interface ContainerConfig {
+  server: ParsedServerConfig;
+  tcpPort: number;
+  tcpHost: string;
+  persistencePath: string | undefined;
+  snapshotIntervalMs: number;
+}
+
+const DEFAULT_TCP_PORT = 6667;
+const DEFAULT_TCP_HOST = '0.0.0.0';
+const DEFAULT_SNAPSHOT_INTERVAL_MS = 60_000;
+
+/** Default server name / network when env vars are missing. */
+const DEFAULT_SERVER_NAME = 'irc.example.com';
+const DEFAULT_NETWORK_NAME = 'ExampleNet';
+
+/**
+ * Loads and validates the IRC server config plus container-specific knobs
+ * from a platform env. Throws on an invalid IRC config (bad port number,
+ * missing required fields, etc.) so boot fails fast.
+ */
+export function loadContainerConfig(env: ContainerConfigEnv): ContainerConfig {
+  const server = parseServerConfig(buildServerInput(env));
+  return {
+    server,
+    tcpPort: parseIntOrDefault(env.TCP_PORT, DEFAULT_TCP_PORT),
+    tcpHost: env.TCP_HOST?.trim() || DEFAULT_TCP_HOST,
+    persistencePath:
+      env.PERSISTENCE_PATH !== undefined && env.PERSISTENCE_PATH.length > 0
+        ? env.PERSISTENCE_PATH
+        : undefined,
+    snapshotIntervalMs: parseIntOrDefault(env.SNAPSHOT_INTERVAL_MS, DEFAULT_SNAPSHOT_INTERVAL_MS),
+  };
+}
+
+function parseIntOrDefault(raw: string | undefined, def: number): number {
+  if (raw === undefined || raw.trim().length === 0) return def;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) ? n : def;
+}
+
+function buildServerInput(env: ContainerConfigEnv): Record<string, unknown> {
+  const input: Record<string, unknown> = {
+    serverName: env.SERVER_NAME ?? DEFAULT_SERVER_NAME,
+    networkName: env.NETWORK_NAME ?? DEFAULT_NETWORK_NAME,
+  };
+  if (env.SERVER_VERSION !== undefined) input.serverVersion = env.SERVER_VERSION;
+  if (env.CREATED_AT !== undefined) input.createdAt = parseCreatedAt(env.CREATED_AT);
+  if (env.MOTD_LINES !== undefined && env.MOTD_LINES.length > 0) {
+    input.motdLines = env.MOTD_LINES.split('\n');
+  }
+  if (env.MAX_CLIENTS !== undefined) input.maxClients = Number.parseInt(env.MAX_CLIENTS, 10);
+  if (env.CHANNEL_PREFIXES !== undefined) input.channelPrefixes = env.CHANNEL_PREFIXES;
+  if (env.OPER_USER !== undefined || env.OPER_PASSWORD !== undefined) {
+    input.operCreds = [{ user: env.OPER_USER ?? '', password: env.OPER_PASSWORD ?? '' }];
+  }
+  if (env.MAX_CHANNELS_PER_USER !== undefined) {
+    input.maxChannelsPerUser = Number.parseInt(env.MAX_CHANNELS_PER_USER, 10);
+  }
+  if (env.MAX_TARGETS_PER_COMMAND !== undefined) {
+    input.maxTargetsPerCommand = Number.parseInt(env.MAX_TARGETS_PER_COMMAND, 10);
+  }
+  if (env.NICK_LEN !== undefined) input.nickLen = Number.parseInt(env.NICK_LEN, 10);
+  if (env.CHANNEL_LEN !== undefined) input.channelLen = Number.parseInt(env.CHANNEL_LEN, 10);
+  if (env.TOPIC_LEN !== undefined) input.topicLen = Number.parseInt(env.TOPIC_LEN, 10);
+  if (env.MAX_LIST_ENTRIES !== undefined) {
+    input.maxListEntries = Number.parseInt(env.MAX_LIST_ENTRIES, 10);
+  }
+  if (env.QUIT_MESSAGE !== undefined) input.quitMessage = env.QUIT_MESSAGE;
+  if (env.SASL_ACCOUNTS !== undefined && env.SASL_ACCOUNTS.length > 0) {
+    input.saslAccounts = parseSaslAccountsLines(env.SASL_ACCOUNTS);
+  }
+  return input;
+}
+
+function parseCreatedAt(raw: string): string | number {
+  if (/^\d+$/.test(raw.trim())) {
+    const n = Number(raw.trim());
+    if (Number.isFinite(n)) return n;
+  }
+  return raw;
+}
+
+function parseSaslAccountsLines(raw: string): Array<{ username: string; password: string }> {
+  const out: Array<{ username: string; password: string }> = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    const sep = trimmed.indexOf(':');
+    if (sep <= 0) continue;
+    const username = trimmed.slice(0, sep);
+    const password = trimmed.slice(sep + 1);
+    if (username.length === 0 || password.length === 0) continue;
+    out.push({ username, password });
+  }
+  return out;
+}

package/apps/cf-tcp-container/src/container-do.ts

@@ -0,0 +1,38 @@
+/**
+ * Cloudflare Container DO for the IRC TCP origin.
+ *
+ * The container runs the IRC core as a plaintext TCP server (port 6667).
+ * Spectrum terminates TLS on :6697 and forwards plaintext to this
+ * container. The DO wrapper provides persistent identity and lifecycle
+ * management.
+ */
+
+import { Container } from '@cloudflare/containers';
+
+export class IrcTcpOrigin extends Container {
+  // The IRC TCP server port inside the container.
+  defaultPort = 6667;
+  requiredPorts = [6667];
+
+  // Keep the container alive for long-lived IRC connections.
+  sleepAfter = '2h';
+
+  enableInternet = true;
+
+  envVars = {
+    TCP_PORT: '6667',
+    TCP_HOST: '0.0.0.0',
+  };
+
+  onStart(): void {
+    console.log('IrcTcpOrigin container started');
+  }
+
+  onStop(): void {
+    console.log('IrcTcpOrigin container stopping');
+  }
+
+  onError(error: Error): void {
+    console.error('IrcTcpOrigin container error:', error);
+  }
+}