serverless-ircd 0.9.0 → 0.11.0

package/docs/Cloudflare-Deployment-Guide.md

@@ -2,15 +2,15 @@
 
 End-to-end guide for deploying ServerlessIRCd to Cloudflare Workers
 (Phase 3 of `PLAN.md`). Covers prerequisites, first-time account setup,
-local development, staging deploy, production deploy, configuration,
-secrets, sharding, CI/CD, cost, and troubleshooting.
+local development, deploy, configuration, secrets, sharding, CI/CD,
+cost, and troubleshooting.
 
 Cross-reference: `PLAN.md` §6.1 (CF mapping), `apps/cf-worker/wrangler.toml`,
 `packages/cf-adapter/`, `.github/workflows/deploy-cf.yml`. For the AWS
-equivalent, see `docs/deployment-aws.md` (TICKET-044).
+equivalent, see `docs/AWS-Deployment.md`.
 
 **Acceptance criterion (TICKET-038):** a new contributor can deploy their
-own staging instance following only this doc.
+own instance following only this doc.
 
 ---
 
@@ -52,8 +52,10 @@ connection's `ConnectionDO`. All IRC protocol logic lives in the shared
 `irc-core` reducers, run by `ConnectionActor` inside the DO. No state is
 held in the Worker process itself.
 
-The same artifacts serve both staging and production; the only difference
-is the `--env` flag and the `[env.staging]` block in `wrangler.toml`.
+There is a single deploy target — the staging/prod split was collapsed.
+The same `wrangler.toml` ships to whichever Cloudflare account the
+deploy credentials target; staging vs production isolation is by
+account, not by a `[env.staging]` block.
 
 ---
 
@@ -63,15 +65,15 @@ is the `--env` flag and the `[env.staging]` block in `wrangler.toml`.
 |-----------------------|--------------------------------------------------------|
 | Node.js               | ≥ 20 (matches CI; `engines.node` in root `package.json`)|
 | pnpm                  | 9.x (`packageManager: pnpm@9.15.9` in root `package.json`)|
-| Cloudflare account    | Free tier is enough for staging. Workers Paid plan     |
-|                       | (USD $5/mo) is recommended for production — see §10.   |
+| Cloudflare account    | Free tier is enough to bring up the Worker. Workers Paid    |
+|                       | plan (USD $5/mo) is recommended for real traffic — see §10.|
 | `wrangler` CLI        | Comes from `apps/cf-worker/devDependencies`; no global install needed. |
-| Git checkout          | Clean working tree on `main` for production deploys.   |
+| Git checkout          | Clean working tree on `main` for deploys.                   |
 
-A **Workers Paid plan** is not strictly required for staging, but
-Durable Objects only run on the Paid plan in any meaningful production
-scenario. The free tier caps DO requests and disables hibernation
-budget headroom. See §10 (Cost).
+A **Workers Paid plan** is not strictly required to bring the Worker
+up, but Durable Objects only run on the Paid plan in any meaningful
+production scenario. The free tier caps DO requests and disables
+hibernation budget headroom. See §10 (Cost).
 
 Confirm the local environment:
 
@@ -136,9 +138,8 @@ export CLOUDFLARE_ACCOUNT_ID=...
 ```
 
 When `CLOUDFLARE_API_TOKEN` is set in the environment, `wrangler` uses
-it directly and skips the OAuth store. The deploy commands in
-`apps/cf-worker/package.json` (`deploy:staging`, `deploy:prod`) honor
-both.
+it directly and skips the OAuth store. The deploy command in
+`apps/cf-worker/package.json` (`deploy`) honors both.
 
 ---
 
@@ -172,7 +173,7 @@ Expected output (success):
 The smoke script (`scripts/smoke.mjs`) replays
 CONNECT → NICK/USER → JOIN #smoke → PRIVMSG → QUIT and asserts the
 server emits `001`, `376`, `353`, `366`, and closes the socket. It is
-the exact same script CI runs against the deployed staging URL.
+the exact same script CI runs against the deployed URL.
 
 The unit + integration suites live in `packages/cf-adapter/tests/` and
 `apps/cf-worker/tests/`; both run under `@cloudflare/vitest-pool-workers`
@@ -185,29 +186,29 @@ pnpm --filter @serverless-ircd/cf-worker test
 
 ---
 
-## 5. Deploy staging
+## 5. Deploy
 
-Staging is the environment CI deploys on every push to `main`; you can
-also deploy it manually from a clean checkout.
+The deploy is `workflow_dispatch`-only (a maintainer triggers it by
+hand); you can also deploy manually from a clean checkout.
 
 ### 5.1 Deploy from your machine
 
 ```bash
 # From the repo root:
