herdr-remote-relay 0.3.12 → 0.3.13

package/dist/metrics.js

@@ -0,0 +1,249 @@
+import os from 'node:os';
+import { monitorEventLoopDelay } from 'node:perf_hooks';
+function finite(value, fallback = 0) {
+    return Number.isFinite(value) ? value : fallback;
+}
+function bytesPerSecond(current, previous, elapsedMs) {
+    if (!elapsedMs || elapsedMs <= 0)
+        return 0;
+    return Math.max(0, ((current - previous) * 1000) / elapsedMs);
+}
+/**
+ * How many people are attached, rather than how many sockets are open.
+ *
+ * A phone and a laptop belonging to one person are two connections but one
+ * paired device each, and one person opening three browser windows is three
+ * connections and one device — so the distinct paired device is the closest
+ * thing the relay has to a user. Connections that predate device pairing carry
+ * no `deviceId`; they fall back to their own connection id so they still count
+ * once instead of collapsing into a single anonymous user.
+ */
+function countActiveUsers(clients = []) {
+    const identities = new Set();
+    for (const client of clients) {
+        if (!client)
+            continue;
+        identities.add(typeof client.deviceId === 'string' && client.deviceId
+            ? `device:${client.deviceId}`
+            : `client:${client.id}`);
+    }
+    return identities.size;
+}
+class RelayMetrics {
+    version;
+    protocolVersion;
+    startedAt;
+    bytesIn;
+    bytesOut;
+    framesIn;
+    framesOut;
+    cleanup;
+    lastSample;
+    hostTraffic;
+    cpuSampleAt;
+    cpuSample;
+    eventLoop;
+    constructor({ version = '0.1.0', protocolVersion = 1 } = {}) {
+        this.version = version;
+        this.protocolVersion = protocolVersion;
+        this.startedAt = Date.now();
+        this.bytesIn = 0;
+        this.bytesOut = 0;
+        this.framesIn = 0;
+        this.framesOut = 0;
+        this.cleanup = {
+            staleClientsPurged: 0,
+            closedPtysCleaned: 0,
+            deadConnectionsClosed: 0,
+            idleHostsTerminated: 0,
+            slowClientsDropped: 0,
+            lastCleanupAt: null,
+        };
+        this.lastSample = { at: this.startedAt, bytesIn: 0, bytesOut: 0, framesIn: 0, framesOut: 0 };
+        this.hostTraffic = new Map();
+        this.cpuSampleAt = process.hrtime.bigint();
+        this.cpuSample = process.cpuUsage();
+        this.eventLoop = monitorEventLoopDelay({ resolution: 20 });
+        this.eventLoop.enable();
+    }
+    hostCounter(hostId) {
+        if (typeof hostId !== 'string' || hostId.length === 0)
+            return null;
+        let counter = this.hostTraffic.get(hostId);
+        if (!counter) {
+            counter = {
+                bytesIn: 0,
+                bytesOut: 0,
+                framesIn: 0,
+                framesOut: 0,
+                sampleAt: Date.now(),
+                sampleBytesIn: 0,
+                sampleBytesOut: 0,
+                sampleFramesIn: 0,
+                sampleFramesOut: 0,
+            };
+            this.hostTraffic.set(hostId, counter);
+        }
+        return counter;
+    }
+    recordIn(bytes, hostId = null) {
+        const amount = Math.max(0, Number(bytes) || 0);
+        this.bytesIn += amount;
+        this.framesIn += 1;
+        const counter = this.hostCounter(hostId);
+        if (counter) {
+            counter.bytesIn += amount;
+            counter.framesIn += 1;
+        }
+    }
+    recordOut(bytes, hostId = null) {
+        const amount = Math.max(0, Number(bytes) || 0);
+        this.bytesOut += amount;
+        this.framesOut += 1;
+        const counter = this.hostCounter(hostId);
+        if (counter) {
+            counter.bytesOut += amount;
+            counter.framesOut += 1;
+        }
+    }
+    forgetHost(hostId) {
+        if (typeof hostId === 'string')
+            this.hostTraffic.delete(hostId);
+    }
+    hostThroughput(hostId, now = Date.now()) {
+        const counter = this.hostCounter(hostId);
+        if (!counter)
+            return {
+                bytesIn: 0,
+                bytesOut: 0,
+                bytesInPerSec: 0,
+                bytesOutPerSec: 0,
+                framesIn: 0,
+                framesOut: 0,
+                framesInPerSec: 0,
+                framesOutPerSec: 0,
+            };
+        const elapsedMs = now - counter.sampleAt;
+        const throughput = {
+            bytesIn: counter.bytesIn,
+            bytesOut: counter.bytesOut,
+            bytesInPerSec: bytesPerSecond(counter.bytesIn, counter.sampleBytesIn, elapsedMs),
+            bytesOutPerSec: bytesPerSecond(counter.bytesOut, counter.sampleBytesOut, elapsedMs),
+            framesIn: counter.framesIn,
+            framesOut: counter.framesOut,
+            framesInPerSec: bytesPerSecond(counter.framesIn, counter.sampleFramesIn, elapsedMs),
+            framesOutPerSec: bytesPerSecond(counter.framesOut, counter.sampleFramesOut, elapsedMs),
+        };
+        counter.sampleAt = now;
+        counter.sampleBytesIn = counter.bytesIn;
+        counter.sampleBytesOut = counter.bytesOut;
+        counter.sampleFramesIn = counter.framesIn;
+        counter.sampleFramesOut = counter.framesOut;
+        return throughput;
+    }
+    recordCleanup(name, amount = 1) {
+        if (Object.hasOwn(this.cleanup, name) && typeof this.cleanup[name] === 'number') {
+            this.cleanup[name] += amount;
+        }
+        this.cleanup.lastCleanupAt = new Date().toISOString();
+    }
+    cpuPercent() {
+        const now = process.hrtime.bigint();
+        const elapsedNs = Number(now - this.cpuSampleAt);
+        const usage = process.cpuUsage(this.cpuSample);
+        this.cpuSampleAt = now;
+        this.cpuSample = process.cpuUsage();
+        if (elapsedNs <= 0)
+            return 0;
+        const percent = ((usage.user + usage.system) * 100000) / elapsedNs;
+        return Math.max(0, Math.round(percent * 100) / 100);
+    }
+    eventLoopDelay() {
+        const percentile = (value) => Math.round(finite(value / 1e6) * 100) / 100;
+        return {
+            p50Ms: percentile(this.eventLoop.percentile(50)),
+            p90Ms: percentile(this.eventLoop.percentile(90)),
+            p99Ms: percentile(this.eventLoop.percentile(99)),
+            maxMs: percentile(this.eventLoop.max),
+            meanMs: percentile(this.eventLoop.mean),
+        };
+    }
+    /**
+     * `activeUserCount` is passed in rather than derived from `clients`: the
+     * public `/api/status` rows deliberately omit `deviceId`, so only the caller
+     * still holding the full connection records can count devices correctly.
+     * Omitting it falls back to counting whatever the given rows identify.
+     */
+    snapshot({ clients = [], hosts = [], ptys = [], sample = true, scopeHostId = null, activeUserCount = null, } = {}) {
+        const now = Date.now();
+        const elapsedMs = now - this.lastSample.at;
+        const throughput = {
+            bytesIn: this.bytesIn,
+            bytesOut: this.bytesOut,
+            bytesInPerSec: bytesPerSecond(this.bytesIn, this.lastSample.bytesIn, elapsedMs),
+            bytesOutPerSec: bytesPerSecond(this.bytesOut, this.lastSample.bytesOut, elapsedMs),
+            framesIn: this.framesIn,
+            framesOut: this.framesOut,
+            framesInPerSec: bytesPerSecond(this.framesIn, this.lastSample.framesIn, elapsedMs),
+            framesOutPerSec: bytesPerSecond(this.framesOut, this.lastSample.framesOut, elapsedMs),
+        };
+        if (sample) {
+            this.lastSample = {
+                at: now,
+                bytesIn: this.bytesIn,
+                bytesOut: this.bytesOut,
+                framesIn: this.framesIn,
+                framesOut: this.framesOut,
+            };
+        }
+        const memory = process.memoryUsage();
+        const load = os.loadavg();
+        // Every attached window has full input, so there is no "active controller"
+        // to name: reporting the first of them as one had an operator reading a
+        // distinction that does not exist. The host is still worth naming, and any
+        // client knows which workstation it is on.
+        const anyClient = clients[0];
+        const scopedThroughput = scopeHostId ? this.hostThroughput(scopeHostId, now) : throughput;
+        return {
+            version: this.version,
+            protocolVersion: this.protocolVersion,
+            uptimeSeconds: Math.floor((now - this.startedAt) / 1000),
+            startTime: new Date(this.startedAt).toISOString(),
+            serverTime: new Date(now).toISOString(),
+            activeControllerId: null,
+            activeHostId: anyClient?.hostId || hosts[0]?.id || null,
+            clients,
+            hosts,
+            ptys,
+            clientCount: clients.length,
+            hostCount: hosts.length,
+            ptyCount: ptys.length,
+            activeUserCount: Number.isFinite(activeUserCount)
+                ? activeUserCount
+                : countActiveUsers(clients),
+            throughput: scopedThroughput,
+            cpu: {
+                load1m: finite(load[0]),
+                load5m: finite(load[1]),
+                load15m: finite(load[2]),
+                cpuPercent: this.cpuPercent(),
+                cores: os.cpus().length,
+            },
+            memory: {
+                rssBytes: memory.rss,
+                heapUsedBytes: memory.heapUsed,
+                heapTotalBytes: memory.heapTotal,
+                externalBytes: memory.external,
+                systemTotalBytes: os.totalmem(),
+                systemFreeBytes: os.freemem(),
+            },
+            eventLoopDelay: this.eventLoopDelay(),
+            cleanup: { ...this.cleanup },
+        };
+    }
+    close() {
+        this.eventLoop.disable();
+        this.hostTraffic.clear();
+    }
+}
+export { RelayMetrics, countActiveUsers };

