herdr-remote 0.2.17 → 0.2.19

package/dist/settings-model.js

@@ -0,0 +1,298 @@
+// Editable settings, independent of how they are rendered.
+//
+// The TUI holds a *draft* copy of the config, mutates it through these pure
+// functions and writes it out on save. Keeping the rules here (rather than in
+// the view) means they can be tested without a terminal, and the same
+// validation applies to the first-run wizard and the settings screen.
+import { ACCESS_MODES, KEEPALIVE_MANAGERS, LANGUAGES, OFFICIAL_RELAY_URL, loadConfig, } from './config.js';
+import { configDir, configPath } from './paths.js';
+import { isLoopbackHost, isUnspecifiedAddress, isUnspecifiedHost, resolvePublicUrl, } from './relay-urls.js';
+import { ensureDir, readJson, writeJsonAtomic } from 'herdr-remote-relay/state';
+import { preferredLanAddress } from './net-interfaces.js';
+function isOneOf(list, value) {
+    return list.includes(value);
+}
+/**
+ * Field metadata. `kind` drives the editor the TUI shows; `visibleFor` limits a
+ * field to the access modes where it means anything.
+ */
+const FIELDS = [
+    { id: 'mode', kind: 'choice', choices: ACCESS_MODES, labelKey: 'field.mode' },
+    { id: 'port', kind: 'text', labelKey: 'field.port', visibleFor: ['local', 'lan'] },
+    { id: 'lanHost', kind: 'address', labelKey: 'field.lanHost', visibleFor: ['lan'] },
+    { id: 'remoteUrl', kind: 'text', labelKey: 'field.remoteUrl', visibleFor: ['remote'] },
+    { id: 'publicUrl', kind: 'text', labelKey: 'field.publicUrl' },
+    { id: 'socketPath', kind: 'text', labelKey: 'field.socketPath' },
+    { id: 'herdrArgs', kind: 'text', labelKey: 'field.herdrArgs' },
+    { id: 'herdrAutoStart', kind: 'toggle', labelKey: 'field.herdrAutoStart' },
+    { id: 'language', kind: 'choice', choices: LANGUAGES, labelKey: 'field.language' },
+    {
+        id: 'keepaliveManager',
+        kind: 'choice',
+        choices: KEEPALIVE_MANAGERS,
+        labelKey: 'field.keepalive',
+    },
+];
+const EMPTY = '';
+/**
+ * The access modes a *person* chooses between.
+ *
+ * The official relay is stored as `remote` with a known URL, because that is
+ * exactly what it is and nothing downstream should have to learn a fourth mode.
+ * It is still a separate answer to "how do I reach this workstation", though:
+ * one option needs no server and no credentials, the other needs both. Keeping
+ * that distinction here — rather than in whichever screen happens to draw it —
+ * is what stops the official relay from being displayed as "self-hosted relay"
+ * that merely happens to hold our address.
+ */
+const SELECTABLE_MODES = ['local', 'lan', 'official', 'remote'];
+/** Which of `SELECTABLE_MODES` this draft represents. */
+function selectedMode(draft) {
+    if (draft.relay.mode === 'remote' && draft.relay.remoteUrl === OFFICIAL_RELAY_URL)
+        return 'official';
+    return draft.relay.mode;
+}
+/** True when the relay is the one we run, so its address and password are ours. */
+function isOfficialRelay(draft) {
+    return selectedMode(draft) === 'official';
+}
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function createDraft(config = loadConfig()) {
+    return clone(config);
+}
+function fieldsForMode(mode) {
+    return FIELDS.filter((field) => !field.visibleFor || field.visibleFor.includes(mode));
+}
+/** Current value of a field as an editable string. */
+function getField(draft, id) {
+    switch (id) {
+        case 'mode':
+            return draft.relay.mode;
+        case 'port':
+            return String(draft.relay.port);
+        case 'lanHost':
+            return draft.relay.lanHost || EMPTY;
+        case 'remoteUrl':
+            return draft.relay.remoteUrl || EMPTY;
+        case 'publicUrl':
+            return draft.relay.publicUrl || EMPTY;
+        case 'socketPath':
+            return draft.herdr.socketPath || EMPTY;
+        case 'herdrArgs':
+            return (draft.herdr.args || []).join(' ');
+        case 'herdrAutoStart':
+            return draft.herdr.autoStart ? 'on' : 'off';
+        case 'language':
+            return draft.ui.language;
+        case 'keepaliveManager':
+            return draft.keepalive.manager;
+        default:
+            return EMPTY;
+    }
+}
+/**
+ * What the field shows when it is empty: the value that will actually be used.
+ * Displaying the derived value beats an empty box the user cannot interpret.
+ */
+function getFieldPlaceholder(draft, id) {
+    switch (id) {
+        case 'lanHost':
+            return preferredLanAddress() || '0.0.0.0';
+        case 'publicUrl':
+            return resolvePublicUrl(draft, preferredLanAddress());
+        case 'socketPath':
+            return 'placeholder.autoDiscovered';
+        case 'herdrArgs':
+            return 'placeholder.none';
+        case 'remoteUrl':
+            return 'wss://relay.example.com';
+        default:
+            return EMPTY;
+    }
+}
+function isValidUrl(value, protocols) {
+    try {
+        const url = new URL(value);
+        return protocols.includes(url.protocol);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Apply a value to a copy of the draft.
+ *
+ * Returns `{ draft, errorKey }`. On a validation failure the draft comes back
+ * unchanged and `errorKey` names a translatable message, so callers never have
+ * to guess whether the edit landed.
+ */
+function setField(draft, id, rawValue) {
+    const next = clone(draft);
+    const value = typeof rawValue === 'string' ? rawValue.trim() : rawValue;
+    // Every field but the toggle is edited as text.
+    const text = value;
+    switch (id) {
+        case 'mode': {
+            if (!isOneOf(SELECTABLE_MODES, value))
+                return { draft, errorKey: 'error.invalidMode' };
+            // Picking the official relay fills in its address in the same edit: a
+            // remote mode with no URL is not a valid state, and asking for the
+            // address we already know would be asking the user to do our filing.
+            if (value === 'official') {
+                next.relay.mode = 'remote';
+                next.relay.remoteUrl = OFFICIAL_RELAY_URL;
+                next.relay.publicUrl = EMPTY;
+                break;
+            }
+            // Leaving the official relay clears its address, so the self-hosted URL
+            // field is empty and asking to be filled in rather than pre-loaded with
+            // an address that belongs to somebody else's server.
+            if (value === 'remote' && next.relay.remoteUrl === OFFICIAL_RELAY_URL) {
+                next.relay.remoteUrl = EMPTY;
+            }
+            next.relay.mode = value;
+            if (value === 'lan' &&
+                (isLoopbackHost(next.relay.lanHost) || isUnspecifiedAddress(next.relay.lanHost))) {
+                next.relay.lanHost = EMPTY;
+            }
+            // A public URL pinned for one mode is wrong for the next one; clearing it
+            // lets derivation produce the right address again.
+            next.relay.publicUrl = EMPTY;
+            break;
+        }
+        case 'port': {
+            const port = Number.parseInt(text, 10);
+            if (!Number.isInteger(port) || port < 1 || port > 65535)
+                return { draft, errorKey: 'error.invalidPort' };
+            next.relay.port = port;
+            break;
+        }
+        case 'lanHost': {
+            if (text && (isLoopbackHost(text) || isUnspecifiedAddress(text))) {
+                return { draft, errorKey: 'error.invalidLanHost' };
+            }
+            next.relay.lanHost = text || EMPTY;
+            break;
+        }
+        case 'remoteUrl': {
+            if (text && !isValidUrl(text, ['ws:', 'wss:', 'http:', 'https:'])) {
+                return { draft, errorKey: 'error.invalidRelayUrl' };
+            }
+            next.relay.remoteUrl = text.replace(/\/+$/, '');
+            break;
+        }
+        case 'publicUrl': {
+            if (text && (!isValidUrl(text, ['http:', 'https:']) || isUnspecifiedHost(text))) {
+                return { draft, errorKey: 'error.invalidPublicUrl' };
+            }
+            next.relay.publicUrl = text.replace(/\/+$/, '');
+            break;
+        }
+        case 'socketPath': {
+            next.herdr.socketPath = text || null;
+            break;
+        }
+        case 'herdrArgs': {
+            const args = text ? text.split(/\s+/).filter(Boolean) : [];
+            if (args.includes('--no-session')) {
+                return { draft, errorKey: 'error.removedHerdrArg' };
+            }
+            next.herdr.args = args;
+            break;
+        }
+        case 'herdrAutoStart': {
+            if (value !== true && value !== false && value !== 'on' && value !== 'off') {
+                return { draft, errorKey: 'error.unknownField' };
+            }
+            next.herdr.autoStart = value === true || value === 'on';
+            break;
+        }
+        case 'language': {
+            if (!isOneOf(LANGUAGES, value))
+                return { draft, errorKey: 'error.invalidLanguage' };
+            next.ui.language = value;
+            break;
+        }
+        case 'keepaliveManager': {
+            if (!isOneOf(KEEPALIVE_MANAGERS, value))
+                return { draft, errorKey: 'error.invalidKeepalive' };
+            next.keepalive.manager = value;
+            break;
+        }
+        default:
+            return { draft, errorKey: 'error.unknownField' };
+    }
+    return { draft: next, errorKey: null };
+}
+/** Problems that should block saving, as translatable keys. */
+function validateDraft(draft) {
+    const problems = [];
+    if (draft.relay.mode === 'remote' && !draft.relay.remoteUrl)
+        problems.push('error.remoteUrlRequired');
+    return problems;
+}
+/**
+ * Persist a draft, merging into whatever is already on disk so keys this
+ * version does not know about survive the round trip.
+ */
+function saveDraft(draft) {
+    const problems = validateDraft(draft);
+    if (problems.length > 0) {
+        throw Object.assign(new Error(`configuration is incomplete: ${problems.join(', ')}`), {
+            problems,
+        });
+    }
+    const current = (readJson(configPath(), {}) || {});
+    const merged = { ...current };
+    merged.ui = { ...(current.ui || {}), language: draft.ui.language };
+    const relay = {
+        ...(current.relay || {}),
+        mode: draft.relay.mode,
+        port: draft.relay.port,
+        lanHost: draft.relay.mode === 'lan' &&
+            (isLoopbackHost(draft.relay.lanHost) || isUnspecifiedAddress(draft.relay.lanHost))
+            ? EMPTY
+            : draft.relay.lanHost,
+        publicUrl: draft.relay.publicUrl,
+        remoteUrl: draft.relay.remoteUrl,
+    };
+    merged.relay = relay;
+    // Fields from the 0.1 schema would otherwise keep overriding the new ones on
+    // the next load.
+    delete relay.local;
+    delete relay.host;
+    delete relay.url;
+    // The optional Herdr source patch is gone. Nothing reads this section any
+    // more, so the next save is where a config written by an older build sheds
+    // it rather than carrying stale checksums and paths forever.
+    delete merged.patch;
+    const herdr = {
+        ...(current.herdr || {}),
+        socketPath: draft.herdr.socketPath,
+        args: draft.herdr.args,
+        autoStart: draft.herdr.autoStart === true,
+    };
+    merged.herdr = herdr;
+    if (!herdr.socketPath)
+        delete herdr.socketPath;
+    merged.keepalive = { ...(current.keepalive || {}), manager: draft.keepalive.manager };
+    ensureDir(configDir());
+    writeJsonAtomic(configPath(), merged);
+    return { ok: true, path: configPath() };
+}
+/**
+ * Settings that only take effect after the services restart. Used to show a
+ * "restart required" hint rather than silently doing nothing.
+ */
+function requiresRestart(before, after) {
+    return (before.relay.mode !== after.relay.mode ||
+        before.relay.port !== after.relay.port ||
+        before.relay.lanHost !== after.relay.lanHost ||
+        before.relay.remoteUrl !== after.relay.remoteUrl ||
+        before.relay.publicUrl !== after.relay.publicUrl ||
+        before.herdr.socketPath !== after.herdr.socketPath ||
+        before.herdr.args.join(' ') !== after.herdr.args.join(' '));
+}
+export { createDraft, fieldsForMode, isOfficialRelay, selectedMode, getField, getFieldPlaceholder, setField, validateDraft, saveDraft, requiresRestart, };

package/dist/socket-discovery.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+function defaultSocketPath(env = process.env, platform = process.platform) {
+    if (env.HERDR_SOCKET_PATH)
+        return env.HERDR_SOCKET_PATH;
+    if (platform === 'win32') {
+        const appData = env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
+        return path.join(appData, 'herdr', 'herdr.sock');
+    }
+    const configHome = env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+    return path.join(configHome, 'herdr', 'herdr.sock');
+}
+function resolveSocketPath(configuredPath = null, env = process.env) {
+    return configuredPath || env.HERDR_SOCKET_PATH || defaultSocketPath(env);
+}
+function inspectSocket(socketPath, options = {}) {
+    if (typeof socketPath !== 'string' || socketPath.length === 0) {
+        return { ok: false, reason: 'socket path is empty', path: socketPath };
+    }
+    try {
+        const stat = fs.statSync(socketPath);
+        if (process.platform !== 'win32' && !stat.isSocket()) {
+            return { ok: false, reason: 'path is not a Unix socket', path: socketPath };
+        }
+        if (options.requireOwner !== false &&
+            typeof process.getuid === 'function' &&
+            stat.uid !== process.getuid()) {
+            return {
+                ok: false,
+                reason: 'socket is not owned by the current user',
+                path: socketPath,
+                uid: stat.uid,
+            };
+        }
+        return { ok: true, path: socketPath, uid: stat.uid, mode: stat.mode };
+    }
+    catch (error) {
+        const { code, message } = error;
+        return {
+            ok: false,
+            missing: code === 'ENOENT',
+            reason: code === 'ENOENT' ? 'socket does not exist' : message,
+            path: socketPath,
+        };
+    }
+}
+export { defaultSocketPath, resolveSocketPath, inspectSocket };

package/dist/supervisor.js

@@ -0,0 +1,319 @@
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+import { loadConfig } from './config.js';
+import { logPath, PACKAGE_ROOT, stateDir } from './paths.js';
+import { ensureDir } from 'herdr-remote-relay/state';
+import { ensureRuntime, managedPids, recordManagedPid, updateRuntime, } from './runtime.js';
+import { baseEnvironment, serviceSpecs } from './service.js';
+import { EXIT_REPLACED, EXIT_AUTH_FAILED } from './exit-codes.js';
+import { pidAlive } from './lib/process.js';
+const MIN_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 30_000;
+// A child that stayed up this long is considered healthy, so the next crash
+// starts backing off from scratch instead of inheriting an old penalty.
+const HEALTHY_UPTIME_MS = 30_000;
+/**
+ * Runs the relay and host connector as managed children and restarts them when
+ * they die.
+ *
+ * This is the process a service manager supervises: `herdr-remote run` stays in
+ * the foreground so systemd/launchd can track it, and the same class backs the
+ * fallback daemon on systems where neither is available.
+ */
+class Supervisor {
+    config;
+    state;
+    logToFiles;
+    onEvent;
+    /** What to run; the relay and host connector unless a test says otherwise. */
+    specs;
+    children = new Map();
+    stopping = false;
+    constructor({ config = loadConfig(), state = ensureRuntime(), logToFiles = false, onEvent = null, specs = null, } = {}) {
+        this.config = config;
+        this.state = state;
+        this.logToFiles = logToFiles;
+        this.onEvent = onEvent;
+        this.specs = specs;
+    }
+    emit(event) {
+        if (this.onEvent)
+            this.onEvent(event);
+        const line = `[${new Date().toISOString()}] herdr-remote supervisor: ${event.message}\n`;
+        process.stdout.write(line);
+    }
+    /**
+     * Stop anything a previous, unmanaged start left behind.
+     *
+     * Taking over without this is what produced the runaway: a detached relay
+     * from `herdr-remote start` kept port 8787, so every relay this supervisor
+     * spawned died with EADDRINUSE and retried forever, while the orphaned host
+     * connector and ours both claimed the same host id on the relay and kicked
+     * each other off — which is what browsers saw as an endless reconnect.
+     */
+    async reclaimStrays({ timeoutMs = 5000 } = {}) {
+        const strays = managedPids().filter((entry) => entry.pid !== process.pid);
+        if (strays.length === 0)
+            return strays;
+        for (const { pid, name } of strays) {
+            this.emit({
+                type: 'reclaim',
+                name,
+                pid,
+                message: `stopping stray ${name} from an earlier start (pid ${pid})`,
+            });
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch {
+                // Already gone, or not ours to signal; the liveness check below decides.
+            }
+        }
+        // Wait for them to actually go: the relay only releases its port on exit,
+        // and spawning ours before then just reproduces the EADDRINUSE loop.
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (strays.every(({ pid }) => !pidAlive(pid)))
+                return strays;
+            await new Promise((resolve) => {
+                setTimeout(resolve, 100);
+            });
+        }
+        for (const { pid, name } of strays) {
+            if (!pidAlive(pid))
+                continue;
+            this.emit({
+                type: 'reclaim',
+                name,
+                pid,
+                message: `stray ${name} (pid ${pid}) ignored SIGTERM, killing`,
+            });
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // Already gone; SIGKILL was the last resort anyway.
+            }
+        }
+        return strays;
+    }
+    async start() {
+        this.stopping = false;
+        ensureDir(stateDir());
+        await this.reclaimStrays();
+        if (this.stopping)
+            return;
+        for (const spec of this.specs ?? serviceSpecs(this.config, this.state)) {
+            this.children.set(spec.name, {
+                spec,
+                child: null,
+                pid: null,
+                restarts: 0,
+                backoffMs: MIN_BACKOFF_MS,
+                timer: null,
+            });
+            this.spawnChild(spec.name);
+        }
+        this.persistPids();
+    }
+    spawnChild(name) {
+        if (this.stopping)
+            return;
+        const entry = this.children.get(name);
+        if (!entry || entry.child)
+            return;
+        let stdio = ['ignore', 'inherit', 'inherit'];
+        let fd = null;
+        if (this.logToFiles) {
+            fd = fs.openSync(logPath(name), 'a');
+            stdio = ['ignore', fd, fd];
+        }
+        let child;
+        try {
+            child = spawn(entry.spec.command, entry.spec.args, {
+                cwd: PACKAGE_ROOT,
+                env: { ...baseEnvironment(), ...entry.spec.env },
+                stdio,
+            });
+        }
+        catch (error) {
+            this.emit({
+                type: 'spawn_failed',
+                name,
+                message: `could not start ${name}: ${error.message}`,
+            });
+            this.scheduleRestart(name);
+            return;
+        }
+        finally {
+            // The child inherited the descriptor during spawn, so this copy is done.
+            if (fd !== null) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch {
+                    // The child holds its own copy; failing to close ours leaks one descriptor at worst.
+                }
+            }
+        }
+        entry.child = child;
+        entry.pid = child.pid;
+        entry.startedAt = Date.now();
+        this.emit({
+            type: 'started',
+            name,
+            pid: child.pid,
+            message: `${name} started (pid ${child.pid})`,
+        });
+        this.persistPids();
+        child.on('exit', (code, signal) => {
+            const uptimeMs = Date.now() - (entry.startedAt ?? Date.now());
+            entry.child = null;
+            entry.pid = null;
+            this.persistPids();
+            if (this.stopping)
+                return;
+            if (code === EXIT_REPLACED) {
+                this.emit({
+                    type: 'replaced',
+                    name,
+                    message: `${name} stood down: another instance owns this workstation. Not restarting it.`,
+                });
+                return;
+            }
+            if (code === EXIT_AUTH_FAILED) {
+                this.emit({
+                    type: 'fatal',
+                    name,
+                    message: `${name} stopped: relay authentication failed. Update credentials before restarting it.`,
+                });
+                return;
+            }
+            if (uptimeMs >= HEALTHY_UPTIME_MS)
+                entry.backoffMs = MIN_BACKOFF_MS;
+            this.emit({
+                type: 'exited',
+                name,
+                code,
+                signal,
+                message: `${name} exited (${signal || `code ${code}`}) after ${Math.round(uptimeMs / 1000)}s, restarting in ${entry.backoffMs}ms`,
+            });
+            this.scheduleRestart(name);
+        });
+        child.on('error', (error) => {
+            this.emit({ type: 'error', name, message: `${name} error: ${error.message}` });
+        });
+    }
+    scheduleRestart(name) {
+        if (this.stopping)
+            return;
+        const entry = this.children.get(name);
+        if (!entry || entry.timer)
+            return;
+        const delay = entry.backoffMs;
+        entry.restarts += 1;
+        entry.backoffMs = Math.min(MAX_BACKOFF_MS, Math.round(entry.backoffMs * 2));
+        const timer = setTimeout(() => {
+            entry.timer = null;
+            this.spawnChild(name);
+        }, delay);
+        entry.timer = timer;
+        timer.unref?.();
+    }
+    persistPids() {
+        try {
+            updateRuntime((current) => {
+                current.supervisorPid = process.pid;
+                current.relayPid = this.children.get('relay')?.pid || null;
+                current.hostPid = this.children.get('host')?.pid || null;
+                current.startedAt = current.startedAt || new Date().toISOString();
+                current.mode = this.config.relay.mode;
+                // Merge into the ledger rather than replacing it, so a pid recorded by
+                // another writer is never dropped and left running with nobody tracking
+                // it.
+                recordManagedPid(current, 'supervisor', process.pid);
+                for (const [name, entry] of this.children) {
+                    if (entry.pid)
+                        recordManagedPid(current, name, entry.pid);
+                }
+            });
+        }
+        catch (error) {
+            process.stderr.write(`herdr-remote supervisor: could not persist pids: ${error.message}\n`);
+        }
+    }
+    async stop({ graceMs = 5000 } = {}) {
+        this.stopping = true;
+        const pending = [];
+        for (const entry of this.children.values()) {
+            if (entry.timer) {
+                clearTimeout(entry.timer);
+                entry.timer = null;
+            }
+            const child = entry.child;
+            if (!child)
+                continue;
+            pending.push(new Promise((resolve) => {
+                const killTimer = setTimeout(() => {
+                    try {
+                        child.kill('SIGKILL');
+                    }
+                    catch {
+                        // Already exited between the timer and the kill.
+                    }
+                    resolve();
+                }, graceMs);
+                killTimer.unref?.();
+                child.once('exit', () => {
+                    clearTimeout(killTimer);
+                    resolve();
+                });
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch {
+                    resolve();
+                }
+            }));
+        }
+        await Promise.all(pending);
+        try {
+            updateRuntime((current) => {
+                current.supervisorPid = null;
+                current.relayPid = null;
+                current.hostPid = null;
+                current.startedAt = null;
+                current.managedPids = (current.managedPids || []).filter((entry) => entry && pidAlive(entry.pid));
+            });
+        }
+        catch {
+            // The runtime file is advisory; stopping must finish even if it cannot be written.
+        }
+    }
+}
+/** Entry point for `herdr-remote run`: supervise in the foreground until told to stop. */
+async function runForeground({ logToFiles = false } = {}) {
+    const supervisor = new Supervisor({ logToFiles });
+    await supervisor.start();
+    return new Promise((resolve) => {
+        let shuttingDown = false;
+        const shutdown = async (signal) => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            supervisor.emit({ type: 'shutdown', message: `${signal} received, stopping services` });
+            await supervisor.stop();
+            resolve(0);
+        };
+        process.on('SIGINT', () => {
+            shutdown('SIGINT');
+        });
+        process.on('SIGTERM', () => {
+            shutdown('SIGTERM');
+        });
+        process.on('SIGHUP', () => {
+            shutdown('SIGHUP');
+        });
+    });
+}
+export { MIN_BACKOFF_MS, runForeground, Supervisor };