-pnpm deploy:cf:staging
+pnpm deploy:cf
 # Equivalent to:
-#   pnpm --filter @serverless-ircd/cf-worker deploy:staging
-#   → wrangler deploy --env staging
+#   pnpm --filter @serverless-ircd/cf-worker run deploy
+#   → wrangler deploy
 ```
 
 The first deploy of a given account will:
 
-1. Create the Worker `serverless-ircd-staging`.
-2. Apply the `[[env.staging.migrations]]` block (`tag = "v1"`,
-   `new_classes = [ConnectionDO, RegistryDO, ChannelDO]`). This is what
-   provisions the three DO namespaces.
+1. Create the Worker `serverless-ircd`.
+2. Apply the `[[migrations]]` block (`tag = "v1"`,
+   `new_sqlite_classes = [ConnectionDO, RegistryDO, ChannelDO,
+   ChannelRegistryDO]`). This is what provisions the DO namespaces.
 3. Print the deployed URL, e.g.
-   `https://serverless-ircd-staging.example.workers.dev`.
+   `https://serverless-ircd.example.workers.dev`.
 
 If you see `Migration tag has already been applied`, the namespaces
 already exist; subsequent deploys just update the Worker code.
@@ -216,7 +217,7 @@ already exist; subsequent deploys just update the Worker code.
 
 ```bash
 node apps/cf-worker/scripts/smoke.mjs \
-  --url wss://serverless-ircd-staging.example.workers.dev
+  --url wss://serverless-ircd.example.workers.dev
 ```
 
 The same JSON `level: "info"` line on stdout means the full
