serverless-ircd 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  verify:
+    name: typecheck / lint / test / coverage
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test with coverage
+        run: pnpm coverage
+
+      - name: Upload coverage
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: |
+            packages/*/coverage
+            apps/*/coverage

package/.github/workflows/deploy-cf.yml

@@ -0,0 +1,97 @@
+name: deploy-cf
+
+# Cloudflare Workers deploy pipeline.
+#
+# On every push to `main`:
+#   1. Install deps (frozen lockfile).
+#   2. Build the cf-adapter + irc-core/irc-server so the Worker entry
+#      typechecks against real workspace packages.
+#   3. `wrangler deploy --env staging` the `apps/cf-worker` worker to the
+#      `serverless-ircd-staging` Worker + DO namespace.
+#   4. Replay the smoke e2e (`scripts/smoke.mjs`) against the deployed
+#      URL — CONNECT/REGISTER/JOIN/PRIVMSG/QUIT. Failure blocks the
+#      merge (the deploy job is required on `main`).
+#
+# Secrets (configure under repo Settings → Secrets and variables → Actions):
+#   CLOUDFLARE_API_TOKEN   Workers API token with `Workers Scripts:Edit`
+#                          and `Durable Objects:Edit` on the target
+#                          account. Never committed.
+#   CLOUDFLARE_ACCOUNT_ID  Optional; required if the token's account
+#                          context is ambiguous.
+#
+# The smoke URL is derived from the staging Worker name
+# (`serverless-ircd-staging`) plus the deployer's account subdomain.
+# Override by setting `CF_SMOKE_URL` in the repo Variables store when
+# custom routes are wired.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Prevent two deploys racing the same DO namespace.
+concurrency:
+  group: cf-staging
+  cancel-in-progress: false
+
+jobs:
+  deploy-staging:
+    name: wrangler deploy --env staging
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build workspace
+        run: pnpm build
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test
+        run: pnpm test
+
+      - name: Deploy to staging
+        working-directory: apps/cf-worker
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: pnpm deploy:staging
+
+      - name: Resolve smoke URL
+        id: smoke-url
+        env:
+          CF_SMOKE_URL: ${{ vars.CF_SMOKE_URL }}
+        run: |
+          if [ -n "$CF_SMOKE_URL" ]; then
+            echo "url=$CF_SMOKE_URL" >> "$GITHUB_OUTPUT"
+          else
+            # Default convention: <worker-name>.<account-subdomain>.workers.dev
+            # The subdomain is per-account; if CF_SMOKE_URL isn't set we
+            # fall back to a workers.dev route that the deployer must
+            # configure once via the Cloudflare dashboard.
+            echo "::warning::CF_SMOKE_URL repo variable is not set; smoke step will be skipped. Set it to the staging Worker's wss:// URL."
+            echo "url=" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Smoke e2e
+        if: steps.smoke-url.outputs.url != ''
+        working-directory: apps/cf-worker
+        env:
+          SMOKE_URL: ${{ steps.smoke-url.outputs.url }}
+        run: node scripts/smoke.mjs --url "$SMOKE_URL"

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, fowlmouth
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF NOT ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,323 @@
+# ServerlessIRCd
+
+A serverless IRC daemon where the IRC protocol logic lives in a pure,
+platform-agnostic core, and two thin adapters run it on **Cloudflare Workers**
+(Durable Objects) or **AWS** (API Gateway WebSockets + Lambda + DynamoDB).
+
+One TypeScript codebase. Two serverless substrates. No S2S linking in v1.
+
+> **Status:** **v0.1.0 (preview).** The pure protocol core, the
+> `IrcRuntime` port + in-memory runtime, a runnable local CLI server,
+> and the Cloudflare Workers adapter (deployed to staging) are all
+> functional. SASL, flood control, the AWS adapter, server-password
+> enforcement, and the CI coverage gate are still ahead. See
+> `CHANGELOG.md` for the v0.1.0 manifest, `docs/release.md` for the
+> release process, and `progress.md` / `tickets.md` for per-ticket
+> status.
+
+---
+
+## Why
+
+IRC servers have historically been long-running stateful processes. This
+project explores what happens when the protocol brain is a set of **pure
+reducers** and the only platform-specific code is the side-effect plumbing
+(transports, registries, fanout). The payoff:
+
+- Every command handler is a trivial unit test: arrange state, apply a message,
+  assert the new state and emitted effects.
+- The same core runs unchanged on Cloudflare and AWS.
+- Authoritative state lives in exactly one place per piece of data, so races
+  are structurally impossible rather than defended against.
+
+---
+
+## Architecture
+
+Hexagonal / ports-and-adapters. The core reasons about IRC; adapters move bytes.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  packages/irc-core         (pure TS, no cloud deps)             │
+│    protocol/  parse · serialize · numerics · messages           │
+│    commands/  pure reducers: (state, msg) → { state, effects }  │
+│    state/     channel · connection · mode · registry shapes     │
+└─────────────────────────────────────────────────────────────────┘
+                               ▲ implements IrcRuntime (port)
+                               │
+┌─────────────────────────────────────────────────────────────────┐
+│  packages/irc-server      (orchestration, defines the port)     │
+│    IrcRuntime   side-effect interface (transport + state IO)    │
+│    dispatch     interprets Effect[] against a bound runtime     │
+└─────────────────────────────────────────────────────────────────┘
+            ▲                                   ▲
+┌────────────────────────────┐      ┌──────────────────────────────┐
+│  adapters/cf               │      │  adapters/aws                │
+│    ConnectionDO            │      │    $connect/$disconnect/     │
+│    ChannelDO               │      │    $default Lambda handlers  │
+│    RegistryDO              │      │    DynamoDB tables           │
+│    CfRuntime               │      │    AwsRuntime                │
+└────────────────────────────┘      └──────────────────────────────┘
+```
+
+A planned `packages/in-memory-runtime` provides a reference implementation of
+`IrcRuntime` used by integration tests and a local CLI server.
+
+### The key idea: pure reducers + location-of-authority
+
+Each command handler is a pure function:
+
+```ts
+type Reducer<S> = (state: S, msg: IrcMessage, ctx: Ctx) => {
+  state: S;
+  effects: Effect[];
+};
+```
+
+Side effects are **values** (`Effect[]`), not performed in the handler. The
+actor layer's `dispatch(effects, runtime)` interprets each effect against the
+bound runtime.
+
+Each reducer runs in whichever authority **owns** the state it mutates:
+
+| Command family              | Runs in authority       | Primary state mutated        |
+|-----------------------------|-------------------------|------------------------------|
+| Registration (NICK/USER)    | Connection entity       | Connection state             |
+| PING/PONG, QUIT, AWAY       | Connection entity       | Connection state             |
+| JOIN / PART / channel MODE  | Channel entity          | Roster, channel modes        |
+| PRIVMSG/NOTICE to channel   | Channel entity          | Fanout (reads roster)        |
+| Nick collision check        | Registry entity         | Nick → Connection map        |
+| NAMES / WHO / WHOIS         | Reads snapshots         | (no mutation)                |
+
+---
+
+## Repository layout
+
+```
+ServerlessIRCd/
+├── packages/
+│   ├── irc-core/          pure protocol + reducers (the brain)
+│   ├── irc-server/        orchestration, IrcRuntime port, dispatch
+│   ├── in-memory-runtime/ reference runtime + local CLI server (planned)
+│   ├── cf-adapter/        Durable Objects + CfRuntime (planned)
+│   └── aws-adapter/       Lambda + DynamoDB + AwsRuntime (planned)
+├── apps/
+│   ├── cf-worker/         worker entry, DO migrations, bindings (planned)
+│   ├── aws-stack/         CDK app entry (planned)
+│   └── local-cli/         runnable WS server using in-memory-runtime
+├── tools/
+│   └── tcp-ws-forwarder/ local TCP↔ws/wss bridge for stock IRC clients
+├── docs/
+│   └── architecture-aws.md
+├── pnpm-workspace.yaml    turbo.json   tsconfig.base.json
+└── PLAN.md                progress.md   tickets.md
+```
+
+---
+
+## Toolchain
+
+| Concern        | Choice                                            |
+|----------------|---------------------------------------------------|
+| Runtime        | Node ≥ 20, ES2022+                                |
+| Package mgr    | pnpm workspaces                                   |
+| Build cache    | turbo                                             |
+| Language       | TypeScript (strict, `exactOptionalPropertyTypes`) |
+| Test runner    | vitest + `@vitest/coverage-v8`                    |
+| Property tests | fast-check                                        |
+| Lint / format  | Biome                                             |
+
+---
+
+## Getting started
+
+Requires Node ≥ 20 and pnpm 9.
+
+```bash
+pnpm install              # install workspace deps
+
+pnpm build                # build all packages (turbo)
+pnpm typecheck            # tsc --noEmit across the workspace
+pnpm test                 # run all tests once
+pnpm test:watch           # vitest watch mode
+pnpm coverage             # tests + v8 coverage report
+
+pnpm lint                 # biome check .
+pnpm lint:fix             # biome check --write .
+pnpm format               # biome format --write .
+
+pnpm clean                # remove dist/coverage/.turbo + node_modules
+```
+
+Coverage reports are written to `packages/*/coverage/`. CI (`.github/workflows/ci.yml`)
+runs lint, typecheck, and coverage on every push and pull request.
+
+---
+
+## Running the local server
+
+`apps/local-cli` is a runnable WebSocket IRC server built on the in-memory
+runtime. It's the manual-test harness and the e2e fixture target — the same
+`irc-core` reducers and `ConnectionActor` the cloud adapters will use, just
+wired to a plain `ws.WebSocketServer` on localhost.
+
+First build the workspace (the CLI runs from compiled `dist/`):
+
+```bash
+pnpm build
+```
+
+Then start the server (from the repo root):
+
+```bash
+pnpm --filter local-cli start
+# or with explicit args:
+pnpm --filter local-cli start --port 6667 --host 127.0.0.1
+```
+
+On startup it logs a JSON line like:
+
+```json
+{"ts":"...","level":"info","msg":"local-cli listening","url":"ws://127.0.0.1:6667/","port":6667,"hostname":"127.0.0.1"}
+```
+
+### CLI flags
+
+| Flag         | Default     | Description                                  |
+|--------------|-------------|----------------------------------------------|
+| `--port <n>` | `6667`      | TCP port to bind. Use `0` for an ephemeral.  |
+| `--host <h>` | `127.0.0.1` | Hostname / interface to bind.                |
+| `-h, --help` |             | Show help and exit.                          |
+
+Pass `--host 0.0.0.0` to expose the server on all interfaces. `SIGINT` /
+`SIGTERM` perform a graceful shutdown (closes active sockets, then exits).
+
+### Connecting
+
+The server speaks WebSocket text frames (one IRC message per frame). Point any
+WebSocket-capable IRC client (WeeChat with the `irc` protocol's WS relay, or a
+small script) at `ws://127.0.0.1:6667/`. Server name and MOTD are fixed
+defaults (`irc.example.com`) until the config-loader ticket lands.
+
+---
+
+## Connecting a TCP IRC client (TCP→WS forwarder)
+
+v1 is WebSocket-only, so a stock TCP IRC client (WeeChat, HexChat, irssi, …)
+cannot dial a deployed worker or the local WS server directly.
+`tools/tcp-ws-forwarder` is a local bridge: it listens on a TCP port and, for
+each connection, opens one WebSocket to a `ws://` / `wss://` target and pumps
+IRC lines both ways — reassembling the TCP byte stream into one message per WS
+frame outbound, and normalizing inbound frames back to canonical CRLF.
+
+Build the workspace, then start the forwarder (from the repo root):
+
+```bash
+pnpm build
+
+# Bridge localhost:16667 → the local WS server started above:
+pnpm --filter tcp-ws-forwarder start \
+  --target ws://127.0.0.1:6667/ --listen-port 16667
+
+# Or bridge straight to a deployed stack:
+pnpm --filter tcp-ws-forwarder start \
+  --target wss://irc.example.com/ --listen-port 16667
+```
+
+On startup it logs a JSON line like:
+
+```json
+{"ts":"...","level":"info","msg":"tcp-ws-forwarder listening","listen":"127.0.0.1:16667","target":"ws://127.0.0.1:6667/"}
+```
+
+### CLI flags
+
+| Flag                | Default     | Description                                      |
+|---------------------|-------------|--------------------------------------------------|
+| `--target <url>`    | (required)  | Upstream `ws://` or `wss://` URL to bridge to.   |
+| `--listen-port <n>` | `6667`      | TCP port to listen on. Use `0` for an ephemeral. |
+| `--listen-host <h>` | `127.0.0.1` | Interface to bind.                               |
+| `-h, --help`        |             | Show help and exit.                              |
+
+### Connecting
+
+Point any TCP IRC client at `127.0.0.1:<listen-port>` and it will appear as a
+direct connection to the WebSocket endpoint. `SIGINT` / `SIGTERM` perform a
+graceful shutdown (closes the listener and every live bridge). The forwarder
+is transport-agnostic — it ships no `@serverless-ircd/*` dependency and works
+against any line-oriented WebSocket endpoint.
+
+---
+
+## Testing strategy
+
+This project follows strict TDD (Red → Green → Refactor) — every reducer is
+landed test-first. See the project-level `CLAUDE.md` / `AGENTS.md` for the
+full rules.
+
+| Layer            | Tooling                                 | What it asserts                       |
+|------------------|-----------------------------------------|---------------------------------------|
+| Parser/serializer| vitest + fast-check                     | Grammar correctness, round-trip       |
+| Reducers (core)  | vitest pure unit tests                  | `(state,msg) → {state,effects}` exact |
+| Runtime contract | vitest parametrized over `IrcRuntime`   | Same scenarios pass in-memory+CF+AWS  |
+| CF adapter       | `vitest-pool-workers` (real workerd)    | DO behavior, alarms, stub fanout      |
+| AWS adapter      | vitest + dynamodb-local / localstack    | DynamoDB schema, transactions, fanout |
+| E2E              | real WS clients in `tools/irc-client`   | RFC-shaped flows vs deployed stack    |
+
+**Determinism:** reducers never touch real timers or randomness. A `Clock`
+port and an `IdFactory` port are injected so tests are fully deterministic.
+
+---
+
+## Roadmap
+
+A v1 ships when `irc-core` is at 100% coverage, the parametrized contract
+suite passes against every runtime, both adapters are deployed to staging,
+and ≥3 reference clients (WeeChat, HexChat, IRCCloud, TheLounge) connect
+cleanly. Full per-ticket status lives in `progress.md`. Per-release
+manifests live in `CHANGELOG.md`; the release process is documented in
+`docs/release.md`.
+
+- **Phase 0** — Foundation (monorepo, turbo, vitest, biome, CI). ✅
+- **Phase 1** — Pure protocol engine: reducers, IRCv3 caps, isupport.
+  Most of this landed in **v0.1.0**; SASL and flood control are still
+  pending.
+- **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 only; prod deploy is manual).
+- **Phase 4** — AWS adapter (APIGW WS + Lambda + DynamoDB + CDK).
+- **Phase 5** — Observability, security hardening, config, CI gates.
+- **Phase 6** — Load testing, client compatibility sweep, ADRs.
+
+---
+
+## Protocol scope (v1)
+
+**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`, `MOTD`.
+
+**Channel modes:** `o v b i k l t n m s p`.
+**User modes:** `i`, `o` (local only), `w`, `s`.
+
+**IRCv3 extensions (negotiated via `CAP`):** `message-tags`, `server-time`,
+`account-tag`, `echo-message`, `batch`, `sasl` (`PLAIN`, `EXTERNAL` reserved),
+`multi-prefix`, `away-notify`, `chghost`, `invite-notify`, `extended-join`.
+
+**Transport:** WebSocket text frames only (one IRC message per frame, with
+tolerance for `\r\n`-joined frames). No plaintext TCP in v1 — keeps the
+serverless story clean. Stock TCP IRC clients reach the server through the
+local [`tcp-ws-forwarder`](#connecting-a-tcp-irc-client-tcpws-forwarder).
+
+---
+
+## Further reading
+
+- `PLAN.md` — full project plan, platform mappings, risks, decisions.
+- `CHANGELOG.md` — per-release manifests (Keep a Changelog format).
+- `docs/release.md` — release process runbook (versioning, tagging,
+  rollback).
+- `progress.md` / `tickets.md` — what's done, what's next.
+- `docs/deployment-cf.md` — Cloudflare deployment guide.
+- `docs/architecture-aws.md` — AWS adapter design notes.

package/apps/cf-worker/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@serverless-ircd/cf-worker",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Cloudflare Worker deploy glue: WebSocket edge entry point + DO bindings + wrangler pipeline",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "main": "./dist/worker.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "dev": "wrangler dev",
+    "deploy:staging": "wrangler deploy --env staging",
+    "deploy:prod": "wrangler deploy",
+    "smoke:staging": "node scripts/smoke.mjs",
+    "clean": "rimraf dist coverage .tsbuildinfo .turbo"
+  },
+  "dependencies": {
+    "@serverless-ircd/cf-adapter": "workspace:*",
+    "@serverless-ircd/irc-core": "workspace:*",
+    "@serverless-ircd/irc-server": "workspace:*"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "0.18.6",
+    "@cloudflare/workers-types": "^5.20260714.1",
+    "@types/ws": "^8.5.13",
+    "@vitest/coverage-v8": "^4.1.0",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.0",
+    "wrangler": "4.112.0",
+    "ws": "^8.18.0"
+  }
+}