herdr-remote-relay 0.3.11 → 0.3.13

package/dist/server/transport.js

@@ -0,0 +1,110 @@
+// Sending to windows and hosts: terminal output with back-pressure, JSON
+// broadcasts, and the development-only latency queue.
+import { detachClient } from './sessions.js';
+import { isOpen, jsonSend } from './sockets.js';
+/** Notify the host whether any browser currently needs business telemetry. */
+export function notifyHostClientCount(host) {
+    if (!host || !isOpen(host.ws))
+        return;
+    jsonSend(host.ws, { type: 'client_count', clientCount: host.clients.size });
+}
+/**
+ * Forward output without allowing one slow browser to grow an unbounded ws
+ * queue. Closing only that browser preserves low latency for the other views.
+ */
+export function sendClientBinary(relay, host, client, payload) {
+    if (!client || !isOpen(client.ws))
+        return false;
+    const limit = relay.config.relay.maxBufferedBytesPerClient;
+    const buffered = Number(client.ws.bufferedAmount) || 0;
+    if (buffered + payload.length > limit) {
+        relay.metrics.recordCleanup('slowClientsDropped');
+        detachClient(relay, client, { notify: true, reason: 'slow_client', closeCode: 1013 });
+        return false;
+    }
+    let sent = false;
+    const doSend = () => {
+        if (!isOpen(client.ws))
+            return;
+        try {
+            client.ws.send(payload);
+            client.bytesSent += payload.length;
+            relay.metrics.recordOut(payload.length, host.id);
+            sent = true;
+        }
+        catch {
+            detachClient(relay, client, { notify: false, reason: 'client_send_failed', closeCode: 1011 });
+        }
+    };
+    if (relay.devLatencyMs > 0)
+        enqueueDelayedSend(relay, client.ws, doSend);
+    else
+        doSend();
+    return relay.devLatencyMs > 0 ? true : sent;
+}
+/**
+ * Queue artificial delay per-socket rather than using naked setTimeout calls.
+ * Concurrent timers experience event loop jitter that can deliver frames out of order;
+ * a single FIFO queue per socket guarantees strict in-order delivery of terminal frames.
+ */
+export function enqueueDelayedSend(relay, socket, task) {
+    let queue = relay.sendQueues.get(socket);
+    if (!queue) {
+        const created = { items: [], timer: null };
+        queue = created;
+        relay.sendQueues.set(socket, created);
+        socket.once('close', () => {
+            if (created.timer) {
+                clearTimeout(created.timer);
+                relay.activeDelayTimers.delete(created.timer);
+                created.timer = null;
+            }
+            created.items = [];
+        });
+    }
+    const sendAt = Date.now() + relay.devDelayMs;
+    queue.items.push({ sendAt, task });
+    if (!queue.timer) {
+        const pending = queue;
+        const timer = setTimeout(() => flushSendQueue(relay, socket, pending), relay.devDelayMs);
+        queue.timer = timer;
+        relay.activeDelayTimers.add(timer);
+    }
+}
+/**
+ * Drain ready frames in FIFO order up to the current timestamp, then schedule the
+ * single next timer if items remain. Ensures only one timer runs per socket at a time.
+ */
+function flushSendQueue(relay, socket, queue) {
+    if (queue.timer) {
+        relay.activeDelayTimers.delete(queue.timer);
+        queue.timer = null;
+    }
+    const now = Date.now();
+    while (queue.items.length > 0 && queue.items[0].sendAt <= now) {
+        const item = queue.items.shift();
+        try {
+            item?.task();
+        }
+        catch {
+            // A send to a socket that closed while queued is dropped like any other.
+        }
+    }
+    if (queue.items.length > 0 && !queue.timer) {
+        const nextDelay = Math.max(0, queue.items[0].sendAt - Date.now());
+        const timer = setTimeout(() => flushSendQueue(relay, socket, queue), nextDelay);
+        queue.timer = timer;
+        relay.activeDelayTimers.add(timer);
+    }
+}
+/** Send one JSON message to every browser attached to `host`. */
+export function broadcastToClients(relay, host, build) {
+    for (const clientId of [...host.clients]) {
+        const client = relay.clients.get(clientId);
+        if (!client)
+            continue;
+        const payload = build(client);
+        if (payload)
+            jsonSend(client.ws, payload);
+    }
+}