@@ -228,7 +229,7 @@ Point any RFC-compliant WebSocket-aware IRC client at the deployed URL.
 For WeeChat:
 
 ```
-/server add ircd serverless-ircd-staging.example.workers.dev/443
+/server add ircd serverless-ircd.example.workers.dev/443
 /set irc.server.ircd.ssl on
 /connect ircd
 /join #test
@@ -241,18 +242,14 @@ section.
 
 ---
 
-## 6. Deploy production
+## 6. Production hardening
 
-Production is the default `wrangler.toml` environment (no `--env`
-flag). It deploys the Worker named `serverless-ircd` (no `-staging`
-suffix) with its own DO namespaces.
+There is a single deploy target per platform (`pnpm deploy:cf`). The
+staging/prod split was collapsed — there is no `[env.staging]` block
+and no `--env` flag. The Worker is always named `serverless-ircd`.
 
-```bash
-# From the repo root:
-pnpm deploy:cf:prod
-```
-
-Before your first production deploy, edit `apps/cf-worker/wrangler.toml`:
+Before your first deploy against a real account, edit
+`apps/cf-worker/wrangler.toml`:
 
 1. Set `[vars].SERVER_NAME` to the public hostname clients should see
    in numerics (`001`, `005`, etc.) — e.g. `irc.your-domain.com`.
@@ -263,60 +260,46 @@ Before your first production deploy, edit `apps/cf-worker/wrangler.toml`:
 3. Set `[vars].MOTD_LINES` to your message-of-the-day (newline-delimited).
 4. (Optional) Add a custom-domain Route under `[[routes]]` — see §8.4.
 
-**First-time production migration:** the default `[[migrations]]` block
-applies on the first `deploy:cf:prod` and creates the production DO
-classes. This is one-way: once a DO namespace has data, you cannot
-rename or delete a class without an explicit migration entry (see
-§9.2).
+**First-time migration:** the `[[migrations]]` block applies on the
+first deploy and creates the DO classes. This is one-way: once a DO
+namespace has data, you cannot rename or delete a class without an
+explicit migration entry (see §9.2).
 
-There is **no CI auto-deploy to production** — production deploys are
-always manual (`workflow_dispatch` only is intentionally not wired; see
-`.github/workflows/deploy-cf.yml`). Staging deploys on every push to
-`main`.
+Staging vs production isolation is by **Cloudflare account** — point a
+separate account's `CLOUDFLARE_API_TOKEN` at the deploy to ship to a
+different Worker namespace.
 
 ---
 
 ## 7. Configuration reference
 
 All deployment knobs live in `apps/cf-worker/wrangler.toml`. The file
-is the single source of truth for both environments.
+is the single source of truth for the Worker.
 
 ### 7.1 Top-level / `[vars]`
 
 | Var             | Purpose                                            | Default                              |
 |-----------------|----------------------------------------------------|--------------------------------------|
-| `name`          | Worker name. Staging overrides to `...-staging`.   | `serverless-ircd`                    |
+| `name`          | Worker name.                                       | `serverless-ircd`                    |
 | `main`          | Worker entry.                                      | `src/worker.ts`                      |
 | `compatibility_date` | Pins Workers runtime behavior.                | `2024-11-01`                         |
 | `compatibility_flags` | `nodejs_compat` enables Node-style APIs.    | `["nodejs_compat"]`                  |
 | `SERVER_NAME`   | Server name sent in `001`/`005` numerics. **Required** — the CF config loader fails fast at boot when unset. | _No default; must be set in `wrangler.toml`._ |
 | `NETWORK_NAME`  | Network label in `005 NETWORK=…`.                  | `ServerlessIRCd`                     |
 | `MOTD_LINES`    | Message-of-the-day, `\n`-delimited.                | Welcome banner string.               |
+| `MAX_CLIENTS`   | Global live-connection cap (enforced by `CounterDO` at the edge). | schema default |
+| `MAX_CONNECTIONS_PER_IP` | Per-IP simultaneous-connection cap (in-memory admission in `ConnectionDO`). | schema default (10) |
+| `PER_IP_CONNECTION_RATE_MAX` | Per-IP upgrade rate budget — how many WebSocket upgrades one `CF-Connecting-IP` may open per sliding window. Enforced at the edge by `RateLimitDO` (429 when over budget). | schema default (5) |
+| `PER_IP_CONNECTION_RATE_WINDOW_MS` | Sliding-window length in ms for the upgrade rate budget. Setting only one half of the pair falls back to the schema default (60 000 ms) for the other. | schema default (60 000) |
 
 These are read by `ConnectionDO` via `Env` (see
 `packages/cf-adapter/src/env.ts:20` and the `serverConfig()` method in
 `connection-do.ts:337`). They are **not** secrets — they ship in the
 bundle and are visible in the dashboard.
 
-### 7.2 `[env.staging]`
-
-The staging block overrides `name` and `[vars]` only. The DO bindings
-and migrations must be redeclared per-environment (wrangler requires
-explicit per-env blocks — they do not inherit):
+### 7.2 Durable Object bindings
 
-```toml
-[env.staging]
-name = "serverless-ircd-staging"
-
-[env.staging.vars]
-SERVER_NAME = "irc-staging.example.com"
-NETWORK_NAME = "ServerlessIRCd (staging)"
-MOTD_LINES = "..."
-```
-
-### 7.3 Durable Object bindings
-
-Three DO classes are exported from `src/worker.ts` (re-exported from
+The DO classes are exported from `src/worker.ts` (re-exported from
 `@serverless-ircd/cf-adapter`) and bound in `wrangler.toml`:
 
 | Binding name      | Class          | Owned state                                |
@@ -324,16 +307,19 @@ Three DO classes are exported from `src/worker.ts` (re-exported from
 | `CONNECTION_DO`   | `ConnectionDO` | Socket + ConnectionState + PING alarms.    |
 | `REGISTRY_DO`     | `RegistryDO`   | Nick uniqueness, nick→connId map (sharded).|
 | `CHANNEL_DO`      | `ChannelDO`    | Per-channel roster, modes, topic, fanout.  |
+| `CHANNEL_REGISTRY_DO` | `ChannelRegistryDO` | The channel-name registry (shard index). |
+| `COUNTER_DO`      | `CounterDO`    | Global live-connection counter (`maxClients` cap, TICKET-194). |
+| `RATE_LIMIT_DO`   | `RateLimitDO`  | Per-IP upgrade rate limiter — one sliding-window admission list per `CF-Connecting-IP`; the Worker edge checks the budget before forwarding an upgrade and rejects over-budget IPs with `429` (the per-IP layer of the connect throttling; runs before the `maxClients` counter so a flooding IP cannot consume global slots). |
 
 The class names in `wrangler.toml`'s `class_name` field MUST match the
 re-exports at the top of `apps/cf-worker/src/worker.ts:29`.
 
-### 7.4 Migrations
+### 7.3 Migrations
 
 ```toml
 [[migrations]]
 tag = "v1"
