herdr-remote 0.2.38 → 0.3.31

package/dist/connector/host-connector.js

@@ -1,433 +0,0 @@
-// The workstation's link to the relay: connect and reconnect, say hello, keep
-// the socket alive, report load while someone watches, and hand each relay
-// message to the part of the connector that owns it.
-import os from 'node:os';
-import path from 'node:path';
-import { unpackStreamFrame } from 'herdr-remote-relay/protocol';
-import { WebSocket } from 'ws';
-import { loadConfig } from '../config.js';
-import { EXIT_AUTH_FAILED, EXIT_REPLACED } from '../exit-codes.js';
-import { cleanPastedDir, savePastedFile } from '../pasted-files.js';
-import { stateDir } from '../paths.js';
-import { hostWebSocketUrl, resolveHostRelayUrl } from '../relay-urls.js';
-import { resolveSocketPath } from '../socket-discovery.js';
-import { resolveHostPalette } from '../terminal-palette.js';
-import { randomToken } from 'herdr-remote-relay/state';
-import { openAdminTabFor } from './admin-tab.js';
-import { AgentWatch } from './agent-watch.js';
-import { FontServer } from './font-server.js';
-import { hostHello } from './host-hello.js';
-import { acquireHostLock, releaseHostLock } from './lock.js';
-import { Sessions } from './sessions.js';
-import { UpdateReport } from './update-report.js';
-import { closeSocket, sendJson, streamOf, terminateSocket } from './wire.js';
-/** Handshake errors that no reconnect can fix. */
-const AUTH_ERROR_CODES = [
-    'relay_password_required',
-    'host_auth_failed',
-    'invalid_host_credentials',
-];
-export class HostConnector {
-    config;
-    relayUrl;
-    hostId;
-    hostToken;
-    relayPassword;
-    socketPath;
-    /**
-     * What the workstation's own terminal looks like. A browser has no way to
-     * know it — the PTY carries color indices, not colors — so the host reports
-     * it and the browser renders the session the way the workstation sees it.
-     * Normally captured by the start path that still had a terminal and passed
-     * down in the environment; `null` when nobody could ask.
-     */
-    terminalPalette;
-    sessions;
-    font;
-    agents;
-    updates;
-    ws = null;
-    reconnectTimer = null;
-    heartbeatTimer = null;
-    keepaliveTimer = null;
-    reconnectAttempts = 0;
-    clientCount = 0;
-    /** The relay predates `client_count`; report load all the time, as it expects. */
-    legacyHeartbeat = false;
-    authFailure = false;
-    stopping = false;
-    lockPath;
-    lockFd = null;
-    onFatal;
-    constructor(options = {}) {
-        const config = options.config || loadConfig();
-        this.config = config;
-        this.relayUrl =
-            options.relayUrl ||
-                (process.env.RELAY_URL
-                    ? hostWebSocketUrl(process.env.RELAY_URL)
-                    : resolveHostRelayUrl(config));
-        this.hostId = options.hostId || process.env.RELAY_HOST_ID || `host-${randomToken(9)}`;
-        this.hostToken = options.hostToken || process.env.RELAY_HOST_TOKEN || '';
-        // Optional; a relay without a password accepts any workstation.
-        this.relayPassword = options.relayPassword ?? process.env.RELAY_PASSWORD ?? '';
-        this.socketPath = options.socketPath || resolveSocketPath(config.herdr.socketPath);
-        this.terminalPalette =
-            options.terminalPalette !== undefined ? options.terminalPalette : resolveHostPalette();
-        const send = (payload) => sendJson(this.ws, payload);
-        this.sessions = new Sessions({
-            ...options,
-            socketPath: this.socketPath,
-            herdrArgs: options.herdrArgs || config.herdr.args,
-            cwd: options.cwd || config.herdr.cwd,
-            herdrLogPath: options.herdrLogPath || path.join(stateDir(), 'herdr-server.log'),
-        }, {
-            send,
-            sendFrame: (frame) => {
-                if (this.ws?.readyState === WebSocket.OPEN)
-                    this.ws.send(frame);
-            },
-            changed: () => this.sendHeartbeat(),
-        });
-        this.font = new FontServer(options, send);
-        this.agents = new AgentWatch({ ...options, socketPath: this.socketPath }, send);
-        this.updates = new UpdateReport(options, send);
-        this.lockPath =
-            options.lockPath ||
-                process.env.HERDR_REMOTE_HOST_LOCK ||
-                path.join(stateDir(), 'host-connector.lock');
-        this.onFatal = options.onFatal || ((exitCode) => process.exit(exitCode));
-        try {
-            cleanPastedDir();
-        }
-        catch {
-            // Old pastes are tidied again next start; a connector must still come up.
-        }
-    }
-    acquireLock() {
-        if (this.lockFd !== null)
-            return;
-        this.lockFd = acquireHostLock(this.lockPath, this.hostId);
-    }
-    releaseLock() {
-        if (this.lockFd === null)
-            return;
-        releaseHostLock(this.lockPath, this.lockFd);
-        this.lockFd = null;
-    }
-    start() {
-        if (!this.hostToken) {
-            throw new Error('RELAY_HOST_TOKEN is required');
-        }
-        this.acquireLock();
-        this.stopping = false;
-        this.connect();
-        // Off unless the user switched it on: Herdr is theirs to start.
-        if (this.config.herdr?.autoStart) {
-            this.sessions.startHerdr().catch((error) => {
-                process.stderr.write(`herdr-remote host connector: could not start Herdr: ${error.message}\n`);
-            });
-        }
-    }
-    stop() {
-        this.stopping = true;
-        if (this.reconnectTimer)
-            clearTimeout(this.reconnectTimer);
-        this.reconnectTimer = null;
-        sendJson(this.ws, { type: 'host_shutdown' });
-        this.disconnected();
-        closeSocket(this.ws, 'host_shutdown');
-        this.ws = null;
-        this.releaseLock();
-    }
-    /** Forget everything that lived on the relay connection. */
-    disconnected() {
-        if (this.heartbeatTimer)
-            clearInterval(this.heartbeatTimer);
-        this.heartbeatTimer = null;
-        this.stopKeepalive();
-        // Nothing to report to, so stop asking Herdr. A reconnect brings the
-        // watcher back with the relay's next client count.
-        this.agents.stop();
-        this.clientCount = 0;
-        this.legacyHeartbeat = false;
-        this.sessions.stopAll();
-    }
-    connect() {
-        if (this.stopping ||
-            this.ws?.readyState === WebSocket.OPEN ||
-            this.ws?.readyState === WebSocket.CONNECTING)
-            return;
-        this.stopKeepalive();
-        let ws;
-        try {
-            ws = new WebSocket(this.relayUrl);
-        }
-        catch (error) {
-            this.scheduleReconnect(error);
-            return;
-        }
-        this.ws = ws;
-        ws.isAlive = true;
-        ws.on('open', () => {
-            // Disable Nagle's algorithm to prevent small frames from stalling ~40ms when delayed ACK is active.
-            try {
-                ws._socket?.setNoDelay(true);
-            }
-            catch {
-                // The socket may not be TCP (tests) or already gone; Nagle is only a latency tweak.
-            }
-            ws.isAlive = true;
-            this.authFailure = false;
-            sendJson(ws, hostHello({
-                hostId: this.hostId,
-                token: this.hostToken,
-                password: this.relayPassword,
-                version: this.updates.runningVersion,
-                terminalPalette: this.terminalPalette,
-                terminalFont: this.font.publicFont(),
-            }));
-            // The relay sends host_ready with the current browser count. No business
-            // heartbeat is started until that message says somebody is watching.
-        });
-        ws.on('pong', () => {
-            ws.isAlive = true;
-        });
-        ws.on('message', (raw, isBinary) => this.handleMessage(raw, isBinary));
-        ws.on('close', (_code, rawReason) => {
-            // A replacement socket may be live while an older socket is still
-            // delivering its close event. Never let that stale event destroy the new
-            // session or clear its heartbeat timer.
-            if (this.ws !== ws)
-                return;
-            this.ws = null;
-            this.disconnected();
-            // Another connector has claimed this workstation. Reconnecting would just
-            // displace it in turn, and each swap drops every attached browser, so
-            // stand down instead of fighting for the slot.
-            const reason = rawReason ? rawReason.toString() : '';
-            if (reason === 'host_replaced') {
-                process.stderr.write('herdr-remote host connector: another instance took over this workstation; exiting\n');
-                this.stop();
-                this.onFatal(EXIT_REPLACED);
-                return;
-            }
-            if (this.authFailure) {
-                this.stopping = true;
-                process.stderr.write('herdr-remote host connector: authentication failed; update relay credentials and restart the service\n');
-                this.releaseLock();
-                this.onFatal(EXIT_AUTH_FAILED);
-                return;
-            }
-            this.scheduleReconnect();
-        });
-        ws.on('error', (error) => {
-            process.stderr.write(`herdr-remote host connector: ${error.message}\n`);
-        });
-    }
-    scheduleReconnect(error = null) {
-        if (this.stopping || this.reconnectTimer)
-            return;
-        if (error)
-            process.stderr.write(`herdr-remote host connector: ${error.message}\n`);
-        const delay = Math.min(30_000, 500 * 1.5 ** this.reconnectAttempts + Math.floor(Math.random() * 250));
-        this.reconnectAttempts += 1;
-        this.reconnectTimer = setTimeout(() => {
-            this.reconnectTimer = null;
-            this.connect();
-        }, delay);
-    }
-    handleMessage(raw, isBinary = false) {
-        if (isBinary) {
-            this.handleFrame(raw);
-            return undefined;
-        }
-        let message;
-        try {
-            message = JSON.parse(typeof raw === 'string' ? raw : raw.toString('utf8'));
-        }
-        catch {
-            // Not JSON: nothing a relay speaking this protocol would send.
-            return undefined;
-        }
-        switch (message.type) {
-            case 'error':
-                // A relay-level error (no clientId) is a rejected handshake — a wrong
-                // relay password, or a host token the relay does not recognise. Without
-                // this the connection just closed silently and reconnected forever,
-                // leaving the user with an empty log and no idea what was wrong.
-                if (message.clientId)
-                    return undefined;
-                this.authFailure = AUTH_ERROR_CODES.includes(message.code);
-                process.stderr.write(`herdr-remote host connector: relay rejected the connection: ${message.message || message.code}\n`);
-                return undefined;
-            case 'host_ready':
-                this.hostReady(message);
-                return undefined;
-            case 'client_count':
-                this.setClientCount(message.clientCount);
-                return undefined;
-            case 'session_start':
-                return this.startSession(message);
-            case 'herdr_start':
-                return this.sessions.startHerdrFor(streamOf(message));
-            case 'admin_tab_open':
-                return openAdminTabFor(streamOf(message), {
-                    socketPath: this.socketPath,
-                    language: this.config.ui?.language,
-                    send: (payload) => sendJson(this.ws, payload),
-                });
-            case 'session_stop': {
-                const streamId = streamOf(message);
-                if (streamId)
-                    this.sessions.stop(streamId);
-                return undefined;
-            }
-            case 'resize':
-                this.sessions.resize(message);
-                return undefined;
-            case 'paste_file':
-                this.savePaste(streamOf(message), message);
-                return undefined;
-            case 'host_font_chunk_request':
-                this.font.sendChunk(streamOf(message), message);
-                return undefined;
-            case 'host_font_subset_request':
-                this.font.sendSubset(streamOf(message), message);
-                return undefined;
-            case 'host_font_refresh':
-                this.font.refresh();
-                return undefined;
-            default:
-                return undefined;
-        }
-    }
-    handleFrame(raw) {
-        let frame;
-        try {
-            frame = unpackStreamFrame(raw);
-        }
-        catch (error) {
-            process.stderr.write(`herdr-remote host connector: invalid relay frame: ${error.message}\n`);
-            return;
-        }
-        if (frame.type !== 'input')
-            return;
-        this.sessions.write(frame.version === 2 ? { streamIndex: frame.streamIndex } : { streamId: frame.streamId }, frame.payload);
-    }
-    hostReady(message) {
-        this.reconnectAttempts = 0;
-        this.startKeepalive();
-        if (Object.hasOwn(message, 'clientCount')) {
-            this.legacyHeartbeat = false;
-            this.setClientCount(message.clientCount);
-            return;
-        }
-        // An older relay does not know client_count. Keep its historical
-        // telemetry behavior so rolling upgrades do not silently lose status.
-        this.legacyHeartbeat = true;
-        this.sendHeartbeat(true);
-        this.heartbeatTimer = setInterval(() => this.sendHeartbeat(), this.config.cleanup.heartbeatIntervalMs);
-    }
-    startSession(message) {
-        if (!streamOf(message))
-            return undefined;
-        // A window opening is when a person is looking; that is when to ask.
-        this.updates.report();
-        this.font.pickUp();
-        return this.sessions.start(message);
-    }
-    savePaste(streamId, message) {
-        try {
-            const savedPath = savePastedFile({ mime: message.mime, dataBase64: message.dataBase64 });
-            sendJson(this.ws, { type: 'paste_file_ready', clientId: streamId, path: savedPath });
-        }
-        catch (error) {
-            sendJson(this.ws, {
-                type: 'error',
-                clientId: streamId,
-                code: 'paste_file_write_failed',
-                message: error.message || 'Failed to save pasted file',
-            });
-        }
-    }
-    startKeepalive() {
-        this.stopKeepalive();
-        if (!this.ws || this.stopping)
-            return;
-        this.ws.isAlive = true;
-        const interval = this.config?.cleanup?.heartbeatIntervalMs || 30_000;
-        this.keepaliveTimer = setInterval(() => this.tickKeepalive(), interval);
-    }
-    stopKeepalive() {
-        if (this.keepaliveTimer) {
-            clearInterval(this.keepaliveTimer);
-            this.keepaliveTimer = null;
-        }
-    }
-    tickKeepalive() {
-        const ws = this.ws;
-        if (!ws || this.stopping)
-            return;
-        if (ws.readyState === WebSocket.CLOSING) {
-            terminateSocket(ws);
-            return;
-        }
-        if (ws.readyState !== WebSocket.OPEN)
-            return;
-        if (!ws.isAlive) {
-            terminateSocket(ws);
-            return;
-        }
-        ws.isAlive = false;
-        try {
-            if (typeof ws.ping === 'function')
-                ws.ping();
-        }
-        catch {
-            // A socket failing mid-ping is caught by the next heartbeat, which terminates it.
-        }
-        if (this.clientCount <= 0 && !this.legacyHeartbeat) {
-            sendJson(ws, { type: 'heartbeat', load: {}, ptys: [] });
-        }
-    }
-    setClientCount(value) {
-        const next = Number.isInteger(value) ? Math.max(0, value) : 0;
-        if (next === this.clientCount && (next === 0 || this.heartbeatTimer))
-            return;
-        const wasActive = this.clientCount > 0;
-        this.clientCount = next;
-        if (this.heartbeatTimer)
-            clearInterval(this.heartbeatTimer);
-        this.heartbeatTimer = null;
-        if (next > 0) {
-            this.sendHeartbeat(true);
-            this.heartbeatTimer = setInterval(() => this.sendHeartbeat(), this.config.cleanup.heartbeatIntervalMs);
-        }
-        else if (wasActive) {
-            this.sendHeartbeat(true);
-        }
-        // Nobody watching, nothing to ask Herdr about itself.
-        if (next > 0 && !this.stopping)
-            this.agents.start();
-        else
-            this.agents.stop();
-    }
-    sendHeartbeat(force = false) {
-        if (!force && this.clientCount <= 0 && !this.legacyHeartbeat)
-            return;
-        const memory = process.memoryUsage();
-        const load = os.loadavg();
-        sendJson(this.ws, {
-            type: 'heartbeat',
-            load: {
-                load1m: load[0] || 0,
-                load5m: load[1] || 0,
-                load15m: load[2] || 0,
-                rssBytes: memory.rss,
-                heapUsedBytes: memory.heapUsed,
-            },
-            ptys: this.sessions.summaries(),
-        });
-    }
-}

