herdr-remote 0.2.18 → 0.2.19

package/dist/relay-urls.js

@@ -0,0 +1,99 @@
+// The addresses a configuration implies: where the local relay binds, the URL
+// a browser opens, and the relay URLs the host connector and the CLI dial.
+import { WS_HOST_PATH } from 'herdr-remote-relay/protocol';
+function isLoopbackHost(value) {
+    return value === '127.0.0.1' || value === 'localhost' || value === '::1' || value === '[::1]';
+}
+function isUnspecifiedAddress(value) {
+    const address = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    return address === '0.0.0.0' || address === '::' || address === '[::]';
+}
+/** An unspecified host is valid for a server bind, but not for a browser URL. */
+function isUnspecifiedHost(value) {
+    try {
+        const hostname = new URL(value).hostname.toLowerCase();
+        return hostname === '0.0.0.0' || hostname === '::' || hostname === '[::]';
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeUrl(value) {
+    return typeof value === 'string' ? value.trim().replace(/\/+$/, '') : '';
+}
+/** Whether this machine runs its own relay process. */
+function runsLocalRelay(config) {
+    return config.relay.mode !== 'remote';
+}
+/** Address the local relay binds to for the configured mode. */
+function bindAddress(config) {
+    return config.relay.mode === 'lan' ? '0.0.0.0' : '127.0.0.1';
+}
+/**
+ * Host name to put into pairing URLs. For "lan" this is the interface address a
+ * phone can actually reach; `lanHost` is the user's pick from the TUI, and the
+ * fallback keeps things working if that interface disappeared.
+ */
+function advertisedHost(config, fallbackLanHost = null) {
+    if (config.relay.mode === 'lan') {
+        const configured = config.relay.lanHost;
+        if (configured && !isLoopbackHost(configured) && !isUnspecifiedAddress(configured))
+            return configured;
+        if (fallbackLanHost &&
+            !isLoopbackHost(fallbackLanHost) &&
+            !isUnspecifiedAddress(fallbackLanHost)) {
+            return fallbackLanHost;
+        }
+        return '127.0.0.1';
+    }
+    return '127.0.0.1';
+}
+/** The URL a browser opens. */
+function resolvePublicUrl(config, fallbackLanHost = null) {
+    if (config.relay.publicUrl)
+        return config.relay.publicUrl;
+    if (config.relay.mode === 'remote')
+        return httpOrigin(config.relay.remoteUrl);
+    return `http://${advertisedHost(config, fallbackLanHost)}:${config.relay.port}`;
+}
+/** Base HTTP origin used for relay admin calls (pairing, health). */
+function resolveAdminOrigin(config) {
+    if (config.relay.mode === 'remote')
+        return httpOrigin(config.relay.remoteUrl);
+    return `http://127.0.0.1:${config.relay.port}`;
+}
+/** WebSocket URL the host connector dials. */
+function resolveHostRelayUrl(config) {
+    const base = config.relay.mode === 'remote' ? config.relay.remoteUrl : `ws://127.0.0.1:${config.relay.port}`;
+    return hostWebSocketUrl(base);
+}
+function httpOrigin(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol === 'ws:')
+            url.protocol = 'http:';
+        if (url.protocol === 'wss:')
+            url.protocol = 'https:';
+        const pathname = url.pathname.replace(/\/+$/, '');
+        return `${url.origin}${pathname}`;
+    }
+    catch {
+        return normalizeUrl(value);
+    }
+}
+function hostWebSocketUrl(base) {
+    const url = new URL(base);
+    if (url.protocol === 'http:')
+        url.protocol = 'ws:';
+    if (url.protocol === 'https:')
+        url.protocol = 'wss:';
+    const pathname = url.pathname.replace(/\/+$/, '');
+    if (!pathname || pathname === '/') {
+        url.pathname = WS_HOST_PATH;
+    }
+    else if (!pathname.endsWith(WS_HOST_PATH)) {
+        url.pathname = `${pathname}${WS_HOST_PATH}`;
+    }
+    return url.toString();
+}
+export { isLoopbackHost, isUnspecifiedAddress, isUnspecifiedHost, normalizeUrl, runsLocalRelay, bindAddress, advertisedHost, resolvePublicUrl, resolveAdminOrigin, resolveHostRelayUrl, hostWebSocketUrl, };

