herdr-remote-relay 0.2.0

package/src/metrics.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const os = require('node:os');
+const { monitorEventLoopDelay } = require('node:perf_hooks');
+
+function finite(value, fallback = 0) {
+  return Number.isFinite(value) ? value : fallback;
+}
+
+function bytesPerSecond(current, previous, elapsedMs) {
+  if (!elapsedMs || elapsedMs <= 0) return 0;
+  return Math.max(0, (current - previous) * 1000 / elapsedMs);
+}
+
+class RelayMetrics {
+  constructor({ version = '0.1.0', protocolVersion = 1 } = {}) {
+    this.version = version;
+    this.protocolVersion = protocolVersion;
+    this.startedAt = Date.now();
+    this.bytesIn = 0;
+    this.bytesOut = 0;
+    this.framesIn = 0;
+    this.framesOut = 0;
+    this.cleanup = {
+      staleClientsPurged: 0,
+      closedPtysCleaned: 0,
+      deadConnectionsClosed: 0,
+      idleHostsTerminated: 0,
+      lastCleanupAt: null,
+    };
+    this.lastSample = { at: this.startedAt, bytesIn: 0, bytesOut: 0, framesIn: 0, framesOut: 0 };
+    this.cpuSampleAt = process.hrtime.bigint();
+    this.cpuSample = process.cpuUsage();
+    this.eventLoop = monitorEventLoopDelay({ resolution: 20 });
+    this.eventLoop.enable();
+  }
+
+  recordIn(bytes) {
+    this.bytesIn += bytes;
+    this.framesIn += 1;
+  }
+
+  recordOut(bytes) {
+    this.bytesOut += bytes;
+    this.framesOut += 1;
+  }
+
+  recordCleanup(name, amount = 1) {
+    if (Object.prototype.hasOwnProperty.call(this.cleanup, name) && typeof this.cleanup[name] === 'number') {
+      this.cleanup[name] += amount;
+    }
+    this.cleanup.lastCleanupAt = new Date().toISOString();
+  }
+
+  cpuPercent() {
+    const now = process.hrtime.bigint();
+    const elapsedNs = Number(now - this.cpuSampleAt);
+    const usage = process.cpuUsage(this.cpuSample);
+    this.cpuSampleAt = now;
+    this.cpuSample = process.cpuUsage();
+    if (elapsedNs <= 0) return 0;
+    const percent = ((usage.user + usage.system) * 100000) / elapsedNs;
+    return Math.max(0, Math.round(percent * 100) / 100);
+  }
+
+  eventLoopDelay() {
+    const percentile = (value) => Math.round(finite(value / 1e6) * 100) / 100;
+    return {
+      p50Ms: percentile(this.eventLoop.percentile(50)),
+      p90Ms: percentile(this.eventLoop.percentile(90)),
+      p99Ms: percentile(this.eventLoop.percentile(99)),
+      maxMs: percentile(this.eventLoop.max),
+      meanMs: percentile(this.eventLoop.mean),
+    };
+  }
+
+  snapshot({ clients = [], hosts = [], ptys = [], sample = true } = {}) {
+    const now = Date.now();
+    const elapsedMs = now - this.lastSample.at;
+    const throughput = {
+      bytesIn: this.bytesIn,
+      bytesOut: this.bytesOut,
+      bytesInPerSec: bytesPerSecond(this.bytesIn, this.lastSample.bytesIn, elapsedMs),
+      bytesOutPerSec: bytesPerSecond(this.bytesOut, this.lastSample.bytesOut, elapsedMs),
+      framesIn: this.framesIn,
+      framesOut: this.framesOut,
+      framesInPerSec: bytesPerSecond(this.framesIn, this.lastSample.framesIn, elapsedMs),
+      framesOutPerSec: bytesPerSecond(this.framesOut, this.lastSample.framesOut, elapsedMs),
+    };
+    if (sample) {
+      this.lastSample = { at: now, bytesIn: this.bytesIn, bytesOut: this.bytesOut, framesIn: this.framesIn, framesOut: this.framesOut };
+    }
+    const memory = process.memoryUsage();
+    const load = os.loadavg();
+    const controller = clients.find((client) => client.role === 'controller');
+    return {
+      version: this.version,
+      protocolVersion: this.protocolVersion,
+      uptimeSeconds: Math.floor((now - this.startedAt) / 1000),
+      startTime: new Date(this.startedAt).toISOString(),
+      serverTime: new Date(now).toISOString(),
+      activeControllerId: controller?.id || null,
+      activeHostId: controller?.hostId || hosts[0]?.id || null,
+      clients,
+      hosts,
+      ptys,
+      clientCount: clients.length,
+      hostCount: hosts.length,
+      ptyCount: ptys.length,
+      throughput,
+      cpu: {
+        load1m: finite(load[0]),
+        load5m: finite(load[1]),
+        load15m: finite(load[2]),
+        cpuPercent: this.cpuPercent(),
+        cores: os.cpus().length,
+      },
+      memory: {
+        rssBytes: memory.rss,
+        heapUsedBytes: memory.heapUsed,
+        heapTotalBytes: memory.heapTotal,
+        externalBytes: memory.external,
+        systemTotalBytes: os.totalmem(),
+        systemFreeBytes: os.freemem(),
+      },
+      eventLoopDelay: this.eventLoopDelay(),
+      cleanup: { ...this.cleanup },
+    };
+  }
+
+  close() {
+    this.eventLoop.disable();
+  }
+}
+
+module.exports = { RelayMetrics };