-new_classes = ["ConnectionDO", "RegistryDO", "ChannelDO"]
+new_sqlite_classes = ["ConnectionDO", "RegistryDO", "ChannelDO", "ChannelRegistryDO", "CounterDO", "RateLimitDO"]
 ```
 
 `tag` is the migration id (string, monotonically tracked by wrangler).
@@ -342,10 +328,10 @@ new_classes = ["ConnectionDO", "RegistryDO", "ChannelDO"]
 block with `tag = "v2"` (etc.) and a `renamed_classes` or `deleted_classes`
 entry. See <https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/>.
 
-Both the default and staging environments carry their own migration
-list. Keep them in sync unless you intentionally diverge.
+There is a single migration list — the `[env.staging]` block was
+removed when staging/prod collapsed into one target.
 
-### 7.5 Custom domain (optional)
+### 7.4 Custom domain (optional)
 
 To serve the Worker on `irc.example.com` instead of the workers.dev
 subdomain, add a route and bind a Cloudflare-managed DNS record:
@@ -357,9 +343,9 @@ zone_name = "example.com"
 custom_domain = false   # true if you'd rather use a Worker Custom Domain
 ```
 
-Custom domains are optional for staging and recommended for production
-(many IRC clients expect a stable, owned hostname). DNS records are
-managed separately in the dashboard.
+Custom domains are optional for a first deploy and recommended for
+real traffic (many IRC clients expect a stable, owned hostname). DNS
+records are managed separately in the dashboard.
 
 ---
 
@@ -372,7 +358,7 @@ disabled (the default). Configure it as a wrangler secret, never a
 plaintext `[vars]` entry:
 
 ```bash
-wrangler secret put SERVER_PASSWORD --env staging
+wrangler secret put SERVER_PASSWORD
 # → prompts for the value; stores it in the Workers secret store,
 #   NOT in wrangler.toml or the repo.
 ```
