serverless-ircd 0.7.0 → 0.8.0

package/docs/WebClientGuide.md

@@ -1,10 +1,11 @@
 # Web Client Guide
 
 End-to-end contributor/operator doc for the ServerlessIRCd web client: a
-vendored **Kiwi IRC** SPA served at `/app/` and a static project landing
-page served at `/` by the Cloudflare Worker. The browser opens a native
-`wss://` WebSocket straight to the Worker's existing IRC-over-WebSocket
-endpoint — no proxy, gateway, or transport adaptation in the hot path.
+vendored **Kiwi IRC** SPA served at `/webclient/` and a static project
+landing page served at `/` by the Cloudflare Worker. The browser opens a
+native `wss://` WebSocket straight to the Worker's existing
+IRC-over-WebSocket endpoint — no proxy, gateway, or transport adaptation
+in the hot path.
 
 Cross-reference: `PLAN.md` §6.1 (CF mapping), `docs/PlanWebClient.md`
 (design), `docs/Cloudflare-Deployment-Guide.md` (Worker deploy),
@@ -23,7 +24,7 @@ following only this doc.
    ┌──────────────────────────────────────────────────────────────┐
    │  Browser                                                     │
    │    GET /            → landing page (project front door)      │
-   │    GET /app/        → Kiwi IRC SPA (index.html + JS bundle)  │
+   │    GET /webclient/    → Kiwi IRC SPA (index.html + JS bundle)  │
    │    wss://.../       → one IRC message per WS text frame      │
    └──────────────────────────────────────────────────────────────┘
            │                                │
@@ -48,8 +49,8 @@ Path layout on the Worker:
 | Path       | Served by                | Content                          |
 |------------|--------------------------|----------------------------------|
 | `/`        | `[assets]` binding       | `dist/index.html` (landing page) |
-| `/app/`    | `[assets]` binding       | `dist/app/index.html` (Kiwi SPA) |
-| `/app/static/...` | `[assets]` binding | Kiwi JS/CSS/themes + baked config |
+| `/webclient/`    | `[assets]` binding       | `dist/webclient/index.html` (Kiwi SPA) |
+| `/webclient/static/...` | `[assets]` binding | Kiwi JS/CSS/themes + baked config |
 | `/health`  | `worker.ts` handler      | Plaintext liveness string        |
 | `/` (WS upgrade) | `worker.ts` → `ConnectionDO` | IRC session               |
 
@@ -94,8 +95,8 @@ pnpm install
 pnpm --filter web build:staging
 #    Equivalent: pnpm --filter @serverless-ircd/web build:staging
 #    → apps/web/dist/index.html        (landing page)
-#    → apps/web/dist/app/index.html    (Kiwi SPA)
-#    → apps/web/dist/app/static/config.json  (baked, env-specific)
+#    → apps/web/dist/webclient/index.html    (Kiwi SPA)
+#    → apps/web/dist/webclient/static/config.json  (baked, env-specific)
 
 # 4. Build the rest of the workspace (Worker imports compiled dist/).
 pnpm build
@@ -103,7 +104,7 @@ pnpm build
 # 5. Serve everything locally (Worker + SPA + landing page).
 pnpm --filter @serverless-ircd/cf-worker dev
 #    → http://localhost:8787/      landing page
-#    → http://localhost:8787/app/  Kiwi SPA
+#    → http://localhost:8787/webclient/  Kiwi SPA
 #    → ws://localhost:8787/        IRC-over-WebSocket (same endpoint)
 
 # 6. Deploy staging (Worker + assets in one command).
