serverless-ircd 0.4.0 → 0.6.0

package/README.md

@@ -6,20 +6,33 @@ platform-agnostic core, and two thin adapters run it on **Cloudflare Workers**
 
 One TypeScript codebase. Two serverless substrates.
 
-> **Status:** **v0.4.0 (preview).** The pure protocol core, the
+> **Status:** **v0.6.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
-> deployed to staging. v0.4.0 ships **dual transport**: both adapters
-> now speak a real `irc+tls :6697` (TLS-over-TCP) surface for stock IRC
+> deployed to staging. v0.4.0 shipped **dual transport**: both adapters
+> speak a real `irc+tls :6697` (TLS-over-TCP) surface for stock IRC
 > clients — Cloudflare via Spectrum + a Container origin, AWS via a
 > Network Load Balancer + Lambda streaming — alongside the WebSocket
-> path. It also lands **SASL `EXTERNAL` via mTLS**, the remaining
-> standard IRC verbs (`WHOWAS`, `VERSION`, `TIME`, `ADMIN`, `INFO`,
-> `USERHOST`, `ISON`), a **Cloudflare D1-backed SASL account store**,
-> config-driven server identity, and a **Node 24 / pnpm 11** toolchain.
-> Remaining 0.x work: oper-gated verbs (`KILL`/`REHASH`/…), a
-> required-`serverName` config gate, and load/compat testing. See
+> path, plus **SASL `EXTERNAL` via mTLS** and a **Cloudflare D1-backed
+> 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. **v0.6.0 lands 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) — closes the
+> required-`serverName` config gate, ships a `tools/load-test`
+> 10k-connection harness, and lifts `aws-adapter` / `aws-stack` over
+> the 90% coverage gate (CF packages moved to istanbul coverage,
+> clearing the v0.5.0 workerd-incompatibility caveat). Remaining 0.x
+> work: the client compatibility sweep (WeeChat / HexChat / IRCCloud /
+> TheLounge), IRC services (NickServ / ChanServ / HostServ /
+> OperServ / MemoServ), a web client (vendored Kiwi IRC), and driving
+> the remaining sub-100% packages to full coverage. See
 > `CHANGELOG.md` for the per-release manifests.
 
 ---
@@ -127,6 +140,7 @@ ServerlessIRCd/
 │   └── 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
