pikiloom 0.4.21 → 0.4.23

package/dist/pikichannel/server.js

@@ -0,0 +1,284 @@
+/**
+ * pikichannel/server.ts — wires pikichannel into the pikiloom dashboard server.
+ *
+ * Responsibilities:
+ *   - build the host over the pikiloom SessionSource,
+ *   - stand up BOTH transport bindings (WebSocket always; WebRTC via a guarded
+ *     dynamic import so a missing/broken werift never blocks startup),
+ *   - register the reference web routes (demo page + browser SDK + status),
+ *   - expose `attachUpgrade(server)` so the dashboard's HTTP server can route
+ *     `/pikichannel/*` upgrade requests to the right binding.
+ *
+ * Both bindings funnel into the SAME `host.handleConnection`, so a session
+ * behaves identically regardless of transport — that is the pluggability the
+ * two bindings exist to demonstrate.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getConnInfo } from '@hono/node-server/conninfo';
+import { writeScopedLog } from '../core/logging.js';
+import { loadUserConfig, updateUserConfig } from '../core/config/user-config.js';
+import { PikichannelHost } from './host.js';
+import { PikiloomSessionSource } from './adapter-pikiloom.js';
+import { WebSocketTransport } from './transports/websocket-host.js';
+import { RendezvousBroker } from './rendezvous-broker.js';
+/** A remote address label is loopback when it is the local host. */
+function isLoopback(remote) {
+    if (!remote)
+        return false;
+    const r = remote.toLowerCase();
+    return r.startsWith('127.') || r.includes('127.0.0.1') || r === '::1' || r.startsWith('::1:') || r.startsWith('[::1]') || r.includes('::ffff:127.');
+}
+/** Constant-time token comparison. */
+function tokenMatches(presented, expected) {
+    if (!presented || !expected)
+        return false;
+    const a = Buffer.from(presented);
+    const b = Buffer.from(expected);
+    return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+function readWebAsset(name) {
+    const file = path.join(import.meta.dirname, 'web', name);
+    return fs.readFileSync(file, 'utf8');
+}
+export async function mountPikichannel(app) {
+    const log = (msg) => writeScopedLog('pikichannel', msg, { level: 'info' });
+    // -- Access token: provision on first run, persist to ~/.pikiloom/setting.json.
+    //    Loopback peers (the local dashboard / same-machine demo) are exempt;
+    //    remote peers must present this token in `hello`. `strict` requires the
+    //    token even from loopback (defense-in-depth / testing). --
+    const cfg = loadUserConfig();
+    // Env overrides (docker / headless): PIKICHANNEL_TOKEN pins the token without
+    // persisting; PIKICHANNEL_STRICT=1 forces token even from loopback.
+    const envToken = String(process.env.PIKICHANNEL_TOKEN || '').trim();
+    let token = envToken || String(cfg.pikichannelToken || '').trim();
+    if (!token) {
+        token = crypto.randomBytes(24).toString('base64url');
+        try {
+            updateUserConfig({ pikichannelToken: token });
+            log('provisioned a new pikichannel access token');
+        }
+        catch (err) {
+            log(`could not persist access token: ${err?.message}`);
+        }
+    }
+    const strict = cfg.pikichannelStrictAuth === true || process.env.PIKICHANNEL_STRICT === '1';
+    const authenticate = (presented, remote) => {
+        if (!strict && isLoopback(remote))
+            return true;
+        return tokenMatches(presented, token);
+    };
+    // -- NodeID: the stable address a remote client dials over the rendezvous. --
+    let nodeId = String(cfg.pikichannelNodeId || '').trim();
+    if (!nodeId) {
+        nodeId = crypto.randomBytes(8).toString('hex');
+        try {
+            updateUserConfig({ pikichannelNodeId: nodeId });
+        }
+        catch { /* persisted best-effort */ }
+    }
+    const rendezvousUrl = String(process.env.PIKICHANNEL_RENDEZVOUS || cfg.pikichannelRendezvous || '').trim();
+    let currentPublicHost = String(process.env.PIKICHANNEL_PUBLIC_HOST || cfg.pikichannelPublicHost || '').trim();
+    // Control-plane tunnel forwarder: replay a tunneled request against the SAME
+    // Hono router that serves /api/* locally — management logic stays single-sourced.
+    // Text responses ride as utf8; anything else (attachment bytes) as base64.
+    const forward = async (req) => {
+        const init = { method: req.method || 'GET', headers: req.headers };
+        if (req.body != null && req.method && req.method !== 'GET' && req.method !== 'HEAD') {
+            init.body = req.encoding === 'base64' ? new Uint8Array(Buffer.from(req.body, 'base64')) : req.body;
+        }
+        const res = await app.fetch(new Request(`http://pikichannel.internal${req.path}`, init));
+        const headers = {};
+        res.headers.forEach((v, k) => { headers[k] = v; });
+        const ct = (res.headers.get('content-type') || '').toLowerCase();
+        const isText = ct === '' || /json|text|javascript|xml|svg|x-ndjson|form-urlencoded/.test(ct);
+        if (isText)
+            return { status: res.status, headers, body: await res.text(), encoding: 'utf8' };
+        const buf = Buffer.from(await res.arrayBuffer());
+        return { status: res.status, headers, body: buf.toString('base64'), encoding: 'base64' };
+    };
+    const source = new PikiloomSessionSource(forward);
+    const host = new PikichannelHost(source, authenticate, log);
+    host.start();
+    // -- WebSocket binding (always available) --
+    const wsTransport = new WebSocketTransport();
+    wsTransport.start((conn) => host.handleConnection(conn));
+    // -- WebRTC binding (guarded; degrades gracefully) --
+    let rtcTransport = null;
+    let webrtcError = null;
+    try {
+        const mod = await import('./transports/webrtc-host.js');
+        const t = new mod.WebRTCTransport();
+        t.start((conn) => host.handleConnection(conn));
+        rtcTransport = t;
+        log('webrtc transport ready');
+    }
+    catch (err) {
+        webrtcError = err?.message || String(err);
+        log(`webrtc transport unavailable: ${webrtcError}`);
+    }
+    // -- Rendezvous broker (NAT traversal): always mounted (no werift dep), so any
+    //    reachable pikiloom can broker signaling for NAT'd peers. Relays signaling
+    //    only; data stays P2P. --
+    const broker = new RendezvousBroker();
+    // -- Rendezvous registrar: when enabled, this host dials OUT to a broker and
+    //    registers its NodeID so remote clients can reach it through NAT. Can be
+    //    toggled at RUNTIME (one-click from the dashboard) — no restart. Needs
+    //    werift, so the host-client class is loaded only when WebRTC is available. --
+    let rendezvousHost = null;
+    let HostClientCtor = null;
+    let currentRendezvous = '';
+    if (rtcTransport) {
+        try {
+            HostClientCtor = (await import('./rendezvous-host.js')).RendezvousHostClient;
+        }
+        catch (err) {
+            log(`rendezvous-host load failed: ${err?.message || err}`);
+        }
+    }
+    async function setRendezvous(url, persist = true) {
+        const next = (url || '').trim();
+        if (rendezvousHost) {
+            rendezvousHost.stop();
+            rendezvousHost = null;
+        }
+        currentRendezvous = '';
+        if (next) {
+            if (!HostClientCtor)
+                return { ok: false, error: 'WebRTC unavailable on this host' };
+            rendezvousHost = new HostClientCtor(next, nodeId, (conn) => host.handleConnection(conn));
+            rendezvousHost.start();
+            currentRendezvous = next;
+        }
+        if (persist) {
+            try {
+                updateUserConfig({ pikichannelRendezvous: next });
+            }
+            catch { /* best-effort */ }
+        }
+        log(`rendezvous ${next ? `enabled url=${next} nodeId=${nodeId}` : 'disabled'}`);
+        return { ok: true };
+    }
+    if (rendezvousUrl)
+        await setRendezvous(rendezvousUrl, false); // initial from env/config
+    // -- Web assets (read once; the demo + SDK double as the OSS reference client) --
+    let sdkJs = '';
+    let demoHtml = '';
+    try {
+        sdkJs = readWebAsset('sdk.js');
+        demoHtml = readWebAsset('demo.html');
+    }
+    catch (err) {
+        log(`web assets missing: ${err?.message}`);
+    }
+    const serveDemo = (c) => { c.header('Cache-Control', 'no-cache'); return c.html(demoHtml || '<h1>pikichannel demo asset missing</h1>'); };
+    app.get('/pikichannel', serveDemo);
+    app.get('/pikichannel/', serveDemo);
+    // QR of a connection code (or any short string) as SVG — reuses the repo's
+    // `qrcode` dep so the browser SDK needs no QR library. Dynamic-imported to
+    // keep startup lean.
+    app.get('/pikichannel/qr', async (c) => {
+        const data = String(c.req.query('data') || '').slice(0, 2048);
+        if (!data)
+            return c.text('missing data', 400);
+        try {
+            const QRCode = (await import('qrcode')).default;
+            const svg = await QRCode.toString(data, { type: 'svg', margin: 1, errorCorrectionLevel: 'M' });
+            c.header('Content-Type', 'image/svg+xml; charset=utf-8');
+            c.header('Cache-Control', 'no-store');
+            return c.body(svg);
+        }
+        catch {
+            return c.text('qr failed', 500);
+        }
+    });
+    app.get('/pikichannel/sdk.js', (c) => {
+        c.header('Content-Type', 'application/javascript; charset=utf-8');
+        c.header('Cache-Control', 'no-cache');
+        return c.body(sdkJs || '// pikichannel sdk asset missing');
+    });
+    app.get('/pikichannel/status', (c) => c.json(statusObj()));
+    // -- Pairing: hand the access token to a trusted LOCAL caller only (the
+    //    dashboard / CLI on this machine). Remote callers get 403 — they must be
+    //    paired out-of-band (token shown in the local dashboard, scanned as a QR). --
+    app.get('/pikichannel/pair', (c) => {
+        let remote;
+        try {
+            remote = getConnInfo(c)?.remote?.address;
+        }
+        catch {
+            remote = undefined;
+        }
+        if (!isLoopback(remote))
+            return c.json({ ok: false, error: 'pairing is only available from localhost' }, 403);
+        return c.json({ ok: true, token, strict, nodeId, rendezvous: currentRendezvous || null, publicHost: currentPublicHost || null, registered: !!rendezvousHost, hint: 'paste the connection code into a client' });
+    });
+    // -- Remote-access settings: configure how others reach THIS host — a public
+    //    address (direct) and/or internet穿透 (rendezvous). Runtime, one-click,
+    //    localhost-only (it changes who can reach this machine). --
+    app.post('/pikichannel/remote', async (c) => {
+        let remote;
+        try {
+            remote = getConnInfo(c)?.remote?.address;
+        }
+        catch {
+            remote = undefined;
+        }
+        if (!isLoopback(remote))
+            return c.json({ ok: false, error: 'only available from localhost' }, 403);
+        const body = await c.req.json().catch(() => ({}));
+        if ('publicHost' in body) {
+            currentPublicHost = String(body.publicHost || '').trim();
+            try {
+                updateUserConfig({ pikichannelPublicHost: currentPublicHost });
+            }
+            catch { /* best-effort */ }
+        }
+        let r = { ok: true };
+        if ('enabled' in body || 'rendezvous' in body) {
+            r = await setRendezvous(body?.enabled ? String(body?.rendezvous || '') : null);
+        }
+        return c.json({ ...r, registered: !!rendezvousHost, rendezvous: currentRendezvous || null, publicHost: currentPublicHost || null, nodeId, token });
+    });
+    function statusObj() {
+        return {
+            ok: true,
+            transports: rtcTransport ? ['websocket', 'webrtc'] : ['websocket'],
+            peers: host.peerCount,
+            authedPeers: host.authedPeerCount,
+            webrtc: !!rtcTransport,
+            webrtcError,
+            authRequired: true,
+            strict,
+            nodeId,
+            rendezvous: currentRendezvous || null,
+            publicHost: currentPublicHost || null,
+            registered: !!rendezvousHost,
+            broker: broker.stats,
+        };
+    }
+    return {
+        handleUpgrade(req, socket, head) {
+            const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+            if (!url.pathname.startsWith('/pikichannel/'))
+                return false; // not ours
+            if (url.pathname === '/pikichannel/ws') {
+                wsTransport.handleUpgrade(req, socket, head);
+                return true;
+            }
+            if (url.pathname === '/pikichannel/signal' && rtcTransport) {
+                rtcTransport.handleUpgrade(req, socket, head);
+                return true;
+            }
+            if (url.pathname === '/pikichannel/rendezvous') {
+                broker.handleUpgrade(req, socket, head);
+                return true;
+            }
+            socket.destroy(); // unknown /pikichannel/* subpath (or webrtc disabled)
+            return true;
+        },
+        status: statusObj,
+        stop() { host.stop(); wsTransport.stop(); rtcTransport?.stop(); rendezvousHost?.stop(); broker.stop(); },
+    };
+}

package/dist/pikichannel/transport.js

@@ -0,0 +1,49 @@
+/**
+ * pikichannel/transport.ts — the L1 transport abstraction (host side).
+ *
+ * This is the seam that makes the two delivery mechanisms — WebSocket and
+ * WebRTC datachannel — interchangeable. A {@link ChannelTransport} accepts peer
+ * connections and surfaces each as a {@link ChannelConnection}: a reliable,
+ * ordered, bidirectional frame pipe. The host ({@link PikichannelHost}) drives
+ * the L2 protocol over a ChannelConnection and is wholly blind to whether the
+ * bytes travel over a TCP WebSocket or an SCTP datachannel — flip the binding,
+ * the session behaves identically. That blindness IS the comparability the two
+ * bindings are meant to demonstrate.
+ *
+ * Contract every binding must honour:
+ *   - reliable + ordered delivery of whole frames (no partial frames),
+ *   - bidirectional,
+ *   - a single 'close' notification, exactly once,
+ *   - `send()` after close is a silent no-op (never throws).
+ */
+/**
+ * Minimal base that implements the callback bookkeeping every binding repeats,
+ * so concrete connections only push frames in and call `emitClose()` once.
+ */
+export class BaseConnection {
+    remote;
+    messageCb = null;
+    closeCb = null;
+    closed = false;
+    onMessage(cb) { this.messageCb = cb; }
+    onClose(cb) {
+        this.closeCb = cb;
+        // If close already happened before the handler was attached, fire now.
+        if (this.closed)
+            cb();
+    }
+    /** Concrete bindings call this when a frame arrives. */
+    emitMessage(frame) {
+        if (this.messageCb)
+            this.messageCb(frame);
+    }
+    /** Concrete bindings call this exactly once when the pipe closes. */
+    emitClose() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.closeCb)
+            this.closeCb();
+    }
+    isOpen() { return !this.closed; }
+}

