transport-io 0.3.0 → 0.5.0

package/README.md

@@ -8,18 +8,17 @@
 Real-time apps over WebTransport. Socket.IO's shape, on a transport with multiple streams
 and datagrams, without Socket.IO's mistakes.
 
-Framing, length prefixes, buffer accumulation and stream lifecycle are hidden. Reliability is
-not: an event declares `reliable` or `unreliable` in the contract, and "this message may be
-dropped" is a property of your data that lives in the type system. The reliable lane is
-carried on QUIC streams, the unreliable lane on QUIC datagrams.
+Framing, length prefixes, buffer accumulation and stream lifecycle are handled for you. An
+event declares `reliable` or `unreliable` in the contract, so "this message may be dropped"
+is visible in the type system. The reliable lane is carried on QUIC streams, the unreliable
+lane on QUIC datagrams.
 
-A request answers with a value or with a **sequence**. `call()` awaits one result;
-`stream()` gives an async iterable, and `break` resets the QUIC stream so the server
-generator's `finally` runs. Cancellation costs no extra API.
+A request answers with a value or with a sequence. `call()` awaits one result. `stream()`
+returns an async iterable, and leaving the loop resets the QUIC stream so the server
+generator's `finally` runs.
 
 **Read [KNOWN-ISSUES.md](https://github.com/transport-io/transport-io/blob/main/KNOWN-ISSUES.md)
-before you start.** It is what this library refuses to do and will not change, plus the one
-measured defect. Full documentation is in the
+before you start.** It lists what this library will not do, and the one measured defect. Full documentation is in the
 [repository README](https://github.com/transport-io/transport-io#readme). The short version:
 
 - **WebTransport only.** No WebSocket fallback, deliberately - a fallback would silently

package/dist/cli/certificate.node.js

@@ -0,0 +1,115 @@
+/**
+ * The certificate `transport-io dev` pins.
+ *
+ * WebTransport will not accept an arbitrary self-signed certificate. It accepts one pinned
+ * by hash, under constraints that are not ours and are easy to get wrong: ECDSA P-256, a
+ * SHA-256 hash, and a total validity of at most 14 days. A newcomer should never learn any
+ * of that, so this module owns all three and the CLI only asks for a usable certificate.
+ *
+ * Fourteen days means expiry is normal operation rather than an error. Every start checks,
+ * and anything expired or expiring within a day is replaced silently. The user finds out
+ * only because a line says the certificate was renewed, and because a browser tab holding
+ * the old hash has to be reloaded.
+ *
+ * Minting shells out to `openssl` because Node cannot issue an X.509 certificate:
+ * `crypto.Certificate` handles SPKAC only, and there is no issuance API. The alternative is
+ * a runtime dependency, and this package has none for the CLI.
+ */
+import { execFileSync } from 'node:child_process';
+import { createHash, createPrivateKey, X509Certificate } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** The spec's ceiling. Not a preference, and not adjustable. */
+export const MAX_VALIDITY_DAYS = 14;
+/**
+ * Replace a certificate with less than this left. A whole day, so a `dev` session started
+ * in the morning cannot expire underneath the person running it before evening.
+ */
+export const RENEW_WITHIN_MS = 24 * 60 * 60 * 1000;
+function openssl(args) {
+    try {
+        execFileSync('openssl', [...args], { stdio: 'pipe' });
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        throw new Error(`openssl failed: ${detail}\n\n` +
+            'transport-io dev mints a short-lived certificate with openssl, because Node cannot ' +
+            'issue one. Install openssl and run this again: `brew install openssl` on macOS, ' +
+            '`apt install openssl` on Debian or Ubuntu.');
+    }
+}
+function readIfUsable(certPath, keyPath) {
+    if (!existsSync(certPath) || !existsSync(keyPath))
+        return undefined;
+    try {
+        const cert = readFileSync(certPath, 'utf8');
+        const privKey = readFileSync(keyPath, 'utf8');
+        const x509 = new X509Certificate(cert);
+        const validTo = new Date(x509.validTo);
+        if (Number.isNaN(validTo.getTime()))
+            return undefined;
+        if (validTo.getTime() - Date.now() < RENEW_WITHIN_MS)
+            return undefined;
+        // The key has to match the certificate, not merely exist. An empty or stale `key.pem`
+        // beside a valid `cert.pem` passed an existence check and was handed to the server,
+        // which then failed to start for a reason no one running `dev` could be expected to
+        // work out. Checking the pair is the only way to catch that here.
+        if (!x509.checkPrivateKey(createPrivateKey(privKey)))
+            return undefined;
+        return {
+            cert,
+            privKey,
+            sha256: new Uint8Array(createHash('sha256').update(x509.raw).digest()),
+            validTo,
+            renewed: false,
+        };
+    }
+    catch {
+        // Corrupt, truncated, or not a certificate. Minting a new one is always the answer.
+        return undefined;
+    }
+}
+/**
+ * Returns a usable certificate, minting one only when there is not already a good one.
+ *
+ * `dir` should be somewhere already ignored by the project's version control, so this never
+ * plants a private key in a commit and never has to edit anyone's `.gitignore`.
+ */
+export function ensureCertificate(dir) {
+    const certPath = join(dir, 'cert.pem');
+    const keyPath = join(dir, 'key.pem');
+    const existing = readIfUsable(certPath, keyPath);
+    if (existing !== undefined)
+        return existing;
+    mkdirSync(dir, { recursive: true });
+    openssl(['ecparam', '-name', 'prime256v1', '-genkey', '-noout', '-out', keyPath]);
+    openssl([
+        'req',
+        '-new',
+        '-x509',
+        '-key',
+        keyPath,
+        '-out',
+        certPath,
+        '-days',
+        String(MAX_VALIDITY_DAYS),
+        '-subj',
+        '/CN=localhost',
+        '-addext',
+        'subjectAltName=DNS:localhost,IP:127.0.0.1',
+    ]);
+    const cert = readFileSync(certPath, 'utf8');
+    const x509 = new X509Certificate(cert);
+    return {
+        cert,
+        privKey: readFileSync(keyPath, 'utf8'),
+        sha256: new Uint8Array(createHash('sha256').update(x509.raw).digest()),
+        validTo: new Date(x509.validTo),
+        renewed: true,
+    };
+}
+/** Whole days left, floored, for the status line. */
+export function daysLeft(validTo, now = Date.now()) {
+    return Math.max(0, Math.floor((validTo.getTime() - now) / (24 * 60 * 60 * 1000)));
+}
+//# sourceMappingURL=certificate.node.js.map

package/dist/cli/certificate.node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"certificate.node.js","sourceRoot":"","sources":["../../src/cli/certificate.node.ts"],"names":[],"mappings":"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"}

package/dist/cli/demo-contract.js

@@ -0,0 +1,6 @@
+import { defineContract, reliable, unreliable } from '../contract.js';
+export const demoContract = defineContract({
+    chat: reliable(),
+    cursor: unreliable(),
+});
+//# sourceMappingURL=demo-contract.js.map

package/dist/cli/demo-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo-contract.js","sourceRoot":"","sources":["../../src/cli/demo-contract.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,cAAc,EAAc,QAAQ,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAajF,MAAM,CAAC,MAAM,YAAY,GASrB,cAAc,CAAC;IACjB,IAAI,EAAE,QAAQ,EAAY;IAC1B,MAAM,EAAE,UAAU,EAAc;CACjC,CAAC,CAAA"}

package/dist/cli/demo.node.js

@@ -0,0 +1,131 @@
+/**
+ * `transport-io dev --demo`: two tabs talking, with no project and no files written.
+ *
+ * This exists because the acceptance test for `dev` is a person who has never used this
+ * library seeing a message cross, and serving a project they do not have cannot meet it. It
+ * writes nothing to disk and scaffolds nothing; it serves a page out of the package.
+ *
+ * It is a second thing to maintain, which is the honest cost. The e2e suite drives it, so it
+ * cannot rot quietly.
+ */
+import { createServer } from '../server.js';
+import { listenDev } from '../transport/fails.node.js';
+import { demoContract } from './demo-contract.js';
+import { LIB_PREFIX } from './dev-server.node.js';
+const ROOM = 'demo';
+/** Starts the demo's WebTransport server. The certificate comes from the environment. */
+export async function startDemoServer() {
+    const server = createServer({ contract: demoContract });
+    server.onSession((peer) => {
+        void peer.join(ROOM);
+        // Reliable: everyone sees it, including the sender, in one order.
+        peer.on('chat', (msg) => void server.to(ROOM).emit('chat', msg));
+        // Unreliable: excluded from the sender, because you know where your own pointer is.
+        peer.on('cursor', (pos) => void server.to(ROOM).except(peer.id).emit('cursor', pos));
+    });
+    await server.listen(await listenDev(), {
+        onAcceptError: (e) => console.error('session refused:', e.message),
+    });
+}
+/**
+ * The page.
+ *
+ * It imports the built package over `LIB_PREFIX` as native ESM, which is why the demo needs
+ * no bundler, and it imports the same contract module the server above uses, which is why
+ * the two cannot disagree.
+ */
+export const DEMO_PAGE = `<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<title>transport-io demo</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 15px/1.5 ui-sans-serif, system-ui, sans-serif; margin: 0; height: 100vh;
+         display: flex; flex-direction: column; }
+  header { padding: .6rem 1rem; border-bottom: 1px solid color-mix(in srgb, currentColor 20%, transparent);
+           display: flex; gap: 1rem; align-items: baseline; }
+  h1 { font-size: 1rem; margin: 0; font-weight: 600; }
+  #status { font-size: .8rem; opacity: .7; }
+  #log { flex: 1; overflow-y: auto; margin: 0; padding: 1rem; list-style: none; }
+  #log li { padding: .15rem 0; }
+  #log .me { opacity: .65; }
+  form { display: flex; gap: .5rem; padding: 1rem; border-top: 1px solid color-mix(in srgb, currentColor 20%, transparent); }
+  input { flex: 1; padding: .5rem .7rem; font: inherit; border-radius: 6px;
+          border: 1px solid color-mix(in srgb, currentColor 30%, transparent); background: transparent; color: inherit; }
+  button { padding: .5rem 1rem; font: inherit; border-radius: 6px; border: 0;
+           background: currentColor; cursor: pointer; }
+  button span { color: Canvas; }
+  .dot { position: fixed; width: 10px; height: 10px; border-radius: 50%;
+         background: crimson; pointer-events: none; transition: translate 60ms linear; }
+</style>
+<header>
+  <h1>transport-io</h1>
+  <span id="status">connecting</span>
+  <span id="hint" style="font-size:.8rem;opacity:.5">open a second tab</span>
+</header>
+<ul id="log"></ul>
+<form id="send">
+  <input id="body" placeholder="Type a message and press enter" autocomplete="off" autofocus>
+  <button type="submit"><span>Send</span></button>
+</form>
+<script type="module">
+import { Client } from '${LIB_PREFIX}index.js'
+import { connectDev } from '${LIB_PREFIX}transport/dev.js'
+import { demoContract } from '${LIB_PREFIX}cli/demo-contract.js'
+
+const me = 'guest-' + Math.random().toString(16).slice(2, 6)
+const log = document.getElementById('log')
+const status = document.getElementById('status')
+
+const add = (text, mine) => {
+  const li = document.createElement('li')
+  li.textContent = text
+  if (mine) li.className = 'me'
+  log.append(li)
+  log.scrollTop = log.scrollHeight
+}
+
+const client = new Client({ contract: demoContract, connect: () => connectDev() })
+
+client.subscribe(() => {
+  const s = client.getSnapshot()
+  status.textContent = s.status
+  if (s.status === 'closed' && s.lastError) add('! ' + s.lastError.message, true)
+})
+
+client.on('chat', (m) => add(m.from + ': ' + m.body, m.from === me))
+
+// The unreliable lane. Dropped frames are the point, not a fault.
+const dots = new Map()
+client.on('cursor', (p) => {
+  let dot = dots.get(p.from)
+  if (!dot) { dot = document.createElement('div'); dot.className = 'dot'; document.body.append(dot); dots.set(p.from, dot) }
+  dot.style.translate = p.x + 'px ' + p.y + 'px'
+})
+
+document.getElementById('send').addEventListener('submit', (e) => {
+  e.preventDefault()
+  const input = document.getElementById('body')
+  const body = input.value.trim()
+  if (body === '') return
+  client.emit('chat', { from: me, body, at: Date.now() })
+  input.value = ''
+})
+
+addEventListener('pointermove', (e) => {
+  if (client.getSnapshot().status === 'connected') {
+    client.emit('cursor', { from: me, x: e.clientX, y: e.clientY })
+  }
+})
+
+try {
+  await client.connect()
+  add('connected as ' + me + '. Open this page in a second tab.', true)
+} catch (err) {
+  status.textContent = 'failed'
+  add('! ' + (err && err.message ? err.message : String(err)), true)
+}
+</script>
+</html>
+`;
+//# sourceMappingURL=demo.node.js.map

package/dist/cli/demo.node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo.node.js","sourceRoot":"","sources":["../../src/cli/demo.node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AACtD,OAAO,EAAgB,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEjD,MAAM,IAAI,GAAG,MAAM,CAAA;AAEnB,yFAAyF;AACzF,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,MAAM,MAAM,GAAG,YAAY,CAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC,CAAA;IAEhE,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACpB,kEAAkE;QAClE,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAA;QAChE,oFAAoF;QACpF,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAA;IACtF,CAAC,CAAC,CAAA;IAEF,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,SAAS,EAAE,EAAE;QACrC,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,kBAAkB,EAAG,CAAW,CAAC,OAAO,CAAC;KAC9E,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAmCP,UAAU;8BACN,UAAU;gCACR,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwDzC,CAAA"}

package/dist/cli/dev-server.node.js

@@ -0,0 +1,98 @@
+/**
+ * The plain HTTP half of `transport-io dev`.
+ *
+ * Three jobs, and deliberately no fourth. It publishes the certificate hash at a fixed
+ * endpoint so the browser can pin it; it serves the package's own built ESM so a page can
+ * import the library without a bundler; and it serves whatever static files the project
+ * already built.
+ *
+ * It does NOT bundle. Bundling browser TypeScript needs a bundler, which would be the first
+ * runtime dependency this package has ever taken for the CLI, so a real project keeps
+ * running its own `vite dev` or `bun build --watch` alongside this. The demo needs no
+ * bundler because it imports the built ESM directly.
+ *
+ * `http` rather than `https` on purpose: `http://localhost` is a trustworthy origin, so the
+ * page gets a secure context for free and only the WebTransport endpoint needs a certificate.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { extname, join, normalize, resolve } from 'node:path';
+import { DEV_ENDPOINT } from '../transport/dev.js';
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+};
+/** Where the package's own built ESM is served, so a page can import it with no build step. */
+export const LIB_PREFIX = '/_transport-io/';
+/**
+ * Resolves a URL path inside a root, refusing anything that escapes it.
+ *
+ * A dev server still serves the filesystem, and `..` in a request path is the oldest way to
+ * read a file that was never meant to be public.
+ */
+function safeJoin(root, urlPath) {
+    const clean = normalize(decodeURIComponent(urlPath)).replace(/^(\.\.[/\\])+/, '');
+    const full = resolve(join(root, clean));
+    const rootFull = resolve(root);
+    if (full !== rootFull && !full.startsWith(rootFull + '/'))
+        return undefined;
+    return full;
+}
+function sendFile(res, file) {
+    if (!existsSync(file))
+        return false;
+    let stat;
+    try {
+        stat = statSync(file);
+    }
+    catch {
+        return false;
+    }
+    if (!stat.isFile())
+        return false;
+    res.writeHead(200, { 'content-type': MIME[extname(file)] ?? 'application/octet-stream' });
+    res.end(readFileSync(file));
+    return true;
+}
+export function startDevServer(opts) {
+    const server = createServer((req, res) => {
+        const path = (req.url ?? '/').split('?')[0] ?? '/';
+        if (path === DEV_ENDPOINT) {
+            res.writeHead(200, {
+                'content-type': 'application/json; charset=utf-8',
+                // The hash changes when the certificate is renewed, so it must never be cached.
+                'cache-control': 'no-store',
+            });
+            res.end(JSON.stringify(opts.manifest));
+            return;
+        }
+        if (path.startsWith(LIB_PREFIX)) {
+            const file = safeJoin(opts.distDir, path.slice(LIB_PREFIX.length));
+            if (file !== undefined && sendFile(res, file))
+                return;
+            res.writeHead(404).end('not found');
+            return;
+        }
+        if (opts.staticDir !== undefined) {
+            const rel = path === '/' ? '/index.html' : path;
+            const file = safeJoin(opts.staticDir, rel);
+            if (file !== undefined && sendFile(res, file))
+                return;
+        }
+        if (opts.indexHtml !== undefined && (path === '/' || path === '/index.html')) {
+            res.writeHead(200, { 'content-type': MIME['.html'] });
+            res.end(opts.indexHtml);
+            return;
+        }
+        res.writeHead(404).end('not found');
+    });
+    return new Promise((ok, fail) => {
+        server.once('error', fail);
+        server.listen(opts.port, '127.0.0.1', () => ok(server));
+    });
+}
+//# sourceMappingURL=dev-server.node.js.map

package/dist/cli/dev-server.node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-server.node.js","sourceRoot":"","sources":["../../src/cli/dev-server.node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAC5D,OAAO,EAAE,YAAY,EAAkD,MAAM,WAAW,CAAA;AACxF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAElD,MAAM,IAAI,GAAqC;IAC7C,OAAO,EAAE,0BAA0B;IACnC,KAAK,EAAE,gCAAgC;IACvC,MAAM,EAAE,yBAAyB;IACjC,OAAO,EAAE,iCAAiC;IAC1C,MAAM,EAAE,iCAAiC;IACzC,MAAM,EAAE,eAAe;CACxB,CAAA;AAED,+FAA+F;AAC/F,MAAM,CAAC,MAAM,UAAU,GAAG,iBAAiB,CAAA;AAc3C;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,IAAY,EAAE,OAAe;IAC7C,MAAM,KAAK,GAAG,SAAS,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAA;IACjF,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;IACvC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9B,IAAI,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,GAAG,GAAG,CAAC;QAAE,OAAO,SAAS,CAAA;IAC3E,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,GAAmB,EAAE,IAAY;IACjD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAA;IACnC,IAAI,IAAiC,CAAA;IACrC,IAAI,CAAC;QACH,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;QAAE,OAAO,KAAK,CAAA;IAChC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,0BAA0B,EAAE,CAAC,CAAA;IACzF,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAA;IAC3B,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAsB;IACnD,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QACvC,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAA;QAElD,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;YAC1B,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;gBACjB,cAAc,EAAE,iCAAiC;gBACjD,gFAAgF;gBAChF,eAAe,EAAE,UAAU;aAC5B,CAAC,CAAA;YACF,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAA;YACtC,OAAM;QACR,CAAC;QAED,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAA;YAClE,IAAI,IAAI,KAAK,SAAS,IAAI,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;gBAAE,OAAM;YACrD,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;YACnC,OAAM;QACR,CAAC;QAED,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAA;YAC/C,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAA;YAC1C,IAAI,IAAI,KAAK,SAAS,IAAI,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;gBAAE,OAAM;QACvD,CAAC;QAED,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,aAAa,CAAC,EAAE,CAAC;YAC7E,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,OAAO,CAAW,EAAE,CAAC,CAAA;YAC/D,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;YACvB,OAAM;QACR,CAAC;QAED,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;IAEF,OAAO,IAAI,OAAO,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE;QAC9B,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;QAC1B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;IACzD,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/cli/main.node.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * `npx transport-io dev`.
+ *
+ * The first thirty minutes with this library used to be two openssl invocations, three
+ * constraints nobody tells you about, a DER extraction, a SHA-256, and an undocumented hop
+ * getting that hash from the server process into the browser bundle. This closes all of it.
+ *
+ * What it does NOT do is bundle. That needs a bundler, which would be this package's first
+ * CLI dependency, so a real project keeps running its own `vite dev` or `bun build --watch`
+ * beside this and points `--static` at the output. `--demo` needs no bundler because the
+ * page imports the built package as native ESM.
+ *
+ * Everything here is Node built-ins and this library's own source. The import boundary check
+ * enforces that, so a future feature cannot quietly add a dependency.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { daysLeft, ensureCertificate } from './certificate.node.js';
+import { startDevServer } from './dev-server.node.js';
+const DEFAULT_PORT = 3000;
+const DEFAULT_WT_PORT = 4433;
+function parse(argv) {
+    let entry;
+    let demo = false;
+    let port = DEFAULT_PORT;
+    let wtPort = DEFAULT_WT_PORT;
+    let staticDir;
+    let help = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--demo')
+            demo = true;
+        else if (a === '--help' || a === '-h')
+            help = true;
+        else if (a === '--port')
+            port = Number(argv[++i]);
+        else if (a === '--wt-port')
+            wtPort = Number(argv[++i]);
+        else if (a === '--static')
+            staticDir = argv[++i];
+        else if (!a.startsWith('-'))
+            entry ??= a;
+    }
+    return { entry, demo, port, wtPort, staticDir, help };
+}
+const USAGE = `transport-io dev - a local WebTransport server with a pinned certificate
+
+  npx transport-io dev [entry]      run your server, with a certificate already minted
+  npx transport-io dev --demo       two tabs talking, no project needed
+
+Options
+  --demo             serve the built-in demo instead of a project
+  --port <n>         HTTP port for the page          (default ${DEFAULT_PORT})
+  --wt-port <n>      WebTransport port               (default ${DEFAULT_WT_PORT})
+  --static <dir>     directory of files to serve     (default ./public, then ./web)
+
+Your server file should listen with the certificate this command minted:
+
+  import { listenDev } from 'transport-io/node-transport'
+  await server.listen(await listenDev())
+
+This does not bundle browser code. Keep running your own bundler and point --static at it.
+`;
+function findStatic(explicit) {
+    if (explicit !== undefined)
+        return resolve(explicit);
+    for (const candidate of ['public', 'web/dist', 'web', 'dist']) {
+        const full = resolve(candidate);
+        if (existsSync(full))
+            return full;
+    }
+    return undefined;
+}
+async function main() {
+    const args = parse(process.argv.slice(2));
+    const command = process.argv[2];
+    if (args.help || command === undefined || (command !== 'dev' && !command.startsWith('-'))) {
+        if (command !== undefined && command !== 'dev' && !command.startsWith('-')) {
+            console.error(`unknown command '${command}'\n`);
+        }
+        console.log(USAGE);
+        process.exit(args.help ? 0 : 1);
+    }
+    // `node_modules/.cache` is ignored by every project already, so a private key never lands
+    // in a commit and this never edits anyone's .gitignore.
+    const cacheDir = resolve('node_modules/.cache/transport-io');
+    const cert = ensureCertificate(cacheDir);
+    const wtUrl = `https://127.0.0.1:${args.wtPort}/`;
+    const here = dirname(fileURLToPath(import.meta.url));
+    // `dist/cli` -> `dist`, the directory served as ESM to the browser.
+    const distDir = resolve(here, '..');
+    const staticDir = args.demo ? undefined : findStatic(args.staticDir);
+    let demoPage;
+    if (args.demo) {
+        const { DEMO_PAGE, startDemoServer } = await import('./demo.node.js');
+        demoPage = DEMO_PAGE;
+        process.env.TRANSPORT_IO_DEV_CERT = cert.cert;
+        process.env.TRANSPORT_IO_DEV_KEY = cert.privKey;
+        process.env.TRANSPORT_IO_DEV_WT_PORT = String(args.wtPort);
+        await startDemoServer();
+    }
+    await startDevServer({
+        port: args.port,
+        ...(staticDir === undefined ? {} : { staticDir }),
+        ...(demoPage === undefined ? {} : { indexHtml: demoPage }),
+        distDir,
+        manifest: { sha256: [...cert.sha256], url: wtUrl },
+    });
+    const short = Buffer.from(cert.sha256).toString('hex').slice(0, 6);
+    console.log('');
+    console.log('transport-io dev');
+    console.log('');
+    console.log(`  page          http://localhost:${args.port}`);
+    console.log(`  webtransport  ${wtUrl}`);
+    console.log(`  certificate   valid ${daysLeft(cert.validTo)}d  sha-256 ${short}…`);
+    if (cert.renewed) {
+        console.log('  certificate renewed, so reload any tab you already had open');
+    }
+    console.log('');
+    console.log('  Open the page in two tabs. Chrome or Firefox; Safari cannot connect.');
+    if (!args.demo && staticDir === undefined) {
+        console.log('');
+        console.log('  No static directory found. Pass --static <dir> to serve your built page.');
+    }
+    console.log('');
+    if (!args.demo && args.entry !== undefined) {
+        const child = spawn(process.execPath, [args.entry], {
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+                TRANSPORT_IO_DEV_CERT: cert.cert,
+                TRANSPORT_IO_DEV_KEY: cert.privKey,
+                TRANSPORT_IO_DEV_WT_PORT: String(args.wtPort),
+            },
+        });
+        child.on('exit', (code) => process.exit(code ?? 0));
+    }
+    else if (!args.demo) {
+        console.log('  No entry given, so no server was started. Pass one, or use --demo.');
+        console.log('');
+    }
+}
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+});
+//# sourceMappingURL=main.node.js.map