package/dist/server/types.d.ts

@@ -0,0 +1,123 @@
+import type { WebSocket } from 'ws';
+import type { AuthStore } from '../auth-store.js';
+import type { RelayMetrics } from '../metrics.js';
+import type { ClientRole, HostPtySummary, ServerAgentStatusMessage, ServerUpdateStatusMessage } from '../protocol/messages.js';
+import type { HostTerminalFont, HostTerminalPalette } from '../protocol/terminal.js';
+import type { RelayConfig } from '../relay-config.js';
+/** A WebSocket plus the liveness flag the heartbeat keeps on it. */
+export type RelaySocket = WebSocket & {
+    isAlive?: boolean;
+};
+/** One browser window's PTY stream on its host. */
+interface ClientSession {
+    streamId: string;
+    /** The v2 frame index, when the host negotiated v2 frames and one was free. */
+    streamIndex: number | null;
+    cols: number;
+    rows: number;
+    ready: boolean;
+}
+/** A connected workstation. */
+export interface RelayHost {
+    id: string;
+    ws: RelaySocket | null;
+    hostname: string;
+    platform: string;
+    arch: string;
+    connectedAt: string;
+    connectedAtMs: number;
+    terminalPalette: HostTerminalPalette | null;
+    terminalFont: HostTerminalFont | null;
+    /** The latest agent summary, replayed to a window that joins late. */
+    agentStatus: ServerAgentStatusMessage | null;
+    /** Whether the workstation's herdr-remote is behind; replayed the same way. */
+    updateStatus: ServerUpdateStatusMessage | null;
+    lastSeenAt: number;
+    /** Ids of the windows attached to this host. */
+    clients: Set<string>;
+    controllerId: null;
+    load: Record<string, unknown>;
+    ptys: HostPtySummary[];
+    reconnecting: boolean;
+    reconnectTimer: NodeJS.Timeout | null;
+    reconnectStartedAt?: number;
+    connectionGeneration: string;
+    handoffCapable: boolean;
+    binaryFrameV2: boolean;
+    /** v2 stream index → client id. */
+    streamIndices: Map<number, string>;
+    nextStreamIndex: number;
+    shutdownRequested: boolean;
+}
+/** A connected browser window. */
+export interface RelayClient {
+    id: string;
+    ws: RelaySocket | null;
+    hostId: string;
+    deviceId: string;
+    /** Stable per browser profile, supplied by the browser itself. */
+    browserClientId: string | null;
+    handoffCapable: boolean;
+    session: ClientSession | null;
+    role: ClientRole;
+    controllerId: null;
+    connectedAt: string;
+    connectedAtMs: number;
+    lastSeenAt: number;
+    lastPingAt: string | null;
+    bytesReceived: number;
+    bytesSent: number;
+    ip: string | null;
+    userAgent: string;
+    cols: number;
+    rows: number;
+    herdrStartAt?: number;
+    fontRefreshAt?: number;
+    /** When each outstanding font chunk request was sent. */
+    fontChunkRequests?: number[];
+    fontSubsetRequests?: number[];
+    /** Cut fonts this window may pull by hash, with their sizes. */
+    fontSubsets?: Map<string, number>;
+}
+/** Requests from one address within the current minute. */
+export interface AttemptWindow {
+    startedAt: number;
+    count: number;
+}
+/** Frames held back by the development latency switch, in order. */
+export interface SendQueue {
+    items: {
+        sendAt: number;
+        task: () => void;
+    }[];
+    timer: NodeJS.Timeout | null;
+}
+/** What the server modules share: the relay's state and two of its methods. */
+export interface RelayContext {
+    config: RelayConfig;
+    relayMode: 'local' | 'remote';
+    hosts: Map<string, RelayHost>;
+    clients: Map<string, RelayClient>;
+    /** Stream id → client id. */
+    streams: Map<string, string>;
+    pairAttempts: Map<string, AttemptWindow>;
+    clientHandshakeAttempts: Map<string, AttemptWindow>;
+    hostHandshakeAttempts: Map<string, AttemptWindow>;
+    startedAt: number;
+    metrics: RelayMetrics;
+    auth: AuthStore;
+    adminToken: string | null;
+    trustProxy: boolean;
+    devLatencyMs: number;
+    devDelayMs: number;
+    sendQueues: WeakMap<RelaySocket, SendQueue>;
+    activeDelayTimers: Set<NodeJS.Timeout>;
+    finishHandshake(ws: RelaySocket): void;
+    address(): {
+        host: string;
+        port: number;
+    } | {
+        path: string;
+    } | null;
+}
+export {};

