serverless-ircd 0.5.0 → 0.7.0

package/README.md

@@ -6,7 +6,7 @@ platform-agnostic core, and two thin adapters run it on **Cloudflare Workers**
 
 One TypeScript codebase. Two serverless substrates.
 
-> **Status:** **v0.5.0 (preview).** The pure protocol core, the
+> **Status:** **v0.7.0 (preview).** The pure protocol core, the
 > `IrcRuntime` port + in-memory runtime, a runnable local CLI server,
 > the **Cloudflare Workers** adapter, and the **AWS** (API Gateway
 > WebSocket + Lambda + DynamoDB + CDK) adapter are all functional and
@@ -15,14 +15,27 @@ One TypeScript codebase. Two serverless substrates.
 > clients — Cloudflare via Spectrum + a Container origin, AWS via a
 > Network Load Balancer + Lambda streaming — alongside the WebSocket
 > path, plus **SASL `EXTERNAL` via mTLS** and a **Cloudflare D1-backed
-> SASL account store**. v0.5.0 completes the **protocol surface**: the
+> SASL account store**. v0.5.0 completed the **protocol surface**: the
 > deferred IRC verbs (`KILL`, `REHASH`, `LUSERS` + `STATS`, `TRACE`,
 > `WALLOPS`, `SETNAME`) all land, and the S2S (`CONNECT` / `SQUIT` /
 > `LINKS`) and obsolete RFC 2812 (`SERVICE` / `SUMMON` / `USERS`) verbs
-> are formally dropped — every standard verb a modern client expects is
-> now implemented. Remaining 0.x work: the load/compat sweep
-> (10k-connection load test + client compatibility matrix) and a
-> required-`serverName` config gate. See `CHANGELOG.md` for the
+> are formally dropped. v0.6.0 landed the **IRCv3 extension sweep
+> (Phase 12)** — ten caps (`account-notify`, `msgid`,
+> `standard-replies`, `MONITOR`, `labeled-response`, `sts`,
+> `draft/typing`, `draft/multiline`, `draft/read-marker`,
+> `draft/pre-away`), the ISUPPORT tokens for the new caps, and the
+> read-only user mode `S` (TLS connected). **v0.7.0 lands the web
+> client (Phase 14)**: a vendored **Kiwi IRC** SPA served at `/app/`
+> and a static landing page at `/` directly by the Cloudflare Worker,
+> with **Cross-Site WebSocket Hijacking (CSWSH) defense** wired into
+> the WS upgrade path (same-origin auto-derive by default, optional
+> `WEB_ORIGINS` allowlist for cross-origin deploys) — the browser
+> opens a native `wss://` straight to the existing IRC-over-WebSocket
+> endpoint. Remaining 0.x work: the client compatibility sweep
+> (WeeChat / HexChat / IRCCloud / TheLounge), the Playwright
+> browser-driven e2e for the SPA, IRC services (NickServ / ChanServ /
+> HostServ / OperServ / MemoServ), and driving the remaining
+> sub-100% packages to full coverage. See `CHANGELOG.md` for the
 > per-release manifests.
 
 ---
@@ -124,12 +137,14 @@ ServerlessIRCd/
 │   ├── cf-adapter/        Durable Objects + CfRuntime
 │   └── aws-adapter/       Lambda + DynamoDB + AwsRuntime
 ├── apps/
-│   ├── cf-worker/         worker entry, DO migrations, bindings
+│   ├── cf-worker/         worker entry, DO migrations, bindings, [assets] + CSWSH gate
 │   ├── cf-tcp-container/  Spectrum + Container origin for irc+tls :6697
 │   ├── aws-stack/         CDK stack (APIGW WS + NLB + Lambda streaming + DynamoDB)
+│   ├── web/               vendored Kiwi IRC SPA (→ /app/) + static landing page (→ /)
 │   └── local-cli/         runnable WS + TCP server using in-memory-runtime
 ├── tools/
 │   ├── tcp-ws-forwarder/  local TCP↔ws/wss bridge for stock IRC clients
