herdr-remote 0.2.39 → 0.3.31

package/dist/connector/sessions.js

@@ -1,381 +0,0 @@
-// One Herdr client in a PTY per browser window, and starting Herdr's server
-// when a window finds it not running.
-import { FRAME_TYPE_OUTPUT, packStreamFrame, packStreamFrameV2, } from 'herdr-remote-relay/protocol';
-import { herdrNotFoundMessage, herdrOutdatedMessage, herdrVersion, resolveHerdrCommand, verifyHerdrCommand, } from '../herdr-command.js';
-import { ensureHerdrServer, probeHerdrServer, } from '../herdr-server.js';
-import { PtySession } from '../pty-session.js';
-import { inspectSocket } from '../socket-discovery.js';
-import { streamOf } from './wire.js';
-/**
- * A session that dies this fast never really started. Anything longer is a
- * session the user actually used and then left.
- */
-const FAST_FAILURE_MS = 1500;
-/** Coalesce Windows ConPTY's many small output chunks before they reach the relay. */
-const WINDOWS_OUTPUT_BATCH_MS = 4;
-/** How many broken starts in a row before we stop calling them exits. */
-export const FAST_FAILURE_LIMIT = 3;
-export class Sessions {
-    /** Running sessions by stream id. */
-    byStream = new Map();
-    /** v2 frame index → stream id. */
-    streamIndexToId = new Map();
-    /** Windows whose session waits on a Herdr that is not running, by stream. */
-    waitingForHerdr = new Map();
-    /** Session starts between their liveness check and their PTY, by stream. */
-    probingStarts = new Map();
-    /** One start at a time, however many windows asked for it. */
-    herdrLaunch = null;
-    herdrVersionWarned = false;
-    fastFailures = 0;
-    herdrCommand;
-    herdrArgs;
-    socketPath;
-    cwd;
-    herdrLookup;
-    herdrLogPath;
-    readHerdrVersion;
-    Pty;
-    probeHerdr;
-    ensureHerdr;
-    link;
-    constructor(options, link) {
-        this.socketPath = options.socketPath;
-        this.herdrLookup = options.herdrLookup || {};
-        this.herdrCommand = options.herdrCommand || resolveHerdrCommand(this.herdrLookup);
-        this.herdrArgs = options.herdrArgs;
-        this.cwd = options.cwd;
-        this.herdrLogPath = options.herdrLogPath;
-        this.readHerdrVersion = options.readHerdrVersion || herdrVersion;
-        this.Pty = options.PtySession || PtySession;
-        this.probeHerdr = options.probeHerdr || probeHerdrServer;
-        this.ensureHerdr = options.ensureHerdr || ensureHerdrServer;
-        this.link = link;
-    }
-    sendError(streamId, code, message) {
-        this.link.send({ type: 'error', clientId: streamId, code, message });
-    }
-    /**
-     * Confirm Herdr is really there before the name reaches `pty.spawn`.
-     *
-     * node-pty resolves the command with `execvp(3)` inside the forked child, so
-     * a missing binary is not a spawn error anyone can catch: the child writes
-     * "execvp(3) failed.: No such file or directory" into the PTY and exits. The
-     * `session_exit` that follows makes the relay drop the browser's socket, the
-     * browser reconnects into the same broken start, and that is the reconnect
-     * loop of issue #1. Refusing to start keeps the socket up and puts the actual
-     * reason in front of the user.
-     *
-     * Re-resolved per session rather than cached from the constructor: a service
-     * that started before Herdr was installed should pick it up without a restart.
-     */
-    ensureHerdrCommand() {
-        const resolved = verifyHerdrCommand(this.herdrCommand, this.herdrLookup);
-        if (resolved.found) {
-            this.herdrCommand = resolved.command;
-            this.warnIfHerdrOutdated();
-            return null;
-        }
-        return herdrNotFoundMessage(this.herdrLookup);
-    }
-    /**
-     * Say once that the installed Herdr is older than this release expects.
-     *
-     * Never a refusal to start. An older Herdr still runs — it just misbehaves in
-     * ways a browser window notices — and the comment on `start` explains what a
-     * refused start does to a reconnecting browser.
-     */
-    warnIfHerdrOutdated() {
-        if (this.herdrVersionWarned)
-            return;
-        const installed = this.readHerdrVersion({ command: this.herdrCommand });
-        if (installed.supported) {
-            // A version we could not read is checked again on the next session: the
-            // install may simply not have been finished writing.
-            if (installed.version)
-                this.herdrVersionWarned = true;
-            return;
-        }
-        this.herdrVersionWarned = true;
-        process.stderr.write(`herdr-remote host connector: ${herdrOutdatedMessage(installed.version)}\n`);
-    }
-    /** Start a window's session, or hold it until Herdr runs. */
-    start(message) {
-        const streamId = streamOf(message);
-        if (!streamId)
-            return undefined;
-        this.stop(streamId);
-        const missingHerdr = this.ensureHerdrCommand();
-        if (missingHerdr) {
-            process.stderr.write(`herdr-remote host connector: ${missingHerdr}\n`);
-            this.sendError(streamId, 'herdr_not_found', missingHerdr);
-            return undefined;
-        }
-        const socketInfo = inspectSocket(this.socketPath);
-        if (!socketInfo.ok && !socketInfo.missing) {
-            this.sendError(streamId, 'herdr_socket_unavailable', socketInfo.reason);
-            return undefined;
-        }
-        if (!socketInfo.ok) {
-            this.waitForHerdr(streamId, message);
-            return undefined;
-        }
-        // The socket file alone proves nothing: a `herdr` client pointed at a dead
-        // one starts a server of its own, inside this process's service, where the
-        // next restart of herdr-remote would kill it. Only a server that accepts a
-        // connection gets a client.
-        const pending = { message };
-        this.probingStarts.set(streamId, pending);
-        return this.probeHerdr(this.socketPath).then((probe) => {
-            // Stopped, or started again, while the answer was in flight.
-            if (this.probingStarts.get(streamId) !== pending)
-                return;
-            this.probingStarts.delete(streamId);
-            if (probe.state === 'running')
-                this.spawn(pending.message);
-            else if (probe.state === 'stopped')
-                this.waitForHerdr(streamId, pending.message);
-            else
-                this.sendError(streamId, 'herdr_socket_unavailable', probe.reason);
-        });
-    }
-    /**
-     * Hold a window's session until Herdr runs, and ask the browser whether it
-     * should be started. Nothing starts until somebody says yes.
-     */
-    waitForHerdr(streamId, message) {
-        this.waitingForHerdr.set(streamId, message);
-        this.sendError(streamId, 'herdr_not_running', `Herdr is not running on this workstation (${this.socketPath}).`);
-    }
-    /**
-     * Start this workstation's Herdr server, once, however many windows or
-     * callers ask at the same time.
-     */
-    startHerdr() {
-        if (!this.herdrLaunch) {
-            this.herdrLaunch = Promise.resolve()
-                .then(() => {
-                const missing = this.ensureHerdrCommand();
-                if (missing)
-                    throw new Error(missing);
-                return this.ensureHerdr({
-                    command: this.herdrCommand,
-                    args: this.herdrArgs,
-                    socketPath: this.socketPath,
-                    cwd: this.cwd,
-                    logPath: this.herdrLogPath,
-                });
-            })
-                .finally(() => {
-                this.herdrLaunch = null;
-            });
-        }
-        return this.herdrLaunch;
-    }
-    /**
-     * A browser said yes. The relay only ever routes this from a window paired
-     * to *this* workstation, so what starts is this user's own Herdr, at the
-     * socket this connector is configured for — never one named by the message.
-     * Once it runs, every window waiting on it gets its session.
-     */
-    async startHerdrFor(streamId) {
-        try {
-            const result = await this.startHerdr();
-            if (result.started)
-                process.stderr.write("herdr-remote host connector: started Herdr at a browser's request\n");
-        }
-        catch (error) {
-            const { message } = error;
-            process.stderr.write(`herdr-remote host connector: could not start Herdr: ${message}\n`);
-            if (streamId)
-                this.sendError(streamId, 'herdr_start_failed', message);
-            return;
-        }
-        const waiting = [...this.waitingForHerdr.values()];
-        this.waitingForHerdr.clear();
-        for (const held of waiting)
-            this.spawn(held);
-    }
-    /** Start the PTY for a window once Herdr is known to be running. */
-    spawn(message) {
-        const streamId = streamOf(message);
-        const streamIndex = typeof message.streamIndex === 'number' ? message.streamIndex : null;
-        const pty = new this.Pty({
-            command: this.herdrCommand,
-            args: this.herdrArgs,
-            cwd: this.cwd,
-            socketPath: this.socketPath,
-        });
-        const session = {
-            id: streamId,
-            streamIndex,
-            pty,
-            cols: Number(message.cols) || PtySession.DEFAULT_COLS,
-            rows: Number(message.rows) || PtySession.DEFAULT_ROWS,
-            createdAt: new Date().toISOString(),
-            startedAtMs: Date.now(),
-            pendingOutput: [],
-            flushImmediate: null,
-            flushTimeout: null,
-        };
-        const flushOutput = () => {
-            if (session.flushImmediate) {
-                clearImmediate(session.flushImmediate);
-                session.flushImmediate = null;
-            }
-            if (session.flushTimeout) {
-                clearTimeout(session.flushTimeout);
-                session.flushTimeout = null;
-            }
-            if (session.pendingOutput.length === 0)
-                return;
-            const payload = Buffer.concat(session.pendingOutput);
-            session.pendingOutput = [];
-            this.link.sendFrame(session.streamIndex !== null
-                ? packStreamFrameV2(FRAME_TYPE_OUTPUT, session.streamIndex, payload)
-                : packStreamFrame('output', streamId, payload));
-        };
-        try {
-            pty.start({
-                cols: session.cols,
-                rows: session.rows,
-                onData: (data) => {
-                    const chunk = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
-                    if (chunk.length === 0)
-                        return;
-                    session.pendingOutput.push(chunk);
-                    if (!session.flushImmediate && !session.flushTimeout) {
-                        if (process.platform === 'win32') {
-                            session.flushTimeout = setTimeout(flushOutput, WINDOWS_OUTPUT_BATCH_MS);
-                        }
-                        else {
-                            session.flushImmediate = setImmediate(flushOutput);
-                        }
-                    }
-                },
-                onExit: ({ exitCode }) => {
-                    if (this.byStream.get(streamId) !== session)
-                        return;
-                    this.forget(session);
-                    this.reportExit(session, exitCode);
-                    this.link.changed();
-                },
-            });
-        }
-        catch (error) {
-            discardOutput(session);
-            this.sendError(streamId, 'pty_start_failed', error.message);
-            pty.kill();
-            return;
-        }
-        this.byStream.set(streamId, session);
-        if (streamIndex !== null)
-            this.streamIndexToId.set(streamIndex, streamId);
-        this.link.send({ type: 'session_ready', clientId: streamId });
-        this.link.changed();
-    }
-    /**
-     * Tell the relay how a session ended.
-     *
-     * `session_exit` is the honest answer for a session that ran, and the relay
-     * closes the browser's socket on it so the window can start a fresh one. That
-     * is also what turns a start that keeps failing into a reconnect loop: exit,
-     * close, reconnect, exit. Once a few starts in a row have died immediately
-     * with a non-zero code the failure is systemic, not a session ending, so it is
-     * reported as an error — which the relay forwards without dropping the socket,
-     * leaving the user with a message instead of a spinner.
-     */
-    reportExit(session, exitCode) {
-        const streamId = session.id;
-        const lifetimeMs = Date.now() - session.startedAtMs;
-        const failedFast = exitCode !== 0 && lifetimeMs < FAST_FAILURE_MS;
-        this.fastFailures = failedFast ? this.fastFailures + 1 : 0;
-        if (this.fastFailures < FAST_FAILURE_LIMIT) {
-            this.link.send({ type: 'session_exit', clientId: streamId, code: exitCode });
-            return;
-        }
-        const message = `"${this.herdrCommand}" exited immediately with code ${exitCode} on ${this.fastFailures} attempts in a row. ` +
-            'Check that it runs from a terminal, and see the host connector log for what it printed.';
-        process.stderr.write(`herdr-remote host connector: ${message}\n`);
-        this.sendError(streamId, 'herdr_start_failed', message);
-    }
-    /** Keyboard input for the session behind a stream id or v2 index. */
-    write(stream, payload) {
-        const streamId = stream.streamIndex !== undefined
-            ? this.streamIndexToId.get(stream.streamIndex)
-            : stream.streamId;
-        if (streamId)
-            this.byStream.get(streamId)?.pty.write(payload);
-    }
-    resize(message) {
-        const id = streamOf(message);
-        if (!id)
-            return;
-        // A window still waiting on Herdr starts at the size it has by then.
-        const held = this.waitingForHerdr.get(id) || this.probingStarts.get(id)?.message;
-        if (held) {
-            if (Number.isInteger(message.cols))
-                held.cols = message.cols;
-            if (Number.isInteger(message.rows))
-                held.rows = message.rows;
-        }
-        const session = this.byStream.get(id);
-        if (!session)
-            return;
-        if (Number.isInteger(message.cols))
-            session.cols = PtySession.clampDimension(message.cols, 0);
-        if (Number.isInteger(message.rows))
-            session.rows = PtySession.clampDimension(message.rows, 0);
-        session.pty.resize(session.cols, session.rows);
-    }
-    stop(streamId) {
-        this.waitingForHerdr.delete(streamId);
-        this.probingStarts.delete(streamId);
-        const session = this.byStream.get(streamId);
-        if (!session)
-            return;
-        this.forget(session);
-        session.pty.kill();
-        this.link.changed();
-    }
-    stopAll() {
-        for (const session of this.byStream.values()) {
-            discardOutput(session);
-            session.pty.kill();
-        }
-        this.byStream.clear();
-        this.streamIndexToId.clear();
-        this.waitingForHerdr.clear();
-        this.probingStarts.clear();
-    }
-    /** The running PTYs, as the relay's status page lists them. */
-    summaries() {
-        return [...this.byStream.values()].map((session) => ({
-            id: session.id,
-            pid: session.pty.terminal?.pid || null,
-            command: session.pty.command,
-            cols: session.cols,
-            rows: session.rows,
-            cwd: session.pty.cwd,
-            createdAt: session.createdAt,
-            activeClients: 1,
-        }));
-    }
-    forget(session) {
-        this.byStream.delete(session.id);
-        if (session.streamIndex !== null)
-            this.streamIndexToId.delete(session.streamIndex);
-        discardOutput(session);
-    }
-}
-function discardOutput(session) {
-    if (session.flushImmediate) {
-        clearImmediate(session.flushImmediate);
-        session.flushImmediate = null;
-    }
-    if (session.flushTimeout) {
-        clearTimeout(session.flushTimeout);
-        session.flushTimeout = null;
-    }
-    session.pendingOutput = [];
-}