package/dist/connector/host-hello.js

@@ -1,32 +0,0 @@
-// The first message a workstation sends the relay: who it is, what it runs,
-// and the facts about its terminal and Herdr that a browser cannot learn itself.
-import os from 'node:os';
-import { CAPABILITY, PROTOCOL_VERSION } from 'herdr-remote-relay/protocol';
-import { readHerdrPrefixKeys } from './herdr-prefix-keys.js';
-/** Built afresh for each connection, so a reconnect reports the config as it is now. */
-export function hostHello(identity) {
-    return {
-        type: 'host_hello',
-        protocol: PROTOCOL_VERSION,
-        hostId: identity.hostId,
-        token: identity.token,
-        password: identity.password || null,
-        hostname: os.hostname(),
-        platform: process.platform,
-        ...(process.platform === 'win32' &&
-            (process.env.MSYSTEM || /(?:^|[\\/])(?:bash|sh)(?:\.exe)?$/i.test(process.env.SHELL || ''))
-            ? { shellProfile: 'git-bash' }
-            : {}),
-        arch: process.arch,
-        version: identity.version,
-        terminalPalette: identity.terminalPalette || null,
-        terminalFont: identity.terminalFont,
-        herdrPrefixKeys: readHerdrPrefixKeys(),
-        capabilities: [
-            CAPABILITY.hostHandoff,
-            CAPABILITY.idleHeartbeat,
-            CAPABILITY.binaryFrameV2,
-            ...(process.platform === 'win32' ? [CAPABILITY.adminTabs] : []),
-        ],
-    };
-}