package/dist/runtime.js

@@ -0,0 +1,106 @@
+// runtime.json: this workstation's relay credentials, the processes started
+// for it, and facts other modules remember there (terminal palette and font).
+// Every read and write of that file goes through here.
+import { ensureDir, randomToken, readJson, writeJsonAtomic } from 'herdr-remote-relay/state';
+import { pidAlive } from './lib/process.js';
+import { configDir, runtimeStatePath, stateDir } from './paths.js';
+const RUNTIME_VERSION = 2;
+export function readRuntime() {
+    const state = readJson(runtimeStatePath(), {});
+    return state && typeof state === 'object' ? state : {};
+}
+export function writeRuntime(state) {
+    writeJsonAtomic(runtimeStatePath(), state);
+}
+/** Read, change and write back in one step, so no field another writer set is lost. */
+export function updateRuntime(change) {
+    const state = readRuntime();
+    change(state);
+    writeRuntime(state);
+    return state;
+}
+/**
+ * Load (creating if needed) the long-lived identifiers and secrets this
+ * workstation uses. These live in the state directory rather than config.json
+ * because they are credentials: writeJsonAtomic stores them mode 0600.
+ */
+export function ensureRuntime() {
+    ensureDir(configDir());
+    ensureDir(stateDir());
+    return updateRuntime((state) => {
+        if (!state.version)
+            state.version = RUNTIME_VERSION;
+        if (!state.hostId)
+            state.hostId = `host-${randomToken(9)}`;
+        if (!state.hostToken)
+            state.hostToken = randomToken(32);
+    });
+}
+/**
+ * Set the password used to join a relay. An empty value means "no password",
+ * which is what a public relay expects.
+ *
+ * It lives in the state file rather than config.json because it is a secret:
+ * writeJsonAtomic stores that file mode 0600.
+ */
+export function setRelayPassword(password) {
+    const state = ensureRuntime();
+    state.relayPassword = typeof password === 'string' ? password.trim() : '';
+    writeRuntime(state);
+    return state;
+}
+/**
+ * Issue this workstation a new identity on the relay.
+ *
+ * The host token is what proves ownership of this workstation, so replacing it
+ * means the relay no longer recognises the old one — useful if it leaked, but
+ * it also orphans the previous record on a relay that already enrolled it.
+ */
+export function regenerateHostIdentity() {
+    const state = ensureRuntime();
+    state.hostId = `host-${randomToken(9)}`;
+    state.hostToken = randomToken(32);
+    writeRuntime(state);
+    return state;
+}
+/**
+ * Remember a process we started, in a list that survives being overwritten.
+ *
+ * `relayPid`/`hostPid` alone were not enough: the supervisor rewrote them with
+ * its own children, which orphaned anything an earlier detached start had
+ * spawned. Those orphans kept the port and the host session, so the relay could
+ * never bind and "stop" had nothing left to kill. The ledger is append-only
+ * (minus dead entries) precisely so no writer can lose another writer's pids.
+ */
+export function recordManagedPid(state, name, pid) {
+    const existing = Array.isArray(state.managedPids) ? state.managedPids : [];
+    const kept = existing.filter((entry) => entry && entry.pid !== pid && pidAlive(entry.pid));
+    // Only track something that is actually running: a pid that already exited
+    // would sit in the ledger until its number is recycled by an unrelated
+    // process, which we would then happily signal.
+    if (Number.isInteger(pid) && pidAlive(pid)) {
+        kept.push({ name, pid: pid, startedAt: new Date().toISOString() });
+    }
+    state.managedPids = kept;
+    return state;
+}
+/** Every process we believe we started, alive right now. */
+export function managedPids(state = readRuntime()) {
+    const pids = new Map();
+    // Supervisor first and never overwritten: `stopServices` relies on the order
+    // to signal it before its children, and one pid can appear under several
+    // fields.
+    for (const [name, pid] of [
+        ['supervisor', state.supervisorPid],
+        ['host', state.hostPid],
+        ['relay', state.relayPid],
+    ]) {
+        if (pidAlive(pid) && !pids.has(pid))
+            pids.set(pid, name);
+    }
+    for (const entry of state.managedPids || []) {
+        if (entry && pidAlive(entry.pid) && !pids.has(entry.pid))
+            pids.set(entry.pid, entry.name);
+    }
+    return [...pids].map(([pid, name]) => ({ pid, name }));
+}

