serverless-ircd 0.5.0 → 0.7.0

package/docs/ADR-008-monorepo-tooling.md

@@ -0,0 +1,60 @@
+# ADR-008: Monorepo and tooling stack
+
+**Date:** 2025-01-10 (Phase 0)
+**Status:** Accepted
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+ServerlessIRCd is a multi-package TypeScript project: a platform-agnostic
+core (`irc-core`), an orchestration layer (`irc-server`), a reference runtime
+(`in-memory-runtime`), two cloud adapters (`cf-adapter`, `aws-adapter`), and
+several apps (`local-cli`, `cf-worker`, `aws-stack`). The toolchain must
+support cross-package type checking, incremental builds, a unified test
+runner, and CI that enforces coverage gates per package.
+
+## Decision
+
+| Concern | Choice | Rationale |
+|---|---|---|
+| Package manager | **pnpm** (workspaces) | Fast, disk-efficient, first-class monorepo support |
+| Build orchestration | **turbo** (caching) | Incremental builds, remote cache, task dependency graph |
+| TypeScript | Project references + `tsconfig.base.json` | Strict mode, `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess` |
+| Test runner | **vitest** | ESM-native, fast, integrates with Workers (`vitest-pool-workers`), built-in coverage |
+| Coverage | v8 provider, gate ≥90% (100% on `irc-core`) | Enforced in CI (`.github/workflows/ci.yml`) |
+| Lint/format | **Biome** | Single tool (replaces ESLint + Prettier), fast, zero config drift |
+| CF bundler | **wrangler** (esbuild internally) | Native Workers toolchain |
+| AWS bundler | **esbuild** (Lambda bundles) + **CDK v2** (infra) | Tree-shaking, fast cold starts |
+| Runtime target | Node 20 (Lambda) + latest Workers runtime; ES2022+ | Aligns with platform-supported runtimes |
+
+## Consequences
+
+**Positive:**
+- pnpm workspaces + turbo give fast local dev: only changed packages rebuild;
+  tests run incrementally.
+- vitest's ESM-native design avoids the CJS/ESM interop pain that plagues
+  Jest-based monorepos. The same test files run under `vitest-pool-workers`
+  (real `workerd`) for CF adapter tests.
+- Biome eliminates the ESLint/Prettier config drift problem — one tool, one
+  config, one command (`biome check`).
+- TypeScript project references enforce package boundaries at compile time:
+  `irc-core` cannot accidentally import from `cf-adapter`.
+
+**Negative:**
+- pnpm's strict node-linker can surprise contributors used to npm/yarn's
+  hoisting. `node_modules` is per-package; global scripts need
+  `pnpm --filter`.
+- turbo's caching requires consistent environment hashing; a CI cache miss
+  (e.g. different Node minor version) degrades to a full rebuild silently.
+- Biome is newer than ESLint and lacks some ecosystem plugins. Custom rules
+  (e.g. "no ticket IDs in source files") are enforced via convention
+  (`AGENTS.md`) rather than a Biome plugin.
+
+## References
+
+- PLAN §9 — "Monorepo: pnpm + TypeScript project references; turbo for
+  caching"
+- `pnpm-workspace.yaml`, `turbo.json`, `tsconfig.base.json`, `biome.json`
+- `.github/workflows/ci.yml` — coverage gates and CI pipeline
+- `AGENTS.md` — code style conventions

package/docs/ADR-009-dual-transport-wss-and-irc-tls.md