package/dist/pikichannel/transports/webrtc-host.js

@@ -0,0 +1,61 @@
+/**
+ * pikichannel/transports/webrtc-host.ts — the DIRECT WebRTC binding (host).
+ *
+ * SDP/ICE over a same-origin `/pikichannel/signal` WebSocket, for clients that
+ * can already reach the host (localhost / LAN / public IP). The cross-NAT path —
+ * where the host dials OUT to a public broker — lives in rendezvous.ts. Both
+ * paths share the same werift answerer (webrtc-shared.ts), so a connection from
+ * either is identical downstream.
+ *
+ * werift is imported (transitively) here; the server wiring loads this module via
+ * a guarded dynamic import, so a missing/broken werift disables WebRTC while the
+ * WebSocket binding and the dashboard keep working.
+ */
+import { WebSocketServer } from 'ws';
+import { writeScopedLog } from '../../core/logging.js';
+import { createAnswerer } from './webrtc-shared.js';
+const dlog = (msg) => writeScopedLog('pikichannel', `[webrtc] ${msg}`, { level: 'info' });
+export class WebRTCTransport {
+    kind = 'webrtc';
+    wss = new WebSocketServer({ noServer: true });
+    onConn = null;
+    start(onConnection) {
+        this.onConn = onConnection;
+        this.wss.on('connection', (ws, req) => this.runSignaling(ws, req));
+    }
+    /** Server wiring routes a matching signaling upgrade request here. */
+    handleUpgrade(req, socket, head) {
+        this.wss.handleUpgrade(req, socket, head, (ws) => this.wss.emit('connection', ws, req));
+    }
+    stop() {
+        this.wss.close();
+    }
+    /** One signaling WebSocket brokers exactly one peer connection. */
+    runSignaling(ws, req) {
+        const remote = req.socket.remoteAddress ? `${req.socket.remoteAddress}:${req.socket.remotePort}` : undefined;
+        const answerer = createAnswerer({
+            remote,
+            log: dlog,
+            onConnection: (conn) => this.onConn?.(conn),
+            sendSignal: (data) => { if (ws.readyState === ws.OPEN)
+                ws.send(JSON.stringify(data)); },
+        });
+        ws.on('message', (raw) => {
+            let msg;
+            try {
+                msg = JSON.parse(String(raw));
+            }
+            catch {
+                return;
+            }
+            void answerer.onSignal(msg);
+        });
+        // The signaling socket is only needed for the handshake; once the datachannel
+        // carries traffic it can close. If it drops before a channel was adopted,
+        // tear the half-open peer down.
+        const cleanup = () => { if (!answerer.isAdopted())
+            answerer.close(); };
+        ws.on('close', cleanup);
+        ws.on('error', cleanup);
+    }
+}

