serverless-ircd 0.7.0 → 0.9.0

package/apps/local-cli/tests/ws-subprotocol.test.ts

@@ -171,6 +171,20 @@ describe('local-cli IRCv3 WebSocket subprotocol', () => {
     await client.close();
   });
 
+  it('falls back to legacy framing when only unsupported protocols are offered', async () => {
+    // `selectSubprotocol` returns undefined for an all-unsupported offer, so
+    // `handleProtocols` returns false and the ws library completes the
+    // handshake with no negotiated subprotocol. Exercises the
+    // `?? false` fallback in handleProtocols. The offering client then
+    // aborts ("Server sent no subprotocol"), which is expected — the
+    // server-side branch is what this covers.
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, ['chat']);
+    client.ws.on('error', () => {
+      // Expected: server returned no subprotocol for an all-unsupported offer.
+    });
+    await expect(client.opened()).rejects.toThrow(/no subprotocol/iu);
+  });
+
   it('completes registration with one IRC message per WebSocket message (text mode)', async () => {
     const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
     await client.opened();
@@ -260,3 +274,81 @@ describe('local-cli IRCv3 WebSocket subprotocol', () => {
     });
   }
 });
+
+describe('local-cli WebSocket — transport seams', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'seam.example.com',
+      networkName: 'SeamNet',
+    });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('logs a spec-mode actor failure without crashing the server', async () => {
+    // Register normally first so the connection has a nick, then swap the
+    // runtime send to throw — the next inbound message's dispatch rejects
+    // inside receiveTextFrame and the spec-mode `.catch` (server.ts:453)
+    // routes it to logError instead of crashing the server.
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    await client.send('NICK specErr');
+    await client.send('USER specErr 0 * :Spec Err');
+    await client.waitFor((l) => l.startsWith(':seam.example.com 001 '));
+
+    const original = server.runtime.send.bind(server.runtime);
+    server.runtime.send = async () => {
+      throw new Error('synthetic spec send failure');
+    };
+    try {
+      // PING dispatches a Send effect → synthetic throw → actor catch.
+      await client.send('PING :will-throw');
+      await new Promise((r) => setTimeout(r, 60));
+    } finally {
+      server.runtime.send = original;
+    }
+
+    // The server must still serve fresh spec-mode connections.
+    const next = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await next.opened();
+    await next.send('NICK specRecover');
+    await next.send('USER specRecover 0 * :Spec Recover');
+    await next.waitFor((l) => l.startsWith(':seam.example.com 001 '), 2_000);
+    await next.close();
+    await client.close();
+  });
+
+  it('drops an outbound send to a WebSocket that is no longer OPEN', async () => {
+    // Register, then transition the server-side ws to CLOSING. The runtime
+    // still tracks the connection until the 'close' event fires on a later
+    // tick, so a synchronous dispatch hits the `ws.readyState !== OPEN`
+    // guard and returns before calling ws.send (server.ts:423).
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    await client.send('NICK dropSend');
+    await client.send('USER dropSend 0 * :Drop');
+    await client.waitFor((l) => l.startsWith(':seam.example.com 001 '));
+
+    const connId = await server.runtime.lookupNick('dropSend');
+    expect(connId).not.toBeNull();
+    const serverWs = [...server.testSockets].find((ws) => ws.readyState === WebSocket.OPEN);
+    expect(serverWs).toBeDefined();
+    serverWs?.close();
+    // Synchronous dispatch before the 'close' cleanup runs: the send handler
+    // must observe readyState !== OPEN and no-op without throwing.
+    await expect(
+      server.runtime.send(connId as string, [{ text: ':seam NOTICE dropSend :dropped' }]),
+    ).resolves.toBeUndefined();
+
+    await new Promise<void>((resolve) => {
+      client.ws.once('close', () => resolve());
+      client.ws.close();
+    });
+  });
+});

package/apps/web/landing/index.html

@@ -4,8 +4,9 @@
 
   Served at `/` by the Worker `[assets]` binding (apps/cf-worker/wrangler.toml).
   The build (`scripts/build.mjs`) copies this file verbatim to `dist/index.html`.