+│   ├── load-test/         synthetic WebSocket IRC client farm (10k conns, p50/p95/p99, drop rate)
 │   ├── ci-hardening/      coverage-gate + mutation-config validators
 │   ├── seed-aws-accounts.ts  scrypt-hash SASL PLAIN accounts into DynamoDB
 │   └── seed-cf-accounts.ts   scrypt-hash SASL PLAIN accounts into Cloudflare D1
@@ -163,6 +178,7 @@ pin is resolved automatically:
 ```bash
 corepack enable            # lets the pinned pnpm@11 run on any Node ≥ 24
 
+git submodule update --init   # docs + apps/web Kiwi upstream sources
 pnpm install              # install workspace deps
 
 pnpm build                # build all packages (turbo)
@@ -180,6 +196,14 @@ pnpm mutation             # Stryker spot-check on irc-core (protocol + commands)
 pnpm clean                # remove dist/coverage/.turbo + node_modules
 ```
 
+The web client (`apps/web`) vendors Kiwi IRC as a git submodule. Building it
+needs the upstream sources (`git submodule update --init apps/web/upstream`)
+and `yarn` (Kiwi ships a `yarn.lock`; `corepack enable` provides it):
+
+```bash
+pnpm --filter web build   # builds the Kiwi SPA into apps/web/dist/app/ (/app/)
+```
+
 Coverage reports are written to `packages/*/coverage/`. CI (`.github/workflows/ci.yml`)
 runs lint, typecheck, the coverage gate, the parametrized contract suite, and a
 Stryker mutation spot-check on every push and pull request. Coverage thresholds
@@ -230,6 +254,8 @@ On startup it logs a JSON line like:
 | `--tcp-port <n>`   | `<port> + 1`  | TCP port for RFC-style IRC clients.                    |
 | `--no-tcp`         |               | Disable the TCP listener (WebSocket only).             |
 | `--motd-file <p>`  | built-in      | Read MOTD lines from this file (one per line).         |
+| `--server-name <h>`| `irc.localhost` | Server hostname advertised in `001`/`005`. Production MUST override. |
+| `--network-name <n>`| `LocalNet`   | Network name advertised in `005 NETWORK=…`.            |
 | `-h, --help`       |               | Show help and exit.                                    |
 
 Pass `--host 0.0.0.0` to expose the server on all interfaces. `SIGINT` /
@@ -302,6 +328,115 @@ against any line-oriented WebSocket endpoint.
 
 ---
 