package/dist/protocol/frames.d.ts

@@ -0,0 +1,27 @@
+export declare const PROTOCOL_VERSION = 1;
+export declare const MAX_HEADER_BYTES: number;
+export declare const FRAME_V2_MAGIC = 255;
+export declare const FRAME_TYPE_OUTPUT = 0;
+export declare const FRAME_TYPE_INPUT = 1;
+export type FrameTypeCode = typeof FRAME_TYPE_OUTPUT | typeof FRAME_TYPE_INPUT;
+export type FrameBytes = Buffer | Uint8Array | ArrayBuffer | readonly number[] | string;
+/** A v1 frame routes by a JSON header naming the stream. */
+export interface StreamFrameV1 {
+    version: 1;
+    type: string;
+    streamId: string;
+    payload: Buffer;
+}
+/** A v2 frame routes by a 16-bit stream index. */
+export interface StreamFrameV2 {
+    version: 2;
+    type: 'output' | 'input';
+    typeCode: FrameTypeCode;
+    streamIndex: number;
+    payload: Buffer;
+}
+export type StreamFrame = StreamFrameV1 | StreamFrameV2;
+export declare function packStreamFrame(type: string, streamId: string, payload?: FrameBytes): Buffer;
+export declare function packStreamFrameV2(type: 'output' | 'input' | FrameTypeCode, streamIndex: number, payload?: FrameBytes): Buffer;
+export declare function unpackStreamFrameV2(buffer: FrameBytes): StreamFrameV2;
+export declare function unpackStreamFrame(value: FrameBytes): StreamFrame;