@@ -111,9 +112,9 @@ pnpm deploy:cf:staging
 #    → wrangler deploy --env staging
 ```
 
-Open `http://localhost:8787/app/` in a browser — Kiwi boots, reads
-`/app/static/config.json`, and opens a `wss://` (or `ws://` in local
-dev) connection to the same origin.
+Open `http://localhost:8787/webclient/` in a browser — Kiwi boots, reads
+`/webclient/static/config.json`, and opens a `wss://` (or `ws://` in
+local dev) connection to the same origin.
 
 > **Forgot the submodule?** `apps/web/scripts/build.mjs` fails fast:
 > `Kiwi upstream missing at .../upstream. Run
@@ -128,7 +129,7 @@ The build is an orchestrated layering over the upstream Kiwi build —
 
 ### 4.1 Per-environment config matrix
 
-| `pnpm ...` command | Reads | Bakes into `dist/app/static/config.json` |
+| `pnpm ...` command | Reads | Bakes into `dist/webclient/static/config.json` |
 |---|---|---|
 | `--filter web build` | `static/config.json` | default (staging-shaped) config |
 | `--filter web build:staging` | `static/config.staging.json` | staging config |
@@ -149,17 +150,17 @@ malformed config fails the build rather than shipping a broken SPA.
    Node ≥ 17 the OpenSSL legacy provider is enabled for webpack 5's md4
    hashing.
 3. **Patch `upstream/vue.config.js`** `publicPath: ''` →
-   `publicPath: '/app/'`, run `yarn build`, then **restore** the file
-   in `finally` so the submodule stays clean. This is why every hashed
-   asset URL comes out `/app/static/js/app.<hash>.js` instead of
-   `static/js/...`, which would 404 at root.
-4. **Copy `upstream/dist/` → `apps/web/dist/app/`.**
+   `publicPath: '/webclient/'`, run `yarn build`, then **restore** the
+   file in `finally` so the submodule stays clean. This is why every
+   hashed asset URL comes out `/webclient/static/js/app.<hash>.js`
+   instead of `static/js/...`, which would 404 at root.
+4. **Copy `upstream/dist/` → `apps/web/dist/webclient/`.**
 5. **Rewrite bare `static/...` refs** in the baked `index.html` (e.g.
    the favicon, which webpack doesn't run through `publicPath`) to
-   `/app/static/...`.
+   `/webclient/static/...`.
 6. **Validate + bake the per-env config**: read
    `static/config.<env>.json`, run `parseKiwiConfig`, re-serialise
-   (stable key order), write to `dist/app/static/config.json`.
+   (stable key order), write to `dist/webclient/static/config.json`.
 7. **Copy the landing page** `landing/index.html` → `dist/index.html`.
 
 Output is reproducible: same checkout + same `--env` → byte-identical
@@ -308,8 +309,8 @@ pnpm --filter @serverless-ircd/cf-worker dev
 Then:
 
 - `http://localhost:8787/` — landing page.
-- `http://localhost:8787/app/` — Kiwi SPA (reads
-  `/app/static/config.json`, opens `ws://localhost:8787/`).
+- `http://localhost:8787/webclient/` — Kiwi SPA (reads
+  `/webclient/static/config.json`, opens `ws://localhost:8787/`).
 - `http://localhost:8787/health` — plaintext liveness.
 
 Smoke the WS path directly (no browser needed):
@@ -403,7 +404,7 @@ deployment; don't change the default config.
 
 The landing page (`apps/web/landing/index.html`) is the project's front
 door: a visitor hitting `/` learns what ServerlessIRCd is and clicks
-through to `/app/` to launch the client. It is intentionally
+through to `/webclient/` to launch the client. It is intentionally
 framework-free (pure HTML + inline CSS, no JS) so it renders without
 JavaScript and costs nothing to serve.
 
@@ -413,16 +414,16 @@ To customise:
   blocks directly. The CSS variables at the top of the `<style>` block
   (`--bg`, `--surface`, `--accent`, …) theme the whole page in one
   place.
-- **Links** — the page links to `/app/` (the SPA), `docs/`, and the
-  source repo. Update the repo URLs and the docs path to match your
-  deployment.
+- **Links** — the page links to `/webclient/` (the SPA), `docs/`, and
+  the source repo. Update the repo URLs and the docs path to match
+  your deployment.
 - **Accessibility** — keep the declared viewport meta tag and the
   no-`<script>` invariant; both are asserted by
   `tests/build-smoke.test.ts`. The build copies the file verbatim to
   `dist/index.html`, so what you author is exactly what is served.
 
 Re-run `pnpm --filter web build` (any `--env`) after edits; the build
-test suite will fail loudly if you accidentally remove the `/app/`
+test suite will fail loudly if you accidentally remove the `/webclient/`
 link, the docs link, or the viewport tag.
 
 ---
@@ -457,7 +458,7 @@ and check the WS upgrade:
   `WEB_ORIGINS` if you're cross-origin, or confirm the SPA and Worker
   are same-origin.
 