+## Load testing (`tools/load-test`)
+
+A synthetic WebSocket IRC client farm (PLAN §7, Phase 7). It opens N
+connections to a `ws://` / `wss://` target, registers each (NICK/USER),
+joins a channel, and optionally chats. Per-phase **p50 / p95 / p99
+latency** (connect / register / join / message) and the **drop rate**
+are captured, then printed as a markdown report to stdout (and written
+to `--report <path>` when given).
+
+Build the workspace, then start a run (from the repo root):
+
+```bash
+pnpm build
+
+pnpm --filter load-test start -- \
+  --target wss://irc.staging.example.com/ \
+  --connections 10000 --concurrency 200 --ramp-ms 60000 \
+  --channel '#loadtest' --messages 3 --platform cf-staging \
+  --report reports/cf-staging-2026-08-03.md
+```
+
+The harness drives the WebSocket transport only (the serverless default);
+a TCP IRC client is not what a serverless load test exercises. Each
+connection is independent — the package ships no `@serverless-ircd/*`
+runtime dependency (only the IRC line framing shared with the
+forwarder), so it can be pointed at any WebSocket IRC endpoint.
+
+### CLI flags
+
+| Flag                    | Default     | Description                                              |
+|-------------------------|-------------|----------------------------------------------------------|
+| `--target <url>`        | (required)  | Upstream `ws://` or `wss://` URL to load test.           |
+| `--connections <n>`     | `1000`      | Total connections to open.                               |
+| `--concurrency <n>`     | `50`        | Concurrent in-flight connection attempts during ramp-up. |
+| `--ramp-ms <ms>`        | `30000`     | Ramp-up duration over which connections are opened.      |
+| `--channel <c>`         | `#loadtest` | Channel every client JOINs.                              |
+| `--messages <n>`        | `0`         | PRIVMSGs each client sends after JOIN (`0` = connect only). |
+| `--echo-message`        |             | Negotiate `echo-message` so sent PRIVMSGs round-trip.    |
+| `--platform <name>`     | `unknown`   | Label baked into the report header.                      |
+| `--report <path>`       |             | Write the markdown report to this path.                  |
+| `-h, --help`            |             | Show help and exit.                                      |
+
+`SIGINT` / `SIGTERM` cancel an in-flight run gracefully (drains live
+sockets, prints the partial report). The package ships its own vitest
+suite at ≥90% coverage (config parsing, framing, harness, metrics,
+report).
+
+---
+
+## Web client (`apps/web`)
+
+A vendored **Kiwi IRC** SPA served at `/app/` and a static project
+landing page served at `/`, both baked out of `apps/web/dist/` and
+served directly by the Cloudflare Worker via its `[assets]` binding.
+The browser opens a native `wss://` straight to the Worker's existing
+IRC-over-WebSocket endpoint — no proxy, gateway, or transport
+adaptation in the hot path. See `docs/WebClientGuide.md` for the
+end-to-end contributor/operator guide.
+
+Build the SPA + landing page (needs the submodule + `yarn`, provided by
+`corepack enable`):
+
+```bash
+git submodule update --init apps/web/upstream   # one-time per clone
+pnpm --filter web build:staging                 # or :prod / default
+# → apps/web/dist/index.html        (landing page, served at /)
+# → apps/web/dist/app/index.html    (Kiwi SPA, served at /app/)
+# → apps/web/dist/app/static/config.json  (baked, env-specific)
+```
+
+Then run everything locally (Worker serves SPA + landing page + WS on
+one origin):
+
+```bash
+pnpm build                                     # workspace packages
+pnpm --filter @serverless-ircd/cf-worker dev   # http://localhost:8787
+#   /        → landing page
+#   /app/    → Kiwi SPA (opens ws://localhost:8787/)
+#   /health  → plaintext liveness
+```
+
+Deploy staging (Worker + assets in one command):
+
+```bash
+pnpm deploy:cf:staging   # wrangler deploy --env staging
+```
+
+### WebSocket Origin policy (CSWSH defense)
+
+WebSocket upgrades do **not** follow the same-origin policy, so the
+Worker rejects browser upgrades whose `Origin` is not allowed — see
+`apps/cf-worker/src/origin-allowlist.ts` and the SPA guide §5. Two
+modes, evaluated in order:
+
+1. **Explicit allowlist** — set `WEB_ORIGINS` (comma-separated) for
+   cross-origin deploys (SPA on a different domain than the Worker,
+   e.g. Cloudflare Pages). Only listed origins proceed.
+2. **Same-origin auto-derive (the default)** — when `WEB_ORIGINS` is
+   unset/empty, the Worker compares the browser's `Origin` against the
+   request's own origin. Match → proceed; mismatch → `403 Forbidden`.
+
+`WEB_ORIGINS` is **optional** — same-origin auto-derive needs zero
+per-env config and works for `*.workers.dev`, custom domains, and
+preview URLs alike. Non-browser clients (curl, WeeChat, the
+`tcp-ws-forwarder`, scripted harnesses) never send `Origin` and pass
+through unchanged in both modes.
+
+---
+
 ## WebSocket transport (IRCv3 subprotocols)
 
 The WebSocket entry points (the local CLI, the Cloudflare Worker, and the
@@ -373,21 +508,23 @@ cleanly. Per-release manifests live in `CHANGELOG.md`.
 - **Phase 2** — `IrcRuntime` port, in-memory runtime, `ConnectionActor`,
   local CLI, parametrized contract suite. ✅ landed in **v0.1.0**.
 - **Phase 3** — Cloudflare adapter (ConnectionDO / ChannelDO / RegistryDO).
-  ✅ landed in **v0.1.0** (staging auto-deploy via CI; prod deploy is manual).
+  ✅ landed in **v0.1.0** (staging deploy via CI; prod deploy is manual).
 - **Phase 4** — AWS adapter (APIGW WS + Lambda + DynamoDB + CDK).
-  ✅ landed in **v0.2.0** (staging auto-deploy via CI; prod deploy is manual).
+  ✅ landed in **v0.2.0** (staging deploy via CI; prod deploy is manual).
 - **Phase 5** — Observability, security hardening, config, CI gates.
   ✅ landed across v0.2.0–v0.4.0 (logger port, server-password, cloaking,
   admission limits, coverage + mutation gates, OPER credential auth, the
-  Cloudflare config loader, and AWS max-clients admission).
+  Cloudflare config loader, and AWS max-clients admission); the
+  required-`serverName` gate closed in **v0.6.0**.
 - **Phase 6** — TLS hardening & raw TCP transport (`irc+tls :6697`).
   ✅ landed in **v0.4.0**: generalized `ConnectionActor` transport seam,
   Cloudflare Spectrum + Container origin, AWS NLB + Lambda streaming,
   mTLS → SASL `EXTERNAL`, transport-parametrized contract suite, ADR-009.