package/dist/protocol/frames.js

@@ -0,0 +1,110 @@
+// Binary stream frames between the host connector and the relay. Node-only
+// (Buffer); browsers receive raw terminal bytes and never parse these.
+export const PROTOCOL_VERSION = 1;
+export const MAX_HEADER_BYTES = 8 * 1024;
+// Framing constants for compact binary frame protocol v2.
+// With permessage-deflate already enabled on the WebSocket connection, the repeated
+// JSON routing header in v1 frames was already compressed down to near-zero network overhead.
+// The actual motivation for v2 framing is reducing CPU consumption: eliminating the per-frame
+// JSON.stringify / JSON.parse serialization and string decoding overhead under heavy terminal output.
+export const FRAME_V2_MAGIC = 0xff;
+export const FRAME_TYPE_OUTPUT = 0;
+export const FRAME_TYPE_INPUT = 1;
+function toBuffer(value) {
+    if (Buffer.isBuffer(value))
+        return value;
+    if (typeof value === 'string')
+        return Buffer.from(value);
+    if (value instanceof ArrayBuffer)
+        return Buffer.from(value);
+    return Buffer.from(value);
+}
+export function packStreamFrame(type, streamId, payload = Buffer.alloc(0)) {
+    if (typeof type !== 'string' || !type || typeof streamId !== 'string' || !streamId) {
+        throw new TypeError('type and streamId must be non-empty strings');
+    }
+    const body = toBuffer(payload);
+    const header = Buffer.from(JSON.stringify({ type, streamId }), 'utf8');
+    if (header.length > MAX_HEADER_BYTES)
+        throw new RangeError('stream frame header is too large');
+    const length = Buffer.allocUnsafe(4);
+    length.writeUInt32BE(header.length, 0);
+    return Buffer.concat([length, header, body]);
+}
+function unpackStreamFrameV1(value) {
+    const frame = toBuffer(value);
+    if (frame.length < 4)
+        throw new Error('stream frame is truncated');
+    const headerLength = frame.readUInt32BE(0);
+    if (headerLength === 0 || headerLength > MAX_HEADER_BYTES || frame.length < 4 + headerLength) {
+        throw new Error('stream frame header is invalid');
+    }
+    let header;
+    try {
+        header = JSON.parse(frame.subarray(4, 4 + headerLength).toString('utf8'));
+    }
+    catch (error) {
+        throw new Error(`stream frame header is not JSON: ${error.message}`);
+    }
+    if (!header || typeof header.type !== 'string' || typeof header.streamId !== 'string') {
+        throw new Error('stream frame header is missing routing fields');
+    }
+    return {
+        version: 1,
+        type: header.type,
+        streamId: header.streamId,
+        payload: frame.subarray(4 + headerLength),
+    };
+}
+export function packStreamFrameV2(type, streamIndex, payload = Buffer.alloc(0)) {
+    let typeCode = type;
+    if (type === 'output')
+        typeCode = FRAME_TYPE_OUTPUT;
+    else if (type === 'input')
+        typeCode = FRAME_TYPE_INPUT;
+    if (typeCode !== FRAME_TYPE_OUTPUT && typeCode !== FRAME_TYPE_INPUT) {
+        throw new TypeError('type must be FRAME_TYPE_OUTPUT (0) or FRAME_TYPE_INPUT (1)');
+    }
+    if (!Number.isInteger(streamIndex) || streamIndex < 0 || streamIndex > 0xffff) {
+        throw new RangeError('streamIndex must be an unsigned 16-bit integer (0-65535)');
+    }
+    const body = toBuffer(payload);
+    const frame = Buffer.allocUnsafe(4 + body.length);
+    frame.writeUInt8(FRAME_V2_MAGIC, 0);
+    frame.writeUInt8(typeCode, 1);
+    frame.writeUInt16BE(streamIndex, 2);
+    body.copy(frame, 4);
+    return frame;
+}
+export function unpackStreamFrameV2(buffer) {
+    const frame = toBuffer(buffer);
+    if (frame.length < 4)
+        throw new Error('v2 stream frame is truncated');
+    const magic = frame.readUInt8(0);
+    if (magic !== FRAME_V2_MAGIC) {
+        throw new Error('invalid v2 stream frame magic byte');
+    }
+    const typeCode = frame.readUInt8(1);
+    if (typeCode !== FRAME_TYPE_OUTPUT && typeCode !== FRAME_TYPE_INPUT) {
+        throw new Error(`unknown v2 stream frame type: ${typeCode}`);
+    }
+    const streamIndex = frame.readUInt16BE(2);
+    return {
+        version: 2,
+        type: typeCode === FRAME_TYPE_OUTPUT ? 'output' : 'input',
+        typeCode,
+        streamIndex,
+        payload: frame.subarray(4),
+    };
+}
+export function unpackStreamFrame(value) {
+    const frame = toBuffer(value);
+    if (frame.length < 4)
+        throw new Error('stream frame is truncated');
+    // v1's headerLength is a 32-bit big-endian integer bounded by MAX_HEADER_BYTES (8KB),
+    // so its first byte is always 0x00. A first byte of 0xFF unambiguously identifies v2 framing.
+    if (frame[0] === FRAME_V2_MAGIC) {
+        return unpackStreamFrameV2(frame);
+    }
+    return unpackStreamFrameV1(frame);
+}

