herdr-remote 0.2.0

package/src/host-connector.js

@@ -0,0 +1,280 @@
+'use strict';
+
+const os = require('node:os');
+const crypto = require('node:crypto');
+const { WebSocket } = require('ws');
+const { loadConfig, hostWebSocketUrl, resolveHostRelayUrl } = require('./config');
+const { resolveSocketPath, inspectSocket } = require('./socket-discovery');
+const { PtySession } = require('./pty-session');
+const { resolveHerdrCommand } = require('./herdr-command');
+// The wire format lives in the relay package so both ends of the protocol are
+// generated from one definition.
+const { packStreamFrame, unpackStreamFrame, PROTOCOL_VERSION } = require('herdr-remote-relay/protocol');
+const { resolveHostPalette } = require('./terminal-palette');
+const { EXIT_REPLACED } = require('./exit-codes');
+
+function randomId(prefix) {
+  return `${prefix}-${crypto.randomBytes(9).toString('base64url')}`;
+}
+
+function sendJson(ws, payload) {
+  if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(payload));
+}
+
+function closeSocket(ws) {
+  if (!ws || ws.readyState === WebSocket.CLOSED || ws.readyState === WebSocket.CLOSING) return;
+  try { ws.close(1000, 'host connector stopping'); } catch {}
+}
+
+class HostConnector {
+  constructor(options = {}) {
+    const config = options.config || loadConfig();
+    this.config = config;
+    this.relayUrl = options.relayUrl
+      || (process.env.RELAY_URL ? hostWebSocketUrl(process.env.RELAY_URL) : resolveHostRelayUrl(config));
+    this.hostId = options.hostId || process.env.RELAY_HOST_ID || randomId('host');
+    this.hostToken = options.hostToken || process.env.RELAY_HOST_TOKEN || '';
+    // Optional; a relay without a password accepts any workstation.
+    this.relayPassword = options.relayPassword ?? process.env.RELAY_PASSWORD ?? '';
+    this.socketPath = options.socketPath || resolveSocketPath(config.herdr.socketPath);
+    this.herdrCommand = options.herdrCommand || resolveHerdrCommand();
+    this.herdrArgs = options.herdrArgs || config.herdr.args;
+    this.cwd = options.cwd || config.herdr.cwd;
+    /**
+     * What the workstation's own terminal looks like. A browser has no way to
+     * know it — the PTY carries color indices, not colors — so the host reports
+     * it and the browser renders the session the way the workstation sees it.
+     * Normally captured by the start path that still had a terminal and passed
+     * down in the environment; `null` when nobody could ask.
+     */
+    this.terminalPalette = options.terminalPalette !== undefined
+      ? options.terminalPalette
+      : resolveHostPalette();
+    this.ws = null;
+    this.sessions = new Map();
+    this.reconnectTimer = null;
+    this.heartbeatTimer = null;
+    this.reconnectAttempts = 0;
+    this.stopping = false;
+  }
+
+  start() {
+    if (!this.hostToken) {
+      throw new Error('RELAY_HOST_TOKEN is required');
+    }
+    this.stopping = false;
+    this.connect();
+  }
+
+  stop() {
+    this.stopping = true;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    this.reconnectTimer = null;
+    this.heartbeatTimer = null;
+    this.destroySessions();
+    closeSocket(this.ws);
+    this.ws = null;
+  }
+
+  connect() {
+    if (this.stopping || (this.ws && [WebSocket.OPEN, WebSocket.CONNECTING].includes(this.ws.readyState))) return;
+    let ws;
+    try {
+      ws = new WebSocket(this.relayUrl);
+    } catch (error) {
+      this.scheduleReconnect(error);
+      return;
+    }
+    this.ws = ws;
+    ws.isAlive = true;
+    ws.on('open', () => {
+      this.reconnectAttempts = 0;
+      ws.isAlive = true;
+      sendJson(ws, {
+        type: 'host_hello',
+        protocol: PROTOCOL_VERSION,
+        hostId: this.hostId,
+        token: this.hostToken,
+        password: this.relayPassword || null,
+        hostname: os.hostname(),
+        platform: process.platform,
+        arch: process.arch,
+        terminalPalette: this.terminalPalette || null,
+      });
+      this.sendHeartbeat();
+      this.heartbeatTimer = setInterval(() => this.sendHeartbeat(), this.config.cleanup.heartbeatIntervalMs);
+    });
+    ws.on('pong', () => { ws.isAlive = true; });
+    ws.on('message', (raw, isBinary) => this.handleMessage(raw, isBinary));
+    ws.on('close', (code, rawReason) => {
+      if (this.ws === ws) this.ws = null;
+      if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+      this.destroySessions();
+
+      // Another connector has claimed this workstation. Reconnecting would just
+      // displace it in turn, and each swap drops every attached browser, so
+      // stand down instead of fighting for the slot.
+      const reason = rawReason ? rawReason.toString() : '';
+      if (reason === 'host_replaced') {
+        this.stopping = true;
+        process.stderr.write('herdr-remote host connector: another instance took over this workstation; exiting\n');
+        this.stop();
+        process.exit(EXIT_REPLACED);
+      }
+      this.scheduleReconnect();
+    });
+    ws.on('error', (error) => {
+      process.stderr.write(`herdr-remote host connector: ${error.message}\n`);
+    });
+  }
+
+  scheduleReconnect(error = null) {
+    if (this.stopping || this.reconnectTimer) return;
+    if (error) process.stderr.write(`herdr-remote host connector: ${error.message}\n`);
+    const delay = Math.min(30000, 500 * (1.5 ** this.reconnectAttempts) + Math.floor(Math.random() * 250));
+    this.reconnectAttempts += 1;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delay);
+  }
+
+  handleMessage(raw, isBinary) {
+    if (isBinary) {
+      let frame;
+      try {
+        frame = unpackStreamFrame(raw);
+      } catch (error) {
+        process.stderr.write(`herdr-remote host connector: invalid relay frame: ${error.message}\n`);
+        return;
+      }
+      if (frame.type === 'input') this.sessions.get(frame.streamId)?.pty.write(frame.payload);
+      return;
+    }
+    let message;
+    try { message = JSON.parse(raw.toString('utf8')); } catch { return; }
+    // A relay-level error (no clientId) is a rejected handshake — a wrong relay
+    // password, or a host token the relay does not recognise. Without this the
+    // connection just closed silently and reconnected forever, leaving the user
+    // with an empty log and no idea what was wrong.
+    if (message.type === 'error' && !message.clientId) {
+      process.stderr.write(`herdr-remote host connector: relay rejected the connection: ${message.message || message.code}\n`);
+      return;
+    }
+    if (message.type === 'session_start') this.startSession(message);
+    else if (message.type === 'session_stop') this.stopSession(message.clientId || message.streamId);
+    else if (message.type === 'resize') this.resizeSession(message);
+  }
+
+  startSession(message) {
+    const streamId = typeof message.streamId === 'string' ? message.streamId : message.clientId;
+    if (!streamId) return;
+    this.stopSession(streamId);
+    const socketInfo = inspectSocket(this.socketPath);
+    if (!socketInfo.ok) {
+      sendJson(this.ws, { type: 'error', clientId: streamId, code: 'herdr_socket_unavailable', message: socketInfo.reason });
+      return;
+    }
+    const pty = new PtySession({
+      command: this.herdrCommand,
+      args: this.herdrArgs,
+      cwd: this.cwd,
+      socketPath: this.socketPath,
+    });
+    const session = {
+      id: streamId,
+      pty,
+      cols: Number(message.cols) || PtySession.DEFAULT_COLS,
+      rows: Number(message.rows) || PtySession.DEFAULT_ROWS,
+      createdAt: new Date().toISOString(),
+      clientId: streamId,
+    };
+    try {
+      pty.start({
+        cols: session.cols,
+        rows: session.rows,
+        onData: (data) => {
+          const payload = Buffer.from(data, 'utf8');
+          if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(packStreamFrame('output', streamId, payload));
+        },
+        onExit: ({ exitCode }) => {
+          if (this.sessions.get(streamId) !== session) return;
+          this.sessions.delete(streamId);
+          sendJson(this.ws, { type: 'session_exit', clientId: streamId, code: exitCode });
+          this.sendHeartbeat();
+        },
+      });
+    } catch (error) {
+      sendJson(this.ws, { type: 'error', clientId: streamId, code: 'pty_start_failed', message: error.message });
+      pty.kill();
+      return;
+    }
+    this.sessions.set(streamId, session);
+    sendJson(this.ws, { type: 'session_ready', clientId: streamId });
+    this.sendHeartbeat();
+  }
+
+  stopSession(streamId) {
+    const session = this.sessions.get(streamId);
+    if (!session) return;
+    this.sessions.delete(streamId);
+    session.pty.kill();
+    this.sendHeartbeat();
+  }
+
+  resizeSession(message) {
+    const id = message.clientId || message.streamId;
+    const session = this.sessions.get(id);
+    if (!session) return;
+    session.cols = Number.isInteger(message.cols) ? Math.min(500, Math.max(2, message.cols)) : session.cols;
+    session.rows = Number.isInteger(message.rows) ? Math.min(500, Math.max(2, message.rows)) : session.rows;
+    session.pty.resize(session.cols, session.rows);
+  }
+
+  destroySessions() {
+    for (const session of this.sessions.values()) session.pty.kill();
+    this.sessions.clear();
+  }
+
+  sendHeartbeat() {
+    const memory = process.memoryUsage();
+    const load = os.loadavg();
+    sendJson(this.ws, {
+      type: 'heartbeat',
+      load: {
+        load1m: load[0] || 0,
+        load5m: load[1] || 0,
+        load15m: load[2] || 0,
+        rssBytes: memory.rss,
+        heapUsedBytes: memory.heapUsed,
+      },
+      ptys: [...this.sessions.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,
+      })),
+    });
+  }
+}
+
+if (require.main === module) {
+  const connector = new HostConnector();
+  try {
+    connector.start();
+  } catch (error) {
+    process.stderr.write(`herdr-remote host connector failed: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+  const stop = () => { connector.stop(); process.exit(0); };
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+}
+
+module.exports = { HostConnector, PROTOCOL_VERSION };

package/src/i18n/en.js

@@ -0,0 +1,219 @@
+'use strict';
+
+// English message catalogue. This file is the reference: zh.js must define
+// exactly the same keys, which tests/i18n.test.js enforces.
+
+module.exports = {
+  'app.name': 'Herdr Remote',
+  'app.tagline': 'Remote browser access to your Herdr workspaces',
+
+  'common.yes': 'Yes',
+  'common.no': 'No',
+  'common.on': 'on',
+  'common.off': 'off',
+  'common.none': 'none',
+  'common.auto': 'auto',
+  'common.unknown': 'unknown',
+  'common.running': 'running',
+  'common.stopped': 'stopped',
+  'common.connected': 'connected',
+  'common.disconnected': 'disconnected',
+  'common.installed': 'installed',
+  'common.notInstalled': 'not installed',
+  'common.enabled': 'enabled',
+  'common.disabled': 'disabled',
+  'common.loading': 'Working…',
+  'common.save': 'Save settings',
+  'common.saved': 'Configuration saved to {path}',
+  'common.back': 'Back',
+  'common.cancel': 'Cancel',
+  'common.confirm': 'Confirm',
+  'common.pid': 'pid {pid}',
+  'common.notApplicable': 'n/a',
+
+  'nav.overview': 'Overview',
+  'nav.pair': 'Pair a device',
+  'nav.services': 'Services',
+  'nav.relay': 'Relay',
+  'nav.keepalive': 'Keep-alive',
+  'nav.herdr': 'Herdr',
+  'nav.about': 'Language & about',
+
+  'mode.local': 'This machine only',
+  'mode.lan': 'Local network / Tailscale',
+  'mode.remote': 'Self-hosted relay',
+  'mode.local.description': 'The relay listens on 127.0.0.1. Only a browser on this machine can reach it.',
+  'mode.lan.description': 'The relay listens on 0.0.0.0 (every interface), so phones on your LAN or tailnet can reach it.',
+  'mode.remote.description': 'No local relay. The workstation dials a relay you run, which is the only way in from outside your network.',
+
+  'overview.title': 'Status',
+  'overview.mode': 'Access mode',
+  'overview.relay': 'Relay',
+  'overview.host': 'Host connector',
+  'overview.socket': 'Herdr socket',
+  'overview.webUrl': 'Web UI',
+  'overview.keepalive': 'Keep-alive',
+  'overview.devices': 'Browsers',
+  'overview.hosts': 'Workstations',
+  'overview.uptime': 'Relay uptime',
+  'overview.relayLocal': 'local, {bind}:{port}',
+  'overview.relayRemote': 'remote, {url}',
+  'overview.socketMissing': 'not found — is Herdr running?',
+  'overview.unreachable': 'unreachable: {message}',
+  'overview.notStarted': 'Services are not running. Open the Services tab to start them.',
+
+  'pair.title': 'Pair a device',
+  'pair.generate': 'Generate a one-time pairing code',
+  'pair.regenerate': 'Generate another code',
+  'pair.working': 'Starting services and requesting a code…',
+  'pair.code': 'Pairing code',
+  'pair.url': 'Open on your phone',
+  'pair.expires': 'Expires in {minutes} (at {time})',
+  'pair.expired': 'This code has expired. Generate a new one.',
+  'pair.instructions': 'Open the URL, enter the code, and the browser is paired for good.',
+  'pair.qrHint': 'Scan the code with your phone camera to open the URL.',
+  'pair.qrUnavailable': 'The terminal is too narrow for a QR code; use the URL above.',
+  'pair.failed': 'Could not create a pairing code: {message}',
+  'pair.hostOffline': 'The relay has no workstation connected yet. Start the services first.',
+
+  'services.title': 'Services',
+  'services.start': 'Start services',
+  'services.stop': 'Stop services',
+  'services.restart': 'Restart services',
+  'services.started': 'Services started.',
+  'services.stopped': 'Services stopped.',
+  'services.restarted': 'Services restarted.',
+  'services.startFailed': 'Could not start services: {message}',
+  'services.stopFailed': 'Could not stop services: {message}',
+  'services.unsavedBlocked': 'There are unsaved changes. Save them first, or the services restart on the configuration still on disk.',
+  'services.managedNotice': 'These services are managed by {manager}; the keep-alive unit was used to apply the change.',
+  'services.logs': 'Recent log output',
+  'services.logEmpty': 'No log output yet.',
+  'services.logRelay': 'Relay',
+  'services.logHost': 'Host connector',
+
+  'relay.title': 'Relay settings',
+  'relay.settings': 'Settings',
+  'relay.password': 'Relay password',
+  'relay.passwordHint': 'Must match RELAY_PASSWORD on the relay. Leave empty for a public relay.',
+  'relay.passwordSet': 'set',
+  'relay.passwordEmpty': 'not set (public relay)',
+  'relay.passwordSaved': 'Relay password saved. Restart the services to apply it.',
+  'relay.showPassword': 'Show the password',
+  'relay.hidePassword': 'Hide the password',
+  'relay.identity': 'Workstation id',
+  'relay.regenerate': 'Generate a new workstation identity',
+  'relay.regenerated': 'New workstation identity generated. Restart the services to enrol again.',
+  'relay.envSnippet': 'Command for your relay server',
+  'relay.envHint': 'Run this on the relay host.',
+  'relay.test': 'Test the relay connection',
+  'relay.testOk': 'Relay reachable: version {version}, {hosts} workstation(s) connected.',
+  'relay.testFailed': 'Relay unreachable: {message}',
+  'relay.selectAddress': 'Choose the address to advertise',
+  'relay.listenAddress': 'Listen address',
+  'relay.listenAddressHint': 'This is the server bind address. The advertised address below is what browsers open.',
+  'relay.addressTailscale': 'Tailscale',
+  'relay.addressLan': 'LAN',
+  'relay.addressVirtual': 'virtual',
+  'relay.addressLoopback': 'loopback',
+  'relay.noAddresses': 'No non-loopback addresses found. Connect to a network or start Tailscale.',
+  'relay.docsHint': 'Running your own relay: see docs/self-hosted-relay.md',
+
+  'keepalive.title': 'Keep-alive service',
+  'keepalive.manager': 'Manager',
+  'keepalive.state': 'State',
+  'keepalive.install': 'Install and start',
+  'keepalive.uninstall': 'Stop and remove',
+  'keepalive.restart': 'Restart the service',
+  'keepalive.installed': 'Keep-alive installed with {manager}.',
+  'keepalive.uninstalled': 'Keep-alive removed.',
+  'keepalive.restarted': 'Keep-alive service restarted.',
+  'keepalive.failed': 'Keep-alive operation failed: {message}',
+  'keepalive.unitPath': 'Unit file',
+  'keepalive.logsHint': 'Follow logs with: {command}',
+  'keepalive.linger': 'Start at boot without logging in',
+  'keepalive.lingerEnabled': 'Lingering is enabled: the service starts at boot.',
+  'keepalive.lingerDisabled': 'Lingering is off, so the service only runs while you are logged in.',
+  'keepalive.enableLinger': 'Enable start at boot',
+  'keepalive.lingerDone': 'Lingering enabled for {username}.',
+  'keepalive.fallbackNote': 'No system service manager is available; a supervised background process is used instead. It does not survive a reboot.',
+
+  'herdr.title': 'Herdr integration',
+  'herdr.socketPath': 'Socket path',
+  'herdr.args': 'Extra arguments',
+  'herdr.plugin': 'Plugin registration',
+  'herdr.pluginRegistered': 'Registered with Herdr.',
+  'herdr.pluginMissing': 'Not registered with Herdr.',
+  'herdr.register': 'Register this package as a Herdr plugin',
+  'herdr.unregister': 'Unregister the Herdr plugin',
+  'herdr.registerDone': 'Registered: {path}',
+  'herdr.unregisterDone': 'Plugin unregistered.',
+  'herdr.registerFailed': 'Registration failed: {message}',
+  'herdr.cliMissing': 'The herdr command was not found on PATH.',
+
+  'about.title': 'Language & about',
+  'about.language': 'Interface language',
+  'about.languageAuto': 'Follow the system ({detected})',
+  'about.languageZh': '中文',
+  'about.languageEn': 'English',
+  'about.version': 'Version',
+  'about.configPath': 'Config file',
+  'about.statePath': 'State directory',
+  'about.relayPackage': 'Relay package',
+  'about.docs': 'Self-hosting guide: docs/self-hosted-relay.md',
+
+  'wizard.title': 'First-time setup',
+  'wizard.step': 'Step {current} of {total}',
+  'wizard.languageTitle': 'Choose your language',
+  'wizard.accessTitle': 'How do you want to reach this machine?',
+  'wizard.accessHint': 'You can change this later on the Relay screen.',
+  'wizard.addressTitle': 'Which address should phones use?',
+  'wizard.relayTitle': 'Your relay server',
+  'wizard.relayUrlLabel': 'Relay URL (wss://…)',
+  'wizard.relayHint': 'The relay must already be running. See docs/self-hosted-relay.md to set one up.',
+  'wizard.passwordTitle': 'Relay password',
+  'wizard.passwordHint': 'The RELAY_PASSWORD your relay was started with. Leave it empty if the relay has none.',
+  'wizard.finishTitle': 'Ready',
+  'wizard.finishHint': 'Configuration will be saved to {path}.',
+  'wizard.startNow': 'Start the services now',
+  'wizard.installKeepalive': 'Keep the services running in the background',
+  'wizard.finish': 'Save and continue',
+
+  'field.mode': 'Access mode',
+  'field.port': 'Relay port',
+  'field.lanHost': 'Browser address',
+  'field.remoteUrl': 'Relay URL',
+  'field.publicUrl': 'Browser URL override',
+  'field.socketPath': 'Herdr socket path',
+  'field.herdrArgs': 'Herdr arguments',
+  'field.language': 'Language',
+  'field.keepalive': 'Keep-alive manager',
+
+  'placeholder.autoDiscovered': 'auto-discovered',
+  'placeholder.none': 'none',
+
+  'error.invalidMode': 'Unknown access mode.',
+  'error.invalidPort': 'The port must be a number between 1 and 65535.',
+  'error.invalidLanHost': 'The browser address must be a reachable LAN or Tailscale address, not loopback or 0.0.0.0.',
+  'error.invalidRelayUrl': 'The relay URL must start with wss://, ws://, https:// or http://.',
+  'error.invalidPublicUrl': 'The browser URL must start with https:// or http:// and cannot use 0.0.0.0 or ::.',
+  'error.invalidLanguage': 'Unknown language.',
+  'error.invalidKeepalive': 'Unknown keep-alive manager.',
+  'error.unknownField': 'Unknown setting.',
+  'error.remoteUrlRequired': 'A relay URL is required for the self-hosted relay mode.',
+  'error.saveFailed': 'Could not save the configuration: {message}',
+
+  'hint.navigate': '↑↓ move',
+  'hint.select': '↵ select',
+  'hint.edit': '↵ edit',
+  'hint.tabs': '← → switch tab',
+  'hint.back': 'esc back',
+  'hint.quit': 'q quit',
+  'hint.mouseOn': 'm mouse off',
+  'hint.mouseOff': 'm mouse on',
+  'hint.mouseUnsupported': 'mouse unsupported',
+  'hint.restartRequired': 'Restart the services to apply these changes.',
+  'hint.unsavedChanges': 'Unsaved changes — press s to save.',
+  'hint.save': 's save',
+  'hint.editing': '↵ confirm · esc cancel',
+};

package/src/i18n/index.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const en = require('./en');
+const zh = require('./zh');
+
+const CATALOGUES = { en, zh };
+const DEFAULT_LOCALE = 'en';
+
+/**
+ * Work out the interface language from the environment.
+ *
+ * Order matters: an explicit override wins, then the saved preference, then the
+ * POSIX locale variables in the order the C library itself consults them.
+ */
+function detectLocale({ env = process.env, preference = 'auto' } = {}) {
+  if (preference && preference !== 'auto' && CATALOGUES[preference]) return preference;
+  if (env.HERDR_REMOTE_LANG && CATALOGUES[env.HERDR_REMOTE_LANG]) return env.HERDR_REMOTE_LANG;
+
+  const raw = env.LC_ALL || env.LC_MESSAGES || env.LANG || env.LANGUAGE || '';
+  const primary = String(raw).split(/[:.@]/)[0].toLowerCase();
+  if (primary.startsWith('zh')) return 'zh';
+  return DEFAULT_LOCALE;
+}
+
+function interpolate(template, values) {
+  if (!values) return template;
+  return template.replace(/\{(\w+)\}/g, (match, key) => (
+    Object.prototype.hasOwnProperty.call(values, key) ? String(values[key]) : match
+  ));
+}
+
+/**
+ * Build a translator for a locale.
+ *
+ * A missing key falls back to English and finally to the key itself, so a typo
+ * shows up as a visible key rather than an empty gap in the layout.
+ */
+function createTranslator(locale = DEFAULT_LOCALE) {
+  const active = CATALOGUES[locale] || CATALOGUES[DEFAULT_LOCALE];
+  const fallback = CATALOGUES[DEFAULT_LOCALE];
+  const t = (key, values) => {
+    const template = active[key] ?? fallback[key] ?? key;
+    return interpolate(template, values);
+  };
+  t.locale = locale;
+  t.has = (key) => Object.prototype.hasOwnProperty.call(active, key);
+  return t;
+}
+
+module.exports = {
+  CATALOGUES,
+  DEFAULT_LOCALE,
+  detectLocale,
+  createTranslator,
+  interpolate,
+};