@@ -227,6 +241,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` /
@@ -299,6 +315,91 @@ 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).
+
+---
+
+## WebSocket transport (IRCv3 subprotocols)
+
+The WebSocket entry points (the local CLI, the Cloudflare Worker, and the
+AWS API Gateway `$connect` route) implement the
+[IRCv3 WebSocket support](https://ircv3.net/specs/websocket.html) subprotocol
+negotiation. A client advertises support by offering one of two registered
+subprotocols in its opening handshake's `Sec-WebSocket-Protocol` header:
+
+| Subprotocol        | Frames   | Notes                                            |
+|--------------------|----------|--------------------------------------------------|
+| `text.ircv3.net`   | UTF-8 text   | Lone surrogates → U+FFFD; binary frames rejected (close `1003`). |
+| `binary.ircv3.net` | binary       | UTF-8 encoded bytes; same framing as `text`.     |
+
+The server echoes back the first supported entry in client-preference order
+(in the `101` response's `Sec-WebSocket-Protocol` header). Once negotiated,
+the connection uses **spec framing**:
+
+- **One IRC message per WebSocket message** — a frame is never split on an
+  embedded line break. A single optional trailing `CR-LF` (or bare `LF`) is
+  stripped; the remainder is exactly one IRC line.
+- **No trailing `CR-LF` on the wire**, outbound or inbound.
+- **510-byte message budget** — the 512-byte IRC line limit minus the omitted
+  `CR-LF`. A message exceeding 510 bytes is a protocol violation and the
+  connection is closed with RFC 6455 code `1009` (Message Too Big).
+
+**Legacy fallback.** A client that offers no recognized subprotocol (or none
+at all) is still accepted, in **legacy mode**: frames are split on `\r\n` so
+older clients that concatenate several messages into one frame keep working,
+and the parser's existing 512-byte line cap applies. Nothing breaks until a
+client opts into a subprotocol. The in-tree
+[`tcp-ws-forwarder`](#connecting-a-tcp-irc-client-to-a-deployed-stack-tcpws-forwarder)
+offers `binary.ircv3.net` upstream, so a stock TCP IRC client bridged to a
+deployed stack exercises the spec path end-to-end.
+
+---
+
 ## Testing strategy
 
 This project follows strict TDD (Red → Green → Refactor) — every reducer is
@@ -334,20 +435,63 @@ 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),
-  client compatibility sweep (WeeChat, HexChat, IRCCloud, TheLounge),
-  remaining ADRs.
+- **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
+  fanout, `OPER` / `TAGMSG` / `WHOWAS`, RFC 1459 case-mapping, real
+  MOTD, config-driven server identity, AWS max-clients admission,
+  CF D1 SASL store, and a sweep of dead-code / stale-comment cleanup).
+- **Phase 9 — Runtime & tooling baseline.** ✅ landed in **v0.4.0**
+  (Node ≥ 24 / pnpm 11).
+- **Phase 10 — IRCv3 WebSocket extension.** ✅ landed in **v0.4.0**:
+  `text.ircv3.net` / `binary.ircv3.net` subprotocol negotiation +
+  per-message framing across the CF Worker, AWS APIGW, local CLI, and
+  `tcp-ws-forwarder` (510-byte budget, `1009`/`1003` close codes,
+  legacy fallback).
+- **Phase 11 — Deferred IRC verbs.** ✅ landed in **v0.5.0**: `KILL`,
+  `REHASH`, `LUSERS` + `STATS`, `TRACE`, `WALLOPS`, `SETNAME`, plus
+  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.** ⬳ pending: vendored Kiwi IRC SPA served
+  from the Worker, WS Origin allowlist (CSWSH defense), landing page,
+  headless browser e2e.
+- **Coverage hardening.** 🔄 partial as of **v0.6.0**: `aws-adapter`
+  and `aws-stack` now clear the 90% gate (CI boots DynamoDB Local via
+  a JRE; the CDK synth no longer re-bundles under coverage), and the
+  CF packages moved to istanbul to clear the v0.5.0 workerd-incompat.
+  Follow-ups drive each remaining sub-100% package to 100%.
 
 ---
 
@@ -356,21 +500,48 @@ cleanly. Per-release manifests live in `CHANGELOG.md`.
 **Core (RFC 1459/2812 subset):** registration (`NICK`/`USER`/`CAP`/`PASS`),
 `PING`/`PONG`, `QUIT`, `JOIN`, `PART`, `PRIVMSG`, `NOTICE`, `MODE` (user +
 channel), `TOPIC`, `KICK`, `INVITE`, `NAMES`, `LIST`, `WHO`, `WHOIS`,
-`WHOWAS`, `MOTD`, `AWAY`, `OPER` (credential auth → `o` user mode), plus
-the query verbs `VERSION`, `TIME`, `ADMIN`, `INFO`, `USERHOST`, `ISON`.
-(Oper-gated verbs — `KILL`/`REHASH`/`CONNECT`/`SQUIT`/`TRACE` — remain
-deferred.)
+`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
+realname-change verb `SETNAME`, and the oper verbs `KILL` (force-
+disconnect), `REHASH` (config reload via `IrcRuntime.reloadConfig()`),
+`WALLOPS` (global broadcast to every `+w` user).
+
+(Out of scope: the S2S verbs `CONNECT`/`SQUIT`/`LINKS` and the obsolete
+RFC 2812 verbs `SERVICE`/`SUMMON`/`USERS` are **formally dropped** as of
+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
@@ -388,9 +559,17 @@ bridges a stock TCP client to a deployed WebSocket endpoint.
 - `CHANGELOG.md` — per-release manifests (Keep a Changelog format), including
   the v0.2.0 work (AWS adapter, SASL, flood control, security hardening, CI
   gates), v0.3.0 (OPER, TAGMSG, RFC 1459 case-mapping, real MOTD,
-  ChannelRegistryDO, SASL account persistence), and v0.4.0 (dual transport
+  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).
+  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), and **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).
 - `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

@@ -8,7 +8,7 @@ least-privilege IAM glue to let the Lambda read/write the tables and post back
 to connected clients via the management API.
 
 The Lambda handler is currently a stub (`{ statusCode: 200 }`); the real
-`AwsRuntime` dispatch lands in TICKET-040.
+`AwsRuntime` dispatch lands with the AWS runtime work.
 
 ## Prerequisites
 
@@ -32,7 +32,7 @@ Repo-level shortcuts (from the monorepo root):
 ```sh
 pnpm deploy:aws:staging
 pnpm deploy:aws:prod