package/dist/protocol/http.d.ts

@@ -0,0 +1,161 @@
+export interface RelayInfoResponse {
+    ok: boolean;
+    version: string;
+    protocol: number;
+    relayMode: 'local' | 'remote';
+    adminConfigured: boolean;
+    adminPath: string;
+    adminStatusPath: string;
+    publicUrl?: string;
+}
+export interface RelayMetadata {
+    mode: 'local' | 'remote';
+    adminConfigured: boolean;
+    adminPath?: string;
+    adminStatusPath?: string;
+    dashboardPath?: string;
+    publicUrl?: string;
+    /** The address the relay listens on, and its port. */
+    bind?: string;
+    port?: number;
+    maxClientsPerHost?: number;
+    maxHosts?: number;
+    maxPendingHandshakes?: number;
+    maxBufferedBytesPerClient?: number;
+    hostReconnectGraceMs?: number;
+}
+export interface ConnectedClientInfo {
+    id: string;
+    role: 'controller' | 'viewer';
+    /** Absent from a host-scoped response, where every row belongs to one host. */
+    hostId?: string;
+    /** Operator-only: which paired device this connection authenticated as. */
+    deviceId?: string;
+    ip?: string | null;
+    userAgent?: string;
+    connectedAt: string;
+    lastPingAt?: string | null;
+    bytesReceived?: number;
+    bytesSent?: number;
+}
+/**
+ * A device that completed pairing and holds a long-lived token. Served only on
+ * `/api/admin/status`, never on `/api/status`.
+ */
+export interface PairedDeviceInfo {
+    deviceId: string;
+    hostId: string;
+    createdAt: string;
+    lastSeenAt: string;
+    expiresAt: number;
+    expiresAtIso: string;
+    userAgent?: string | null;
+    lastIp?: string | null;
+}
+export type HostStatus = 'online' | 'busy' | 'reconnecting' | 'offline';
+export interface HostInfo {
+    id: string;
+    hostname: string;
+    platform: string;
+    arch?: string;
+    status: HostStatus;
+    connectedAt: string;
+    activePtyCount: number;
+    /** Distinct devices attached to this host right now, not open sockets. */
+    connectedDeviceCount?: number;
+    /** Devices holding a valid pairing token for this host, online or not. */
+    pairedDeviceCount?: number;
+}
+export interface PtyInfo {
+    id: string;
+    /** Absent from a host-scoped response, where every row belongs to one host. */
+    hostId?: string;
+    pid: number | null;
+    command: string;
+    cols: number;
+    rows: number;
+    cwd?: string;
+    createdAt?: string;
+    activeClients: number;
+}
+export interface ThroughputMetrics {
+    bytesIn: number;
+    bytesOut: number;
+    bytesInPerSec: number;
+    bytesOutPerSec: number;
+    framesIn: number;
+    framesOut: number;
+    framesInPerSec: number;
+    framesOutPerSec: number;
+}
+export interface CpuLoadMetrics {
+    load1m: number;
+    load5m: number;
+    load15m: number;
+    cpuPercent: number;
+    cores: number;
+}
+export interface MemoryMetrics {
+    rssBytes: number;
+    heapUsedBytes: number;
+    heapTotalBytes: number;
+    externalBytes?: number;
+    systemTotalBytes?: number;
+    systemFreeBytes?: number;
+}
+export interface EventLoopDelayMetrics {
+    p50Ms: number;
+    p90Ms?: number;
+    p99Ms: number;
+    maxMs: number;
+    meanMs?: number;
+}
+export interface CleanupCounters {
+    staleClientsPurged: number;
+    closedPtysCleaned: number;
+    deadConnectionsClosed: number;
+    idleHostsTerminated: number;
+    slowClientsDropped?: number;
+    lastCleanupAt?: string | null;
+}
+export interface AdminStatusResponse {
+    version: string;
+    uptimeSeconds: number;
+    startTime: string;
+    serverTime: string;
+    activeControllerId?: string | null;
+    activeHostId?: string | null;
+    clients: ConnectedClientInfo[];
+    hosts: HostInfo[];
+    ptys: PtyInfo[];
+    /**
+     * Distinct people attached, counted by paired device rather than by socket,
+     * so several windows of one browser stay one user.
+     */
+    activeUserCount?: number;
+    /** Operator-only roster of paired devices; absent from `/api/status`. */
+    devices?: PairedDeviceInfo[];
+    throughput: ThroughputMetrics;
+    cpu: CpuLoadMetrics;
+    memory: MemoryMetrics;
+    eventLoopDelay: EventLoopDelayMetrics;
+    cleanup: CleanupCounters;
+    protocolVersion: number;
+    relay?: RelayMetadata;
+    isRemoteRelay?: boolean;
+    remoteAdminUrl?: string;
+    relayMode?: 'local' | 'remote';
+    [key: string]: unknown;
+}
+/** POST /api/pair/start, answered to a workstation's own host token. */
+export interface PairStartResponse {
+    ok: true;
+    code: string;
+    hostId: string;
+    publicUrl: string;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+    expiresAtIso: string;
+    /** The web app's address with the code filled in. */
+    pairUrl: string;
+}

package/dist/protocol/http.js

@@ -0,0 +1,3 @@
+// Bodies of the relay's HTTP API: GET /api/info, /api/status and
+// /api/admin/status, and POST /api/pair/start. Browser-safe: types only.
+export {};

package/dist/protocol/index.d.ts

@@ -0,0 +1,5 @@
+export * from './frames.js';
+export * from './terminal.js';
+export * from './messages.js';
+export * from './paste.js';
+export type * from './http.js';

package/dist/protocol/index.js

@@ -0,0 +1,7 @@
+// `herdr-remote-relay/protocol`: everything that crosses the wire between the
+// host connector, the relay and the browser. The single definition both
+// packages build against; nothing here may be copied into the CLI or the web.
+export * from './frames.js';
+export * from './terminal.js';
+export * from './messages.js';
+export * from './paste.js';