package/dist/cli/main.node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.node.js","sourceRoot":"","sources":["../../src/cli/main.node.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -5,7 +5,7 @@
  * scope, so importing this on a server - which Next.js will do - is safe. Feature
  * detection happens inside connect().
  */
-import { type AnyMap, type CallableOf, type Contract, type StreamableOf } from './contract.ts';
+import { type AnyMap, type CallableOf, type Contract, type Registered, type StreamableOf } from './contract.ts';
 import { TransportError } from './errors.ts';
 import { type SessionStats, type StreamResult } from './session.ts';
 import type { Connection } from './transport/types.ts';
@@ -34,7 +34,7 @@ export interface ClientOptions<C extends Contract = Contract> {
     /** Test seam: the clock the TTL is measured against. Defaults to `Date.now`. */
     readonly now?: () => number;
 }
-export declare class Client<M extends AnyMap = AnyMap> {
+export declare class Client<M extends AnyMap = Registered> {
     #private;
     constructor(opts: ClientOptions);
     /**
@@ -56,9 +56,9 @@ export declare class Client<M extends AnyMap = AnyMap> {
         readonly signal?: AbortSignal;
     }): Promise<M[K]['returns']>;
     /**
-     * Available only on events declaring `yields`. Iterate it, or `.collect()` the whole
-     * sequence. Leaving the loop with `break` resets the QUIC stream, which is what reaches
-     * the responder's `ctx.signal`; there is no separate cancel call and none is needed.
+     * Available only on events declaring `yields`. Iterate it, or `.toArray()` the whole
+     * sequence. Leaving the loop with `break` resets the QUIC stream, and that reset is what
+     * fires the responder's `ctx.signal`. There is no separate cancel call.
      */
     stream<K extends StreamableOf<M> & string>(event: K, payload: M[K]['payload'], options?: {
         readonly signal?: AbortSignal;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,KAAK,MAAM,EAEX,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,YAAY,EAClB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE5C,OAAO,EAAW,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE/E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAAA;CAC1C;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ;IAC1D;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAErC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAA;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAA;IAC3C,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAA;IAClC,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,mFAAmF;IACnF,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;IACpD,gFAAgF;IAChF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AAED,qBAAa,MAAM,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;;IAc3C,YAAY,IAAI,EAAE,aAAa,EAE9B;IAED;;;;OAIG;IACH,WAAW,IAAI,WAAW,CAEzB;IAED,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAK1C;IAED;oFACgF;IAC1E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAS7B;IAED,UAAU,IAAI,IAAI,CAQjB;IAED,mEAAmE;IACnE,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAEzE;IAED,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAC3B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,IAAI,GAC1C,MAAM,IAAI,CAYZ;IAED,qFAAqF;IAC/E,IAAI,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,EACzC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,EACxB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC1C,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAE1B;IAED;;;;OAIG;IACH,MAAM,CAAC,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,EACvC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,EACxB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC1C,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAI9B;IAED,KAAK,IAAI,YAAY,GAAG,SAAS,CAEhC;CAoFF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,KAAK,MAAM,EAEX,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,YAAY,EAClB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE5C,OAAO,EAAW,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE/E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAAA;CAC1C;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ;IAC1D;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAErC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAA;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAA;IAC3C,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAA;IAClC,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,mFAAmF;IACnF,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;IACpD,gFAAgF;IAChF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AAED,qBAAa,MAAM,CAAC,CAAC,SAAS,MAAM,GAAG,UAAU;;IAc/C,YAAY,IAAI,EAAE,aAAa,EAE9B;IAED;;;;OAIG;IACH,WAAW,IAAI,WAAW,CAEzB;IAED,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAK1C;IAED;oFACgF;IAC1E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAS7B;IAED,UAAU,IAAI,IAAI,CAQjB;IAED,mEAAmE;IACnE,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAEzE;IAED,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAC3B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,IAAI,GAC1C,MAAM,IAAI,CAYZ;IAED,qFAAqF;IAC/E,IAAI,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,EACzC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,EACxB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC1C,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAE1B;IAED;;;;OAIG;IACH,MAAM,CAAC,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,EACvC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,EACxB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC1C,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAI9B;IAED,KAAK,IAAI,YAAY,GAAG,SAAS,CAEhC;CAoFF"}

package/dist/client.js

@@ -85,9 +85,9 @@ export class Client {
         return (await this.#requireSession().call(event, payload, options));
     }
     /**
-     * Available only on events declaring `yields`. Iterate it, or `.collect()` the whole
-     * sequence. Leaving the loop with `break` resets the QUIC stream, which is what reaches
-     * the responder's `ctx.signal`; there is no separate cancel call and none is needed.
+     * Available only on events declaring `yields`. Iterate it, or `.toArray()` the whole
+     * sequence. Leaving the loop with `break` resets the QUIC stream, and that reset is what
+     * fires the responder's `ctx.signal`. There is no separate cancel call.
      */
     stream(event, payload, options) {
         return this.#requireSession().stream(event, payload, options);
@@ -102,7 +102,7 @@ export class Client {
             const conn = await this.#opts.connect();
             // Chrome implements neither `requireUnreliable` nor `reliability`, so `undefined`
             // must pass or every session on the dominant browser would be refused. Only an
-            // explicit reliable-only is a lie about the unreliable lane.
+            // explicit reliable-only would misreport what the unreliable lane does.
             if (conn.reliability() === 'reliable-only') {
                 // §10.2 code 1006. Throwing without closing left the peer holding a session this
                 // side had already abandoned, with nothing on the wire to say why.