rollbridge 0.1.5 → 0.1.7

package/src/config.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import fs from "node:fs/promises"
+import os from "node:os"
 import path from "node:path"
 import {pathToFileURL} from "node:url"
 
@@ -10,11 +11,15 @@ import {pathToFileURL} from "node:url"
  * @typedef {{path: string, startDelayMs: number, timeoutMs: number, intervalMs: number}} HealthConfig
  * @typedef {"proxied" | "companion" | "singleton" | "service"} ProcessPolicy
  * @typedef {{backoffFactor: number, maxDelayMs: number, maxRestarts: number | undefined, windowMs: number}} RestartConfig
- * @typedef {{cwd?: string, env: Record<string, string>, gracefulStopMs: number, health?: HealthConfig, id: string, outputLines: number, policy: ProcessPolicy, port?: PortRange, restart: RestartConfig, restartDelayMs: number, command: string}} ProcessConfig
- * @typedef {{mode?: number, path: string}} ControlConfig
+ * @typedef {{checkIntervalMs: number, limitBytes: number, warnBytes: number}} MemoryConfig
+ * @typedef {{drainCommand?: string, drainTimeoutMs: number, quietCommand?: string, stopCommand?: string}} LifecycleConfig
+ * @typedef {{cwd?: string, env: Record<string, string>, gracefulStopMs: number, health?: HealthConfig, id: string, lifecycle: LifecycleConfig, memory?: MemoryConfig, nonBlockingDrain: boolean, outputLines: number, policy: ProcessPolicy, port?: PortRange, replicas: number, restart: RestartConfig, restartDelayMs: number, stopSignal: string, command: string}} ProcessConfig
+ * @typedef {{group?: number | string, mode?: number, owner?: number | string, path: string}} ControlConfig
  * @typedef {{drainTimeoutMs: number, forceStopTimeoutMs: number, healthPath: string, healthTimeoutMs: number, host: string, port: number, upstreamHost: string}} ProxyConfig
+ * @typedef {{includes: string[], name: string}} LegacyTakeoverProcessConfig
+ * @typedef {{forceStopTimeoutMs: number, processes: LegacyTakeoverProcessConfig[], screens: string[]}} LegacyTakeoverConfig
  * @typedef {{keep: number, maxAgeMs: number}} ReleaseRetentionConfig
- * @typedef {{application: string, control: ControlConfig, processes: ProcessConfig[], proxy: ProxyConfig, releaseRetention: ReleaseRetentionConfig}} RollbridgeConfig
+ * @typedef {{application: string, control: ControlConfig, legacyTakeover?: LegacyTakeoverConfig, processes: ProcessConfig[], proxy: ProxyConfig, releaseRetention: ReleaseRetentionConfig, statePath?: string}} RollbridgeConfig
  * @typedef {{fix: string, message: string}} ConfigIssue
  */
 