package/dist/connector/update-report.js

@@ -1,70 +0,0 @@
-// Telling a workstation's windows whether its herdr-remote is behind.
-import { checkForUpdate, compareVersions, currentVersion, installedVersionOnDisk, updateChecksEnabled, } from '../updater.js';
-/** Windows opening within this long of a check reuse its answer. */
-const UPDATE_RECHECK_MS = 60_000;
-/**
- * Whether a newer herdr-remote is out, asked when a window opens. The version
- * this process runs is fixed at start; the one on disk moves when somebody
- * updates without restarting.
- */
-export class UpdateReport {
-    checkUpdate;
-    readInstalledVersion;
-    /** The release this process runs, fixed at start. */
-    runningVersion;
-    send;
-    checkedAt = 0;
-    /** The check in flight, if any. */
-    pending = null;
-    constructor(options, send) {
-        this.checkUpdate =
-            options.checkUpdate !== undefined
-                ? options.checkUpdate
-                : updateChecksEnabled()
-                    ? checkForUpdate
-                    : null;
-        this.readInstalledVersion = options.readInstalledVersion || installedVersionOnDisk;
-        this.runningVersion = options.runningVersion || currentVersion();
-        this.send = send;
-    }
-    /**
-     * Tell every window whether this workstation's herdr-remote is behind the
-     * newest release. Asked at most once a minute however many windows open;
-     * the relay keeps the last answer for windows that open in between. A failed
-     * check says nothing: offline is not news.
-     */
-    report({ now = Date.now() } = {}) {
-        const checkUpdate = this.checkUpdate;
-        if (!checkUpdate || this.pending)
-            return this.pending;
-        if (now - this.checkedAt < UPDATE_RECHECK_MS)
-            return null;
-        this.checkedAt = now;
-        this.pending = Promise.resolve()
-            .then(() => checkUpdate())
-            .then((result) => {
-            if (!result?.ok || !result.latest)
-                return;
-            const running = this.runningVersion;
-            const installed = this.readInstalledVersion() || running;
-            this.send({
-                type: 'update_status',
-                current: running,
-                installed,
-                latest: result.latest,
-                updateAvailable: compareVersions(result.latest, running) > 0,
-                // Updated on disk, still running the old code: a restart finishes it.
-                restartPending: compareVersions(installed, running) > 0,
-                // Older connectors leave this out, and their windows keep the npm steps.
-                updateCommand: true,
-            });
-        })
-            .catch(() => {
-            // Offline, or the registry is down: nothing worth telling a window.
-        })
-            .finally(() => {
-            this.pending = null;
-        });
-        return this.pending;
-    }
-}