-### 10.3 Asset 404s at `/static/...` (instead of `/app/static/...`)
+### 10.3 Asset 404s at `/static/...` (instead of `/webclient/static/...`)
 
 The `publicPath` patch in step 3 of the build didn't take. Confirm
 `upstream/vue.config.js` still contains a `publicPath: ''` literal to
@@ -483,8 +484,8 @@ packages.
 ### 10.6 Build-smoke tests fail in CI but pass locally
 
 The `dist/`-dependent assertions in `tests/build-smoke.test.ts` are
-gated on `existsSync(dist/app/index.html)` and are skipped when the
-SPA hasn't been built. CI runs `pnpm --filter web build` (or
+gated on `existsSync(dist/webclient/index.html)` and are skipped when
+the SPA hasn't been built. CI runs `pnpm --filter web build` (or
 `pnpm build`) before `pnpm --filter web test`, so the assertions fire
 there. If you run `pnpm --filter web test` locally without building,
 only the landing-page source assertions run — that's expected, not a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-ircd",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": false,
   "description": "Serverless IRC daemon with a platform-agnostic core and Cloudflare Workers + AWS adapters",
   "license": "BSD-3-Clause",
@@ -17,7 +17,7 @@
     "typescript": "^5.9.3",
     "vite": "^7.3.6",
     "vitest": "^4.1.10",