package/src/relay-config.js

@@ -0,0 +1,278 @@
+'use strict';
+
+// Standalone relay configuration.
+//
+// The relay is deliberately decoupled from the herdr-remote plugin: it never
+// reads the plugin's config directory and never imports plugin code. Settings
+// come from (lowest to highest precedence) built-in defaults, an optional JSON
+// config file, environment variables, then command line flags.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+function defaultStateDir() {
+  if (process.env.RELAY_STATE_DIR) return process.env.RELAY_STATE_DIR;
+  const stateHome = process.env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state');
+  return path.join(stateHome, 'herdr-remote-relay');
+}
+
+const DEFAULTS = {
+  relay: {
+    // A relay package is remote/operator-facing by default. The workstation
+    // service sets this to local for the private relay it starts itself so the
+    // web client can distinguish its own status page from the operator console.
+    mode: 'remote',
+    // Bind to loopback by default: the common production shape is a TLS
+    // reverse proxy on the same machine. Containers and LAN deployments set
+    // RELAY_BIND=0.0.0.0 explicitly.
+    host: '127.0.0.1',
+    port: 8787,
+    publicUrl: 'http://127.0.0.1:8787',
+    maxPayloadBytes: 1024 * 1024,
+    maxClientsPerHost: 16,
+    allowedOrigins: [],
+    trustProxy: false,
+  },
+  auth: {
+    pairingTtlMs: 10 * 60 * 1000,
+    deviceTtlMs: 30 * 24 * 60 * 60 * 1000,
+    maxDevices: 32,
+    // Optional shared password. Unset means a public relay: anyone may connect
+    // a workstation, and each one is still reachable only through its own host
+    // token.
+    password: null,
+    // Optional operator credential for the standalone relay dashboard. This is
+    // deliberately separate from the join password and from device tokens:
+    // the former is shared with workstations, while the latter is scoped to a
+    // single workstation.
+    adminToken: null,
+    stateFile: null,
+  },
+  cleanup: {
+    intervalMs: 60 * 1000,
+    heartbeatIntervalMs: 30 * 1000,
+    staleAfterMs: 90 * 1000,
+  },
+};
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function readJsonFile(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw new Error(`cannot read relay config ${filePath}: ${error.message}`);
+  }
+}
+
+function parseBoolean(value, fallback) {
+  if (value === undefined || value === null || value === '') return fallback;
+  if (value === true || value === false) return value;
+  const normalized = String(value).trim().toLowerCase();
+  if (['true', '1', 'yes', 'on'].includes(normalized)) return true;
+  if (['false', '0', 'no', 'off'].includes(normalized)) return false;
+  return fallback;
+}
+
+function parseInteger(value, fallback, min, max) {
+  const numeric = Number(value);
+  if (!Number.isInteger(numeric) || numeric < min || numeric > max) return fallback;
+  return numeric;
+}
+
+function parseOriginList(value) {
+  if (Array.isArray(value)) return value.map((entry) => String(entry).trim()).filter(Boolean);
+  if (typeof value !== 'string') return null;
+  return value.split(',').map((entry) => entry.trim()).filter(Boolean);
+}
+
+function mergeSection(target, source) {
+  if (!source || typeof source !== 'object') return;
+  for (const key of Object.keys(target)) {
+    if (source[key] !== undefined) target[key] = source[key];
+  }
+}
+
+/**
+ * Parse `--flag value` / `--flag=value` pairs plus the standalone flags the
+ * relay binary understands. Returns { options, help, version, errors }.
+ */
+function parseArgv(argv = []) {
+  const options = {};
+  const errors = [];
+  let help = false;
+  let version = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') { help = true; continue; }
+    if (arg === '--version' || arg === '-v') { version = true; continue; }
+    if (!arg.startsWith('--')) { errors.push(`unexpected argument: ${arg}`); continue; }
+    const equals = arg.indexOf('=');
+    const name = equals === -1 ? arg.slice(2) : arg.slice(2, equals);
+    let value = equals === -1 ? undefined : arg.slice(equals + 1);
+    if (value === undefined) {
+      const next = argv[index + 1];
+      if (next === undefined || next.startsWith('--')) {
+        // Bare boolean flag.
+        value = 'true';
+      } else {
+        value = next;
+        index += 1;
+      }
+    }
+    options[name] = value;
+  }
+  return { options, help, version, errors };
+}
+
+function applyFile(config, fileConfig) {
+  if (!fileConfig || typeof fileConfig !== 'object') return;
+  mergeSection(config.relay, fileConfig.relay);
+  mergeSection(config.auth, fileConfig.auth);
+  mergeSection(config.cleanup, fileConfig.cleanup);
+}
+
+function applyEnvironment(config, env) {
+  if (env.RELAY_DEPLOYMENT_MODE === 'local' || env.RELAY_DEPLOYMENT_MODE === 'remote') {
+    config.relay.mode = env.RELAY_DEPLOYMENT_MODE;
+  }
+  if (env.RELAY_BIND) config.relay.host = env.RELAY_BIND;
+  if (env.RELAY_PORT) config.relay.port = env.RELAY_PORT;
+  if (env.RELAY_PUBLIC_URL) config.relay.publicUrl = env.RELAY_PUBLIC_URL;
+  if (env.RELAY_MAX_PAYLOAD_BYTES) config.relay.maxPayloadBytes = env.RELAY_MAX_PAYLOAD_BYTES;
+  if (env.RELAY_MAX_CLIENTS_PER_HOST) config.relay.maxClientsPerHost = env.RELAY_MAX_CLIENTS_PER_HOST;
+  if (env.RELAY_ALLOWED_ORIGINS !== undefined) {
+    const origins = parseOriginList(env.RELAY_ALLOWED_ORIGINS);
+    if (origins) config.relay.allowedOrigins = origins;
+  }
+  if (env.RELAY_TRUST_PROXY !== undefined) {
+    config.relay.trustProxy = parseBoolean(env.RELAY_TRUST_PROXY, config.relay.trustProxy);
+  }
+  if (env.RELAY_PASSWORD) config.auth.password = env.RELAY_PASSWORD;
+  if (env.RELAY_ADMIN_TOKEN) config.auth.adminToken = env.RELAY_ADMIN_TOKEN;
+  if (env.RELAY_AUTH_STATE_FILE) config.auth.stateFile = env.RELAY_AUTH_STATE_FILE;
+  if (env.RELAY_PAIRING_TTL_MS) config.auth.pairingTtlMs = env.RELAY_PAIRING_TTL_MS;
+  if (env.RELAY_DEVICE_TTL_MS) config.auth.deviceTtlMs = env.RELAY_DEVICE_TTL_MS;
+  if (env.RELAY_MAX_DEVICES) config.auth.maxDevices = env.RELAY_MAX_DEVICES;
+}
+
+function applyOptions(config, options) {
+  if (options['deployment-mode'] === 'local' || options['deployment-mode'] === 'remote') {
+    config.relay.mode = options['deployment-mode'];
+  }
+  if (options.bind) config.relay.host = options.bind;
+  if (options.port) config.relay.port = options.port;
+  if (options['public-url']) config.relay.publicUrl = options['public-url'];
+  if (options['allowed-origins'] !== undefined) {
+    const origins = parseOriginList(options['allowed-origins']);
+    if (origins) config.relay.allowedOrigins = origins;
+  }
+  if (options['trust-proxy'] !== undefined) {
+    config.relay.trustProxy = parseBoolean(options['trust-proxy'], config.relay.trustProxy);
+  }
+  if (options.password) config.auth.password = options.password;
+  if (options['admin-token']) config.auth.adminToken = options['admin-token'];
+  if (options['state-file']) config.auth.stateFile = options['state-file'];
+  if (options['max-clients']) config.relay.maxClientsPerHost = options['max-clients'];
+}
+
+function validate(config) {
+  if (config.relay.mode !== 'local' && config.relay.mode !== 'remote') config.relay.mode = DEFAULTS.relay.mode;
+  config.relay.port = parseInteger(config.relay.port, DEFAULTS.relay.port, 0, 65535);
+  config.relay.maxPayloadBytes = parseInteger(
+    config.relay.maxPayloadBytes,
+    DEFAULTS.relay.maxPayloadBytes,
+    4096,
+    16 * 1024 * 1024,
+  );
+  config.relay.maxClientsPerHost = parseInteger(config.relay.maxClientsPerHost, DEFAULTS.relay.maxClientsPerHost, 1, 256);
+  config.auth.pairingTtlMs = parseInteger(config.auth.pairingTtlMs, DEFAULTS.auth.pairingTtlMs, 30 * 1000, 24 * 60 * 60 * 1000);
+  config.auth.deviceTtlMs = parseInteger(config.auth.deviceTtlMs, DEFAULTS.auth.deviceTtlMs, 60 * 1000, 365 * 24 * 60 * 60 * 1000);
+  config.auth.maxDevices = parseInteger(config.auth.maxDevices, DEFAULTS.auth.maxDevices, 1, 10000);
+  config.cleanup.intervalMs = parseInteger(config.cleanup.intervalMs, DEFAULTS.cleanup.intervalMs, 1000, 24 * 60 * 60 * 1000);
+  config.cleanup.heartbeatIntervalMs = parseInteger(
+    config.cleanup.heartbeatIntervalMs,
+    DEFAULTS.cleanup.heartbeatIntervalMs,
+    1000,
+    10 * 60 * 1000,
+  );
+  config.cleanup.staleAfterMs = parseInteger(
+    config.cleanup.staleAfterMs,
+    DEFAULTS.cleanup.staleAfterMs,
+    config.cleanup.heartbeatIntervalMs * 2,
+    24 * 60 * 60 * 1000,
+  );
+
+  if (typeof config.relay.host !== 'string' || config.relay.host.length === 0) {
+    config.relay.host = DEFAULTS.relay.host;
+  }
+  if (typeof config.relay.publicUrl !== 'string' || config.relay.publicUrl.length === 0) {
+    config.relay.publicUrl = `http://${config.relay.host}:${config.relay.port}`;
+  }
+  config.relay.publicUrl = String(config.relay.publicUrl).replace(/\/+$/, '');
+  if (!Array.isArray(config.relay.allowedOrigins)) config.relay.allowedOrigins = [];
+  config.relay.trustProxy = parseBoolean(config.relay.trustProxy, false);
+  if (!config.auth.stateFile) {
+    config.auth.stateFile = path.join(defaultStateDir(), 'relay-auth.json');
+  }
+  return config;
+}
+
+/**
+ * Warnings a standalone operator should see at startup. These are advisory —
+ * the relay still starts, because a loopback-only development run legitimately
+ * needs neither TLS nor tokens.
+ */
+function configWarnings(config) {
+  const warnings = [];
+  const isLoopbackBind = ['127.0.0.1', 'localhost', '::1'].includes(config.relay.host);
+  let publicUrl;
+  try {
+    publicUrl = new URL(config.relay.publicUrl);
+  } catch {
+    warnings.push(`publicUrl is not a valid URL: ${config.relay.publicUrl}`);
+  }
+  if (!config.auth.password) {
+    warnings.push('no password set (RELAY_PASSWORD): this is a public relay, anyone may connect a workstation to it');
+  }
+  if (config.relay.mode === 'remote' && !config.auth.adminToken) {
+    warnings.push('no admin token set (RELAY_ADMIN_TOKEN): the relay operator dashboard is unavailable');
+  }
+  if (!isLoopbackBind && publicUrl && publicUrl.protocol === 'http:' && !['127.0.0.1', 'localhost'].includes(publicUrl.hostname)) {
+    warnings.push(`publicUrl uses plain http on a non-loopback address (${config.relay.publicUrl}); terminate TLS in front of the relay`);
+  }
+  return warnings;
+}
+
+function loadRelayConfig({ argv = [], env = process.env } = {}) {
+  const { options, help, version, errors } = parseArgv(argv);
+  const config = clone(DEFAULTS);
+
+  const configFile = options.config || env.HERDR_RELAY_CONFIG || null;
+  if (configFile) {
+    const fileConfig = readJsonFile(path.resolve(configFile));
+    if (fileConfig === null) throw new Error(`relay config not found: ${configFile}`);
+    applyFile(config, fileConfig);
+  }
+  applyEnvironment(config, env);
+  applyOptions(config, options);
+  validate(config);
+
+  return { config, help, version, errors, configFile, warnings: configWarnings(config) };
+}
+
+module.exports = {
+  PACKAGE_ROOT,
+  DEFAULTS,
+  loadRelayConfig,
+  parseArgv,
+  validate,
+  configWarnings,
+  defaultStateDir,
+};