-- **Phase 7** — Load testing (10k concurrent connections per platform)
-  and client compatibility sweep (WeeChat, HexChat, IRCCloud, TheLounge).
-  ⬳ pending; the dual-transport surface it needs
-  landed in v0.4.0.
+- **Phase 7 — Load testing & compatibility sweep.** 🔄 partial as of
+  **v0.6.0**: the `tools/load-test` 10k-connection harness is in-tree;
+  the formal 10k-connection report per platform and the client
+  compatibility matrix (WeeChat / HexChat / IRCCloud / TheLounge) are
+  still pending.
 - **Phase 8 — PLAN-FIXES remediation.** ✅ landed across v0.3.0–v0.4.0
   (MessageStore wired into all three adapters, AccountStore end-to-end,
   the DynamoDB `Accounts` table decided, CF enumeration RPCs, AWS QUIT
@@ -406,6 +543,33 @@ cleanly. Per-release manifests live in `CHANGELOG.md`.
   the formal drop of the S2S (`CONNECT`/`SQUIT`/`LINKS`) and obsolete
   RFC 2812 (`SERVICE`/`SUMMON`/`USERS`) verbs. The protocol surface is
   feature-complete for modern clients.
+- **Phase 12 — IRCv3 extension sweep.** ✅ landed in **v0.6.0**: ten
+  negotiated caps (`account-notify`, `msgid`, `standard-replies`,
+  `MONITOR`, `labeled-response`, `sts`, `draft/typing`,
+  `draft/multiline`, `draft/read-marker`, `draft/pre-away`), the
+  ISUPPORT tokens for the new caps (`MONITOR`/`MULTILINE`/`TYPING`/
+  `STATUSMSG`/`EXTBAN`/`ACCOUNTEXTBAN`), the read-only user mode `S`
+  (TLS connected), and the async push fanout seam (Registry hooks →
+  `MONITOR` online/offline, `BroadcastWallops`-style caps-gated
+  delivery).
+- **Phase 13 — IRC services.** ⬳ pending: `ServicesStore` port +
+  NickServ / ChanServ / HostServ / OperServ / MemoServ. Adapter
+  backends (D1 / DynamoDB) ship alongside; until then
+  `draft/read-marker` and `draft/pre-away` use in-memory reference
+  stores and do not survive an adapter restart.
+- **Phase 14 — Web client.** 🔄 partial as of **v0.7.0**: a vendored
+  Kiwi IRC SPA is served at `/app/` and a static landing page at `/`
+  by the Cloudflare Worker via an `[assets]` binding, with a Zod-
+  validated per-env config matrix and **CSWSH defense** (same-origin
+  auto-derive + optional `WEB_ORIGINS` allowlist). The Playwright
+  headless-browser e2e is the remaining open ticket.
+  See `docs/WebClientGuide.md` for the contributor/operator guide.
+- **Coverage hardening.** 🔄 partial as of **v0.7.0**: `aws-adapter`
+  and `aws-stack` clear the 90% gate (v0.6.0); the CF packages run
+  under istanbul (v0.6.0). The remaining packages (`cf-adapter`,
+  `local-cli`, `load-test`, `cf-tcp-container`, `tcp-ws-forwarder`,
+  `irc-test-support`, `web`) are **above the gate but below 100%** —
+  follow-ups drive each to 100%.
 
 ---
 
@@ -416,6 +580,8 @@ cleanly. Per-release manifests live in `CHANGELOG.md`.
 channel), `TOPIC`, `KICK`, `INVITE`, `NAMES`, `LIST`, `WHO`, `WHOIS`,
 `WHOWAS`, `MOTD`, `AWAY`, `OPER` (credential auth → `o` user mode), the
 query verbs `VERSION`, `TIME`, `ADMIN`, `INFO`, `USERHOST`, `ISON`, the