@@ -125,15 +130,19 @@ export function validateConfig(rawConfig, configPath = process.cwd()) {
   const processesSource = arrayAt(source.processes, "processes", issues)
   const proxy = normalizeProxy(proxySource, issues)
   const control = {
+    group: normalizeControlPrincipal(controlSource.group, "control.group", issues),
     mode: normalizeSocketMode(controlSource.mode, "control.mode", issues),
+    owner: normalizeControlPrincipal(controlSource.owner, "control.owner", issues),
     path: normalizeString(controlSource.path, "control.path", issues, {default: `/tmp/rollbridge-${application}.sock`})
   }
   const processes = processesSource.map((processSource, index) => normalizeProcess(processSource, index, proxy, issues))
+  const legacyTakeover = normalizeLegacyTakeover(source.legacyTakeover, proxy, issues)
   const releaseRetention = normalizeReleaseRetention(objectAt(source.releaseRetention, "releaseRetention", issues, {}), issues)
+  const statePath = source.statePath === undefined || source.statePath === null ? undefined : normalizeString(source.statePath, "statePath", issues)
 
   validateProcessSet(processes, issues)
 
-  return {config: {application, control, processes, proxy, releaseRetention}, issues}
+  return {config: {application, control, legacyTakeover, processes, proxy, releaseRetention, statePath}, issues}
 }
 
 /**
@@ -176,7 +185,7 @@ function normalizeProcess(value, index, proxy, issues) {
   if (!isPlainObject(value)) {
     issues.push({fix: `Define processes[${index}] as a mapping with id, policy, and command.`, message: `processes[${index}] must be an object`})
 
-    return {command: "", cwd: undefined, env: {}, gracefulStopMs: proxy.forceStopTimeoutMs, health: undefined, id: "", outputLines: 50, policy: "companion", port: undefined, restart: defaultRestartConfig(), restartDelayMs: 1000}
+    return {command: "", cwd: undefined, env: {}, gracefulStopMs: proxy.forceStopTimeoutMs, health: undefined, id: "", lifecycle: {drainTimeoutMs: 0}, memory: undefined, nonBlockingDrain: false, outputLines: 50, policy: "companion", port: undefined, replicas: 1, restart: defaultRestartConfig(), restartDelayMs: 1000, stopSignal: "SIGTERM"}
   }
 
   const source = value
@@ -188,11 +197,16 @@ function normalizeProcess(value, index, proxy, issues) {
     gracefulStopMs: normalizeNumber(source.gracefulStopMs, `processes[${index}].gracefulStopMs`, issues, {default: proxy.forceStopTimeoutMs}),
     health: normalizeHealth(source.health, `processes[${index}].health`, proxy, issues),
     id: normalizeString(source.id, `processes[${index}].id`, issues),
+    lifecycle: normalizeLifecycle(source.lifecycle, `processes[${index}].lifecycle`, issues),
+    memory: normalizeMemory(source.memory, `processes[${index}].memory`, issues),
+    nonBlockingDrain: normalizeBoolean(source.nonBlockingDrain, `processes[${index}].nonBlockingDrain`, issues, false),
     outputLines: normalizeOutputLines(source.outputLines, `processes[${index}].outputLines`, issues),
     policy: normalizePolicy(source.policy, `processes[${index}].policy`, issues),
     port: normalizePortRange(source.port, `processes[${index}].port`, issues),
+    replicas: normalizeReplicas(source.replicas, `processes[${index}].replicas`, issues),
     restart: normalizeRestart(source.restart, `processes[${index}].restart`, issues),
-    restartDelayMs: normalizeNumber(source.restartDelayMs, `processes[${index}].restartDelayMs`, issues, {default: 1000})
+    restartDelayMs: normalizeNumber(source.restartDelayMs, `processes[${index}].restartDelayMs`, issues, {default: 1000}),
+    stopSignal: normalizeStopSignal(source.stopSignal, `processes[${index}].stopSignal`, issues)
   }
 }
 
@@ -265,6 +279,184 @@ function normalizeBackoffFactor(value, key, issues) {
   return factor
 }
 
+/**
+ * @param {JsonValue} value - Raw memory supervision config.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {MemoryConfig | undefined} Normalized memory config, or undefined when monitoring is off.
+ */
+function normalizeMemory(value, key, issues) {
+  if (value === undefined || value === null) return undefined
+
+  if (!isPlainObject(value)) {
+    issues.push({fix: `Set ${key} to a mapping with limitBytes (and optionally warnBytes, checkIntervalMs), or omit it to disable memory supervision.`, message: `${key} must be an object`})
+
+    return undefined
+  }
+
+  const limitBytes = normalizeNumber(value.limitBytes, `${key}.limitBytes`, issues, {default: 0})
+  const warnBytes = normalizeNumber(value.warnBytes, `${key}.warnBytes`, issues, {default: 0})
+  const checkIntervalMs = normalizeNumber(value.checkIntervalMs, `${key}.checkIntervalMs`, issues, {default: 5000})
+
+  if (!Number.isInteger(limitBytes) || limitBytes <= 0) {
+    issues.push({fix: `Set ${key}.limitBytes to a positive integer number of bytes, e.g. 536870912 (512 MiB).`, message: `${key}.limitBytes must be a positive integer`})
+  }
+
+  if (!Number.isInteger(warnBytes) || warnBytes < 0) {
+    issues.push({fix: `Set ${key}.warnBytes to a non-negative integer number of bytes below limitBytes, e.g. 402653184 (384 MiB).`, message: `${key}.warnBytes must be a non-negative integer`})
+  }
+
+  if (checkIntervalMs <= 0) {
+    issues.push({fix: `Set ${key}.checkIntervalMs to a positive number of milliseconds, e.g. 5000.`, message: `${key}.checkIntervalMs must be a positive number`})
+  }
+
+  return {checkIntervalMs, limitBytes, warnBytes}
+}
+
+/**
+ * @param {JsonValue} value - Raw lifecycle config.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {LifecycleConfig} Normalized lifecycle hooks (no commands and a 0 drain by default).
+ */
+function normalizeLifecycle(value, key, issues) {
+  if (value === undefined || value === null) return {drainTimeoutMs: 0}
+
+  if (!isPlainObject(value)) {
+    issues.push({fix: `Set ${key} to a mapping with optional quietCommand, drainCommand, stopCommand, and drainTimeoutMs.`, message: `${key} must be an object`})
+
+    return {drainTimeoutMs: 0}
+  }
+
+  const drainTimeoutMs = normalizeNumber(value.drainTimeoutMs, `${key}.drainTimeoutMs`, issues, {default: 0})
+  /** @type {LifecycleConfig} */
+  const lifecycle = {drainTimeoutMs: nonNegativeOrDefault(drainTimeoutMs, `${key}.drainTimeoutMs`, issues, 0, false)}
+
+  if (value.quietCommand !== undefined) lifecycle.quietCommand = normalizeString(value.quietCommand, `${key}.quietCommand`, issues)
+  if (value.drainCommand !== undefined) lifecycle.drainCommand = normalizeString(value.drainCommand, `${key}.drainCommand`, issues)
+  if (value.stopCommand !== undefined) lifecycle.stopCommand = normalizeString(value.stopCommand, `${key}.stopCommand`, issues)
+
+  if (lifecycle.drainCommand !== undefined && lifecycle.drainTimeoutMs <= 0) {
+    issues.push({fix: `Set ${key}.drainTimeoutMs to a positive number to bound ${key}.drainCommand; with 0 the drain step is skipped and the command never runs.`, message: `${key}.drainCommand requires a positive ${key}.drainTimeoutMs`})
+  }
+
+  return lifecycle
+}
+
+/**
+ * @param {JsonValue} value - Raw legacy takeover config.
+ * @param {ProxyConfig} proxy - Proxy config defaults.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {LegacyTakeoverConfig | undefined} Normalized legacy takeover config, or undefined when omitted.
+ */
+function normalizeLegacyTakeover(value, proxy, issues) {
+  if (value === undefined || value === null) return undefined
+
+  if (!isPlainObject(value)) {
+    issues.push({fix: "Set legacyTakeover to a mapping with screens and/or processes.", message: "legacyTakeover must be an object"})
+
+    return {forceStopTimeoutMs: proxy.forceStopTimeoutMs, processes: [], screens: []}
+  }
+
+  const forceStopTimeoutMs = normalizeNumber(value.forceStopTimeoutMs, "legacyTakeover.forceStopTimeoutMs", issues, {default: proxy.forceStopTimeoutMs})
+  const screens = normalizeStringList(value.screens, "legacyTakeover.screens", issues)
+  const processes = normalizeLegacyTakeoverProcesses(value.processes, issues)
+
+  if (screens.length === 0 && processes.length === 0) {
+    issues.push({fix: "Set legacyTakeover.screens or legacyTakeover.processes so predeploy-cleanup knows what legacy processes it may stop.", message: "legacyTakeover must define at least one screen or process matcher"})
+  }
+
+  return {
+    forceStopTimeoutMs: nonNegativeOrDefault(forceStopTimeoutMs, "legacyTakeover.forceStopTimeoutMs", issues, proxy.forceStopTimeoutMs, false),
+    processes,
+    screens
+  }
+}
+
+/**
+ * @param {JsonValue} value - Raw list value.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {string[]} Normalized strings.
+ */
+function normalizeStringList(value, key, issues) {
+  if (value === undefined || value === null) return []
+
+  if (!Array.isArray(value)) {
+    issues.push({fix: `Set ${key} to a list of strings.`, message: `${key} must be an array`})
+
+    return []
+  }
+
+  return value.flatMap((entry, index) => {
+    if (typeof entry === "string" && entry.length > 0) return [entry]
+
+    issues.push({fix: `Set ${key}[${index}] to a non-empty string.`, message: `${key}[${index}] must be a non-empty string`})
+    return []
+  })
+}
+
+/**
+ * @param {JsonValue} value - Raw legacy process matchers.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {LegacyTakeoverProcessConfig[]} Normalized process matchers.
+ */
+function normalizeLegacyTakeoverProcesses(value, issues) {
+  if (value === undefined || value === null) return []
+
+  if (!Array.isArray(value)) {
+    issues.push({fix: "Set legacyTakeover.processes to a list of mappings with includes strings.", message: "legacyTakeover.processes must be an array"})
+
+    return []
+  }
+
+  return value.flatMap((entry, index) => normalizeLegacyTakeoverProcess(entry, index, issues))
+}
+
+/**
+ * @param {JsonValue} value - Raw legacy process matcher.
+ * @param {number} index - Matcher index.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {LegacyTakeoverProcessConfig[]} Normalized matcher, or an empty list when invalid.
+ */
+function normalizeLegacyTakeoverProcess(value, index, issues) {
+  const key = `legacyTakeover.processes[${index}]`
+
+  if (!isPlainObject(value)) {
+    issues.push({fix: `Set ${key} to a mapping with includes strings.`, message: `${key} must be an object`})
+
+    return []
+  }
+
+  const includes = normalizeStringList(value.includes, `${key}.includes`, issues)
+  if (includes.length === 0) {
+    issues.push({fix: `Set ${key}.includes to one or more command-line substrings that identify the legacy process.`, message: `${key}.includes must contain at least one matcher`})
+  }
+
+  return [{
+    includes,
+    name: normalizeString(value.name, `${key}.name`, issues, {default: `legacy process ${index + 1}`})
+  }]
+}
+
+/**
+ * @param {JsonValue} value - Raw stop signal.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {string} The graceful-stop signal name (default "SIGTERM").
+ */
+function normalizeStopSignal(value, key, issues) {
+  if (value === undefined || value === null) return "SIGTERM"
+
+  if (typeof value === "string" && Object.prototype.hasOwnProperty.call(os.constants.signals, value)) {
+    return value
+  }
+
+  issues.push({fix: `Set ${key} to a signal name such as "SIGTERM", "SIGINT", or "SIGQUIT".`, message: `${key} must be a valid signal name`})
+
+  return "SIGTERM"
+}
+
 /**
  * @param {JsonValue} value - Raw output retention value.
  * @param {string} key - Config key.
@@ -283,6 +475,40 @@ function normalizeOutputLines(value, key, issues) {
   return outputLines
 }
 
+/**
+ * @param {JsonValue} value - Raw replica count.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {number} Number of replicas to run (default 1).
+ */
+function normalizeReplicas(value, key, issues) {
+  const replicas = normalizeNumber(value, key, issues, {default: 1})
+
+  if (!Number.isInteger(replicas) || replicas < 1) {
+    issues.push({fix: `Set ${key} to a positive integer number of replicas, e.g. 1 or 4.`, message: `${key} must be a positive integer`})
+
+    return 1
+  }
+
+  return replicas
+}
+
+/**
+ * @param {JsonValue} value - Raw boolean value.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @param {boolean} fallback - Default when unset.
+ * @returns {boolean} The boolean value, or the fallback when unset/invalid.
+ */
+function normalizeBoolean(value, key, issues, fallback) {
+  if (value === undefined || value === null) return fallback
+  if (typeof value === "boolean") return value
+
+  issues.push({fix: `Set ${key} to true or false.`, message: `${key} must be a boolean`})
+
+  return fallback
+}
+
 /**
  * @param {Record<string, JsonValue>} source - Raw release retention config.
  * @param {ConfigIssue[]} issues - Issue collector.
@@ -339,6 +565,26 @@ function normalizeSocketMode(value, key, issues) {
   return undefined
 }
 
+/**
+ * @param {JsonValue} value - Raw owner/group value.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {number | string | undefined} A numeric id, a name (resolved at bind time), or undefined when unset.
+ */
+function normalizeControlPrincipal(value, key, issues) {
+  if (value === undefined || value === null) return undefined
+
+  if (typeof value === "number") {
+    if (Number.isInteger(value) && value >= 0) return value
+  } else if (typeof value === "string" && value.length > 0) {
+    return value
+  }
+
+  issues.push({fix: `Set ${key} to a non-negative integer id or a user/group name, e.g. "deploy".`, message: `${key} must be a non-negative integer id or a name`})
+
+  return undefined
+}
+
 /**
  * Validates cross-process rules: unique ids, exactly one proxied process, and proxied ports.
  * @param {ProcessConfig[]} processes - Normalized processes.
@@ -356,6 +602,22 @@ function validateProcessSet(processes, issues) {
     }
 
     seenIds.add(processConfig.id)
+
+    if (processConfig.id.includes("#")) {
+      issues.push({fix: `Remove "#" from the process id "${processConfig.id}"; it is reserved for replica instance ids (e.g. "${processConfig.id.replace(/#/g, "")}#0").`, message: `Process id "${processConfig.id}" must not contain "#"`})
+    }
+
+    if (processConfig.replicas > 1 && (processConfig.policy !== "companion" || processConfig.port)) {
+      issues.push({fix: `Run replicas (${processConfig.replicas}) only on a companion process without a port; "${processConfig.id}" is ${processConfig.policy}${processConfig.port ? " with a port" : ""}.`, message: `Process "${processConfig.id}" can only set replicas > 1 on a companion process without a port`})
+    }
+
+    if (processConfig.nonBlockingDrain && processConfig.policy !== "companion") {
+      issues.push({fix: `Set nonBlockingDrain only on a companion process; "${processConfig.id}" is ${processConfig.policy}.`, message: `Process "${processConfig.id}" can only set nonBlockingDrain on a companion process`})
+    }
+
+    if (processConfig.lifecycle.stopCommand && processConfig.stopSignal !== "SIGTERM") {
+      issues.push({fix: `Drop the custom stopSignal "${processConfig.stopSignal}" or lifecycle.stopCommand from "${processConfig.id}": with a stopCommand set, Rollbridge runs it to stop the process instead of sending stopSignal, so the signal is never used.`, message: `Process "${processConfig.id}" sets both lifecycle.stopCommand and a custom stopSignal, but stopCommand replaces stopSignal`})
+    }
   }
 
   const proxiedProcesses = processes.filter((processConfig) => processConfig.policy === "proxied")