package/dist/server/types.js

@@ -0,0 +1,3 @@
+// The relay's records for connected hosts and browser windows, and the state
+// every server module works on.
+export {};

package/dist/server/version.d.ts

@@ -0,0 +1,2 @@
+/** This relay's release, as its package.json names it. */
+export declare const VERSION: string;

package/dist/server/version.js

@@ -0,0 +1,5 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { PACKAGE_ROOT } from '../relay-config.js';
+/** This relay's release, as its package.json names it. */
+export const VERSION = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8')).version;

package/dist/state.d.ts

@@ -0,0 +1,6 @@
+declare function ensureDir(dirPath: string): void;
+declare function writeJsonAtomic(filePath: string, value: unknown): void;
+/** Parsed JSON at `filePath`, or `fallback` when it is missing or unreadable. */
+declare function readJson<T>(filePath: string, fallback: T): T;
+declare function randomToken(bytes?: number): string;
+export { ensureDir, writeJsonAtomic, readJson, randomToken };

package/dist/state.js

@@ -0,0 +1,47 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+function ensureDir(dirPath) {
+    fs.mkdirSync(dirPath, { recursive: true, mode: 0o700 });
+    try {
+        fs.chmodSync(dirPath, 0o700);
+    }
+    catch {
+        // Some filesystems (Windows, some mounts) ignore modes; mkdir already asked for 0700.
+    }
+}
+function writeJsonAtomic(filePath, value) {
+    ensureDir(path.dirname(filePath));
+    const tempPath = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+    fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    try {
+        fs.chmodSync(tempPath, 0o600);
+    }
+    catch {
+        // Some filesystems ignore modes; the file was written with 0600 already.
+    }
+    fs.renameSync(tempPath, filePath);
+    try {
+        fs.chmodSync(filePath, 0o600);
+    }
+    catch {
+        // Some filesystems ignore modes; the file was written with 0600 already.
+    }
+}
+/** Parsed JSON at `filePath`, or `fallback` when it is missing or unreadable. */
+function readJson(filePath, fallback) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch (error) {
+        const { code, message } = error;
+        if (code !== 'ENOENT') {
+            process.stderr.write(`herdr-remote: invalid state at ${filePath}: ${message}\n`);
+        }
+        return fallback;
+    }
+}
+function randomToken(bytes = 32) {
+    return crypto.randomBytes(bytes).toString('base64url');
+}
+export { ensureDir, writeJsonAtomic, readJson, randomToken };

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "herdr-remote-relay",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "description": "Standalone relay server and web terminal for Herdr Remote",
   "license": "MIT",
+  "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/dibin666/herdr-remote.git",
@@ -25,28 +26,51 @@
   "bin": {
     "herdr-remote-relay": "./bin/herdr-remote-relay.js"
   },
-  "main": "./src/relay-server.js",
+  "main": "./dist/relay-server.js",
+  "types": "./dist/relay-server.d.ts",
   "exports": {
-    ".": "./src/relay-server.js",
-    "./protocol": "./src/stream-frame.js",
-    "./config": "./src/relay-config.js",
+    ".": {
+      "types": "./dist/relay-server.d.ts",
+      "default": "./dist/relay-server.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol/index.d.ts",
+      "default": "./dist/protocol/index.js"
+    },
+    "./config": {
+      "types": "./dist/relay-config.d.ts",
+      "default": "./dist/relay-config.js"
+    },
+    "./state": {
+      "types": "./dist/state.d.ts",
+      "default": "./dist/state.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "bin",
-    "src",
+    "dist",
     "web/dist",
     "deploy",
     "config.example.json",
     "README.zh-CN.md"
   ],
   "scripts": {
-    "build": "npm --prefix web run build",
+    "build": "npm run build:server && npm --prefix web run build",
+    "build:server": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "prepack": "npm run build",
     "start": "node bin/herdr-remote-relay.js",
-    "test": "node --test tests/*.test.js"
+    "pretest": "npm run build:server",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "@types/ws": "^8.18.1",
+    "typescript": "~5.7.3",
+    "vitest": "^3.2.7"
   }
 }