@@ -463,8 +449,7 @@ node --import tsx tools/seed-cf-accounts.ts \
   --accounts alice:change-me bob:also-change-me
 ```
 
-For staging, add `--env staging` and use the staging database name. The
-seed CLI hashes each password locally and executes the `INSERT OR REPLACE`
+The seed CLI hashes each password locally and executes the `INSERT OR REPLACE`
 via `wrangler d1 execute`.
 
 > The `SASL_ACCOUNTS` env var remains the quick-start path (no D1 needed):
@@ -548,9 +533,9 @@ the public list price as of 2024-11; verify current pricing at
 
 Practical numbers:
 
-- **Workers Free plan**: sufficient to bring up staging, exercise the
+- **Workers Free plan**: sufficient to bring up the Worker, exercise the
   smoke e2e, and validate a handful of concurrent connections. Not
-  suitable for production traffic (request caps, no reserved DO
+  suitable for sustained traffic (request caps, no reserved DO
   compute).
 - **Workers Paid plan** (USD $5/mo base + usage): enough headroom for a
   small production network. The dominant cost driver at scale is
@@ -572,10 +557,10 @@ mitigations (batched fanout, per-channel send-list cache).
 
 ## 11. CI/CD
 
-The GitHub Actions workflow at `.github/workflows/deploy-cf.yml`
-deploys staging on every push to `main` and replays the smoke e2e. It
-is the canonical deploy path — manual `pnpm deploy:cf:staging` is for
-iteration only.
+The GitHub Actions workflow at `.github/workflows/deploy-cf.yml` is
+`workflow_dispatch`-only (a maintainer triggers it by hand); there is
+no automatic push-to-main deploy. It deploys the single Worker target
+and replays the smoke e2e.
 
 Steps performed by the workflow (in order):
 
@@ -584,13 +569,13 @@ Steps performed by the workflow (in order):
 3. `pnpm install --frozen-lockfile`.
 4. `pnpm build` — builds all workspace packages.
 5. `pnpm typecheck` and `pnpm test` — gate the deploy.
-6. `pnpm deploy:cf:staging` — `wrangler deploy --env staging`.
+6. `pnpm deploy:cf` — `wrangler deploy`.
 7. Resolve the smoke URL from the `CF_SMOKE_URL` repo variable. If
    unset, the smoke step is skipped with a warning.
 8. Run `node scripts/smoke.mjs --url "$SMOKE_URL"`. Failure fails the
    build.
 
-Concurrency is serialized via `concurrency.group: cf-staging` so two
+Concurrency is serialized via `concurrency.group: cf-deploy` so two
 deploys cannot race the same DO namespace.
 
 Required repo configuration (under Settings → Secrets and variables →
@@ -599,12 +584,12 @@ Actions):
 - **Secret `CLOUDFLARE_API_TOKEN`** — required.
 - **Secret `CLOUDFLARE_ACCOUNT_ID`** — required if the token's account
   context is ambiguous.
-- **Variable `CF_SMOKE_URL`** — set to the staging Worker's `wss://`
+- **Variable `CF_SMOKE_URL`** — set to the Worker's `wss://`
   URL. Without it, the smoke step silently no-ops.
 
-There is **no auto-deploy to production**. Production deploys are
-intentionally manual (`pnpm deploy:cf:prod` from a clean checkout on
-`main`).
+There is a single deploy target — the staging/prod split was collapsed,
+so the same workflow + account ships to whichever Worker namespace the
+credentials target.
 
 ---
 
@@ -619,10 +604,10 @@ the `[[migrations]]` block, wrangler refuses to proceed.
 - If you intentionally changed the DO schema, append a new
   `[[migrations]]` block with `tag = "v2"` (and `renamed_classes` /
   `deleted_classes` as needed). Never edit an already-applied `tag`.
-- If the staging namespace has stale state from an aborted experiment,
+- If the namespace has stale state from an aborted experiment,
   you can destroy and recreate it from the dashboard (Workers & Pages →
-  Durable Objects → namespaces). **Production namespaces must never be
-  deleted** — that data is gone permanently.
+  Durable Objects → namespaces). **Namespaces carrying real traffic must
+  never be deleted** — that data is gone permanently.
 
 ### 12.2 `Cannot find module '@serverless-ircd/cf-adapter'`
 
