serverless-ircd 0.3.0 → 0.4.0

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

@@ -0,0 +1,363 @@
+/**
+ * CF TCP container origin — the stateful IRC server behind Cloudflare
+ * Spectrum.
+ *
+ * Spectrum terminates TLS at the edge and forwards plaintext TCP to this
+ * origin. The container runs the shared IRC core (`ConnectionActor` +
+ * `InMemoryRuntime`) over the `TcpByteStreamTransport` seam,
+ * which reassembles `\r\n`-terminated IRC lines across arbitrary TCP
+ * chunks. The actor/reducer/dispatch pipeline is identical to the wss
+ * path — only the line-framing transport differs.
+ *
+ * When `persistencePath` is supplied, channel state (topics, modes, bans)
+ * is restored from a snapshot file on boot and auto-saved on an interval
+ * plus at graceful shutdown, so a restart doesn't lose channel topology.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { type Server, type Socket, createServer } from 'node:net';
+import { InMemoryRuntime } from '@serverless-ircd/in-memory-runtime';
+import {
+  type AccountStore,
+  type AdmissionConfig,
+  type ChanName,
+  type Clock,
+  type ConnectionState,
+  ConsoleLogger,
+  InMemoryAccountStore,
+  InMemoryMessageStore,
+  InMemoryNickHistoryStore,
+  LogLevel,
+  type Logger,
+  type MessageStore,
+  type NickHistoryStore,
+  type RawLine,
+  createConnection,
+} from '@serverless-ircd/irc-core';
+import { ConnectionActor, TcpByteStreamTransport } from '@serverless-ircd/irc-server';
+import { loadSnapshot, restoreRuntime, saveSnapshot, snapshotRuntime } from './persistence.js';
+
+/** Options accepted by {@link startContainerServer}. */
+export interface StartContainerOptions {
+  /** Plaintext TCP port. Use 0 for an ephemeral port. */
+  readonly port: number;
+  /** Bind address. Defaults to `0.0.0.0` (Spectrum forwards from the edge). */
+  readonly host?: string;
+  readonly serverName: string;
+  readonly networkName: string;
+  readonly motdLines?: string[];
+  readonly maxChannelsPerUser?: number;
+  readonly maxTargetsPerCommand?: number;
+  readonly maxListEntries?: number;
+  readonly nickLen?: number;
+  readonly channelLen?: number;
+  readonly topicLen?: number;
+  readonly quitMessage?: string;
+  readonly serverPassword?: string;
+  readonly cloaking?: { enabled: boolean; secret: string; cloakedSuffix?: string };
+  readonly maxConnectionsPerIp?: number;
+  readonly maxConnectionsPerUser?: number;
+  readonly perIpConnectionRate?: { max: number; windowMs: number };
+  readonly historyMaxPerChannel?: number;
+  readonly saslAccounts?: Array<{ username: string; password: string }>;
+  /**
+   * Path to the persistence snapshot file. When set, channel state is
+   * restored on boot and auto-saved every {@link snapshotIntervalMs} plus
+   * at shutdown. Omit to disable persistence.
+   */
+  readonly persistencePath?: string;
+  /** Auto-snapshot interval in milliseconds. Defaults to 60 000. */
+  readonly snapshotIntervalMs?: number;
+  /** Injected clock (testing). Defaults to wall-clock `Date.now()`. */
+  readonly clock?: Clock;
+}
+
+/** A running container origin. Call {@link close} to shut down. */
+export interface ContainerServer {
+  readonly port: number;
+  readonly host: string;
+  readonly runtime: InMemoryRuntime;
+  readonly messages: MessageStore;
+  readonly history: NickHistoryStore;
+  /**
+   * Test-only seam: live server-side TCP sockets. Production code MUST
+   * NOT use.
+   */
+  readonly testSockets: ReadonlySet<Socket>;
+  close(): Promise<void>;
+}
+
+interface ConnectionBindings {
+  state: ConnectionState;
+  actor: ConnectionActor;
+}
+
+const DEFAULT_ID_FACTORY = {
+  batchId: () => randomUUID(),
+  nonce: () => randomUUID(),
+  sessionId: () => randomUUID(),
+  traceId: () => randomUUID(),
+};
+
+const DEFAULT_MAX_CONNECTIONS_PER_IP = 10;
+const DEFAULT_MAX_CONNECTIONS_PER_USER = 5;
+const DEFAULT_PER_IP_CONNECTION_RATE = { max: 5, windowMs: 60_000 };
+const DEFAULT_SNAPSHOT_INTERVAL_MS = 60_000;
+
+/**
+ * Starts the TCP container origin. Resolves once the TCP listener is
+ * ready. When `persistencePath` is set and a snapshot file exists, channel
+ * state is restored before any connection is accepted.
+ */
+export async function startContainerServer(opts: StartContainerOptions): Promise<ContainerServer> {
+  const host = opts.host ?? '0.0.0.0';
+  const clock: Clock = opts.clock ?? { now: () => Date.now() };
+
+  const admission: AdmissionConfig | undefined =
+    opts.maxConnectionsPerIp !== undefined ||
+    opts.maxConnectionsPerUser !== undefined ||
+    opts.perIpConnectionRate !== undefined
+      ? {
+          maxConnectionsPerIp: opts.maxConnectionsPerIp ?? DEFAULT_MAX_CONNECTIONS_PER_IP,
+          maxConnectionsPerUser: opts.maxConnectionsPerUser ?? DEFAULT_MAX_CONNECTIONS_PER_USER,
+          perIpConnectionRate: opts.perIpConnectionRate ?? DEFAULT_PER_IP_CONNECTION_RATE,
+        }
+      : undefined;
+
+  const runtime = new InMemoryRuntime({
+    clock,
+    ...(admission !== undefined ? { admission } : {}),
+  });
+
+  const messages = new InMemoryMessageStore(opts.historyMaxPerChannel);
+  const history = new InMemoryNickHistoryStore(clock);
+  const accounts: AccountStore | undefined =
+    opts.saslAccounts !== undefined && opts.saslAccounts.length > 0
+      ? new InMemoryAccountStore(opts.saslAccounts)
+      : undefined;
+
+  // Restore persisted channel state before accepting connections.
+  if (opts.persistencePath !== undefined) {
+    try {
+      const snap = await loadSnapshot(opts.persistencePath);
+      if (snap !== null) {
+        restoreRuntime(runtime, snap);
+      }
+    } catch (err) {
+      logError('failed to load persistence snapshot; starting fresh', err);
+    }
+  }
+
+  const connections = new Map<Socket, ConnectionBindings>();
+  const sockets = new Set<Socket>();
+
+  const tcpServer = createServer((socket) => {
+    sockets.add(socket);
+
+    const ip = socket.remoteAddress ?? 'unknown';
+    const decision = runtime.admitConnection(ip, undefined);
+    if (!decision.ok) {
+      if (socket.writable) {
+        socket.write(`ERROR :Closing link: (connection limit reached: ${decision.reason})\r\n`);
+      }
+      socket.destroy();
+      sockets.delete(socket);
+      return;
+    }
+    const admissionRecordId = decision.recordId;
+    runtime.commitAdmission(ip, undefined, admissionRecordId);
+
+    const { state, actor } = attachConnection(runtime, opts, messages, accounts, history, clock, {
+      sendText: (text) => {
+        if (socket.writable) socket.write(text);
+      },
+      closeTransport: () => socket.destroy(),
+      admissionRecordId,
+      sourceHost: ip,
+    });
+    connections.set(socket, { state, actor });
+
+    socket.on('data', (chunk: Buffer) => {
+      actor.receive(chunk.toString('utf8')).catch((err) => {
+        logError('actor failure', err);
+      });
+    });
+
+    const cleanup = (): void => {
+      connections.delete(socket);
+      sockets.delete(socket);
+      runtime.unregisterConnection(state.id);
+    };
+    socket.on('close', cleanup);
+    socket.on('error', (err) => {
+      logError('tcp socket error', err);
+      cleanup();
+    });
+  });
+
+  // Auto-snapshot timer.
+  const snapshotIntervalMs = opts.snapshotIntervalMs ?? DEFAULT_SNAPSHOT_INTERVAL_MS;
+  const timer: ReturnType<typeof setInterval> | undefined =
+    opts.persistencePath !== undefined
+      ? setInterval(() => {
+          void snapshotNow(runtime, opts.persistencePath as string);
+        }, snapshotIntervalMs)
+      : undefined;
+  if (timer !== undefined) timer.unref?.();
+
+  return new Promise<ContainerServer>((resolve, reject) => {
+    const onError = (err: Error): void => {
+      tcpServer.removeListener('listening', onListening);
+      reject(err);
+    };
+    const onListening = (): void => {
+      tcpServer.removeListener('error', onError);
+      const addr = tcpServer.address();
+      // c8 ignore next 1
+      const port = typeof addr === 'object' && addr !== null ? addr.port : opts.port;
+      resolve({
+        port,
+        host,
+        runtime,
+        messages,
+        history,
+        testSockets: sockets,
+        close: () =>
+          closeServer({
+            tcpServer,
+            connections,
+            sockets,
+            timer,
+            runtime,
+            persistencePath: opts.persistencePath,
+          }),
+      });
+    };
+    tcpServer.once('listening', onListening);
+    tcpServer.once('error', onError);
+    tcpServer.listen(opts.port, host);
+  });
+}
+
+function attachConnection(
+  runtime: InMemoryRuntime,
+  opts: StartContainerOptions,
+  messages: MessageStore,
+  accounts: AccountStore | undefined,
+  history: NickHistoryStore,
+  clock: Clock,
+  transport: {
+    sendText: (text: string) => void;
+    closeTransport: () => void;
+    admissionRecordId?: string;
+    sourceHost?: string;
+  },
+): ConnectionBindings {
+  const id = randomUUID();
+  const state = createConnection({ id, connectedSince: clock.now() });
+  if (transport.sourceHost !== undefined) {
+    state.host = transport.sourceHost;
+  }
+
+  const logger: Logger = new ConsoleLogger({ connectionId: id }, undefined, LogLevel.Info);
+
+  const actor = new ConnectionActor({
+    state,
+    runtime,
+    channels: runtime,
+    serverConfig: {
+      serverName: opts.serverName,
+      networkName: opts.networkName,
+      maxChannelsPerUser: opts.maxChannelsPerUser ?? 30,
+      maxTargetsPerCommand: opts.maxTargetsPerCommand ?? 10,
+      maxListEntries: opts.maxListEntries ?? 50,
+      nickLen: opts.nickLen ?? 30,
+      channelLen: opts.channelLen ?? 50,
+      topicLen: opts.topicLen ?? 390,
+      quitMessage: opts.quitMessage ?? 'Client Quit',
+      ...(opts.serverPassword !== undefined ? { serverPassword: opts.serverPassword } : {}),
+      ...(opts.cloaking !== undefined ? { cloaking: opts.cloaking } : {}),
+    },
+    clock,
+    ids: DEFAULT_ID_FACTORY,
+    motd: { lines: () => opts.motdLines ?? [] },
+    messages,
+    ...(accounts !== undefined ? { accounts } : {}),
+    history,
+    logger,
+    transport: new TcpByteStreamTransport(),
+  });
+
+  runtime.registerConnection(
+    state,
+    {
+      send: (lines: RawLine[]) => {
+        const text = `${lines.map((l) => l.text).join('\r\n')}\r\n`;
+        transport.sendText(text);
+      },
+      disconnect: (reason?: string) => {
+        if (reason !== undefined) {
+          transport.sendText(`ERROR :Closing link: (${reason})\r\n`);
+        }
+        transport.closeTransport();
+      },
+    },
+    transport.admissionRecordId,
+  );
+
+  return { state, actor };
+}
+
+async function closeServer(args: {
+  tcpServer: Server;
+  connections: Map<Socket, ConnectionBindings>;
+  sockets: Set<Socket>;
+  timer: ReturnType<typeof setInterval> | undefined;
+  runtime: InMemoryRuntime;
+  persistencePath: string | undefined;
+}): Promise<void> {
+  const { tcpServer, connections, sockets, timer, runtime, persistencePath } = args;
+
+  if (timer !== undefined) clearInterval(timer);
+
+  // Destroy all live sockets so clients see the disconnect.
+  for (const socket of sockets) {
+    if (!socket.destroyed) socket.destroy();
+  }
+  sockets.clear();
+  connections.clear();
+
+  if (persistencePath !== undefined) {
+    try {
+      await snapshotNow(runtime, persistencePath);
+    } catch (err) {
+      logError('failed to save final snapshot', err);
+    }
+  }
+
+  // Stop accepting new connections. We do NOT await the callback because
+  // `server.close()` waits for every connection's 'close' event, which can
+  // hang if a destroyed socket's TCP cleanup is delayed by the OS. All
+  // sockets are already destroyed above; the server is safe to abandon.
+  tcpServer.close();
+  (tcpServer as Server & { closeAllConnections?: () => void }).closeAllConnections?.();
+  tcpServer.unref();
+}
+
+async function snapshotNow(runtime: InMemoryRuntime, path: string): Promise<void> {
+  const state = await snapshotRuntime(runtime);
+  await saveSnapshot(path, state);
+}
+
+function logError(msg: string, err: unknown): void {
+  const payload = {
+    ts: new Date().toISOString(),
+    level: 'error',
+    msg,
+    err: err instanceof Error ? { name: err.name, message: err.message } : err,
+  };
+  // eslint-disable-next-line no-console
+  console.error(JSON.stringify(payload));
+}
+
+export type { ChanName };

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

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * CF TCP container origin entry point.
+ *
+ * Boots the IRC core as a plaintext TCP server behind Cloudflare Spectrum.
+ * Spectrum terminates TLS at the edge and forwards plaintext TCP to this
+ * process. Configuration comes from environment variables (set by the
+ * Cloudflare Container runtime, Docker, or Kubernetes).
+ *
+ * Usage:
+ *   TCP_PORT=6667 SERVER_NAME=irc.example.com node dist/main.js
+ *
+ * The process runs until SIGINT/SIGTERM. On shutdown it writes a final
+ * persistence snapshot (when PERSISTENCE_PATH is set) so channel state
+ * survives the next boot.
+ */
+
+import { loadContainerConfig } from './config-loader.js';
+import { startContainerServer } from './container-server.js';
+
+async function main(): Promise<void> {
+  const cfg = loadContainerConfig(process.env as Record<string, string | undefined>);
+
+  const server = await startContainerServer({
+    port: cfg.tcpPort,
+    host: cfg.tcpHost,
+    serverName: cfg.server.serverName,
+    networkName: cfg.server.networkName,
+    motdLines: cfg.server.motdLines,
+    maxChannelsPerUser: cfg.server.maxChannelsPerUser,
+    maxTargetsPerCommand: cfg.server.maxTargetsPerCommand,
+    maxListEntries: cfg.server.maxListEntries,
+    nickLen: cfg.server.nickLen,
+    channelLen: cfg.server.channelLen,
+    topicLen: cfg.server.topicLen,
+    quitMessage: cfg.server.quitMessage,
+    snapshotIntervalMs: cfg.snapshotIntervalMs,
+    ...(cfg.persistencePath !== undefined ? { persistencePath: cfg.persistencePath } : {}),
+    ...(cfg.server.saslAccounts !== undefined && cfg.server.saslAccounts.length > 0
+      ? { saslAccounts: cfg.server.saslAccounts }
+      : {}),
+  });
+
+  process.stdout.write(
+    `${JSON.stringify({
+      ts: new Date().toISOString(),
+      level: 'info',
+      msg: 'cf-tcp-container listening',
+      host: server.host,
+      port: server.port,
+      persistence: cfg.persistencePath ?? null,
+      serverName: cfg.server.serverName,
+    })}\n`,
+  );
+
+  const shutdown = (signal: string): void => {
+    process.stdout.write(
+      `${JSON.stringify({ ts: new Date().toISOString(), level: 'info', msg: 'shutdown', signal })}\n`,
+    );
+    server
+      .close()
+      .then(() => process.exit(0))
+      .catch((err) => {
+        process.stderr.write(`shutdown error: ${String(err)}\n`);
+        process.exit(1);
+      });
+  };
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
+
+main().catch((err) => {
+  process.stderr.write(
+    `fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`,
+  );
+  process.exit(1);
+});

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

@@ -0,0 +1,144 @@
+/**
+ * Runtime persistence for the CF TCP container origin.
+ *
+ * The container is a stateful process fronted by Cloudflare Spectrum (TLS
+ * termination). When the container restarts (crash, deploy, scale event)
+ * every live TCP connection drops — clients must reconnect. But the
+ * channel topology they built (topics, modes, ban masks) must survive so
+ * a reconnecting client doesn't find a bare server.
+ *
+ * This module snapshots the non-connection channel state (everything
+ * EXCEPT the member roster — those ConnIds are stale after a restart) to
+ * a JSON file on the container's persistent volume and restores it on
+ * boot. The shape is deliberately minimal and forward-compatible
+ * (`version` field) so future schema changes can migrate.
+ *
+ * Connection state survives origin reconnect via the runtime's
+ * persistence layer.
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+
+import type { InMemoryRuntime } from '@serverless-ircd/in-memory-runtime';
+import type { ChanSnapshot, ChannelModes, ChannelTopic } from '@serverless-ircd/irc-core';
+
+/** Schema version for the persisted snapshot file. */
+const SCHEMA_VERSION = 1;
+
+/**
+ * One channel's persistent state. Mirrors {@link ChannelState} minus the
+ * member roster and pending invites — both are per-connection and cannot
+ * outlive the connections that created them.
+ */
+export interface PersistedChannel {
+  name: string;
+  nameLower: string;
+  modes: ChannelModes;
+  banMasks: string[];
+  topic?: ChannelTopic;
+  createdAt: number;
+}
+
+/** Top-level persisted state envelope. */
+export interface PersistedState {
+  version: typeof SCHEMA_VERSION;
+  savedAt: number;
+  channels: PersistedChannel[];
+}
+
+/**
+ * Extracts every channel's durable state from `runtime`. Members and
+ * pending invites are omitted — they reference ConnIds that will be stale
+ * after a restart.
+ */
+export async function snapshotRuntime(runtime: InMemoryRuntime): Promise<PersistedState> {
+  return snapshotFromList(await runtime.listChannels());
+}
+
+/** Pure extraction from pre-fetched channel snapshots. */
+export function snapshotFromList(channels: ReadonlyArray<ChanSnapshot>): PersistedState {
+  return {
+    version: SCHEMA_VERSION,
+    savedAt: Date.now(),
+    channels: channels.map((c) => {
+      const entry: PersistedChannel = {
+        name: c.name,
+        nameLower: c.nameLower,
+        modes: { ...c.modes },
+        banMasks: [...c.banMasks],
+        createdAt: c.createdAt,
+      };
+      if (c.topic !== undefined) entry.topic = c.topic;
+      return entry;
+    }),
+  };
+}
+
+/** Serializes a {@link PersistedState} to a JSON string. */
+export function serializeState(state: PersistedState): string {
+  return JSON.stringify(state);
+}
+
+/**
+ * Parses and validates a JSON string into a {@link PersistedState}. Throws
+ * on malformed JSON or an incompatible schema version.
+ */
+export function deserializeState(json: string): PersistedState {
+  const parsed = JSON.parse(json) as unknown;
+  if (typeof parsed !== 'object' || parsed === null) {
+    throw new Error('invalid persisted state: expected an object');
+  }
+  const obj = parsed as Record<string, unknown>;
+  if (obj.version !== SCHEMA_VERSION) {
+    throw new Error(
+      `incompatible persisted state version: got ${String(obj.version)}, expected ${SCHEMA_VERSION}`,
+    );
+  }
+  if (!Array.isArray(obj.channels)) {
+    throw new Error('invalid persisted state: channels is not an array');
+  }
+  return {
+    version: SCHEMA_VERSION,
+    savedAt: typeof obj.savedAt === 'number' ? obj.savedAt : 0,
+    channels: obj.channels as PersistedChannel[],
+  };
+}
+
+/** Writes a snapshot to `filePath`. */
+export async function saveSnapshot(filePath: string, state: PersistedState): Promise<void> {
+  await writeFile(filePath, serializeState(state), 'utf8');
+}
+
+/**
+ * Reads and parses a snapshot from `filePath`. Returns `null` when the
+ * file does not exist (first boot). Throws on corrupt content so the
+ * caller can log and continue with a fresh state.
+ */
+export async function loadSnapshot(filePath: string): Promise<PersistedState | null> {
+  let raw: string;
+  try {
+    raw = await readFile(filePath, 'utf8');
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw err;
+  }
+  return deserializeState(raw);
+}
+
+/**
+ * Restores channels from a persisted snapshot into `runtime`. Each channel
+ * is created via `getOrCreateChannel` (so the runtime owns it) and then its
+ * modes, ban masks, topic, and original `createdAt` are overwritten. The
+ * member roster stays empty — clients reconnect and rejoin after a restart.
+ */
+export function restoreRuntime(runtime: InMemoryRuntime, state: PersistedState): void {
+  for (const pc of state.channels) {
+    const chan = runtime.getOrCreateChannel(pc.name);
+    chan.modes = { ...pc.modes };
+    chan.banMasks = new Set(pc.banMasks);
+    if (pc.topic !== undefined) {
+      chan.topic = pc.topic;
+    }
+    chan.createdAt = pc.createdAt;
+  }
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Worker entry for the CF TCP container origin.
+ *
+ * This Worker is a thin management wrapper around the Cloudflare Container.
+ * It is NOT in the data path for IRC traffic — Spectrum terminates TLS on
+ * :6697 and forwards plaintext TCP directly to the container's port 6667.
+ * The Worker exists for:
+ *   - Health checks (`GET /health` → container status).
+ *   - Container lifecycle management (start/stop via the DO binding).
+ */
+
+export { IrcTcpOrigin } from './container-do.js';
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+
+    if (url.pathname === '/health') {
+      const container = env.IRC_TCP_ORIGIN.getByName('singleton');
+      try {
+        await container.startAndWaitForPorts();
+        return new Response(JSON.stringify({ ok: true, status: 'running' }), {
+          headers: { 'content-type': 'application/json' },
+        });
+      } catch {
+        return new Response(JSON.stringify({ ok: false, status: 'error' }), {
+          status: 503,
+          headers: { 'content-type': 'application/json' },
+        });
+      }
+    }
+
+    return new Response('ServerlessIRCd TCP origin management endpoint\n', {
+      headers: { 'content-type': 'text/plain' },
+    });
+  },
+};
+
+interface Env {
+  IRC_TCP_ORIGIN: DurableObjectNamespace;
+}

package/apps/cf-tcp-container/terraform/provider.tf

@@ -0,0 +1,24 @@
+###############################################################################
+# Terraform provider config for Cloudflare Spectrum.
+#
+# Configure via environment variables:
+#   export CLOUDFLARE_API_TOKEN=cf-secret-token
+#   export CLOUDFLARE_ACCOUNT_ID=your-account-id
+#
+# Or via a *.tfvars file passed with -var-file.
+###############################################################################
+
+terraform {
+  required_version = ">= 1.5"
+  required_providers {
+    cloudflare = {
+      source  = "cloudflare/cloudflare"
+      version = "~> 4.0"
+    }
+  }
+}
+
+provider "cloudflare" {
+  # api_token and account_id are read from CLOUDFLARE_API_TOKEN and
+  # CLOUDFLARE_ACCOUNT_ID environment variables.
+}