serverless-ircd 0.4.0 → 0.6.0

package/docs/Cloudflare-TCP-Deployment.md

@@ -0,0 +1,510 @@
+# Cloudflare TCP+TLS Deployment Guide (`irc+tls` :6697)
+
+End-to-end guide for deploying the **raw TCP+TLS** transport of
+ServerlessIRCd to Cloudflare (Phase 7 of `PLAN.md`, TICKET-055). This is
+the RFC 1459/2812-compliant path that older clients, bots, and bridges
+use. The default **wss** transport is documented separately in
+[`Cloudflare-Deployment-Guide.md`](./Cloudflare-Deployment-Guide.md);
+the two are independent and a deployment can enable either or both.
+
+> **Read first:** [`ADR-009`](./ADR-009-dual-transport-wss-and-irc-tls.md)
+> for *why* a second transport exists and the per-platform mapping.
+> This doc covers the *how*.
+
+**Acceptance criterion (TICKET-058):** a new contributor can deploy
+their own TCP+TLS staging instance following only this doc.
+
+Cross-reference: `apps/cf-tcp-container/` (origin),
+`apps/cf-tcp-container/wrangler.toml` (container config),
+`apps/cf-tcp-container/terraform/spectrum.tf` (Spectrum TLS config),
+`.github/workflows/deploy-cf-tcp.yml` (CI), TICKET-054 (mTLS), ADR-006
+(SASL mechanism scope).
+
+---
+
+## 1. What gets deployed
+
+The wss path is pure-serverless (Worker + Durable Objects). The TCP path
+**cannot** be — Cloudflare Workers cannot accept raw TCP. So the TCP+TLS
+path adds two stateful pieces in front of the shared IRC core:
+
+```
+  IRC client (irc+tls :6697)
+        │
+        │  TLS handshake (client ⟷ Cloudflare)
+        ▼
+  ┌──────────────────────────────────────────────────────────────┐
+  │  Cloudflare Spectrum  (Enterprise)                           │
+  │    • terminates TLS on :6697                                 │
+  │    • forwards plaintext TCP to the origin                    │
+  │    • PROXY protocol v1 carries the real client IP            │
+  └──────────────────────────┬───────────────────────────────────┘
+                             │ plaintext TCP (:6667)
+                             ▼
+  ┌──────────────────────────────────────────────────────────────┐
+  │  Cloudflare Container  (apps/cf-tcp-container)               │
+  │    • node:24 process, EXPOSE 6667                            │
+  │    • ConnectionActor + InMemoryRuntime + TcpByteStream-      │
+  │      Transport (the shared transport seam, TICKET-053)       │
+  │    • persistence snapshot at /data/state.json                │
+  │      (channel topology survives restart; live connections    │
+  │      do not — clients reconnect)                             │
+  └──────────────────────────────────────────────────────────────┘
+```
+
+The **parser → reducer → dispatch pipeline is shared verbatim** with the
+wss path. Only the line-framing transport differs: a `TcpByteStreamTransport`
+reassembles `\r\n`-terminated IRC lines across arbitrary TCP chunks
+(partial-line buffering), whereas the wss Worker uses one-message-per-frame.
+
+Two artifacts are deployed and configured:
+
+| Artifact                              | Tool           | What it does                                   |
+|---------------------------------------|----------------|------------------------------------------------|
+| `sirc-tcp-origin` Cloudflare Container| `wrangler`     | Builds + runs the IRC core container image.    |
+| `cloudflare_spectrum_application`     | `terraform`    | TLS termination on :6697 + origin forwarding.  |
+
+---
+
+## 2. Prerequisites
+
+| Requirement              | Detail                                                              |
+|--------------------------|---------------------------------------------------------------------|
+| Node.js                  | ≥ 24 (`engines.node` in root `package.json`).                       |
+| pnpm                     | 11.x (`packageManager: pnpm@11.17.0`).                              |
+| `wrangler` CLI           | v4.112+ (comes from `apps/cf-tcp-container/devDependencies`).       |
+| `terraform` CLI          | ≥ 1.5 (for the Spectrum step). Install separately.                  |
+| **Cloudflare Enterprise**| **Spectrum is an Enterprise-tier feature.** Required for the TCP path. |
+| Containers beta access   | Cloudflare Containers is in beta; request access in the dashboard.  |
+| A Cloudflare zone        | The public hostname (e.g. `irc.example.com`) must live in a zone you control. |
+| Git checkout             | Clean working tree on `main` for production deploys.                |
+
+> The wss path runs on the Workers Free/Paid plan. The TCP path does
+> **not** — Spectrum mandates Enterprise. If you do not have Enterprise,
+> deploy the wss path instead (see `Cloudflare-Deployment-Guide.md`).
+
+Confirm the local environment:
+
+```bash
+node --version          # v24.x or newer
+pnpm --version          # 11.x
+terraform version       # >= 1.5
+pnpm install            # from repo root
+pnpm build              # builds irc-core, irc-server, in-memory-runtime, cf-tcp-container
+```
+
+---
+
+## 3. First-time setup
+
+Done once per Cloudflare account + zone.
+
+### 3.1 API token
+
+Same token shape as the wss path works, but it additionally needs
+Spectrum edit rights. Create a token at
+<https://dash.cloudflare.com/profile/api-tokens> with:
+
+- `Account · Workers Scripts · Edit` (Containers deploy)
+- `Zone · Spectrum · Edit` (terraform `cloudflare_spectrum_application`)
+- `Zone · DNS · Edit` (Spectrum creates a CNAME)
+
+Restrict to the target zone. Set as `CLOUDFLARE_API_TOKEN` locally and as
+a GitHub Actions secret for CI.
+
+### 3.2 Collect the IDs the deploy needs
+
+| Secret / var             | Where to find it                                        |
+|--------------------------|---------------------------------------------------------|
+| `CLOUDFLARE_ACCOUNT_ID`  | Dashboard sidebar (any zone → Overview, lower right).   |
+| `CF_ZONE_ID`             | Dashboard sidebar of the target zone → Overview.        |
+| `CF_TCP_ORIGIN_ADDRESS`  | The Container's origin hostname (printed after first `wrangler deploy`, see §5.1). |
+
+### 3.3 Authenticate the CLI
+
+```bash
+npx wrangler login                  # interactive
+# or non-interactive:
+export CLOUDFLARE_API_TOKEN=...
+export CLOUDFLARE_ACCOUNT_ID=...
+```
+
+---
+
+## 4. Local development
+
+Run the container origin locally without Spectrum — connect a plaintext
+TCP IRC client directly to :6667. This exercises the exact
+`ConnectionActor` + `TcpByteStreamTransport` pipeline.
+
+```bash
+# Build the workspace + the container package.
+pnpm build
+
+# Run the origin on plaintext :6667 (default TCP_PORT).
+pnpm --filter @serverless-ircd/cf-tcp-container start \
+  -- --env-file <(printf 'SERVER_NAME=irc.local\nTCP_PORT=6667\n')
+```
+
+Connect a plaintext client (no TLS) to `localhost:6667`:
+
+```
+/eval /connect localhost 6667        # WeeChat, no SSL
+NICK alice
+USER alice 0 * :Alice
+JOIN #test
+PRIVMSG #test :hello over plaintext TCP
+```
+
+For a TLS-terminated local loop, put `stunnel` (or `openssl s_server`)
+in front of :6667 and connect on :6697 — mirroring the Spectrum topology.
+
+The unit + the TLS e2e suites live in `apps/cf-tcp-container/tests/`
+(including `tls-e2e.test.ts`, which runs a real TLS handshake against the
+origin). Run them with:
+
+```bash
+pnpm --filter @serverless-ircd/cf-tcp-container test
+```
+
+---
+
+## 5. Deploy staging
+
+Staging is what CI deploys on every push that touches
+`apps/cf-tcp-container/**`. You can also deploy it manually.
+
+### 5.1 Deploy the container origin
+
+```bash
+# From the repo root:
+pnpm deploy:cf-tcp:staging
+# Equivalent to:
+#   pnpm build && pnpm --filter @serverless-ircd/cf-tcp-container deploy:staging
+#   → wrangler deploy --env staging   (inside apps/cf-tcp-container)
+```
+
+This builds the container image from `apps/cf-tcp-container/Dockerfile`
+and deploys the `sirc-tcp-origin-staging` Container. The first deploy
+prints the **origin address** — copy it into `CF_TCP_ORIGIN_ADDRESS`
+(used by the Spectrum step next).
+
+### 5.2 Apply the Spectrum TLS config
+
+```bash
+cd apps/cf-tcp-container/terraform
+terraform init
+terraform apply \
+  -var zone_id=$CF_ZONE_ID \
+  -var origin_address=$CF_TCP_ORIGIN_ADDRESS \
+  -var hostname=irc-staging.example.com
+```
+
+This creates the `cloudflare_spectrum_application.irc_tls` resource:
+TLS on :6697 → plaintext TCP to the container origin on :6667.
+
+### 5.3 Smoke test over TLS
+
+```bash
+# Minimal smoke: register + quit over the real TLS endpoint.
+printf 'NICK smoke\r\nUSER smoke 0 * :Smoke\r\nQUIT :smoke\r\n' | \
+  timeout 10 openssl s_client -connect irc-staging.example.com:6697 -quiet | \
+  grep -q '001' && echo "SMOKE PASS" || echo "SMOKE FAIL"
+```
+
+CI does the same — see `.github/workflows/deploy-cf-tcp.yml` step
+"Smoke e2e (irc+tls)", gated on the `CF_TCP_SMOKE_HOST` repo variable.
+
+### 5.4 Connect a real IRC client
+
+```
+/server add ircd irc-staging.example.com/6697
+/set irc.server.ircd.ssl on
+/connect ircd
+/join #test
+```
+
+---
+
+## 6. Deploy production
+
+Production is the default `wrangler.toml` environment (no `--env` flag).
+
+```bash
+# 1. Edit wrangler.toml [vars] for production identity.
+# 2. Deploy the container:
+pnpm deploy:cf-tcp:prod
+# 3. Apply Spectrum config for the production hostname:
+cd apps/cf-tcp-container/terraform
+terraform apply -var zone_id=$CF_ZONE_ID \
+  -var origin_address=$CF_TCP_ORIGIN_ADDRESS \
+  -var hostname=irc.example.com
+```
+
+There is **no CI auto-deploy to production** — production deploys are
+manual. Staging deploys on every push to `main` that touches the
+container path.
+
+---
+
+## 7. Configuration reference
+
+### 7.1 Container — `apps/cf-tcp-container/wrangler.toml`
+
+Top-level `[vars]` map directly to the container config loader
+(`apps/cf-tcp-container/src/config-loader.ts`):
+
+| Var                  | Purpose                                              | Default                  |
+|----------------------|------------------------------------------------------|--------------------------|
+| `SERVER_NAME`        | Server name in `001`/`005` numerics. **Required** — the container config loader fails fast when unset. | _No default; must be set._ |
+| `NETWORK_NAME`       | Network label in `005 NETWORK=…`.                    | `ExampleNet`             |
+| `SERVER_VERSION`     | Version string in `002`.                             | (from package version)   |
+| `CREATED_AT`         | Creation text/time in `003`.                         | build/deploy timestamp   |
+| `MOTD_LINES`         | Message-of-the-day, `\n`-delimited.                  | welcome banner           |
+| `TCP_PORT`           | Plaintext port the container listens on.             | `6667`                   |
+| `TCP_HOST`           | Bind address (Spectrum forwards from the edge).      | `0.0.0.0`                |
+| `PERSISTENCE_PATH`   | Snapshot file path; enables channel-state survival.  | `/data/state.json`       |
+| `SNAPSHOT_INTERVAL_MS`| Auto-snapshot cadence (ms).                         | `60000`                  |
+| `OPER_USER` / `OPER_PASSWORD` | Oper credentials for `OPER`.              | —                        |
+| `SASL_ACCOUNTS`      | `\n`-delimited `user:password` lines for SASL PLAIN. | —                        |
+| `MAX_CHANNELS_PER_USER`, `MAX_TARGETS_PER_COMMAND`, `NICK_LEN`, `CHANNEL_LEN`, `TOPIC_LEN`, `MAX_LIST_ENTRIES`, `QUIT_MESSAGE` | Standard `ServerConfig` knobs (mirror the wss path). | shared defaults |
+
+The container block itself:
+
+```toml
+[[containers]]
+class_name = "IrcTcpOrigin"
+image = "./Dockerfile"
+instance_type = "standard-1"
+max_instances = 3
+sleep_after = "2h"
+```
+
+- `max_instances` caps horizontal scale; the `InMemoryRuntime` is
+  per-process, so connections on different instances do not share state.
+  Tune `max_instances` to your expected concurrency (one origin handles
+  thousands of idle connections thanks to the async TCP server).
+- `sleep_after = "2h"` lets an idle origin scale to zero; the first new
+  connection cold-starts it. Persistence (§8) means channel topology is
+  not lost across sleep.
+
+### 7.2 Spectrum — `apps/cf-tcp-container/terraform/spectrum.tf`
+
+| Variable          | Purpose                                            | Default             |
+|-------------------|---------------------------------------------------|---------------------|
+| `zone_id`         | Cloudflare zone for the hostname.                 | *(required)*        |
+| `origin_address`  | Hostname/IP of the container origin.              | *(required)*        |
+| `origin_port`     | Port the origin listens on (plaintext).           | `6667`              |
+| `hostname`        | Public hostname clients connect to.               | `irc.example.com`   |
+| `spectrum_port`   | Public port Spectrum listens on.                  | `6697`              |
+| `tls_mode`        | `flexible` (TLS→CF, plain→origin) / `full` / `strict`. | `flexible`     |
+
+`ip_firewall = true` (Cloudflare's L3/L4 DDoS) and
+`argo_smart_routing = true` are on by default. `proxy_protocol = "v1"`
+forwards the **real client IP** to the origin so the container's
+per-IP admission gate sees the actual source, not Spectrum's address.
+
+---
+
+## 8. Persistence & state survival
+
+The origin is a **stateful process** — a hard requirement that the wss
+path (Durable Objects) does not have. Two layers of survival:
+
+1. **Across chunks within a connection** — the `TcpByteStreamTransport`
+   buffers partial lines in memory; a chunk may split an IRC command at
+   an arbitrary byte boundary and the next chunk completes it. This is
+   all in-process; nothing to configure.
+2. **Across origin restarts** (crash, deploy, scale-to-zero) — every
+   live TCP connection **drops**; clients must reconnect. But the
+   **channel topology** (topics, modes, ban masks) is snapshotted to
+   `PERSISTENCE_PATH` (`/data/state.json`, a `/data` volume in the
+   Dockerfile) on an interval (`SNAPSHOT_INTERVAL_MS`) and at graceful
+   shutdown, then restored on boot. Member rosters are **not** persisted
+   — they reference ConnIds that are stale after a restart, so a
+   reconnecting client rejoins an otherwise-empty channel.
+
+> **Operational caveat:** the snapshot is per-instance. With
+> `max_instances > 1`, each instance owns disjoint channels (no
+> cross-instance state share). For a single coordinated channel space,
+> keep `max_instances = 1` until the Durable-Object-backed persistent
+> variant lands (ADR-009 "Negative", follow-up to this ticket).
+
+---
+
+## 9. mTLS (SASL EXTERNAL)
+
+SASL `EXTERNAL` needs the client certificate to reach the application
+layer (ADR-006, TICKET-054). On the TCP path this is the TLS handshake:
+
+- **Flexible mode (default):** Spectrum terminates TLS; the origin sees
+  plaintext. The cert is consumed at the edge and the app only gets a
+  verified subject via Cloudflare's mTLS config — SASL `EXTERNAL` is
+  **not** available in flexible mode.
+- **Full mode:** set `tls_mode = "full"` and configure the origin to
+  present its own certificate; configure Spectrum/API Shield mTLS with
+  your CA pool. The verified client-cert subject is then exposed to the
+  origin, feeding the `MtlsIdentityProvider` port → `AccountStore` →
+  `AUTHENTICATE EXTERNAL` succeeds (`903`) or fails (`904`).
+
+Cross-reference: TICKET-054 (mTLS support), ADR-006 (SASL scope). The wss
+path achieves the same via CF API Shield mTLS (see
+`Cloudflare-Deployment-Guide.md`).
+
+---
+
+## 10. Secrets
+
+The container consumes **no Cloudflare secret bindings** for v1; oper
+and SASL credentials ship as `[vars]` (`OPER_*`, `SASL_ACCOUNTS`). When
+strong-secret handling lands, set them via:
+
+```bash
+wrangler secret put OPER_PASSWORD --env staging
+```
+
+CI uses these **GitHub Actions secrets/variables** (configure under
+Settings → Secrets and variables → Actions):
+
+| Secret / var             | Used by                | Purpose                                    |
+|--------------------------|------------------------|--------------------------------------------|
+| `CLOUDFLARE_API_TOKEN`   | `deploy-cf-tcp.yml`    | `wrangler deploy` + terraform (`TF_VAR_*`).|
+| `CLOUDFLARE_ACCOUNT_ID`  | `deploy-cf-tcp.yml`    | Account context.                           |
+| `CF_ZONE_ID`             | `deploy-cf-tcp.yml`    | `TF_VAR_zone_id`.                          |
+| `CF_TCP_ORIGIN_ADDRESS`  | `deploy-cf-tcp.yml`    | `TF_VAR_origin_address`.                   |
+| `CF_TCP_SMOKE_HOST` (var)| `deploy-cf-tcp.yml`    | Host the TLS smoke step connects to.       |
+
+**Never** commit credentials to `wrangler.toml` or terraform `.tfvars`.
+
+---
+
+## 11. CI/CD
+
+`.github/workflows/deploy-cf-tcp.yml` runs alongside `deploy-cf.yml`
+(the wss path). The two are independent — a deployment can enable
+either or both.
+
+Triggers: push to `main` touching `apps/cf-tcp-container/**` or the
+workflow itself, plus `workflow_dispatch`. Steps (in order):
+
+1. Checkout → pnpm 11 + Node 24 → `pnpm install --frozen-lockfile`.
+2. `pnpm build`, `pnpm typecheck`, `pnpm --filter cf-tcp-container test`.
+3. `wrangler deploy --env staging` (container).
+4. `terraform init && terraform apply -auto-approve` (Spectrum).
+5. TLS smoke (`openssl s_client`), gated on `CF_TCP_SMOKE_HOST`.
+
+Concurrency is serialized via `concurrency.group: cf-tcp-staging`.
+
+There is **no auto-deploy to production**; production is manual
+(`pnpm deploy:cf-tcp:prod` + `terraform apply` for the prod hostname).
+
+---
+
+## 12. Cost notes (versus the wss path)
+
+The TCP path is materially more expensive to operate than the wss path
+because of the stateful origin:
+
+| Dimension              | wss path (Workers + DO)            | TCP path (Spectrum + Container)            |
+|------------------------|------------------------------------|--------------------------------------------|
+| **Plan tier**          | Workers Paid ($5/mo) suffices.     | **Enterprise required** (Spectrum).        |
+| **Idle connections**   | Hibernation → ~zero memory cost.   | Origin holds every socket; `sleep_after` only helps when *all* connections are idle. |
+| **Compute**            | Per-request (WebSocket frames).    | **GB-second** of running container time.   |
+| **State durability**   | DO storage (managed).              | Container volume snapshot (self-managed).  |
+| **DDoS**               | Cloudflare built-in.               | Spectrum `ip_firewall` + Argo.             |
+
+Recommendation: keep the wss path as the default and only enable the TCP
+path when you specifically need RFC-compliant clients or mTLS-via-TLS.
+Most modern clients (WeeChat, IRCCloud, TheLounge) work over wss.
+
+---
+
+## 13. Troubleshooting
+
+### 13.1 `terraform apply` fails: `Spectrum app creation not permitted`
+
+Spectrum is Enterprise-only. The API token's account/zone must be on an
+Enterprise plan. Confirm in the dashboard (Network → Spectrum). If the
+zone is not Enterprise, use the wss path.
+
+### 13.2 Client connects to :6697 but gets no `001`
+
+The TLS handshake completed (Spectrum is up) but the origin did not
+respond. Causes:
+
+- The container is scaled to zero (`sleep_after`) and the cold start is
+  slow — wait a few seconds and retry.
+- `CF_TCP_ORIGIN_ADDRESS` points at the wrong origin. It must match the
+  address printed by `wrangler deploy` (§5.1).
+- The origin crashed on boot. Check `wrangler tail` for the container
+  (or container logs in the dashboard). A common cause is an invalid
+  `MOTD_LINES` or a malformed `SASL_ACCOUNTS` line.
+
+### 13.3 Channel topic/modes lost after a restart
+
+`PERSISTENCE_PATH` is unset or the volume is not attached. Confirm
+`PERSISTENCE_PATH=/data/state.json` in `[vars]` and that the `/data`
+volume (`VOLUME ["/data"]` in the `Dockerfile`) is mounted on the
+container platform. Without it the snapshot is written to ephemeral
+storage and lost.
+
+### 13.4 Client IP seen as Spectrum's address
+
+`proxy_protocol = "v1"` must be set in `spectrum.tf` (it is by default).
+If you overrode it, the origin's per-IP admission gate sees Spectrum's
+egress IP for every client and will wrongly throttle/cap.
+
+### 13.5 Messages split across chunks get lost
+
+This is a transport-layer bug, not a config issue — the
+`TcpByteStreamTransport` is contract-tested for chunk boundaries
+(TICKET-053 / TICKET-057). If you see it, run
+`pnpm --filter @serverless-ircd/cf-tcp-container test` and the shared
+transport suite; a regression there will fail.
+
+### 13.6 `wrangler deploy` fails: `Containers beta not enabled`
+
+Cloudflare Containers is in beta. Request access in the dashboard
+(Workers & Pages → Containers). Until granted, only the local Docker
+path (§4) and the wss transport work.
+
+---
+
+## 14. Quick reference
+
+```bash
+# One-time account setup
+npx wrangler login                           # or set CLOUDFLARE_API_TOKEN
+terraform version                            # >= 1.5
+
+# Local dev (plaintext :6667, no Spectrum)
+pnpm build
+pnpm --filter @serverless-ircd/cf-tcp-container start
+
+# Staging
+pnpm deploy:cf-tcp:staging                   # container
+cd apps/cf-tcp-container/terraform && \
+  terraform apply -var zone_id=$CF_ZONE_ID \
+    -var origin_address=$CF_TCP_ORIGIN_ADDRESS \
+    -var hostname=irc-staging.example.com     # Spectrum
+
+# Production (manual)
+pnpm deploy:cf-tcp:prod
+cd apps/cf-tcp-container/terraform && terraform apply ...   # prod hostname
+
+# Tests
+pnpm --filter @serverless-ircd/cf-tcp-container test
+```
+
+Key files:
+
+| Path                                            | What                                       |
+|-------------------------------------------------|--------------------------------------------|
+| `apps/cf-tcp-container/src/main.ts`             | Container entry point.                     |
+| `apps/cf-tcp-container/src/container-server.ts` | TCP server + actor wiring + persistence.   |
+| `apps/cf-tcp-container/src/config-loader.ts`    | Env → `ServerConfig` + container knobs.    |
+| `apps/cf-tcp-container/src/persistence.ts`      | Channel-topology snapshot/restore.         |
+| `apps/cf-tcp-container/wrangler.toml`           | Container deploy config.                   |
+| `apps/cf-tcp-container/Dockerfile`              | Image (node:24, `/data` volume, :6667).    |
+| `apps/cf-tcp-container/terraform/spectrum.tf`   | Spectrum TLS :6697 → origin :6667.         |
+| `.github/workflows/deploy-cf-tcp.yml`           | Staging deploy + Spectrum + smoke CI.      |

package/docs/Home.md

@@ -0,0 +1,15 @@
+Welcome to the Wiki.
+
+## Pages
+
+- [AWS Adapter Architecture](AWS-Adapter-Architecture)
+- [AWS Deployment Guide](AWS-Deployment)
+- [AWS TCP+TLS Deployment Guide](AWS-TCP-Deployment)
+- [Cloudflare Deployment Guide](Cloudflare-Deployment-Guide)
+- [Cloudflare TCP+TLS Deployment Guide](Cloudflare-TCP-Deployment)
+- [Observability](Observability)
+- [IRCv3 WebSocket Extension Plan](PlanIRCv3Websocket)
+- [Web Client Plan](PlanWebClient)
+- [Extensions Plan](PlanExtensions)
+- [Release Process](Release-Process)
+- [ADR Index](ADR-Index)

package/docs/Observability.md

@@ -0,0 +1,87 @@
+# Observability
+
+The server ships a structured-logger port that every adapter uses to emit
+JSON log lines carrying a per-request `traceId` and per-connection
+`connectionId`. The canonical event names are the contract dashboards and
+log queries are built against.
+
+## Log contract
+
+Every record is one physical line of JSON with at least:
+
+| Field          | Source                                          |
+|----------------|-------------------------------------------------|
+| `ts`           | ISO-8601 timestamp from the injected `Clock`.   |
+| `level`        | `debug` / `info` / `warn` / `error`.            |
+| `msg`          | Event name (see below).                         |
+| `traceId`      | Per-request id; fresh per inbound frame.        |
+| `connectionId` | The bound connection's id (`ConnId`).           |
+
+Additional structured fields appear per event. The `msg` catalogue:
+
+| `msg`              | Level | Emitted by              | Notes                                                |
+|--------------------|-------|-------------------------|------------------------------------------------------|
+| `frame.receive`    | debug | `ConnectionActor`       | One per parsed IRC line. Fields: `command`, `lines`. |
+| `frame.parse-error`| warn  | `ConnectionActor`       | A line failed to parse. Fields: `line`, `token`.     |
+| `dispatch`         | debug | `dispatch()`            | Before interpreting an effect list. Fields: `effects` (array of tags), `histogram`. |
+| `dispatch.error`   | warn  | `dispatch()`            | A runtime method rejected. Fields: `effect`, `err`.  |
+
+Adapters may emit their own events (e.g. `local-cli listening`, `shutdown`)
+following the same shape.
+
+## Cloudflare Workers
+
+The `apps/cf-worker/wrangler.toml` enables `[observability]` so every
+`console.*` line emitted by the `ConsoleLogger` inside `ConnectionDO` is
+captured by Workers Analytics.
+
+- Tail the live feed: `pnpm --filter @serverless-ircd/cf-worker tail`
+- Filter by connection: `connectionId = "<DO hex id>"`
+- Filter by trace: `traceId = "<uuid>"`
+- Errors only: `level = "error" or msg = "dispatch.error"`
+
+Workers Analytics dashboards can be built on the Cloudflare dashboard
+under **Workers & Pages → <Worker> → Observability**.
+
+## AWS (Lambda + API Gateway WebSocket)
+
+The Lambda handler writes to CloudWatch Logs via the global `console`.
+Each invocation emits one JSON line per log record; the log group name
+follows the standard `/aws/lambda/<function-name>` convention.
+
+A starter CloudWatch dashboard is checked in at
+`dashboards/cloudwatch-irc.json`. Provision it via:
+
+```sh
+aws cloudwatch put-dashboard \
+  --dashboard-name ServerlessIRCd-staging \
+  --dashboard-body file://dashboards/cloudwatch-irc.json
+```
+
+The dashboard variables (`API_ID`, `LAMBDA_NAME`, `LOG_GROUP_ARN`,
+`AWS_REGION`) are templated by CloudWatch's dashboard variables feature —
+set them once in the dashboard UI after import.
+
+Sample CloudWatch Logs Insights query — count dispatched effects by tag
+over the last hour:
+
+```
+fields @timestamp, msg, fields.histogram
+| filter msg = "dispatch"
+| sort @timestamp desc
+```
+
+## Local CLI
+
+The local-cli server uses the same `ConsoleLogger` so the structured
+stream is visible while developing:
+
+```
+{"ts":"2026-07-22T12:34:56.789Z","level":"debug","msg":"frame.receive","traceId":"…","connectionId":"…","command":"PRIVMSG","lines":1}
+```
+
+Filter with `jq`:
+
+```
+pnpm --filter local-cli start | jq 'select(.msg=="dispatch.error")'
+```