herdr-remote 0.2.0

package/src/settings-model.js

@@ -0,0 +1,265 @@
+'use strict';
+
+// 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.
+
+const {
+  ACCESS_MODES,
+  KEEPALIVE_MANAGERS,
+  LANGUAGES,
+  configDir,
+  configPath,
+  isLoopbackHost,
+  isUnspecifiedAddress,
+  isUnspecifiedHost,
+  loadConfig,
+  resolvePublicUrl,
+} = require('./config');
+const { ensureDir, readJson, writeJsonAtomic } = require('./state');
+const { preferredLanAddress } = require('./net-interfaces');
+
+/**
+ * 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: 'language', kind: 'choice', choices: LANGUAGES, labelKey: 'field.language' },
+  { id: 'keepaliveManager', kind: 'choice', choices: KEEPALIVE_MANAGERS, labelKey: 'field.keepalive' },
+];
+
+const EMPTY = '';
+
+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 '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;
+
+  switch (id) {
+    case 'mode': {
+      if (!ACCESS_MODES.includes(value)) return { draft, errorKey: 'error.invalidMode' };
+      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(value, 10);
+      if (!Number.isInteger(port) || port < 1 || port > 65535) return { draft, errorKey: 'error.invalidPort' };
+      next.relay.port = port;
+      break;
+    }
+    case 'lanHost': {
+      if (value && (isLoopbackHost(value) || isUnspecifiedAddress(value))) {
+        return { draft, errorKey: 'error.invalidLanHost' };
+      }
+      next.relay.lanHost = value || EMPTY;
+      break;
+    }
+    case 'remoteUrl': {
+      if (value && !isValidUrl(value, ['ws:', 'wss:', 'http:', 'https:'])) {
+        return { draft, errorKey: 'error.invalidRelayUrl' };
+      }
+      next.relay.remoteUrl = value.replace(/\/+$/, '');
+      break;
+    }
+    case 'publicUrl': {
+      if (value && (!isValidUrl(value, ['http:', 'https:']) || isUnspecifiedHost(value))) {
+        return { draft, errorKey: 'error.invalidPublicUrl' };
+      }
+      next.relay.publicUrl = value.replace(/\/+$/, '');
+      break;
+    }
+    case 'socketPath': {
+      next.herdr.socketPath = value || null;
+      break;
+    }
+    case 'herdrArgs': {
+      next.herdr.args = value ? value.split(/\s+/).filter(Boolean) : [];
+      break;
+    }
+    case 'language': {
+      if (!LANGUAGES.includes(value)) return { draft, errorKey: 'error.invalidLanguage' };
+      next.ui.language = value;
+      break;
+    }
+    case 'keepaliveManager': {
+      if (!KEEPALIVE_MANAGERS.includes(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) {
+    const error = new Error(`configuration is incomplete: ${problems.join(', ')}`);
+    error.problems = problems;
+    throw error;
+  }
+
+  const current = readJson(configPath(), {}) || {};
+  const merged = { ...current };
+  merged.ui = { ...(current.ui || {}), language: draft.ui.language };
+  merged.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,
+  };
+  // Fields from the 0.1 schema would otherwise keep overriding the new ones on
+  // the next load.
+  delete merged.relay.local;
+  delete merged.relay.host;
+  delete merged.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;
+  merged.herdr = {
+    ...(current.herdr || {}),
+    socketPath: draft.herdr.socketPath,
+    args: draft.herdr.args,
+  };
+  if (!merged.herdr.socketPath) delete merged.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(' ');
+}
+
+module.exports = {
+  FIELDS,
+  createDraft,
+  fieldsForMode,
+  getField,
+  getFieldPlaceholder,
+  setField,
+  validateDraft,
+  saveDraft,
+  requiresRestart,
+};

package/src/socket-discovery.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('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) {
+    return { ok: false, reason: error.code === 'ENOENT' ? 'socket does not exist' : error.message, path: socketPath };
+  }
+}
+
+function assertSocket(socketPath, options = {}) {
+  const result = inspectSocket(socketPath, options);
+  if (!result.ok) {
+    const error = new Error(`Herdr socket unavailable at ${socketPath}: ${result.reason}`);
+    error.code = 'HERDR_SOCKET_UNAVAILABLE';
+    error.details = result;
+    throw error;
+  }
+  return result;
+}
+
+module.exports = {
+  defaultSocketPath,
+  resolveSocketPath,
+  inspectSocket,
+  assertSocket,
+};

package/src/state.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true, mode: 0o700 });
+  try {
+    fs.chmodSync(dirPath, 0o700);
+  } catch {}
+}
+
+function writeJsonAtomic(filePath, value) {
+  ensureDir(path.dirname(filePath));
+  const tempPath = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  try {
+    fs.chmodSync(tempPath, 0o600);
+  } catch {}
+  fs.renameSync(tempPath, filePath);
+  try {
+    fs.chmodSync(filePath, 0o600);
+  } catch {}
+}
+
+function readJson(filePath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      process.stderr.write(`herdr-remote: invalid state at ${filePath}: ${error.message}\n`);
+    }
+    return fallback;
+  }
+}
+
+function randomToken(bytes = 32) {
+  return crypto.randomBytes(bytes).toString('base64url');
+}
+
+module.exports = {
+  ensureDir,
+  writeJsonAtomic,
+  readJson,
+  randomToken,
+};

package/src/supervisor.js

@@ -0,0 +1,242 @@
+'use strict';
+
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+const { PACKAGE_ROOT, loadConfig, runtimeStatePath, stateDir } = require('./config');
+const { ensureDir, readJson, writeJsonAtomic } = require('./state');
+const { baseEnvironment, ensureRuntime, logPath, managedPids, pidAlive, recordManagedPid, serviceSpecs } = require('./service');
+const { EXIT_REPLACED } = require('./exit-codes');
+
+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 {
+  constructor({ config = loadConfig(), state = ensureRuntime(), logToFiles = false, onEvent = null } = {}) {
+    this.config = config;
+    this.state = state;
+    this.logToFiles = logToFiles;
+    this.onEvent = onEvent;
+    this.children = new Map();
+    this.stopping = false;
+  }
+
+  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 {}
+    }
+
+    // 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 {}
+    }
+    return strays;
+  }
+
+  async start() {
+    this.stopping = false;
+    ensureDir(stateDir());
+    await this.reclaimStrays();
+    if (this.stopping) return;
+    for (const spec of 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 {}
+      }
+    }
+
+    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;
+      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 (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));
+    entry.timer = setTimeout(() => {
+      entry.timer = null;
+      this.spawnChild(name);
+    }, delay);
+    entry.timer.unref?.();
+  }
+
+  persistPids() {
+    try {
+      const current = readJson(runtimeStatePath(), {});
+      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);
+      }
+      writeJsonAtomic(runtimeStatePath(), current);
+    } 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 {}
+          resolve();
+        }, graceMs);
+        killTimer.unref?.();
+        child.once('exit', () => {
+          clearTimeout(killTimer);
+          resolve();
+        });
+        try { child.kill('SIGTERM'); } catch { resolve(); }
+      }));
+    }
+    await Promise.all(pending);
+    try {
+      const current = readJson(runtimeStatePath(), {});
+      current.supervisorPid = null;
+      current.relayPid = null;
+      current.hostPid = null;
+      current.startedAt = null;
+      current.managedPids = (current.managedPids || []).filter((entry) => entry && pidAlive(entry.pid));
+      writeJsonAtomic(runtimeStatePath(), current);
+    } catch {}
+  }
+}
+
+/** 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'); });
+  });
+}
+
+module.exports = { Supervisor, runForeground, MIN_BACKOFF_MS, MAX_BACKOFF_MS, HEALTHY_UPTIME_MS };