package/dist/connector/lock.js

@@ -1,73 +0,0 @@
-// One host connector per workstation: a lock file naming the process that holds it.
-import fs from 'node:fs';
-import path from 'node:path';
-import { ensureDir } from 'herdr-remote-relay/state';
-import { processStart, stillRunning } from '../lib/process.js';
-function readOwner(lockPath) {
-    try {
-        return JSON.parse(fs.readFileSync(lockPath, 'utf8'));
-    }
-    catch {
-        // Missing, or half-written by a process that died mid-write: nobody owns it.
-        return null;
-    }
-}
-function lockError(message, code) {
-    const error = new Error(message);
-    error.code = code;
-    return error;
-}
-/**
- * Take the lock, or throw `HOST_ALREADY_RUNNING` when a live process holds it.
- * A lock left by a dead process is removed and taken over — including one whose
- * pid a reboot handed to an unrelated process, which would otherwise keep every
- * later connector standing down.
- */
-export function acquireHostLock(lockPath, hostId) {
-    ensureDir(path.dirname(lockPath));
-    for (let attempt = 0; attempt < 2; attempt += 1) {
-        try {
-            const fd = fs.openSync(lockPath, 'wx', 0o600);
-            fs.writeFileSync(fd, `${JSON.stringify({
-                pid: process.pid,
-                processStart: processStart(process.pid),
-                hostId,
-                startedAt: new Date().toISOString(),
-            })}\n`);
-            return fd;
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST')
-                throw error;
-            const owner = readOwner(lockPath);
-            if (owner && stillRunning([owner]).length > 0) {
-                throw lockError(`another host connector is already running (pid ${owner.pid})`, 'HOST_ALREADY_RUNNING');
-            }
-            try {
-                fs.rmSync(lockPath, { force: true });
-            }
-            catch {
-                // Not ours to remove; the second attempt fails and says so below.
-            }
-        }
-    }
-    throw lockError('could not acquire host connector lock', 'HOST_LOCK_FAILED');
-}
-/** Close `fd` and remove the lock, unless another process has taken it since. */
-export function releaseHostLock(lockPath, fd) {
-    try {
-        fs.closeSync(fd);
-    }
-    catch {
-        // Already closed; the file below is what matters.
-    }
-    const owner = readOwner(lockPath);
-    if (owner && owner.pid !== process.pid)
-        return;
-    try {
-        fs.rmSync(lockPath, { force: true });
-    }
-    catch {
-        // Stopping must not fail over a lock file; a dead owner's lock is taken over.
-    }
-}