+modern-online-presence verb `MONITOR` (`+`/`-`/`C`/`L`/`S` with the
+`730`/`731`/`732`/`734` numerics and async online/offline push), the
 network-statistics verbs `LUSERS` and `STATS` (`u` uptime + `l` link-info
 letters; unknown letters get the charybdis-style empty body), the
 routing-diagnostic verb `TRACE` (oper-gated per-connection detail), the
@@ -429,15 +595,31 @@ v0.5.0 — they return `421 ERR_UNKNOWNCOMMAND`, and their reserved
 numerics have been removed. S2S linking is a PLAN non-goal.)
 
 **Channel modes:** `o v b i k l t n m s p`.
-**User modes:** `i`, `o` (local only), `w`, `s`.
+**User modes:** `i`, `o` (local only), `w`, `s`, and the read-only `S`
+(TLS connected — set by the transport at registration, surfaced in WHOIS
+via `276 RPL_WHOISSECURE`, not settable via `MODE`).
 
 **IRCv3 extensions (negotiated via `CAP`):** `message-tags` (incl. the
-`TAGMSG` command), `server-time`, `account-tag`, `echo-message`, `batch`,
+`TAGMSG` command), `server-time`, `account-tag`, `account-notify`
+(pushes `ACCOUNT` on SASL login/logout), `echo-message`, `batch`,
 `sasl` (`PLAIN` always; `EXTERNAL` via mTLS when a client-cert trust store
-is bound),
-`multi-prefix`, `away-notify`, `chghost`, `invite-notify`, `extended-join`,
-`draft/chathistory`, `safelist`. Case-insensitive nick/channel comparison
-uses **RFC 1459** case-mapping (advertised via `005 CASEMAPPING=rfc1459`).
+is bound), `multi-prefix`, `away-notify`, `chghost`, `invite-notify`,
+`extended-join`, `msgid` (`@+msgid=<id>` on every PRIVMSG/NOTICE/TAGMSG,
+shared between live and `draft/chathistory` replay), `standard-replies`
+(`FAIL`/`WARN`/`NOTE` replacements for a curated numeric subset),
+`MONITOR=<n>` (config-driven ceiling, default 30), `labeled-response`
+(`+label=<id>` → `BATCH +id labeled-response … BATCH -id` wrapping),
+`sts` (Strict Transport Security — conditionally advertised with
+`duration`/`port`/optional `preload` from `ServerConfig` when configured,
+so compliant clients upgrade from plaintext to TLS and pin the secure
+listener), `draft/chathistory`, `safelist`, `draft/typing` (typing-indicator
+broadcast), `draft/multiline=<n>` (multi-line `BATCH`, default 4096-byte
+budget), `draft/read-marker` (per-account persisted last-read), and
+`draft/pre-away` (per-account persisted away reason, replayed at
+identify). Case-insensitive nick/channel comparison uses **RFC 1459**
+case-mapping (advertised via `005 CASEMAPPING=rfc1459`). The new
+`MONITOR` / `MULTILINE` / `TYPING` / `STATUSMSG` / `EXTBAN` /
+`ACCOUNTEXTBAN` ISUPPORT tokens are advertised from `ServerConfig`.
 
 **Transport:** deployed stacks (Cloudflare Workers, AWS API Gateway) speak
 WebSocket text frames by default (one IRC message per frame, with tolerance
@@ -457,9 +639,24 @@ bridges a stock TCP client to a deployed WebSocket endpoint.
   gates), v0.3.0 (OPER, TAGMSG, RFC 1459 case-mapping, real MOTD,
   ChannelRegistryDO, SASL account persistence), v0.4.0 (dual transport
   `irc+tls :6697`, SASL `EXTERNAL`/mTLS, WHOWAS + remaining verbs, D1 account
-  store, Node 24/pnpm 11), and v0.5.0 (deferred IRC verbs `KILL` / `REHASH`
+  store, Node 24/pnpm 11), v0.5.0 (deferred IRC verbs `KILL` / `REHASH`
   / `LUSERS` + `STATS` / `TRACE` / `WALLOPS` / `SETNAME`, plus the formal
-  drop of the S2S and obsolete RFC 2812 verbs).
+  drop of the S2S and obsolete RFC 2812 verbs), v0.6.0 (the IRCv3
+  extension sweep — `account-notify`, `msgid`, `standard-replies`,
+  `MONITOR`, `labeled-response`, `sts`, `draft/typing`, `draft/multiline`,
+  `draft/read-marker`, `draft/pre-away`, plus user mode `S`; the
+  required-`serverName` gate; `tools/load-test`; aws-adapter / aws-stack
+  coverage unblocks; CF packages moved to istanbul; deploys now
+  manual-only), and **v0.7.0** (the web client — vendored Kiwi IRC SPA
+  at `/app/`, static landing page at `/`, Cloudflare Worker `[assets]`
+  binding, per-env Zod-validated config matrix, and CSWSH defense via
+  same-origin auto-derive + optional `WEB_ORIGINS`; `/health` becomes
+  an explicit route; mutation-killing tests for `irc-core`'s parser /
+  batch / numerics).
+- `docs/WebClientGuide.md` — end-to-end contributor/operator doc for the
+  web client: build pipeline, per-env config matrix, CSWSH rationale and
+  the optional `WEB_ORIGINS` var, local dev, optional Cloudflare Pages
+  alternative, and troubleshooting.
 - `docs/Cloudflare-TCP-Deployment.md` and `docs/AWS-TCP-Deployment.md` —
   end-to-end guides for the `:6697` TCP+TLS variants (Spectrum/Container on
   CF, NLB + Lambda streaming on AWS), including mTLS trust-store setup.

