herdr-remote 0.2.32 → 0.2.34

package/node_modules/herdr-remote-relay/dist/relay-server.js

@@ -0,0 +1,194 @@
+// The relay: one HTTP server that answers the API, serves the web app and
+// upgrades /ws/host and /ws/client. The work itself lives in ./server/.
+import http from 'node:http';
+import path from 'node:path';
+import { URL } from 'node:url';
+import { WebSocketServer } from 'ws';
+import { AuthStore } from './auth-store.js';
+import { RelayMetrics } from './metrics.js';
+import { PROTOCOL_VERSION, WS_CLIENT_PATH, WS_HOST_PATH } from './protocol/index.js';
+import { DEFAULTS, defaultStateDir, loadRelayConfig } from './relay-config.js';
+import { handleClientConnection } from './server/client-channel.js';
+import { handleHostConnection } from './server/host-channel.js';
+import { handleHttp } from './server/http-api.js';
+import { heartbeat, sweep } from './server/maintenance.js';
+import { isAllowedOrigin } from './server/requests.js';
+import { detachClient, detachHost } from './server/sessions.js';
+import { VERSION } from './server/version.js';
+import { ensureDir } from './state.js';
+class RelayServer {
+    config;
+    relayMode;
+    hosts = new Map();
+    clients = new Map();
+    streams = new Map();
+    pairAttempts = new Map();
+    clientHandshakeAttempts = new Map();
+    hostHandshakeAttempts = new Map();
+    /** Sockets that are upgraded but have not finished their hello. */
+    pendingHandshakes = new Set();
+    startedAt = Date.now();
+    metrics;
+    stateFile;
+    password;
+    adminToken;
+    trustProxy;
+    devLatencyMs;
+    devDelayMs;
+    sendQueues = new WeakMap();
+    activeDelayTimers = new Set();
+    auth;
+    server;
+    wss;
+    heartbeatTimer = null;
+    cleanupTimer = null;
+    constructor(config = loadRelayConfig().config, options = {}) {
+        this.config = {
+            relay: { ...DEFAULTS.relay, ...config.relay },
+            auth: { ...DEFAULTS.auth, ...config.auth },
+            cleanup: { ...DEFAULTS.cleanup, ...config.cleanup },
+        };
+        const { relay, auth } = this.config;
+        this.relayMode = relay.mode === 'local' ? 'local' : 'remote';
+        this.metrics =
+            options.metrics || new RelayMetrics({ version: VERSION, protocolVersion: PROTOCOL_VERSION });
+        this.stateFile =
+            options.stateFile || auth.stateFile || path.join(defaultStateDir(), 'relay-auth.json');
+        this.password = options.password ?? auth.password ?? null;
+        this.adminToken = options.adminToken ?? auth.adminToken ?? null;
+        this.trustProxy = Boolean(options.trustProxy ?? relay.trustProxy);
+        // Development-only artificial latency switch for local responsiveness profiling.
+        // When unset or 0, this incurs zero overhead and avoids entering the delayed path.
+        // RELAY_DEV_LATENCY_MS specifies round-trip delay, so each one-way leg
+        // (host -> browser and browser -> host) is delayed by half.
+        const devLatencyRaw = options.devLatencyMs ?? relay.devLatencyMs ?? process.env.RELAY_DEV_LATENCY_MS;
+        this.devLatencyMs = devLatencyRaw
+            ? Math.max(0, Number.parseInt(String(devLatencyRaw), 10) || 0)
+            : 0;
+        this.devDelayMs = this.devLatencyMs > 0 ? Math.round(this.devLatencyMs / 2) : 0;
+        this.auth =
+            options.auth ||
+                new AuthStore({
+                    stateFile: this.stateFile,
+                    pairingTtlMs: auth.pairingTtlMs,
+                    deviceTtlMs: auth.deviceTtlMs,
+                    maxDevices: auth.maxDevices,
+                    password: this.password,
+                });
+        this.server = http.createServer((req, res) => handleHttp(this, req, res));
+        this.wss = new WebSocketServer({
+            noServer: true,
+            clientTracking: false,
+            maxPayload: relay.maxPayloadBytes,
+            // Frames below 1024 bytes bypass compression completely, ensuring single
+            // keystrokes and small echoes incur zero CPU and zero buffering delay.
+            // Keeping context across messages (NoContextTakeover=false) maximizes
+            // compression ratios on highly repetitive full-screen ratatui/ANSI redraws;
+            // level 3 provides low CPU cost and low latency over peak compression.
+            perMessageDeflate: {
+                threshold: 1024,
+                zlibDeflateOptions: { level: 3 },
+                serverNoContextTakeover: false,
+                clientNoContextTakeover: false,
+                concurrencyLimit: 10,
+            },
+        });
+        this.server.on('upgrade', (req, socket, head) => this.handleUpgrade(req, socket, head));
+    }
+    listen(port = this.config.relay.port, host = this.config.relay.host) {
+        ensureDir(path.dirname(this.stateFile));
+        return new Promise((resolve, reject) => {
+            const onError = (error) => {
+                this.server.off('listening', onListening);
+                reject(error);
+            };
+            const onListening = () => {
+                this.server.off('error', onError);
+                this.heartbeatTimer = setInterval(() => heartbeat(this), this.config.cleanup.heartbeatIntervalMs);
+                this.cleanupTimer = setInterval(() => sweep(this), this.config.cleanup.intervalMs);
+                resolve(this.address());
+            };
+            this.server.once('error', onError);
+            this.server.once('listening', onListening);
+            this.server.listen(port, host);
+        });
+    }
+    address() {
+        const address = this.server.address();
+        if (!address)
+            return null;
+        return typeof address === 'string'
+            ? { path: address }
+            : { host: address.address, port: address.port };
+    }
+    async close() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        if (this.cleanupTimer)
+            clearInterval(this.cleanupTimer);
+        this.heartbeatTimer = null;
+        this.cleanupTimer = null;
+        for (const timer of this.activeDelayTimers)
+            clearTimeout(timer);
+        this.activeDelayTimers.clear();
+        for (const client of [...this.clients.values()])
+            detachClient(this, client, { notify: false });
+        for (const host of [...this.hosts.values()])
+            detachHost(this, host, { notify: false });
+        this.streams.clear();
+        this.pairAttempts.clear();
+        this.clientHandshakeAttempts.clear();
+        this.hostHandshakeAttempts.clear();
+        this.pendingHandshakes.clear();
+        this.metrics.close();
+        await new Promise((resolve) => {
+            if (!this.server.listening)
+                return resolve();
+            this.server.close(() => resolve());
+        });
+    }
+    handleUpgrade(req, socket, head) {
+        const pathname = (() => {
+            try {
+                return new URL(req.url || '', 'http://localhost').pathname;
+            }
+            catch {
+                return '';
+            }
+        })();
+        if (![WS_HOST_PATH, WS_CLIENT_PATH].includes(pathname) ||
+            !isAllowedOrigin(this, req.headers.origin, req)) {
+            socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+            socket.destroy();
+            return;
+        }
+        if (this.pendingHandshakes.size >= this.config.relay.maxPendingHandshakes) {
+            socket.write('HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\n\r\n');
+            socket.destroy();
+            return;
+        }
+        // Small ANSI/input frames should not wait behind Nagle's timer. This is
+        // safe for both plain HTTP and TLS sockets and also benefits a relay behind
+        // a reverse proxy by keeping the relay leg immediately writable.
+        try {
+            const tcp = socket;
+            tcp.setNoDelay(true);
+            tcp.setKeepAlive?.(true, this.config.cleanup.heartbeatIntervalMs);
+        }
+        catch {
+            // Not a TCP socket (tests, proxies); these are only latency and liveness tweaks.
+        }
+        this.wss.handleUpgrade(req, socket, head, (ws) => {
+            this.pendingHandshakes.add(ws);
+            ws.once('close', () => this.finishHandshake(ws));
+            if (pathname === WS_HOST_PATH)
+                handleHostConnection(this, ws, req);
+            else
+                handleClientConnection(this, ws, req);
+        });
+    }
+    finishHandshake(ws) {
+        this.pendingHandshakes.delete(ws);
+    }
+}
+export { RelayServer, PROTOCOL_VERSION, VERSION };