package/dist/connector/wire.js

@@ -1,42 +0,0 @@
-// The host connector's side of its WebSocket to the relay.
-import { WebSocket } from 'ws';
-export function sendJson(ws, payload) {
-    if (ws && ws.readyState === WebSocket.OPEN)
-        ws.send(JSON.stringify(payload));
-}
-export function closeSocket(ws, reason = 'host connector stopping') {
-    if (!ws || ws.readyState === WebSocket.CLOSED || ws.readyState === WebSocket.CLOSING)
-        return;
-    try {
-        ws.close(1000, reason);
-    }
-    catch {
-        // Closing a socket that is already failing needs no further handling.
-    }
-}
-export function terminateSocket(ws) {
-    if (!ws || ws.readyState === WebSocket.CLOSED)
-        return;
-    // Tests stand in a plain object for the socket; end it however it allows.
-    const socket = ws;
-    try {
-        if (typeof socket.terminate === 'function')
-            socket.terminate();
-        else if (typeof socket.destroy === 'function')
-            socket.destroy();
-        else
-            socket.close?.();
-    }
-    catch {
-        // Tearing down a dead socket; there is nothing left to recover.
-    }
-}
-/**
- * The stream a relay message is about. The relay sends `clientId` and
- * `streamId` with the same value; `clientId` is read first, as the protocol
- * says.
- */
-export function streamOf(message) {
-    const id = message.clientId || message.streamId;
-    return typeof id === 'string' && id ? id : null;
-}

