serverless-ircd 0.9.0 → 0.11.0

package/docs/AWS-TCP-Deployment.md

@@ -12,7 +12,7 @@ CDK stack and a deployment can enable either or both.
 > This doc covers the *how*.
 
 **Acceptance criterion (TICKET-058):** a new contributor can deploy
-their own TCP+TLS staging instance following only this doc.
+their own TCP+TLS instance following only this doc.
 
 Cross-reference: `apps/aws-stack/src/aws-stack.ts` (CDK), the wss path
 (`AWS-Deployment.md`), TICKET-054 (mTLS), ADR-006 (SASL scope).
@@ -102,7 +102,6 @@ The `IrcAwsStack` construct accepts an optional prop
 
 ```ts
 export interface IrcStackProps extends StackProps {
-  readonly environmentName?: string;
   readonly serverName?: string;
   readonly networkName?: string;
   readonly motdLines?: string[];
@@ -130,21 +129,20 @@ deploys — the existing pipeline stays green.
 
 ---
 
-## 4. Deploy staging (TCP+TLS)
+## 4. Deploy (TCP+TLS)
 
 ```bash
 # From the repo root:
-pnpm deploy:aws:staging -- \
-  -c environmentName=staging \
-  -c tcpTlsDomainName=irc-staging.example.com
+pnpm deploy:aws -- \
+  -c tcpTlsDomainName=irc.example.com
 ```
 
 This is the same `cdk deploy --all` the wss path uses
-(`apps/aws-stack/package.json` `deploy:staging`), just with the extra
+(`apps/aws-stack/package.json` `deploy`), just with the extra
 context var. The deploy will:
 
-1. Create the ACM certificate for `irc-staging.example.com` (DNS
-   validation via Route 53; if the hosted zone is not in this account,
+1. Create the ACM certificate for `irc.example.com` (DNS
+   validation via Route 53; if the hosted zone is not in this account,
    validate out-of-band and import the cert ARN — see §9.2).
 2. Provision `NlbVpc`, the internet-facing NLB, the `TLS` listener on
    `:6697`, and the `IrcNlbHandler` Lambda target group.
@@ -165,15 +163,15 @@ unchanged** — enabling TCP does not disable wss.
 The first deploy can take several minutes while ACM validates the
 certificate. `cdk deploy` waits on the certificate resource; do not
 interrupt it. If validation times out, confirm the hosted zone for the
-domain is in this account and Route 53 can write the `_acme-challenge`
+domain is in this account and Route 53 can write the `_acme-challenge`
 CNAME.
 
 ### 4.2 Point a DNS record at the NLB (recommended)
 
 The NLB prints a long `.elb.amazonaws.com` DNS name. For a stable,
-owned hostname, create an **alias A record** (Route 53) or a CNAME
-pointing `irc-staging.example.com` → the NLB DNS name. Clients then
-connect to `irc-staging.example.com:6697`.
+owned hostname, create an **alias A record** (Route 53) or a CNAME
+pointing `irc.example.com` → the NLB DNS name. Clients then
+connect to `irc.example.com:6697`.
 
 (You can connect directly to the raw NLB DNS, but the cert is issued for
 your domain, so TLS SNI/hostname verification wants the owned name.)
@@ -182,28 +180,12 @@ your domain, so TLS SNI/hostname verification wants the owned name.)
 
 ```bash
 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 | \