package/dist/service.js

@@ -0,0 +1,260 @@
+// The processes that make up a running herdr-remote — the local relay and the
+// host connector — and starting, stopping and describing them.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { ensureDir } from 'herdr-remote-relay/state';
+import { loadConfig } from './config.js';
+import { findHerdrCommand, herdrVersion, MIN_HERDR_VERSION, resolveHerdrCommand, } from './herdr-command.js';
+import { pidAlive } from './lib/process.js';
+import { preferredLanAddress } from './net-interfaces.js';
+import { logPath, PACKAGE_ROOT, stateDir } from './paths.js';
+import { healthUrl, hostHeaders, requestJson, waitForHost, waitForRelay } from './relay-client.js';
+import { bindAddress, resolveAdminOrigin, resolveHostRelayUrl, resolvePublicUrl, runsLocalRelay, } from './relay-urls.js';
+import { ensureRuntime, managedPids, readRuntime, recordManagedPid, updateRuntime, writeRuntime, } from './runtime.js';
+import { resolveSocketPath } from './socket-discovery.js';
+import { resolveHostFont } from './terminal-font/index.js';
+import { hostTerminalPalette } from './terminal-palette.js';
+export function relayBinPath() {
+    // Resolved rather than hard-coded: the relay is a separate npm package, so
+    // its location depends on how npm hoisted it.
+    const manifest = createRequire(import.meta.url).resolve('herdr-remote-relay/package.json');
+    return path.join(path.dirname(manifest), 'bin', 'herdr-remote-relay.js');
+}
+function relayAuthStatePath() {
+    return path.join(stateDir(), 'relay-auth.json');
+}
+/**
+ * The processes that make up a running herdr-remote, as declarative specs.
+ *
+ * Both the detached starter and the foreground supervisor build their children
+ * from this one list so the two paths cannot drift in how they configure the
+ * relay or the host connector.
+ */
+export function serviceSpecs(config = loadConfig(), state = ensureRuntime()) {
+    const specs = [];
+    const publicUrl = resolvePublicUrl(config, preferredLanAddress());
+    if (runsLocalRelay(config)) {
+        specs.push({
+            name: 'relay',
+            command: process.execPath,
+            args: [relayBinPath()],
+            env: {
+                // Let the shared web UI tell a private workstation relay apart from
+                // the operator-facing self-hosted relay. Standalone relay installs
+                // default to remote mode.
+                RELAY_DEPLOYMENT_MODE: 'local',
+                RELAY_BIND: bindAddress(config),
+                RELAY_PORT: String(config.relay.port),
+                RELAY_PUBLIC_URL: publicUrl,
+                // A relay we start ourselves is closed to everything but this
+                // workstation: reusing the host token as its password costs nothing and
+                // stops another machine on the LAN from enrolling into it.
+                RELAY_PASSWORD: state.hostToken,
+                RELAY_AUTH_STATE_FILE: relayAuthStatePath(),
+                RELAY_ALLOWED_ORIGINS: (config.relay.allowedOrigins || []).join(','),
+                RELAY_MAX_CLIENTS_PER_HOST: String(config.relay.maxClientsPerHost),
+                RELAY_MAX_HOSTS: String(config.relay.maxHosts),
+                RELAY_MAX_PENDING_HANDSHAKES: String(config.relay.maxPendingHandshakes),
+                RELAY_MAX_BUFFERED_BYTES_PER_CLIENT: String(config.relay.maxBufferedBytesPerClient),
+                RELAY_HOST_RECONNECT_GRACE_MS: String(config.relay.hostReconnectGraceMs),
+            },
+        });
+    }
+    const terminalPalette = hostTerminalPalette();
+    // What this command detected at its entry point, else what an earlier start
+    // with a terminal wrote down. Only the family, size and terminal travel here;
+    // the connector finds the files itself, on the machine that has them.
+    const terminalFont = resolveHostFont();
+    specs.push({
+        name: 'host',
+        command: process.execPath,
+        args: [path.join(PACKAGE_ROOT, 'dist', 'connector', 'main.js')],
+        env: {
+            // Captured here, where a terminal may still be attached, because the
+            // connector itself usually runs detached with no terminal to ask.
+            ...(terminalPalette ? { HERDR_TERM_PALETTE_JSON: JSON.stringify(terminalPalette) } : {}),
+            ...(terminalFont ? { HERDR_TERM_FONT_JSON: JSON.stringify(terminalFont) } : {}),
+            RELAY_URL: resolveHostRelayUrl(config),
+            RELAY_HOST_ID: state.hostId,
+            RELAY_HOST_TOKEN: state.hostToken,
+            RELAY_PASSWORD: runsLocalRelay(config) ? state.hostToken : state.relayPassword || '',
+            HERDR_SOCKET_PATH: resolveSocketPath(config.herdr.socketPath),
+            HERDR_ARGS_JSON: JSON.stringify(config.herdr.args),
+            HERDR_CWD: config.herdr.cwd,
+            HERDR_BIN_PATH: resolveHerdrCommand(),
+        },
+    });
+    return specs;
+}
+export function baseEnvironment() {
+    return { ...process.env, HERDR_REMOTE_SERVICE: '1' };
+}
+function spawnDetached(spec) {
+    ensureDir(stateDir());
+    const logFd = fs.openSync(logPath(spec.name), 'a');
+    try {
+        const child = spawn(spec.command, spec.args, {
+            cwd: PACKAGE_ROOT,
+            env: { ...baseEnvironment(), ...spec.env },
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+        });
+        child.unref();
+        return child.pid;
+    }
+    finally {
+        fs.closeSync(logFd);
+    }
+}
+/** Where each service's pid is kept in runtime.json. */
+const PID_FIELDS = { relay: 'relayPid', host: 'hostPid' };
+export function startServices() {
+    const config = loadConfig();
+    const state = ensureRuntime();
+    const next = { ...state };
+    const specs = serviceSpecs(config, state);
+    for (const spec of specs) {
+        const field = PID_FIELDS[spec.name];
+        if (pidAlive(next[field]))
+            continue;
+        next[field] = spawnDetached(spec) ?? null;
+        recordManagedPid(next, spec.name, next[field]);
+    }
+    // A relay that is no longer part of the plan (switched to remote mode) must
+    // not be left running on the old port.
+    if (!specs.some((spec) => spec.name === 'relay') && pidAlive(next.relayPid)) {
+        try {
+            process.kill(next.relayPid, 'SIGTERM');
+        }
+        catch {
+            // Exited between the check and the signal: the port is free either way.
+        }
+        next.relayPid = null;
+    }
+    next.startedAt = next.startedAt || new Date().toISOString();
+    next.mode = config.relay.mode;
+    writeRuntime(next);
+    return {
+        ok: true,
+        mode: config.relay.mode,
+        relay: {
+            local: runsLocalRelay(config),
+            pid: next.relayPid || null,
+            alive: pidAlive(next.relayPid),
+            bind: runsLocalRelay(config) ? bindAddress(config) : null,
+            port: config.relay.port,
+            remoteUrl: config.relay.remoteUrl || null,
+        },
+        host: {
+            pid: next.hostPid || null,
+            alive: pidAlive(next.hostPid),
+            socketPath: resolveSocketPath(config.herdr.socketPath),
+        },
+        publicUrl: resolvePublicUrl(config, preferredLanAddress()),
+    };
+}
+export function stopServices() {
+    const stopped = [];
+    ensureDir(stateDir());
+    updateRuntime((state) => {
+        // Supervisor first: it would otherwise see its children die and restart
+        // them faster than we can kill them.
+        const targets = managedPids(state).sort((a, b) => (a.name === 'supervisor' ? 0 : 1) - (b.name === 'supervisor' ? 0 : 1));
+        for (const { pid, name } of targets) {
+            try {
+                process.kill(pid, 'SIGTERM');
+                stopped.push({ name, pid });
+            }
+            catch (error) {
+                process.stderr.write(`herdr-remote: could not stop ${name} (pid ${pid}): ${error.message}\n`);
+            }
+        }
+        state.hostPid = null;
+        state.relayPid = null;
+        state.supervisorPid = null;
+        state.managedPids = [];
+        state.startedAt = null;
+    });
+    return { ok: true, stopped };
+}
+export function restartServices() {
+    stopServices();
+    return startServices();
+}
+export async function statusServices() {
+    const config = loadConfig();
+    const state = readRuntime();
+    const lanAddress = preferredLanAddress();
+    let health;
+    try {
+        health = await requestJson(healthUrl(config), { timeout: 1200 });
+    }
+    catch (error) {
+        health = { ok: false, message: error.message };
+    }
+    const socketPath = resolveSocketPath(config.herdr.socketPath);
+    // Where Herdr was found, and whether it was found at all: under a service
+    // manager this is the first thing to check when sessions will not start.
+    const herdr = findHerdrCommand();
+    // Only worth spawning when there is something to spawn; an unresolved command
+    // has already answered the question the version would.
+    const installed = herdr.found
+        ? herdrVersion({ command: herdr.command })
+        : { version: null, supported: true };
+    return {
+        ok: true,
+        mode: config.relay.mode,
+        relay: {
+            local: runsLocalRelay(config),
+            pid: state.relayPid || null,
+            alive: runsLocalRelay(config) ? pidAlive(state.relayPid) : null,
+            bind: runsLocalRelay(config) ? bindAddress(config) : null,
+            port: config.relay.port,
+            remoteUrl: config.relay.remoteUrl || null,
+            health,
+        },
+        host: {
+            pid: state.hostPid || null,
+            alive: pidAlive(state.hostPid),
+            hostId: state.hostId || null,
+            socketPath,
+            socketExists: Boolean(socketPath) && fs.existsSync(socketPath),
+            herdrCommand: herdr.command,
+            herdrCommandFound: herdr.found,
+            herdrCommandSource: herdr.source,
+            herdrVersion: installed.version,
+            herdrVersionSupported: installed.supported,
+            herdrVersionMinimum: MIN_HERDR_VERSION,
+        },
+        publicUrl: resolvePublicUrl(config, lanAddress),
+        startedAt: state.startedAt || null,
+    };
+}
+/** Start what pairing needs, then ask the relay for a code. */
+export async function pair() {
+    const config = loadConfig();
+    if (runsLocalRelay(config))
+        startServices();
+    await waitForRelay(config);
+    await waitForHost(config);
+    // Authenticated with this workstation's own host token: on a shared relay
+    // that is what proves the pairing code is being minted for our terminal and
+    // nobody else's.
+    return requestJson(`${resolveAdminOrigin(config)}/api/pair/start`, {
+        method: 'POST',
+        headers: hostHeaders(),
+        timeout: 5000,
+    });
+}
+export function readLogTail(name, lines = 40) {
+    try {
+        const content = fs.readFileSync(logPath(name), 'utf8');
+        return content.split('\n').filter(Boolean).slice(-lines);
+    }
+    catch {
+        // No log yet: the service has never run.
+        return [];
+    }
+}