package/dist/exit-codes.js

@@ -1,13 +0,0 @@
-/**
- * Exit codes the supervisor interprets.
- *
- * `REPLACED` means another host connector has taken over this workstation on
- * the relay. Restarting after that would make the two instances kick each other
- * off in turn, and every browser attached to the relay is disconnected on each
- * swap — the endless "Connection closed (1012). Retrying…" loop. So it is the
- * one exit the supervisor must respect rather than recover from.
- */
-const EXIT_REPLACED = 12;
-/** Credentials need operator intervention; a supervisor must not loop. */
-const EXIT_AUTH_FAILED = 13;
-export { EXIT_REPLACED, EXIT_AUTH_FAILED };

package/dist/font-subset.js

@@ -1,116 +0,0 @@
-/**
- * Cuts the characters a browser needs out of a large font.
- *
- * A CJK face is 16–20 MB — too much to send a phone whole — but a terminal
- * only ever shows a few thousand distinct characters. HarfBuzz's subsetter
- * (the same code Google Fonts slices its CJK families with) produces a small,
- * valid font holding exactly the requested characters: 3,755 common Hanzi in
- * about 1.7 MB and 50 ms, a handful of rare ones in a few KB and milliseconds.
- *
- * The WebAssembly build has no imports and runs synchronously. A loaded face
- * costs its file size twice over (the file and the wasm heap), so the whole
- * instance is dropped after a quiet minute; wasm memory never shrinks, only
- * a new instance gives it back.
- */
-import { createRequire } from 'node:module';
-import fs from 'node:fs';
-import path from 'node:path';
-import { PACKAGE_ROOT } from './paths.js';
-/** How long a loaded font may sit unused before its memory is released. */
-const IDLE_RELEASE_MS = 60_000;
-/** Never cut more than this many characters in one go. */
-const MAX_CODEPOINTS = 16_384;
-const HB_MEMORY_MODE_READONLY = 1;
-let wasmModule = null;
-function loadModule() {
-    if (!wasmModule) {
-        // A release bundles harfbuzzjs away and ships only this file beside the bundle.
-        const bundled = path.join(PACKAGE_ROOT, 'dist', 'harfbuzz-subset.wasm');
-        const file = fs.existsSync(bundled)
-            ? bundled
-            : createRequire(import.meta.url).resolve('harfbuzzjs/dist/harfbuzz-subset.wasm');
-        wasmModule = new WebAssembly.Module(fs.readFileSync(file));
-    }
-    return wasmModule;
-}
-class FontSubsetter {
-    idleMs;
-    instance = null;
-    /** Loaded faces by source key, in the current instance. */
-    faces = new Map();
-    idleTimer = null;
-    constructor({ idleMs = IDLE_RELEASE_MS } = {}) {
-        this.idleMs = idleMs;
-    }
-    exports() {
-        if (!this.instance) {
-            this.instance = new WebAssembly.Instance(loadModule(), {}).exports;
-            // An Emscripten reactor: static constructors run here, before any call.
-            this.instance._initialize();
-        }
-        return this.instance;
-    }
-    face(source) {
-        const key = `${source.path}\0${source.index || 0}`;
-        const loaded = this.faces.get(key);
-        if (loaded)
-            return loaded.face;
-        const hb = this.exports();
-        const data = fs.readFileSync(source.path);
-        const pointer = hb.malloc(data.length);
-        if (!pointer)
-            throw new Error('out of memory loading font');
-        new Uint8Array(hb.memory.buffer).set(data, pointer);
-        const blob = hb.hb_blob_create(pointer, data.length, HB_MEMORY_MODE_READONLY, 0, 0);
-        const face = hb.hb_face_create(blob, source.index || 0);
-        hb.hb_blob_destroy(blob);
-        this.faces.set(key, { pointer, face });
-        return face;
-    }
-    /** A standalone font with just `codepoints` from `source` (`{ path, index }`). */
-    subset(source, codepoints) {
-        const hb = this.exports();
-        const face = this.face(source);
-        const input = hb.hb_subset_input_create_or_fail();
-        if (!input)
-            throw new Error('font subsetting is unavailable');
-        let result = 0;
-        let subsetFace = 0;
-        try {
-            const set = hb.hb_subset_input_unicode_set(input);
-            for (const codepoint of codepoints.slice(0, MAX_CODEPOINTS))
-                hb.hb_set_add(set, codepoint);
-            subsetFace = hb.hb_subset_or_fail(face, input);
-            if (!subsetFace)
-                throw new Error('the font could not be subset');
-            result = hb.hb_face_reference_blob(subsetFace);
-            const length = hb.hb_blob_get_length(result);
-            const pointer = hb.hb_blob_get_data(result, 0);
-            // Copied out: the heap may grow (and move) on the next call.
-            return Buffer.from(new Uint8Array(hb.memory.buffer, pointer, length));
-        }
-        finally {
-            if (result)
-                hb.hb_blob_destroy(result);
-            if (subsetFace)
-                hb.hb_face_destroy(subsetFace);
-            hb.hb_subset_input_destroy(input);
-            this.scheduleRelease();
-        }
-    }
-    scheduleRelease() {
-        if (this.idleTimer)
-            clearTimeout(this.idleTimer);
-        this.idleTimer = setTimeout(() => this.release(), this.idleMs);
-        this.idleTimer.unref?.();
-    }
-    /** Drop every loaded face and the instance holding them. */
-    release() {
-        if (this.idleTimer)
-            clearTimeout(this.idleTimer);
-        this.idleTimer = null;
-        this.faces.clear();
-        this.instance = null;
-    }
-}
-export { FontSubsetter };