package/apps/aws-stack/README.md

@@ -60,6 +60,39 @@ export AWS_DEFAULT_REGION=us-east-1
 LOCALSTACK=1 pnpm test
 ```
 
+## Test-mode bundle stub (why coverage does not re-bundle)
+
+The stack ships four `NodejsFunction` constructs (the wss `IrcHandler`,
+`IrcSweeper`, `IrcPingChecker`, and the optional NLB `IrcNlbHandler`).
+Each one invokes esbuild at synth time to bundle the shared handler
+entry. Repeated across the ~80 synth assertions in `tests/stack.test.ts`,
+that meant the bundler ran **dozens to hundreds of times per coverage
+invocation**, exhausting CI memory before vitest could print its
+coverage table — the failure mode presented as a wall of
+`Bundling asset TestStack/IrcHandler/Code/Stage…` lines followed by
+`[ELIFECYCLE] Command failed with exit code N` and no report.
+
+The fix is a single env-var toggle consumed by `makeLambda()` in
+`src/aws-stack.ts`:
+
+| Env var                           | Effect on the synth                                                   |
+|-----------------------------------|-----------------------------------------------------------------------|
+| `IRC_AWS_STACK_TEST_NO_BUNDLE=1`  | Every Lambda is emitted as an inline `Code.fromInline('void 0')` zip; esbuild is not invoked at all. CloudFormation shape (runtime, env vars, IAM grants, route wiring, …) is identical to the production synth. |
+| _(unset)_                         | Production path: every Lambda is a real `NodejsFunction` whose asset is esbuild-bundled at synth time. This is what `cdk synth` / `cdk deploy` run. |
+
+`tests/vitest.setup.ts` sets the flag once per test file so the entire
+`pnpm test` / `pnpm coverage` run stays on the stub path. Production
+synth (`bin/aws.ts` via the CDK CLI) never loads vitest, so it cannot
+accidentally inherit the flag.
+
+A small `tests/synth-no-bundle.test.ts` locks both paths in place: it
+asserts the stub emits `Code: { ZipFile }` when the flag is set, and
+exercises the production `NodejsFunction` return once (with the flag
+explicitly unset) so the production branch stays covered. The
+end-to-end guard lives in `tests/coverage-command.test.ts`, which
+spawns `pnpm --filter @serverless-ircd/aws-stack coverage` in a
+subprocess and asserts the report prints an `All files` row.
+
 ## Stack outputs
 
 | Output         | Description                                                        |

package/apps/aws-stack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-stack",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "private": true,
   "description": "AWS CDK v2 stack: API Gateway v2 WebSocket API, Lambda, DynamoDB tables, least-privilege IAM",
   "license": "BSD-3-Clause",

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

@@ -37,8 +37,8 @@ import {
 import { LambdaTarget } from 'aws-cdk-lib/aws-elasticloadbalancingv2-targets';
 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 { Code, Function as Lambda, Runtime } from 'aws-cdk-lib/aws-lambda';
+import { NodejsFunction, type NodejsFunctionProps } from 'aws-cdk-lib/aws-lambda-nodejs';
 import type { Construct } from 'constructs';
 
 /** Stage name served by the auto-deploying WebSocket stage. */
@@ -64,8 +64,14 @@ const PING_CHECKER_SCHEDULE_RATE = Duration.minutes(1);
  */
 const DEFAULT_ENVIRONMENT_NAME = 'staging';
 
-/** Default server identity, used when the corresponding prop is omitted. */
-const DEFAULT_SERVER_NAME = 'irc.example.com';
+/**
+ * Fallback server identity, used when the corresponding prop is omitted.
+ * Deliberately not `irc.example.com` (the retired placeholder) so a
+ * deployment that forgets to override advertises an obviously-local name
+ * instead of a deceptive example domain. Production stacks MUST pass
+ * `serverName` explicitly.
+ */
+const DEFAULT_SERVER_NAME = 'irc.localhost';
 const DEFAULT_NETWORK_NAME = 'ExampleNet';
 const DEFAULT_MOTD_LINES = [
   'Welcome to the ServerlessIRCd deployment.',
@@ -74,6 +80,22 @@ const DEFAULT_MOTD_LINES = [
 
 const HERE = fileURLToPath(new URL('.', import.meta.url));
 
+/**
+ * Env-var flag that flips {@link makeLambda} onto a stub code path which
+ * emits an inline Lambda zip and skips esbuild entirely. The IrcAwsStack
+ * test suite synthesizes the stack dozens of times per coverage run; if
+ * each synth invoked esbuild the runner exhausted its memory budget
+ * before the vitest coverage table could print. The stub preserves every
+ * CloudFormation shape the rest of the test suite asserts on (runtime,
+ * env vars, IAM grants, route wiring, …) while making the bundling step
+ * a no-op.
+ *
+ * Intentionally a plain `process.env` read (not a CDK context var or
+ * construct prop) so the toggle lives in one place — `tests/vitest.setup.ts`
+ * — and cannot leak into a production synth driven by `bin/aws.ts`.
+ */
+const TEST_NO_BUNDLE_FLAG = 'IRC_AWS_STACK_TEST_NO_BUNDLE';
+
 /**
  * Construct props for {@link IrcAwsStack}. Acts as the single
  * configuration bag extended by deploy-time knobs (environment name,
@@ -93,7 +115,8 @@ export interface IrcStackProps extends StackProps {
 
   /**
    * Server name advertised to clients (`SERVER_NAME` / the `001`
-   * welcome source). Defaults to `irc.example.com`.
+   * welcome source). Falls back to `irc.localhost` when omitted; production
+   * stacks MUST pass an explicit value.
    */
   readonly serverName?: string;
 
@@ -150,7 +173,7 @@ export class IrcAwsStack extends Stack {
       }),
     );
 
-    const handler = new NodejsFunction(this, 'IrcHandler', {
+    const handler = makeLambda(this, 'IrcHandler', {
       runtime: Runtime.NODEJS_24_X,
       entry: handlerEntry(),
       handler: 'handler',
@@ -166,7 +189,7 @@ export class IrcAwsStack extends Stack {
     // 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', {
+    const sweeper = makeLambda(this, 'IrcSweeper', {
       runtime: Runtime.NODEJS_24_X,
       entry: handlerEntry(),
       handler: 'sweeperHandler',
@@ -180,7 +203,7 @@ export class IrcAwsStack extends Stack {
     // 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', {
+    const pingChecker = makeLambda(this, 'IrcPingChecker', {
       runtime: Runtime.NODEJS_24_X,
       entry: handlerEntry(),
       handler: 'pingCheckerHandler',
@@ -318,7 +341,7 @@ export class IrcAwsStack extends Stack {
       // Shares the bundled aws-adapter code (tree-shaken to the nlb-stream
       // path by esbuild at synth time). Reuses the same DynamoDB tables,
       // server identity, and MANAGEMENT_URL as the wss handler.
-      const nlbHandler = new NodejsFunction(this, 'IrcNlbHandler', {
+      const nlbHandler = makeLambda(this, 'IrcNlbHandler', {
         runtime: Runtime.NODEJS_24_X,
         entry: handlerEntry(),
         handler: 'nlbStreamHandler',
@@ -391,6 +414,48 @@ function handlerEntry(): string {
   return resolve(HERE, '..', '..', '..', 'packages', 'aws-adapter', 'src', 'handlers', 'index.ts');
 }
 
+/**
+ * Internal Lambda-construct props: `NodejsFunctionProps` narrowed so the
+ * runtime and handler are required. Every call site in the stack already
+ * passes both explicitly; this type just makes that invariant visible to
+ * the compiler so {@link makeLambda} can hand them straight through to
+ * the stub `Function` constructor without a non-null assertion.
+ */
+type StrictLambdaProps = NodejsFunctionProps & {
+  readonly runtime: Runtime;
+  readonly handler: string;
+};
+
+/**
+ * Builds a Lambda function for the IRC stack, selecting between the real
+ * esbuild-bundled `NodejsFunction` and a no-op stub `Function` based on
+ * {@link TEST_NO_BUNDLE_FLAG}.
+ *
+ * Production synth (`bin/aws.ts`) never sets the flag, so it always lands
+ * on the `NodejsFunction` branch and produces a real bundled asset. The
+ * test suite sets the flag via `tests/vitest.setup.ts`, which routes
+ * every Lambda onto the inline-zip stub so the synth does not invoke
+ * esbuild and the coverage pipeline can complete.
+ *
+ * The stub mirrors only the fields the rest of the stack mutates
+ * post-construction (`runtime`, `handler`, env vars, IAM grants) — it
+ * deliberately ignores `entry` and `bundling` because both are
+ * meaningless once esbuild is bypassed.
+ *
+ * Returns the base `Function` type (not `NodejsFunction`) so callers
+ * cannot reach for bundler-only APIs on the stub path.
+ */
+function makeLambda(scope: Construct, id: string, props: StrictLambdaProps): Lambda {
+  if (process.env[TEST_NO_BUNDLE_FLAG] === '1') {
+    return new Lambda(scope, id, {
+      runtime: props.runtime,
+      handler: props.handler,
+      code: Code.fromInline('void 0'),
+    });
+  }
+  return new NodejsFunction(scope, id, props);
+}
+
 /**
  * Builds the physical DynamoDB table name for a logical id under the
  * given environment. Capitalises the environment's first letter so it