-  The Kiwi IRC SPA lives at `/app/`; this page links through to it plus the
-  project docs and source repo. Pure static HTML + inline CSS, no JavaScript.
+  The Kiwi IRC SPA lives at `/webclient/`; the rendered docs at `/docs/`
+  (built from the `docs/` submodule); this page links through to both plus
+  the source repo. Pure static HTML + inline CSS, no JavaScript.
 -->
 <html lang="en">
   <head>
@@ -135,6 +136,113 @@
         border-radius: 4px;
         font-size: 0.9em;
       }
+      pre {
+        font-family: var(--mono);
+        background-color: var(--surface);
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        padding: 14px 16px;
+        margin: 12px 0;
+        overflow-x: auto;
+        line-height: 1.5;
+        font-size: 0.88rem;
+      }
+      pre code {
+        background: none;
+        border: none;
+        padding: 0;
+        font-size: inherit;
+      }
+      section.connect {
+        margin: 36px 0 8px;
+        padding: 24px 0;
+        border-top: 1px solid var(--border);
+      }
+      section.connect h2 {
+        margin: 0 0 12px;
+        font-size: 1.4rem;
+        letter-spacing: -0.01em;
+      }
+      section.connect h3 {
+        margin: 22px 0 6px;
+        font-size: 1.08rem;
+        color: var(--accent-hover);
+      }
+      section.connect p {
+        margin: 8px 0;
+        color: var(--text);
+      }
+      section.connect p.lead {
+        color: var(--muted);
+      }
+      section.connect .note {
+        color: var(--muted);
+        font-size: 0.92rem;
+      }
+      section.connect .cta {
+        margin: 14px 0;
+      }
+      /* Client picker — pure CSS, no JavaScript. Radio inputs hold the
+         selected tab; the labels are the visible buttons arranged in a
+         horizontal row; `:checked ~` reveals the matching panel and
+         highlights its label. See build-smoke "works without JavaScript". */
+      .client-tabs {
+        margin: 8px 0 4px;
+      }
+      .client-tabs > input[type="radio"] {
+        position: absolute;
+        opacity: 0;
+        pointer-events: none;
+      }
+      .client-tabs .tablist {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+        margin-bottom: 16px;
+      }
+      .client-tabs .tablist label {
+        padding: 10px 16px;
+        cursor: pointer;
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        background-color: var(--surface);
+        color: var(--muted);
+        font-weight: 600;
+        font-size: 0.95rem;
+        -webkit-tap-highlight-color: transparent;
+        transition: border-color 0.15s, color 0.15s, background-color 0.15s;
+      }
+      .client-tabs .tablist label:hover {
+        border-color: var(--accent);
+        color: var(--text);
+      }
+      .client-tabs .panel {
+        display: none;
+      }
+      .client-tabs .panel h3 {
+        margin-top: 0;
+      }
+      #tab-web:checked ~ .tablist label[for="tab-web"],
+      #tab-weechat:checked ~ .tablist label[for="tab-weechat"],
+      #tab-hexchat:checked ~ .tablist label[for="tab-hexchat"],
+      #tab-irccloud:checked ~ .tablist label[for="tab-irccloud"] {
+        background-color: var(--bg);
+        color: var(--accent-hover);
+        border-color: var(--accent);
+      }
+      #tab-web:focus-visible ~ .tablist label[for="tab-web"],
+      #tab-weechat:focus-visible ~ .tablist label[for="tab-weechat"],
+      #tab-hexchat:focus-visible ~ .tablist label[for="tab-hexchat"],
+      #tab-irccloud:focus-visible ~ .tablist label[for="tab-irccloud"] {
+        outline: 2px solid var(--accent);
+        outline-offset: 2px;
+      }
+      #tab-web:checked ~ #panel-web,
+      #tab-weechat:checked ~ #panel-weechat,
+      #tab-hexchat:checked ~ #panel-hexchat,
+      #tab-irccloud:checked ~ #panel-irccloud {
+        display: block;
+      }
       .links {
         margin-top: 28px;
         padding: 20px 0;
@@ -170,7 +278,7 @@
     <header>
       <div class="container">
         <h1>Serverless<span class="irc">IRCd</span></h1>
-        <p>A serverless IRC daemon. One TypeScript core, two serverless substrates.</p>
+        <p>IRC daemon with a serverless deployment model.</p>
       </div>
     </header>
 
@@ -178,28 +286,141 @@
       <div class="container">
         <p>
           ServerlessIRCd is an IRC server where the protocol logic lives in a
-          pure, platform-agnostic core, and two thin adapters run it on
-          <strong>Cloudflare Workers</strong> (Durable Objects) or
+          platform-agnostic TypeScript core. Two adapters run that core on
+          <strong>Cloudflare Workers</strong> (Durable Objects) and
           <strong>AWS</strong> (API Gateway WebSockets + Lambda + DynamoDB).
-          The same code, unchanged, on both.
         </p>
 
         <ul class="features">
-          <li>Pure-reducer protocol core — every command is a trivial unit test</li>
-          <li>Dual transport: WebSocket <em>and</em> <code>irc+tls</code> on port 6697</li>
-          <li>Full IRCv3 surface: message-tags, chathistory, SASL, labeled-response, and more</li>
-          <li>Authoritative state in one place per datum — races are structurally impossible</li>
+          <li>Reducer-based protocol core: each command is a pure function</li>
+          <li>WebSocket and <code>irc+tls</code> (port 6697) transports</li>
+          <li>IRCv3 extensions: message-tags, chathistory, SASL, labeled-response</li>
+          <li>Per-datum authoritative state held in a single location</li>
         </ul>
 
         <div class="cta">
-          <a class="primary" href="/app/">Launch Web Client</a>
-          <a class="secondary" href="docs/">Read the Docs</a>
+          <a class="primary" href="/webclient/">Launch Web Client</a>
         </div>
 
+        <section class="connect">
+          <h2>Connect</h2>
+          <p class="lead">
+            ServerlessIRCd speaks IRC over secure WebSocket
+            (<code>wss://</code>, port <code>443</code>) as its primary
+            transport, and optionally raw <code>irc+tls</code> on port
+            <code>6697</code>. Replace <code>irc.example.com</code> with your
+            deployed Worker hostname in the snippets below. This page is
+            static and identical across staging and prod.
+          </p>
+
+          <div class="client-tabs">
+            <input type="radio" name="client-tab" id="tab-web" checked />
+            <input type="radio" name="client-tab" id="tab-weechat" />
+            <input type="radio" name="client-tab" id="tab-hexchat" />
+            <input type="radio" name="client-tab" id="tab-irccloud" />
+
+            <div
+              class="tablist"
+              role="tablist"
+              aria-label="IRC client connect instructions"
+            >
+              <label for="tab-web" class="tab" role="tab">Web client</label>
+              <label for="tab-weechat" class="tab" role="tab">WeeChat</label>
+              <label for="tab-hexchat" class="tab" role="tab"
+                >HexChat / irssi</label
+              >
+              <label for="tab-irccloud" class="tab" role="tab"
+                >IRCCloud / TheLounge</label
+              >
+            </div>
+
+            <div
+              class="panel"
+              id="panel-web"
+              role="tabpanel"
+              aria-labelledby="tab-web"
+            >
+              <p>
+                <code>wss</code> on port <code>443</code>, same origin as this
+                page. No client install or bridge required.
+              </p>
+              <div class="cta">
+                <a class="primary" href="/webclient/">Launch Web Client</a>
+              </div>
+            </div>
+
+            <div
+              class="panel"
+              id="panel-weechat"
+              role="tabpanel"
+              aria-labelledby="tab-weechat"
+            >
+              <p>
+                Connect over <code>wss</code> (port <code>443</code>) using the
+                snippet below, or directly over <code>irc+tls</code> on port
+                <code>6697</code> when the TCP+TLS surface is deployed.
+              </p>
+              <pre><code>/server add ircd irc.example.com/443
+/set irc.server.ircd.ssl on
+/connect ircd
+/join #test</code></pre>
+              <p class="note">
+                For the <code>irc+tls :6697</code> path, swap the port above for
+                <code>6697</code>. The TCP surface is a separate deployment
+                (Cloudflare Spectrum + Container); see the
+                <a
+                  href="https://gitea.com/ServerlessIRCd/ServerlessIRCd/wiki/Cloudflare-TCP-Deployment"
+                  >Cloudflare TCP Deployment Guide</a
+                >.
+              </p>
+            </div>
+
+            <div
+              class="panel"
+              id="panel-hexchat"
+              role="tabpanel"
+              aria-labelledby="tab-hexchat"
+            >
+              <p>
+                These TCP-only IRC clients do not support WebSocket natively.
+                Use <code>tools/tcp-ws-forwarder</code> to bridge them: it
+                listens on a local TCP port and forwards each IRC line over
+                <code>wss</code> to the Worker, negotiating the
+                <code>binary.ircv3.net</code> subprotocol upstream.
+              </p>
+              <pre><code>pnpm --filter tcp-ws-forwarder start \
+  --target wss://irc.example.com/ --listen-port 16667</code></pre>
+              <p class="note">
+                Then point HexChat / irssi at <code>127.0.0.1:16667</code>
+                (TLS off &mdash; the bridge is local). Bridging instructions
+                are in the
+                <a
+                  href="https://gitea.com/ServerlessIRCd/ServerlessIRCd/wiki/WebClientGuide"
+                  >Web Client Guide</a
+                >.
+              </p>
+            </div>
+
+            <div
+              class="panel"
+              id="panel-irccloud"
+              role="tabpanel"
+              aria-labelledby="tab-irccloud"
+            >
+              <p>
+                Both support WebSocket natively. Add a network pointing at
+                <code>wss://irc.example.com/</code> (port <code>443</code>, TLS
+                on); no bridge required.
+              </p>
+            </div>
+          </div>
+        </section>
+
         <div class="links">
-          <a href="https://github.com/fowlmouth/ServerlessIRCd">Source Code (GitHub)</a>
-          <a href="https://github.com/fowlmouth/ServerlessIRCd/issues">Issue Tracker</a>
-          <a href="/app/">Web IRC Client</a>
+          <a href="/docs/">Docs</a>
+          <a href="https://gitea.com/ServerlessIRCd/ServerlessIRCd">Source Code (Gitea)</a>
+          <a href="https://gitea.com/ServerlessIRCd/ServerlessIRCd/issues">Issue Tracker</a>
+          <a href="/webclient/">Web IRC Client</a>
         </div>
       </div>
     </main>
@@ -208,7 +429,7 @@
       <div class="container">
         <p>
           ServerlessIRCd &middot;
-          <a href="https://github.com/fowlmouth/ServerlessIRCd">GitHub</a> &middot;
+          <a href="https://gitea.com/ServerlessIRCd/ServerlessIRCd">Gitea</a> &middot;
           BSD-3-Clause License
         </p>
       </div>

package/apps/web/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@serverless-ircd/web",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "private": true,
-  "description": "Web client workspace: Kiwi IRC SPA served at /app/ and project landing page at /",
+  "description": "Web client workspace: Kiwi IRC SPA served at /webclient/ and project landing page at /",
   "license": "BSD-3-Clause",
   "type": "module",
   "scripts": {
@@ -21,6 +21,7 @@
   "devDependencies": {
     "@types/node": "^26.1.1",
     "@vitest/coverage-v8": "^4.1.0",
+    "marked": "^18.0.9",
     "rimraf": "^6.0.0",
     "typescript": "^5.6.0",
     "vitest": "^4.1.0"

package/apps/web/scripts/build.mjs

@@ -5,17 +5,22 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveConfigFile } from '../src/build-env.ts';
 import { parseKiwiConfig } from '../src/config-schema.ts';
+import { buildDocs } from '../src/render-docs.ts';
 
 const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const upstream = path.resolve(pkgRoot, 'upstream');
 const dist = path.resolve(pkgRoot, 'dist');
-const appDist = path.join(dist, 'app');
+const appDist = path.join(dist, 'webclient');
 const staticDir = path.join(pkgRoot, 'static');
+// The `docs/` submodule lives at the monorepo root (two levels up from
+// apps/web). Rendered to dist/docs/ by the docs build step (see step 6).
+const docsSrc = path.resolve(pkgRoot, '..', '..', 'docs');
+const docsDist = path.join(dist, 'docs');
 
-// The SPA is served at /app/ on the Worker (the [assets] binding arrives in a
-// later ticket). All hashed asset URLs must be /app/-prefixed so they load
-// from /app/static/... rather than /static/... (which would 404 at root).
-const PUBLIC_PATH = '/app/';
+// The SPA is served at /webclient/ on the Worker (the [assets] binding serves
+// `dist/`). All hashed asset URLs must be /webclient/-prefixed so they load
+// from /webclient/static/... rather than /static/... (which would 404 at root).
+const PUBLIC_PATH = '/webclient/';
 
 // Yarn runs from a pnpm lifecycle script. Kiwi v1.7.1's package.json has no
 // `packageManager` field, so yarn classic walks up and finds the workspace
@@ -44,16 +49,32 @@ if (!existsSync(upstream)) {
   );
 }
 
+// The `docs/` submodule must be checked out — step 6 renders every docs/*.md
+// to dist/docs/. Mirrors the Kiwi upstream guard above so a stale/partial
+// submodule checkout fails loudly with the recovery command instead of
+// producing an empty docs/ section on the deployed site.
+if (!existsSync(docsSrc)) {
+  throw new Error(
+    `Docs submodule missing at ${docsSrc}. Run \`git submodule update --init docs\` first.`,
+  );
+}
+
 // 1. Install upstream deps. Kiwi ships a yarn.lock; --frozen-lockfile gives a
-//    reproducible tree. Contributors get yarn via `corepack enable`.
-if (!existsSync(path.join(upstream, 'node_modules'))) {
+//    reproducible tree. Contributors get yarn via `corepack enable`. The
+//    guard checks for the actual binary the build invokes, not just the
+//    `node_modules` directory — a stale/partial install (interrupted, or
+//    populated by a foreign package manager that skipped `.bin/` linking)
+//    leaves the directory present but `vue-cli-service` unresolvable, which
+//    would otherwise crash the build at step 2 with a confusing exit 127.
+const vueCliBin = path.join(upstream, 'node_modules', '.bin', 'vue-cli-service');
+if (!existsSync(vueCliBin)) {
   runYarn(['install', '--frozen-lockfile', '--ignore-engines']);
 }
 
-// 2. Build with publicPath=/app/. Upstream pins publicPath:'' (relative); we
-//    temporarily patch vue.config.js so webpack emits /app/-prefixed asset
-//    URLs and the runtime public_path matches the mount point. Restored in
-//    `finally` so the submodule stays clean.
+// 2. Build with publicPath=/webclient/. Upstream pins publicPath:'' (relative);
+//    we temporarily patch vue.config.js so webpack emits /webclient/-prefixed
+//    asset URLs and the runtime public_path matches the mount point. Restored
+//    in `finally` so the submodule stays clean.
 const vueConfigPath = path.join(upstream, 'vue.config.js');
 const originalVueConfig = await readFile(vueConfigPath, 'utf8');
 try {
@@ -67,14 +88,15 @@ try {
   await writeFile(vueConfigPath, originalVueConfig);
 }
 
-// 3. Copy the built SPA into dist/app/.
+// 3. Copy the built SPA into dist/webclient/.
 await rm(appDist, { recursive: true, force: true });
 await mkdir(appDist, { recursive: true });
 await cp(path.join(upstream, 'dist'), appDist, { recursive: true });
 
 // 3b. Webpack applies publicPath to the bundles it emits, but template-hardcoded
 //     refs (e.g. the favicon) stay relative. Prefix every bare `static/...`
-//     reference so all asset URLs resolve to /app/static/... when served at /app/.
+//     reference so all asset URLs resolve to /webclient/static/... when served
+//     at /webclient/.
 const indexDest = path.join(appDist, 'index.html');
 let indexHtml = await readFile(indexDest, 'utf8');
 indexHtml = indexHtml.replace(/((?:src|href)=["'])(static\/)/g, `$1${PUBLIC_PATH}$2`);
@@ -109,8 +131,8 @@ await writeFile(
 
 // 5. Landing page: copy the static landing page (landing/index.html) to
 //    dist/index.html so the Worker `[assets]` binding serves it at `/`. Pure
-//    static HTML + inline CSS (no JS); links to /app/ (the SPA), docs/, and
-//    the source repo.
+//    static HTML + inline CSS (no JS); links to /webclient/ (the SPA),
+//    /docs/ (the rendered docs built in step 6), and the source repo.
 await mkdir(dist, { recursive: true });
 const landingSrc = path.join(pkgRoot, 'landing', 'index.html');
 if (!existsSync(landingSrc)) {
@@ -120,6 +142,14 @@ if (!existsSync(landingSrc)) {
 }
 await cp(landingSrc, path.join(dist, 'index.html'));
 
+// 6. Docs: render every docs/*.md to standalone HTML under dist/docs/ so the
+//    Worker `[assets]` binding serves them at /docs/<name>.html (and /docs/
+//    for the index — Home.md becomes index.html). Requires the `docs/`
+//    submodule (guarded at step 0). Zero Worker changes — the existing
+//    [assets] binding already serves dist/ with not_found_handling = "none".
+const docsResult = await buildDocs({ srcDir: docsSrc, outDir: docsDist });
+
 console.log(
-  `Kiwi SPA built -> dist/app/ (publicPath=${PUBLIC_PATH}, config=${configFileName}, env=${configEnv})`,
+  `Kiwi SPA built -> dist/webclient/ (publicPath=${PUBLIC_PATH}, config=${configFileName}, env=${configEnv})`,
 );
+console.log(`Docs rendered -> dist/docs/ (${docsResult.emitted.length} pages, index=index.html)`);

package/apps/web/src/build-env.ts

@@ -4,7 +4,7 @@
  * Extracted from the build script so the `--env` → config-file mapping is
  * unit-testable without running the (slow) Kiwi upstream build. The build
  * script delegates here and then validates the selected file against
- * {@link parseKiwiConfig} before baking it into `dist/app/static/config.json`.
+ * {@link parseKiwiConfig} before baking it into `dist/webclient/static/config.json`.
  */
 
 /** argv values accepted by `--env`; mapped to a `static/config.<env>.json` file. */

package/apps/web/src/config-schema.ts

@@ -4,16 +4,16 @@
  * supply to drive the embedded Kiwi SPA.
  *
  * `build.mjs` runs {@link parseKiwiConfig} against the selected env config
- * before baking it into `dist/app/static/config.json`, so a malformed config
- * fails the build with a readable aggregated error rather than shipping a
- * broken SPA. The schema only models the fields ServerlessIRCd cares about
- * (server, port, channel, WS path); the rest of Kiwi's surface is passed
- * through untouched.
+ * before baking it into `dist/webclient/static/config.json`, so a malformed
+ * config fails the build with a readable aggregated error rather than
+ * shipping a broken SPA. The schema only models the fields ServerlessIRCd
+ * cares about (server, port, channel, WS path); the rest of Kiwi's surface
+ * is passed through untouched.
  *
  * Hosting layout reminder:
  *   - The Worker's WebSocket endpoint is at `/` (root), so Kiwi's
  *     `startupOptions.path` — when supplied — MUST be `/`.
- *   - The SPA itself is served from `/app/` by the Worker `[assets]`
+ *   - The SPA itself is served from `/webclient/` by the Worker `[assets]`
  *     binding (a separate concern handled by the public-path patch in
  *     `build.mjs`); that is independent of the WS path modelled here.
  */