+  timeout 10 openssl s_client -connect irc.example.com:6697 -quiet | \
   grep -q '001' && echo "SMOKE PASS" || echo "SMOKE FAIL"
 ```
 
 ---
 
-## 5. Deploy production
-
-```bash
-pnpm deploy:aws:prod -- \
-  -c environmentName=production \
-  -c tcpTlsDomainName=irc.example.com
-```
-
-Production deploys are manual. The staging CI workflow
-(`deploy-aws.yml`) deploys only the wss path (`-c environmentName=staging`
-without `tcpTlsDomainName`); there is **no auto-deploy for the TCP path
-yet** — add a `deploy-aws-tcp.yml` workflow (mirroring `deploy-cf-tcp.yml`)
-as a follow-up when the TCP path is ready for continuous staging.
-
----
-
 ## 6. Operational model & limits
 
 The NLB + Lambda streaming model has hard platform limits the wss path
@@ -230,6 +212,18 @@ State lifecycle is identical to the wss path: the **sweeper** Lambda
 no-PONG. Both cover TCP connections because the `connId` lives in the
 same `Connections` table.
 
+**Per-IP new-flow rate limit.** The NLB path has no `$connect` event —
+flow establishment IS the first chunk — so the `perIpConnectionRate`
+budget is enforced inside `handleNlbStream`: the source IP (from
+`x-forwarded-for`) is counted against the same `sourceIp-connectedSince`
+GSI the wss `$connect` gate consults, and over-budget flows receive
+`429` with no row written. Only establishment is budgeted: every
+subsequent chunk of an established flow is also an invocation, and
+rate-limiting those would starve an active IRC session. The knobs are
+the shared `PER_IP_CONNECTION_RATE_MAX` / `PER_IP_CONNECTION_RATE_WINDOW_MS`
+env vars (default 5 per 60 s; see `AWS-Deployment.md` §7.8 for the
+three-layer throttling model).
+
 ---
 
 ## 7. Configuration reference
@@ -240,17 +234,20 @@ TCP-specific ones:
 | Knob (context var / prop)     | Purpose                                          | Default when omitted       |
 |-------------------------------|--------------------------------------------------|----------------------------|
 | `tcpTlsDomainName`            | Domain for the ACM cert + NLB TLS listener.      | *(TCP path not provisioned)* |
-| `environmentName`             | Env prefix for table names + stack id.           | `staging`                  |
 
 The NLB handler Lambda inherits the **same** identity/table knobs as the
-wss handler (`serverName`, `networkName`, `motd`, `environmentName`),
-injected in `aws-stack.ts`:
+wss handler (`serverName`, `networkName`, `motd`), injected in
+`aws-stack.ts`:
 
 - `SERVER_NAME`, `NETWORK_NAME`, `MOTD` (read by the shared
   `config-loader.ts`).
 - `MANAGEMENT_URL` — the wss stage's callback URL, so cross-connection
-  fanout reaches recipients on either transport.
-- `<TABLE>_TABLE` for each of the five tables (prefixed by environment).
+  fanout reaches recipients on either transport. The NLB handler's
+  execution role also carries `execute-api:ManageConnections` on the
+  wss stage (`stage.grantManagementApiAccess(nlbHandler)` in
+  `aws-stack.ts`, asserted by a synth-time test) — without it every
+  cross-transport `postToConnection` fails with 403.
+- `<TABLE>_TABLE` for each of the five tables (bare logical ids).
 
 The Lambda handler entry is the same file
 (`packages/aws-adapter/src/handlers/index.ts`); esbuild tree-shakes to
@@ -259,7 +256,10 @@ excluded from the bundle (ships with the runtime).
 
 There are **no TCP-specific DynamoDB tables** — the existing `Connections`
 table gains a `transportBuffer` string attribute (SET when non-empty,
-REMOVE when empty) on rows whose `connectionId` starts with `nlb-`.
+REMOVE when empty) on rows whose `connectionId` starts with `nlb-`, plus
+the `sourceIp` attribute + `sourceIp-connectedSince` GSI shared with the
+wss path's per-IP admission gates (both transports stamp the flow/client
+IP at establishment).
 
 ---
 
@@ -325,6 +325,22 @@ then fanout uses `ApiGatewayManagementApi.postToConnection`, which works
 for both transports. If `MANAGEMENT_URL` is unset, `managementApi` is
 `null` and cross-connection sends are silent no-ops.
 
+The mirror-image symptom — a TCP client's messages never reaching wss
+recipients — is an IAM problem, not a push problem: the NLB handler's
+role must carry `execute-api:ManageConnections` on the wss stage
+(`stage.grantManagementApiAccess(nlbHandler)`; synth-time asserted in
+`apps/aws-stack/tests/stack.test.ts`). Without the grant the NLB
+handler's `postToConnection` calls fail with 403 and the delivery is
+silently dropped. Verify manually after a deploy:
+
+```bash
+# 1. Connect over wss (e.g. the web client) and JOIN #fanout-check.
+# 2. Connect over TLS :6697 (openssl one-liner in §11) and JOIN #fanout-check.
+# 3. PRIVMSG from the TCP side — the wss client must receive it, and vice
+#    versa. A silent drop + 403 in the IrcNlbHandler CloudWatch logs
+#    means the ManageConnections grant is missing.
+```
+
 ### 9.4 Lurkers get disconnected after a few minutes
 
 The NLB idle timeout. A receiving-only client sends no chunks, so the
@@ -372,25 +388,19 @@ RFC-compliant clients that need it.
 ## 11. Quick reference
 
 ```bash