package/dist/pikichannel/transports/webrtc-shared.js

@@ -0,0 +1,132 @@
+/**
+ * pikichannel/transports/webrtc-shared.ts — shared werift answerer + connection.
+ *
+ * The host is always the WebRTC *answerer* (the browser/SDK creates the offer +
+ * datachannel). The same answerer logic drives two signaling paths:
+ *   - direct  (webrtc-host.ts): SDP/ICE over a same-origin `/pikichannel/signal`
+ *     WebSocket — for clients that can already reach the host.
+ *   - rendezvous (rendezvous.ts): SDP/ICE relayed through a public broker both
+ *     peers dial OUTBOUND — the NAT-traversal path.
+ *
+ * Once the datachannel opens the bytes are pure P2P (DTLS-encrypted); signaling
+ * only brokers the handshake. `getIceServers()` is the STUN/TURN config hook:
+ * STUN by default, TURN added via PIKICHANNEL_ICE_SERVERS for symmetric NAT.
+ */
+import { RTCPeerConnection } from 'werift';
+import { BaseConnection } from '../transport.js';
+let connCounter = 0;
+/**
+ * ICE servers for hole-punching. STUN alone covers most NATs; add a TURN relay
+ * for symmetric-NAT reliability via:
+ *   PIKICHANNEL_ICE_SERVERS='[{"urls":"stun:stun.l.google.com:19302"},
+ *     {"urls":"turn:turn.example.com:3478","username":"u","credential":"p"}]'
+ */
+export function getIceServers() {
+    const raw = process.env.PIKICHANNEL_ICE_SERVERS;
+    if (raw) {
+        try {
+            const v = JSON.parse(raw);
+            if (Array.isArray(v) && v.length)
+                return v;
+        }
+        catch { /* fall through to default */ }
+    }
+    return [{ urls: 'stun:stun.l.google.com:19302' }];
+}
+function coerceFrame(data) {
+    if (typeof data === 'string')
+        return data;
+    if (Buffer.isBuffer(data))
+        return data.toString('utf8');
+    try {
+        return Buffer.from(new Uint8Array(data)).toString('utf8');
+    }
+    catch {
+        return String(data);
+    }
+}
+/** A pikichannel connection riding an SCTP datachannel. */
+export class RtcConnection extends BaseConnection {
+    channel;
+    pc;
+    id;
+    kind = 'webrtc';
+    constructor(channel, pc, remote) {
+        super();
+        this.channel = channel;
+        this.pc = pc;
+        this.id = `rtc-${++connCounter}`;
+        this.remote = remote || 'webrtc-peer';
+        channel.onmessage = (ev) => this.emitMessage(coerceFrame(ev?.data));
+        channel.onclose = () => this.close();
+        pc.connectionStateChange.subscribe((state) => {
+            if (state === 'failed' || state === 'closed' || state === 'disconnected')
+                this.close();
+        });
+    }
+    send(frame) {
+        if (this.channel.readyState === 'open') {
+            try {
+                this.channel.send(frame);
+            }
+            catch { /* drop on closing channel */ }
+        }
+    }
+    isOpen() { return this.channel.readyState === 'open'; }
+    close() {
+        try {
+            this.channel.close();
+        }
+        catch { /* ignore */ }
+        try {
+            this.pc.close();
+        }
+        catch { /* ignore */ }
+        this.emitClose();
+    }
+}
+/**
+ * Build a werift answerer. The caller wires `sendSignal` to whatever signaling
+ * channel it has (a WS, or the rendezvous), feeds inbound signals to `onSignal`,
+ * and receives the live {@link ChannelConnection} via `onConnection` once the
+ * datachannel opens. Trickle ICE: the answer is sent immediately, candidates
+ * follow as they are gathered.
+ */
+export function createAnswerer(opts) {
+    const pc = new RTCPeerConnection({ iceServers: getIceServers() });
+    let adopted = false;
+    pc.onDataChannel.subscribe((channel) => {
+        adopted = true;
+        opts.onConnection(new RtcConnection(channel, pc, opts.remote));
+    });
+    pc.onIceCandidate.subscribe((candidate) => {
+        if (candidate)
+            opts.sendSignal({ kind: 'candidate', candidate: candidate.toJSON ? candidate.toJSON() : candidate });
+    });
+    return {
+        async onSignal(data) {
+            try {
+                if (data.kind === 'offer' && typeof data.sdp === 'string') {
+                    await pc.setRemoteDescription({ type: 'offer', sdp: data.sdp });
+                    const answer = await pc.createAnswer();
+                    await pc.setLocalDescription(answer);
+                    const local = pc.localDescription;
+                    if (local)
+                        opts.sendSignal({ kind: 'answer', type: local.type, sdp: local.sdp });
+                }
+                else if (data.kind === 'candidate' && data.candidate) {
+                    await pc.addIceCandidate(data.candidate);
+                }
+            }
+            catch (err) {
+                opts.log?.(`answerer signal error: ${err?.message || err}`);
+                opts.sendSignal({ kind: 'error', message: err?.message || 'signaling failed' });
+            }
+        },
+        isAdopted: () => adopted,
+        close() { try {
+            pc.close();
+        }
+        catch { /* ignore */ } },
+    };
+}