@@ -636,10 +621,10 @@ The connection upgrade succeeded but registration didn't complete.
 Common causes:
 
 - The deployed Worker is reachable but the DO threw on the first frame.
-  Tail the logs: `wrangler tail --env staging` and reproduce.
+  Tail the logs: `wrangler tail` and reproduce.
 - The `MOTD_LINES` or `SERVER_NAME` var was deleted — `ConnectionDO`'s
   `serverConfig()` falls back to defaults, but a malformed value can
-  break parsing. Check the `[env.staging.vars]` block.
+  break parsing. Check the `[vars]` block.
 - Client connected over `ws://` to a Worker that requires `wss://`.
   Use the `wss://` URL the deploy step printed.
 
@@ -649,8 +634,8 @@ The DO alarm fired but the handler threw. The most likely cause is a
 stale persisted-state version after a code change; the serializer in
 `packages/cf-adapter/src/serialize.ts` carries `PERSISTED_STATE_VERSION`
 and will reject incompatible blobs. If this happens after an upgrade,
-ship a `deserialize` migration that upgrades the old version (or, on
-staging, clear the DO storage from the dashboard).
+ship a `deserialize` migration that upgrades the old version (or, on a
+throwaway deployment, clear the DO storage from the dashboard).
 
 ### 12.5 Nick reservation always fails
 
@@ -658,9 +643,9 @@ A client's `NICK` command always returns `433 ERR_NICKNAMEINUSE`, even
 for nicknames that should be free. This happens when two deployments
 share a `RegistryDO` namespace but were supposed to be separate —
 e.g., staging and production point at the same DO class name. Verify
-that each environment has its own DO namespace (the Worker name
-differs: `serverless-ircd` vs `serverless-ircd-staging`, and wrangler
-allocates a distinct namespace per Worker).
+that each deployment has its own DO namespace (a distinct Worker name
+per Cloudflare account means wrangler allocates a distinct namespace
+per Worker).
 
 ### 12.6 High request cost / DO request spike
 
@@ -687,9 +672,9 @@ appears lost, either:
 - The persisted-state version changed without a deserialize migration
   (see 12.4).
 
-For staging, the fastest recovery is usually to clear DO storage and
-re-test. For production, treat any migration tag change as a release
-blocker requiring a runbook entry.
+For a throwaway deployment, the fastest recovery is usually to clear DO
+storage and re-test. For real traffic, treat any migration tag change
+as a release blocker requiring a runbook entry.
 
 ---
 
@@ -705,15 +690,11 @@ pnpm build
 pnpm --filter @serverless-ircd/cf-worker dev    # http://localhost:8787
 node apps/cf-worker/scripts/smoke.mjs           # smoke against localhost
 
-# Staging
-pnpm deploy:cf:staging
+# Deploy (single target — staging vs prod is which account you point at)
+pnpm deploy:cf
 node apps/cf-worker/scripts/smoke.mjs \
-  --url wss://serverless-ircd-staging.<subdomain>.workers.dev
-npx wrangler tail --env staging                 # live logs
-
-# Production (manual only)
-pnpm deploy:cf:prod
-npx wrangler tail                               # default env = production
+  --url wss://serverless-ircd.<subdomain>.workers.dev
+npx wrangler tail                                  # live logs
 
 # Tests / lint
 pnpm test                                       # full workspace
@@ -732,4 +713,4 @@ Key files:
 | `packages/cf-adapter/src/`              | `ConnectionDO`, `RegistryDO`, `ChannelDO`, `CfRuntime`, sharding. |
 | `packages/cf-adapter/src/sharding.ts`   | Shard function + `DEFAULT_REGISTRY_SHARDS`.  |
 | `packages/cf-adapter/src/env.ts`        | `Env` interface (binding contract).          |
-| `.github/workflows/deploy-cf.yml`       | Staging deploy + smoke e2e CI.               |
+| `.github/workflows/deploy-cf.yml`       | Deploy + smoke e2e CI (manual dispatch).     |