-pnpm smoke:aws:staging   # deferred to TICKET-043
+pnpm smoke:aws:staging   # deferred (smoke harness not yet wired)
 ```
 
 ## Optional localstack validation
@@ -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                                                        |
@@ -70,4 +103,5 @@ LOCALSTACK=1 pnpm test
 ## Handoff
 
 Lambda runtime logic, DynamoDB access patterns, and the `AwsRuntime`
-implementation are TICKET-040. The scheduler/sweeper is TICKET-041/042.
+implementation land with the AWS runtime work. The scheduler/sweeper is
+the EventBridge sweeper work.

package/apps/aws-stack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-stack",
-  "version": "0.4.0",
+  "version": "0.6.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

@@ -17,7 +17,12 @@ 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 {
+  CfnIntegrationResponse,
+  WebSocketApi,
+  type WebSocketIntegration,
+  WebSocketStage,
+} from 'aws-cdk-lib/aws-apigatewayv2';
 import { WebSocketLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
 import { Certificate } from 'aws-cdk-lib/aws-certificatemanager';
 import { Table } from 'aws-cdk-lib/aws-dynamodb';
@@ -32,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. */
@@ -59,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.',
@@ -69,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,
@@ -88,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;
 
@@ -145,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',
@@ -161,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',
@@ -175,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',
@@ -191,9 +219,6 @@ export class IrcAwsStack extends Stack {
     }
 
     const webSocketApi = new WebSocketApi(this, 'IrcWsApi', {
-      connectRouteOptions: {
-        integration: new WebSocketLambdaIntegration('ConnectIntegration', handler),
-      },
       disconnectRouteOptions: {
         integration: new WebSocketLambdaIntegration('DisconnectIntegration', handler),
       },
@@ -202,6 +227,32 @@ export class IrcAwsStack extends Stack {
       },
     });
 
+    // The `$connect` route is added explicitly (rather than via
+    // `connectRouteOptions`) so the negotiated IRCv3 WebSocket subprotocol can
+    // be echoed back to the client. API Gateway selects the WebSocket
+    // subprotocol from the `$connect` integration response, so the route is
+    // configured to return a response and an `IntegrationResponse` maps the
+    // `Sec-WebSocket-Protocol` header from the Lambda's reply onto the
+    // handshake. The Lambda reads the client's offer, selects the first
+    // supported entry, and returns it in its response header (see
+    // `handleConnect` / `dispatch`).
+    const connectRoute = webSocketApi.addRoute('$connect', {
+      integration: new WebSocketLambdaIntegration('ConnectIntegration', handler),
+      returnResponse: true,
+    });
+    const connectIntegration = connectRoute.node.findChild(
+      'ConnectIntegration',
+    ) as WebSocketIntegration;
+    new CfnIntegrationResponse(this, 'ConnectSubprotocolResponse', {
+      apiId: webSocketApi.apiId,
+      integrationId: connectIntegration.integrationId,
+      integrationResponseKey: '$default',
+      responseParameters: {
+        'method.response.header.Sec-WebSocket-Protocol':
+          'integration.response.header.Sec-WebSocket-Protocol',
+      },
+    });
+
     // 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
@@ -290,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',
@@ -363,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