package/dist/pikichannel/transports/websocket-host.js

@@ -0,0 +1,78 @@
+/**
+ * pikichannel/transports/websocket-host.ts — the WebSocket L1 binding (host).
+ *
+ * The baseline transport: protocol frames ride a raw WebSocket. Same-machine /
+ * LAN clients (the Dashboard case) want exactly this — there is no NAT to
+ * traverse, so a TCP WebSocket is the optimal path. It is the control against
+ * which the WebRTC binding is compared.
+ *
+ * The server wiring owns upgrade routing and feeds matching upgrades to
+ * `handleUpgrade`; this class only manages the noServer WebSocketServer and
+ * wraps each socket as a {@link ChannelConnection}.
+ */
+import { WebSocketServer } from 'ws';
+import { BaseConnection } from '../transport.js';
+const WS_KEEPALIVE_MS = 25_000;
+let connCounter = 0;
+class WsConnection extends BaseConnection {
+    ws;
+    id;
+    kind = 'websocket';
+    constructor(ws, remote) {
+        super();
+        this.ws = ws;
+        this.id = `ws-${++connCounter}`;
+        this.remote = remote;
+        ws.on('message', (raw) => {
+            const data = raw;
+            const frame = typeof data === 'string'
+                ? data
+                : Buffer.isBuffer(data)
+                    ? data.toString('utf8')
+                    : Array.isArray(data)
+                        ? Buffer.concat(data).toString('utf8')
+                        : Buffer.from(data).toString('utf8');
+            this.emitMessage(frame);
+        });
+        ws.on('close', () => this.emitClose());
+        ws.on('error', () => this.emitClose());
+    }
+    send(frame) {
+        if (this.ws.readyState === this.ws.OPEN)
+            this.ws.send(frame);
+    }
+    isOpen() {
+        return this.ws.readyState === this.ws.OPEN;
+    }
+    close() {
+        try {
+            this.ws.close();
+        }
+        catch { /* ignore */ }
+        this.emitClose();
+    }
+}
+export class WebSocketTransport {
+    kind = 'websocket';
+    wss = new WebSocketServer({ noServer: true });
+    onConn = null;
+    start(onConnection) {
+        this.onConn = onConnection;
+        this.wss.on('connection', (ws, req) => {
+            const remote = req.socket.remoteAddress ? `${req.socket.remoteAddress}:${req.socket.remotePort}` : undefined;
+            const keepalive = setInterval(() => {
+                if (ws.readyState === ws.OPEN)
+                    ws.ping();
+            }, WS_KEEPALIVE_MS);
+            ws.on('close', () => clearInterval(keepalive));
+            this.onConn?.(new WsConnection(ws, remote));
+        });
+    }
+    /** Server wiring routes a matching upgrade request here. */
+    handleUpgrade(req, socket, head) {
+        this.wss.handleUpgrade(req, socket, head, (ws) => this.wss.emit('connection', ws, req));
+    }
+    stop() {
+        this.wss.close();
+    }
+}