package/node_modules/herdr-remote-relay/dist/scroll-input.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Wheel-report recognition for read-only clients.
+ *
+ * A viewer holds no control lease and may not type into the terminal. It may
+ * still scroll, for the same reason `resize` does not require the lease: every
+ * client drives its *own* PTY stream (`session_start` is emitted per client
+ * with `streamId: client.id`), so a wheel report moves only that viewer's own
+ * screen and cannot disturb the controller.
+ *
+ * This module is the trust boundary for that allowance, so the match is exact
+ * rather than heuristic. A frame is forwarded only when it consists entirely
+ * of wheel reports in the encodings a terminal emits; a single stray byte —
+ * a keystroke, a click, a drag — rejects the whole frame.
+ */
+/** Whether every byte of `payload`, a raw client input frame, belongs to a wheel report. */
+declare function isWheelOnlyInput(payload: Uint8Array | ArrayBuffer | null | undefined): boolean;
+export { isWheelOnlyInput };

package/node_modules/herdr-remote-relay/dist/scroll-input.js

@@ -0,0 +1,124 @@
+/**
+ * Wheel-report recognition for read-only clients.
+ *
+ * A viewer holds no control lease and may not type into the terminal. It may
+ * still scroll, for the same reason `resize` does not require the lease: every
+ * client drives its *own* PTY stream (`session_start` is emitted per client
+ * with `streamId: client.id`), so a wheel report moves only that viewer's own
+ * screen and cannot disturb the controller.
+ *
+ * This module is the trust boundary for that allowance, so the match is exact
+ * rather than heuristic. A frame is forwarded only when it consists entirely
+ * of wheel reports in the encodings a terminal emits; a single stray byte —
+ * a keystroke, a click, a drag — rejects the whole frame.
+ */
+const ESC = 0x1b;
+const LEFT_BRACKET = 0x5b; // [
+const LESS_THAN = 0x3c; // <
+const SEMICOLON = 0x3b; // ;
+const UPPER_M = 0x4d; // M
+const ZERO = 0x30;
+const NINE = 0x39;
+/**
+ * The wheel sets bit 64 of the event code; bit 1 is up/down and bits 4/8/16
+ * are shift/alt/ctrl. Every other bit belongs to something that is not a
+ * wheel: bit 32 marks motion, bits 2 and 128 select other buttons.
+ */
+const WHEEL_BASE = 64;
+const WHEEL_CODE_MASK = ~(1 | 4 | 8 | 16);
+/** Single-byte (X10) parameters are biased by 32 and cannot exceed one byte. */
+const X10_PARAM_BIAS = 32;
+const X10_PARAM_MAX = 255;
+function isWheelCode(code) {
+    return Number.isInteger(code) && (code & WHEEL_CODE_MASK) === WHEEL_BASE;
+}
+function isDigit(byte) {
+    return byte >= ZERO && byte <= NINE;
+}
+/** Reads one decimal parameter. */
+function readNumber(bytes, start) {
+    let index = start;
+    let value = 0;
+    while (index < bytes.length && isDigit(bytes[index])) {
+        value = value * 10 + (bytes[index] - ZERO);
+        // A parameter long enough to overflow is not something a terminal emits.
+        if (value > 0xffff)
+            return null;
+        index += 1;
+    }
+    if (index === start)
+        return null;
+    return { value, next: index };
+}
+/**
+ * Matches `ESC [ < Pb ; Px ; Py M`, the SGR and SGR-pixels encodings.
+ * @returns offset after the report, or -1
+ */
+function matchSgrWheel(bytes, start) {
+    if (bytes[start] !== ESC || bytes[start + 1] !== LEFT_BRACKET || bytes[start + 2] !== LESS_THAN) {
+        return -1;
+    }
+    const code = readNumber(bytes, start + 3);
+    if (!code || !isWheelCode(code.value) || bytes[code.next] !== SEMICOLON)
+        return -1;
+    const first = readNumber(bytes, code.next + 1);
+    if (!first || bytes[first.next] !== SEMICOLON)
+        return -1;
+    const second = readNumber(bytes, first.next + 1);
+    if (!second)
+        return -1;
+    // A wheel is never released, so the terminator is always `M`. Accepting `m`
+    // here would admit button releases, which are not scrolling.
+    if (bytes[second.next] !== UPPER_M)
+        return -1;
+    return second.next + 1;
+}
+/**
+ * Matches `ESC [ M Pb Px Py`, the default single-byte encoding.
+ * @returns offset after the report, or -1
+ */
+function matchX10Wheel(bytes, start) {
+    if (bytes[start] !== ESC || bytes[start + 1] !== LEFT_BRACKET || bytes[start + 2] !== UPPER_M) {
+        return -1;
+    }
+    if (start + 6 > bytes.length)
+        return -1;
+    const code = bytes[start + 3] - X10_PARAM_BIAS;
+    const column = bytes[start + 4];
+    const row = bytes[start + 5];
+    if (!isWheelCode(code))
+        return -1;
+    if (column < X10_PARAM_BIAS || column > X10_PARAM_MAX)
+        return -1;
+    if (row < X10_PARAM_BIAS || row > X10_PARAM_MAX)
+        return -1;
+    return start + 6;
+}
+/** Whether every byte of `payload`, a raw client input frame, belongs to a wheel report. */
+function isWheelOnlyInput(payload) {
+    if (!payload)
+        return false;
+    const bytes = payload instanceof Uint8Array
+        ? payload
+        : payload instanceof ArrayBuffer
+            ? new Uint8Array(payload)
+            : null;
+    if (!bytes || bytes.length === 0)
+        return false;
+    let offset = 0;
+    while (offset < bytes.length) {
+        const sgr = matchSgrWheel(bytes, offset);
+        if (sgr > offset) {
+            offset = sgr;
+            continue;
+        }
+        const x10 = matchX10Wheel(bytes, offset);
+        if (x10 > offset) {
+            offset = x10;
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+export { isWheelOnlyInput };

package/node_modules/herdr-remote-relay/dist/server/client-channel.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage } from 'node:http';
+import type { RelayContext, RelaySocket } from './types.js';
+export declare function handleClientConnection(relay: RelayContext, ws: RelaySocket, req: IncomingMessage): void;