@@ -0,0 +1,138 @@
+# ADR-009: Dual transport — wss (default) + irc+tls on :6697
+
+**Date:** 2026-07-26 (Phase 7)
+**Status:** Accepted
+**Supersedes:** ADR-005 (wss-only transport in v1)
+**Superseded by:** —
+
+## Context
+
+ADR-005 chose **wss-only** for v1. That decision rested on four points, all
+still accurate as facts about the serverless substrates:
+
+1. Both target platforms (CF Workers, AWS API Gateway WebSocket) support wss
+   natively with zero additional infrastructure; neither can accept raw TCP
+   from its request-response compute (Workers is request-response; API Gateway
+   is WebSocket-only).
+2. wss is TLS-terminated at the edge (CF) or at API Gateway (AWS), so the
+   Lambda/Worker never sees plaintext credentials.
+3. One IRC message per WebSocket text frame eliminates the need for a
+   stateful byte-stream line buffer in the core (the parser already tolerates
+   `\r\n`-joined frames for robustness).
+4. The serverless cost/ops story stays clean: no long-running origin, no TCP
+   keepalive management, one codebase + two adapters.
+
+What changed the decision is **demand, not capability**:
+
+- **RFC 1459/2812 compliance.** The target modern clients (WeeChat, HexChat,
+  IRCCcd, TheLounge) mostly support wss, but there is a long tail of older
+  clients, bots, bridges, and monitoring tools that only speak `irc+tls`
+  (raw TCP + TLS on :6697). Supporting them was a non-goal for the initial v1
+  cut; the gap now matters for the compatibility-sweep deliverable.
+- **SASL EXTERNAL (mTLS).** `AUTHENTICATE EXTERNAL` needs the client
+  certificate to reach the application layer (ADR-006). With wss and
+  edge-terminated TLS, the cert is consumed at the edge and the app only gets
+  a verified subject via platform config (CF API Shield mTLS, API Gateway
+  custom-domain mTLS — both TICKET-054). A real `irc+tls` path gives a more
+  conventional mTLS surface that matches client expectations.
+- **Marginal cost is small.** The core is transport-agnostic by design: pure
+  reducers + a `ConnectionActor` that already accepts `\r\n`-joined frames.
+  Adding a second transport is a **second per-platform entry-point adapter**,
+  not a re-architecture. The generalized TCP byte-stream transport seam is
+  TICKET-053; the per-platform adapters are TICKET-055 (CF) and TICKET-056
+  (AWS).
+
+## Decision
+
+v1.x adopts a **dual-transport** model:
+
+- **wss stays the serverless default.** `wss://server.tld/` with one IRC
+  message per WebSocket text frame remains the primary path. It needs zero
+  extra infrastructure on either platform and keeps the clean serverless
+  story for the common case.
+- **`irc+tls` on :6697 is added** as a second, per-platform adapter for
+  RFC-compliant clients. TLS is mandatory; **plaintext TCP on :6667 stays
+  unsupported.** The entry point differs per platform because neither
+  serverless compute can accept raw TCP directly:
+
+  | Platform | Edge (TLS termination)              | Origin / compute                              |
+  |----------|-------------------------------------|-----------------------------------------------|
+  | CF       | Cloudflare Spectrum (Enterprise)     | Cloudflare Container running TCP byte-stream  |
+  |          |                                     | `ConnectionActor` over a persistent runtime  |
+  | AWS      | Network Load Balancer (`tls` listener) | Lambda **streaming** function (target);     |
+  |          |                                     | connection ID derived from NLB flow metadata |
+
+  Spectrum terminates TLS at the edge and forwards plaintext TCP to the
+  container origin; NLB terminates TLS and invokes a Lambda streaming
+  function as target. Both reuse `AwsRuntime`/the CF runtime storage layer
+  for connection/channel/nick state.
+
+The **pure reducer core and `ConnectionActor` are shared** across both
+transports and both platforms. Only two things differ on the new path:
+
+1. The **transport seam** (TICKET-053): `ConnectionActor` accepts either a
+   `WsTextFrameTransport` (one message per frame — current behavior) or a
+   `TcpByteStreamTransport` (stateful `\r\n` framing across chunks with
+   partial-line buffering). Parser → reducer → dispatch is unchanged.
+2. The **entry-point adapter** (TICKET-055 / TICKET-056): Spectrum+Container
+   on CF, NLB+Lambda streaming on AWS.
+
+mTLS (TICKET-054) is done at the edge on the wss path (CF API Shield mTLS /
+API Gateway custom-domain mTLS) and via the TLS handshake on the TCP path
+(Spectrum cert verification / NLB ACM cert + optional client-cert
+verification).
+
+## Consequences
+
+**Positive:**
+- RFC 1459/2812-compliant clients, bots, and bridges connect natively without
+  a `tcp-ws-forwarder` bridge. This unblocks the compatibility-sweep
+  deliverable for the long tail of TCP-only clients.
+- A conventional mTLS surface opens for SASL `EXTERNAL` (TICKET-054): the
+  client cert reaches the application via the TLS handshake on the TCP path,
+  matching standard IRC client expectations, in addition to the edge-mTLS
+  path on wss.
+- Core reuse: the pure reducers, `IrcRuntime` port, and `ConnectionActor`
+  are shared verbatim. The transport seam (TICKET-053) is the only new
+  abstraction in the core; everything else is per-platform glue.
+- The wss default is untouched — deployments that do not need raw TCP pay no
+  infra cost and keep the clean serverless story.
+
+**Negative:**
+- **CF breaks the pure-serverless story on the TCP path.** Spectrum is an
+  Enterprise-tier feature, and the origin is a stateful Cloudflare Container
+  (or external compute), not a Worker. Connection state must survive origin
+  reconnects via the runtime's persistence layer — a new operational surface
+  that the wss path (Durable Objects) does not have.
+- **AWS NLB + Lambda streaming has hard limits:** Lambda streaming invoke
+  idle timeout and maximum connection/duration caps. Long-idle IRC clients
+  can be dropped; reconnect/PING behavior must tolerate this (same class of
+  risk as the APIGW 2h WS cap, PLAN §10).
+- **Extra per-platform adapter surface.** Two entry-point adapters
+  (TICKET-055, TICKET-056) and a new transport contract dimension
+  (TICKET-057) are added to the test matrix. Cross-adapter drift is now a
+  transport × runtime matrix, mitigated by the parametrized contract suite.
+- **Double deploy/ops paths per platform.** Each platform now ships a wss
+  stack and a TCP+TLS stack with different infra (DO vs Container; APIGW vs
+  NLB). Deploy docs, cost monitoring, and incident runbooks must cover both
+  (TICKET-058).
+
+## References
+
+- ADR-005 — wss-only transport in v1 (**superseded** by this ADR)
+- ADR-006 — SASL mechanism scope (PLAIN only; EXTERNAL deferred to Phase 7;
+  this ADR unblocks the mTLS path for EXTERNAL)
+- PLAN §3 — Protocol scope (connection framing)
+- PLAN §9 — Key technical decisions (framing)
+- TICKET-052 — this ADR; revises the transport decision
+- TICKET-053 — generalize `ConnectionActor` transport seam (TCP byte-stream
+  framing)
+- TICKET-054 — mTLS support (edge config + `AccountStore` plumbing; enables
+  functional SASL EXTERNAL)
+- TICKET-055 — CF TCP+TLS adapter via Cloudflare Spectrum + Container origin
+- TICKET-056 — AWS TCP+TLS adapter via Network Load Balancer (TLS) + Lambda
+  streaming
+- TICKET-057 — extend integration contract suite over transport
+  (wss × TCP+TLS)
+- TICKET-058 — docs: `Cloudflare-TCP-Deployment.md` and `AWS-TCP-Deployment.md`
+  (TCP+TLS variants)

package/docs/ADR-Index.md

@@ -0,0 +1,15 @@
+# ADR Index
+
+This is an index of all Architecture Decision Records (ADRs), in chronological order.
+
+| ADR | Title |
+| --- | --- |
+| [ADR-001](ADR-001-pure-reducers-and-effect-system) | Pure reducers and the effect system |
+| [ADR-002](ADR-002-location-of-authority) | Location-of-authority state split |
+| [ADR-003](ADR-003-durable-object-sharding) | Cloudflare Durable Object sharding strategy |
+| [ADR-004](ADR-004-dynamodb-schema) | AWS DynamoDB schema |
+| [ADR-005](ADR-005-wss-only-transport-v1) | wss-only transport in v1 (no raw TCP) |
+| [ADR-006](ADR-006-sasl-mechanism-scope) | SASL mechanism scope (PLAIN always; EXTERNAL mTLS-conditional) |
+| [ADR-007](ADR-007-deterministic-ports) | Deterministic ports for time and ID generation |
+| [ADR-008](ADR-008-monorepo-tooling) | Monorepo and tooling stack |
+| [ADR-009](ADR-009-dual-transport-wss-and-irc-tls) | Dual transport — wss (default) + irc+tls on :6697 |