-# Staging (TCP+TLS added alongside wss)
-pnpm deploy:aws:staging -- \
-  -c environmentName=staging \
-  -c tcpTlsDomainName=irc-staging.example.com
+# Deploy (TCP+TLS added alongside wss)
+pnpm deploy:aws -- \
+  -c tcpTlsDomainName=irc.example.com
 
 # Read the TCP endpoint from stack outputs
 aws cloudformation describe-stacks \
-  --stack-name IrcAwsStack-staging \
+  --stack-name IrcAwsStack \
   --query 'Stacks[0].Outputs[?OutputKey==`TcpConnectUrl`].OutputValue' \
   --output text
 
 # Smoke over TLS
 printf 'NICK smoke\r\nUSER smoke 0 * :Smoke\r\nQUIT :smoke\r\n' | \
-  openssl s_client -connect irc-staging.example.com:6697 -quiet | grep '001'
-
-# Production (manual)
-pnpm deploy:aws:prod -- \
-  -c environmentName=production \
-  -c tcpTlsDomainName=irc.example.com
+  openssl s_client -connect irc.example.com:6697 -quiet | grep '001'
 
 # Tests (synth-time assertions for the NLB path)
 pnpm --filter @serverless-ircd/aws-stack test

package/docs/Chat-History.md

@@ -0,0 +1,55 @@
+# Chat History (`draft/chathistory`)
+
+The server implements the IRCv3 [`draft/chathistory`](https://ircv3.net/specs/extensions/chathistory)
+extension: a client that negotiates the `draft/chathistory` cap may query
+stored backlog (`LATEST` / `BEFORE` / `AFTER` / `AROUND` / `BETWEEN` /
+`TARGETS`) and receives the matching messages wrapped in a
+`BATCH chathistory <target>` frame, each replay line carrying its original
+`@time=…` and `msgid=…` tags.
+
+## Query limit ceiling
+
+Every client-supplied `limit` is **silently capped** at a deployment
+ceiling before it reaches the `MessageStore`:
+
+- `CHATHISTORY LATEST #chan * 999999999` returns at most
+  `chathistory.maxLimit` messages (default **100**) — the oversized value
+  never reaches the store, so a future higher-capacity backend cannot be
+  tricked into materializing a huge result set.
+- The cap is silent: the client receives up to the ceiling worth of
+  replay lines and no error. Requests below the ceiling pass through
+  unchanged; a request for exactly the ceiling is honored in full.
+- When the client omits the limit, the server default (50) applies —
+  also bounded by the ceiling, so a deployment that lowers
+  `chathistory.maxLimit` below 50 caps the default too.
+- A limit that is not a non-negative integer (e.g. `abc`, `-5`) is
+  rejected with `461 ERR_NEEDMOREPARAMS` (Invalid parameters), unchanged
+  by the ceiling.
+
+### Configuration
+
+| Knob                        | Default | Notes                                          |
+|-----------------------------|---------|------------------------------------------------|
+| `chathistory.maxLimit`      | `100`   | Positive integer; per-`CHATHISTORY`-query cap. |
+
+The knob lives in the server config (parsed by `ServerConfigSchema`), so
+any adapter's config source can set it:
+
+```json
+{
+  "serverName": "irc.example.com",
+  "networkName": "ExampleNet",
+  "chathistory": { "maxLimit": 250 }
+}
+```
+
+Omitting the `chathistory` section entirely inherits the default of 100.
+
+## Related
+
+- JOIN auto-playback (`chatHistoryPlaybackLimit`, default 50) is a
+  separate knob covering the backlog replayed on JOIN; see
+  `packages/irc-core/src/config.ts`.
+- `draft/read-marker` integration: `CHATHISTORY BEFORE` without an
+  explicit pivot falls back to the connection's last-read marker; see
+  `docs/PlanExtensions.md`.