-    "@serverless-ircd/aws-adapter": "0.7.0"
+    "@serverless-ircd/aws-adapter": "0.8.0"
   },
   "scripts": {
     "build": "turbo run build",

package/packages/aws-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-adapter",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": true,
   "description": "AWS Lambda + DynamoDB adapter: AwsRuntime implementing IrcRuntime + $connect/$disconnect/$default handlers",
   "license": "BSD-3-Clause",

package/packages/aws-adapter/src/aws-runtime.ts

@@ -57,6 +57,7 @@ import {
   toSnapshot as toConnSnapshot,
 } from '@serverless-ircd/irc-core';
 import type { IrcRuntime } from '@serverless-ircd/irc-server';
+import { decrementConnectionCount } from './connection-counter.js';
 import {
   type MarshalledChannelMember,
   type MarshalledChannelMeta,
@@ -733,6 +734,10 @@ export async function cleanupConnection(
   await dynamo.send(
     new DeleteCommand({ TableName: tables.Connections, Key: { connectionId: connId } }),
   );
+  // Release the admission slot this connection reserved at `$connect`. The
+  // meta counter is best-effort (decrement floors at 0; a missing/zero
+  // counter is a silent no-op), so a drifted count never fails teardown.
+  await decrementConnectionCount(dynamo, tables.Connections);
 
   if (item.nick !== undefined) {
     try {

package/packages/aws-adapter/src/cdk-table-defs.ts

@@ -70,4 +70,10 @@ export const TABLE_DEFS: Record<TableName, TableProps> = {
     partitionKey: { name: 'account', type: AttributeType.STRING },
     billingMode: BillingMode.PAY_PER_REQUEST,
   },
+  Services: {
+    tableName: 'Services',
+    partitionKey: { name: 'pk', type: AttributeType.STRING },
+    sortKey: { name: 'sk', type: AttributeType.STRING },
+    billingMode: BillingMode.PAY_PER_REQUEST,
+  },
 };

package/packages/aws-adapter/src/config-loader.ts

@@ -35,6 +35,14 @@ export interface LambdaConfigEnv {
   CHANNEL_PREFIXES?: string;
   OPER_USER?: string;
   OPER_PASSWORD?: string;
+  /**
+   * Server-password gate. Treat as an AWS secret (Secrets Manager or
+   * SSM `SecureString`); the loader threads it through to
+   * `ServerConfig.serverPassword` so the registration reducer requires
+   * `PASS <value>` (or a SASL-identified connection) before
+   * `001 RPL_WELCOME`. Undefined / empty disables the gate.
+   */
+  SERVER_PASSWORD?: string;
   MAX_CHANNELS_PER_USER?: string;
   MAX_TARGETS_PER_COMMAND?: string;
   NICK_LEN?: string;
@@ -87,6 +95,9 @@ export function buildLambdaConfigInput(env: LambdaConfigEnv): Record<string, unk
       },
     ];
   }
+  if (env.SERVER_PASSWORD !== undefined) {
+    input.serverPassword = env.SERVER_PASSWORD;
+  }
   if (env.MAX_CHANNELS_PER_USER !== undefined) {
     input.maxChannelsPerUser = Number.parseInt(env.MAX_CHANNELS_PER_USER, 10);
   }

package/packages/aws-adapter/src/connection-counter.ts

@@ -0,0 +1,89 @@
+/**
+ * O(1) admission counter for the AWS `$connect` handler.
+ *
+ * Replaces the previous full-table `Scan COUNT` over `Connections` (which
+ * grew linearly with the connection count and made `$connect` latency
+ * spike into the multi-second range). The live connection count is kept in
+ * a single meta row inside the `Connections` table and updated atomically:
+ *
+ *   - `$connect` reserves a slot with {@link incrementConnectionCount}.
+ *   - `$disconnect` / the gone-connection sweeper release a slot with
+ *     {@link decrementConnectionCount} (via `cleanupConnection`).
+ *
+ * The meta row is keyed by the {@link CONNECTION_COUNT_META_ID} sentinel
+ * and deliberately carries **no** `idleSince`, so the sweeper (which only
+ * tears down rows with a stale numeric `idleSince`) skips it; stats and
+ * the sweeper filter this id out of their connection lists.
+ */
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { UpdateCommand } from '@aws-sdk/lib-dynamodb';
+
+/**
+ * Sentinel partition key for the connection-count meta row. Real APIGW
+ * connection ids are opaque alphanumeric tokens, so this `__meta:`-prefixed
+ * value never collides.
+ */
+export const CONNECTION_COUNT_META_ID = '__meta:connectionCount__';
+
+/** Attribute name holding the integer count on the meta row. */
+export const CONNECTION_COUNT_ATTR = 'count';
+
+/**
+ * Atomically reserves one connection slot: increments the counter and
+ * returns the **new** value (i.e. including this reservation). Creates the
+ * meta row on first use via `if_not_exists`.
+ *
+ * Idempotent at the DynamoDB level: a single `UpdateItem` with
+ * `ReturnValues=UPDATED_NEW` is the whole operation — no read-modify-write
+ * loop, so concurrent `$connect` invocations never lose an increment.
+ */
+export async function incrementConnectionCount(
+  dynamo: DynamoDBDocumentClient,
+  tableName: string,
+): Promise<number> {
+  const res = await dynamo.send(
+    new UpdateCommand({
+      TableName: tableName,
+      Key: { connectionId: CONNECTION_COUNT_META_ID },
+      UpdateExpression: 'SET #c = if_not_exists(#c, :zero) + :one',
+      ExpressionAttributeNames: { '#c': CONNECTION_COUNT_ATTR },
+      ExpressionAttributeValues: { ':zero': 0, ':one': 1 },
+      ReturnValues: 'UPDATED_NEW',
+    }),
+  );
+  const updated = res.Attributes as Record<string, unknown> | undefined;
+  const count = updated?.[CONNECTION_COUNT_ATTR];
+  return typeof count === 'number' ? count : 0;
+}
+
+/**
+ * Atomically releases one connection slot: decrements the counter, floored
+ * at 0. The `attribute_exists(count) AND count > :zero` condition makes a
+ * stray decrement (e.g. a sweeper pass after a counter-reset deploy) a
+ * silent no-op instead of driving the count negative.
+ *
+ * Errors are swallowed: the counter is best-effort and self-correcting
+ * (a drifted count only tightens or loosens the admission cap slightly;
+ * it never crashes connection teardown).
+ */
+export async function decrementConnectionCount(
+  dynamo: DynamoDBDocumentClient,
+  tableName: string,
+): Promise<void> {
+  try {
+    await dynamo.send(
+      new UpdateCommand({
+        TableName: tableName,
+        Key: { connectionId: CONNECTION_COUNT_META_ID },
+        UpdateExpression: 'SET #c = #c - :one',
+        ConditionExpression: 'attribute_exists(#c) AND #c > :zero',
+        ExpressionAttributeNames: { '#c': CONNECTION_COUNT_ATTR },
+        ExpressionAttributeValues: { ':zero': 0, ':one': 1 },
+      }),
+    );
+  } catch {
+    // ConditionalCheckFailedException (counter missing / already 0) → no-op.
+    // Any other error is also swallowed: teardown must not fail because the
+    // admission counter drifted.
+  }
+}