rollbridge 0.1.1

package/src/managed-process.js

@@ -0,0 +1,232 @@
+// @ts-check
+
+import {EventEmitter} from "node:events"
+import {spawn} from "node:child_process"
+
+/**
+ * @typedef {import("./json.js").JsonValue} JsonValue
+ * @typedef {"starting" | "running" | "stopping" | "stopped" | "failed"} ManagedProcessState
+ * @typedef {import("node:child_process").ChildProcess["signalCode"]} ProcessExitSignal
+ * @typedef {{at: string, line: string, stream: "stdout" | "stderr"}} ManagedProcessLog
+ * @typedef {{command: string, cwd: string | undefined, env: Record<string, string | undefined>, logger: (message: string, data?: Record<string, import("./json.js").JsonValue>) => void, restartDelayMs: number, shouldRestart: () => boolean, stopTimeoutMs: number}} ManagedProcessDefinition
+ * @typedef {{command: string, cwd: string | undefined, exitCode: number | null | undefined, exitSignal: ProcessExitSignal | undefined, id: string, logs: ManagedProcessLog[], pid: number | undefined, state: ManagedProcessState}} ManagedProcessStatus
+ */
+
+export default class ManagedProcess extends EventEmitter {
+  /**
+   * @param {object} args - Options.
+   * @param {string} args.command - Shell command.
+   * @param {string | undefined} args.cwd - Working directory.
+   * @param {Record<string, string | undefined>} args.env - Environment.
+   * @param {string} args.id - Process id.
+   * @param {(message: string, data?: Record<string, JsonValue>) => void} args.logger - Logger callback.
+   * @param {number} args.restartDelayMs - Restart delay.
+   * @param {() => boolean} args.shouldRestart - Restart policy callback.
+   * @param {number} args.stopTimeoutMs - Stop timeout.
+   */
+  constructor({command, cwd, env, id, logger, restartDelayMs, shouldRestart, stopTimeoutMs}) {
+    super()
+
+    this.command = command
+    this.cwd = cwd
+    this.env = env
+    this.id = id
+    this.logger = logger
+    this.restartDelayMs = restartDelayMs
+    this.shouldRestart = shouldRestart
+    this.stopTimeoutMs = stopTimeoutMs
+    this.state = /** @type {ManagedProcessState} */ ("stopped")
+    this.logs = /** @type {ManagedProcessLog[]} */ ([])
+    this.intentionalStop = false
+    this.restartTimer = undefined
+    this.child = undefined
+    this.exitPromise = undefined
+    this.pid = undefined
+    this.exitCode = undefined
+    this.exitSignal = undefined
+  }
+
+  /** @returns {Promise<void>} Resolves after spawn. */
+  async start() {
+    if (this.child) return
+
+    this.intentionalStop = false
+    this.exitCode = undefined
+    this.exitSignal = undefined
+    this.state = "starting"
+
+    await new Promise((resolve, reject) => {
+      const child = spawn(this.command, {
+        cwd: this.cwd,
+        detached: true,
+        env: {...process.env, ...this.env},
+        shell: true,
+        stdio: ["ignore", "pipe", "pipe"]
+      })
+
+      this.child = child
+      this.pid = child.pid
+      this.exitPromise = new Promise((exitResolve) => {
+        child.once("exit", (code, signal) => {
+          this.onExit(code, signal)
+          exitResolve(undefined)
+        })
+      })
+
+      child.once("spawn", () => {
+        this.state = "running"
+        this.logger("process started", {command: this.command, id: this.id, pid: child.pid || null})
+        this.emit("started")
+        resolve(undefined)
+      })
+      child.once("error", (error) => {
+        this.state = "failed"
+        reject(error)
+      })
+      child.stdout.setEncoding("utf8")
+      child.stderr.setEncoding("utf8")
+      child.stdout.on("data", (chunk) => this.appendLog("stdout", chunk))
+      child.stderr.on("data", (chunk) => this.appendLog("stderr", chunk))
+    })
+  }
+
+  /**
+   * Updates the command template used for future restarts without touching the currently running child.
+   * @param {ManagedProcessDefinition} definition - Replacement process definition.
+   * @returns {void}
+   */
+  updateDefinition(definition) {
+    this.command = definition.command
+    this.cwd = definition.cwd
+    this.env = definition.env
+    this.logger = definition.logger
+    this.restartDelayMs = definition.restartDelayMs
+    this.shouldRestart = definition.shouldRestart
+    this.stopTimeoutMs = definition.stopTimeoutMs
+  }
+
+  /**
+   * @param {"stdout" | "stderr"} stream - Stream name.
+   * @param {string} chunk - Output chunk.
+   * @returns {void}
+   */
+  appendLog(stream, chunk) {
+    for (const line of String(chunk).split(/\r?\n/)) {
+      if (!line) continue
+
+      this.logs.push({at: new Date().toISOString(), line, stream})
+
+      if (this.logs.length > 200) {
+        this.logs.splice(0, this.logs.length - 200)
+      }
+    }
+  }
+
+  /**
+   * @param {number | null} code - Exit code.
+   * @param {ProcessExitSignal} signal - Exit signal.
+   * @returns {void}
+   */
+  onExit(code, signal) {
+    const wasIntentional = this.intentionalStop
+
+    this.exitCode = code
+    this.exitSignal = signal
+    this.child = undefined
+    this.pid = undefined
+    this.exitPromise = undefined
+    this.state = wasIntentional ? "stopped" : "failed"
+    this.logger("process exited", {code, id: this.id, signal})
+    this.emit("exit", {code, signal})
+
+    if (!wasIntentional && this.shouldRestart()) {
+      this.restartTimer = setTimeout(() => {
+        this.restartTimer = undefined
+        this.start().catch((error) => {
+          this.logger("process restart failed", {error: error instanceof Error ? error.message : String(error), id: this.id})
+        })
+      }, this.restartDelayMs)
+    }
+  }
+
+  /**
+   * @param {{timeoutMs?: number}} [options] - Stop options.
+   * @returns {Promise<void>} Resolves when stopped.
+   */
+  async stop(options = {}) {
+    this.intentionalStop = true
+
+    if (this.restartTimer) {
+      clearTimeout(this.restartTimer)
+      this.restartTimer = undefined
+    }
+
+    const child = this.child
+
+    if (!child || !child.pid) {
+      this.state = "stopped"
+      return
+    }
+
+    this.state = "stopping"
+    this.killProcessGroup("SIGTERM")
+    const timeoutMs = options.timeoutMs ?? this.stopTimeoutMs
+    const stopped = await this.waitForExit(timeoutMs)
+
+    if (!stopped) {
+      this.logger("process stop timed out; sending SIGKILL", {id: this.id, pid: child.pid})
+      this.killProcessGroup("SIGKILL")
+      await this.waitForExit(5000)
+    }
+
+    this.state = "stopped"
+  }
+
+  /**
+   * @param {"SIGTERM" | "SIGKILL"} signal - Signal to send.
+   * @returns {void}
+   */
+  killProcessGroup(signal) {
+    if (!this.child || !this.child.pid) return
+
+    try {
+      process.kill(-this.child.pid, signal)
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ESRCH") return
+      throw error
+    }
+  }
+
+  /**
+   * @param {number} timeoutMs - Timeout.
+   * @returns {Promise<boolean>} True when the process exited before timeout.
+   */
+  async waitForExit(timeoutMs) {
+    if (!this.exitPromise) return true
+
+    let timer = /** @type {ReturnType<typeof setTimeout> | undefined} */ (undefined)
+    const timeoutPromise = new Promise((resolve) => {
+      timer = setTimeout(() => resolve(false), timeoutMs)
+    })
+    const exitPromise = this.exitPromise.then(() => true)
+    const result = await Promise.race([exitPromise, timeoutPromise])
+
+    if (timer) clearTimeout(timer)
+
+    return Boolean(result)
+  }
+
+  /** @returns {ManagedProcessStatus} Status payload. */
+  status() {
+    return {
+      command: this.command,
+      cwd: this.cwd,
+      exitCode: this.exitCode,
+      exitSignal: this.exitSignal,
+      id: this.id,
+      logs: this.logs.slice(-20),
+      pid: this.pid,
+      state: this.state
+    }
+  }
+}

package/src/port-allocator.js

@@ -0,0 +1,88 @@
+// @ts-check
+
+import net from "node:net"
+
+/**
+ * @typedef {{from: number, to: number}} PortRange
+ */
+
+/**
+ * Tests whether a port can be bound.
+ * @param {object} args - Options.
+ * @param {string} args.host - Bind host.
+ * @param {number} args.port - Candidate port.
+ * @returns {Promise<{port: number} | {code: string}>} The bound port, or the bind error code.
+ */
+async function tryPort({host, port}) {
+  const server = net.createServer()
+
+  return await new Promise((resolve) => {
+    server.once("error", (error) => {
+      const code = error && typeof error === "object" && "code" in error ? String(error.code) : "EUNKNOWN"
+
+      resolve({code})
+    })
+    server.listen(port, host, () => {
+      const address = server.address()
+      const boundPort = address && typeof address === "object" ? address.port : port
+
+      server.close(() => resolve({port: boundPort}))
+    })
+  })
+}
+
+/**
+ * Finds an available port in a range.
+ * @param {object} args - Options.
+ * @param {string} args.host - Bind host.
+ * @param {PortRange | undefined} args.range - Candidate range.
+ * @param {Set<number>} args.usedPorts - Ports already allocated by this deploy.
+ * @returns {Promise<number>} Available port.
+ */
+export async function findAvailablePort({host, range, usedPorts}) {
+  if (!range || range.from === 0 || range.to === 0) {
+    const result = await tryPort({host, port: 0})
+
+    if (!("port" in result)) throw new Error(`Unable to allocate an ephemeral port on ${host} (${result.code})`)
+    usedPorts.add(result.port)
+
+    return result.port
+  }
+
+  let reserved = 0
+  let inUse = 0
+  let unavailable = 0
+  /** @type {string | undefined} */
+  let lastErrorCode
+
+  for (let port = range.from; port <= range.to; port += 1) {
+    if (usedPorts.has(port)) {
+      reserved += 1
+      continue
+    }
+
+    const result = await tryPort({host, port})
+
+    if ("port" in result) {
+      usedPorts.add(result.port)
+      return result.port
+    }
+
+    if (result.code === "EADDRINUSE") {
+      inUse += 1
+    } else {
+      unavailable += 1
+      lastErrorCode = result.code
+    }
+  }
+
+  const total = range.to - range.from + 1
+  const details = [`${reserved} reserved by this deploy`, `${inUse} already in use`]
+
+  if (unavailable > 0) details.push(`${unavailable} could not be bound (e.g. ${lastErrorCode})`)
+
+  throw new Error(
+    `No available ports in range ${range.from}-${range.to} (${total} port${total === 1 ? "" : "s"} on ${host}): ` +
+    `${details.join(", ")}. Widen the port range, free a port, or check bind permissions.`
+  )
+}

package/src/release-group.js

@@ -0,0 +1,287 @@
+// @ts-check
+
+import {EventEmitter} from "node:events"
+import ManagedProcess from "./managed-process.js"
+import {findAvailablePort} from "./port-allocator.js"
+import {renderObject, renderTemplate} from "./template.js"
+import {waitForHealth} from "./health.js"
+
+/**
+ * @typedef {import("./json.js").JsonValue} JsonValue
+ * @typedef {"starting" | "active" | "draining" | "stopped" | "failed"} ReleaseState
+ * @typedef {{http: number, websocket: number}} ReleaseConnections
+ * @typedef {{activatedAt: string | undefined, connectionCount: number, connections: ReleaseConnections, drainStartedAt: string | undefined, ports: Record<string, number>, processes: import("./managed-process.js").ManagedProcessStatus[], releaseId: string, releasePath: string, revision: string, state: ReleaseState, stoppedAt: string | undefined}} ReleaseStatus
+ * @typedef {{shouldRestart?: () => boolean}} BuildProcessOptions
+ */
+
+/**
+ * @param {string} id - Process id.
+ * @returns {string} Environment suffix.
+ */
+function envId(id) {
+  return id.replace(/[^a-zA-Z0-9]+/g, "_").toUpperCase()
+}
+
+export default class ReleaseGroup extends EventEmitter {
+  /**
+   * @param {object} args - Options.
+   * @param {import("./config.js").RollbridgeConfig} args.config - Rollbridge config.
+   * @param {(message: string, data?: Record<string, JsonValue>) => void} args.logger - Logger.
+   * @param {string} args.releaseId - Release id.
+   * @param {string} args.releasePath - Release path.
+   * @param {string | undefined} args.revision - Revision.
+   * @param {Record<string, number>} [args.servicePorts] - Ports already owned by daemon-wide services.
+   */
+  constructor({config, logger, releaseId, releasePath, revision, servicePorts = {}}) {
+    super()
+
+    this.config = config
+    this.logger = logger
+    this.releaseId = releaseId
+    this.releasePath = releasePath
+    this.revision = revision || releaseId
+    this.state = /** @type {ReleaseState} */ ("starting")
+    this.connectionCount = 0
+    this.connections = /** @type {ReleaseConnections} */ ({http: 0, websocket: 0})
+    this.processes = /** @type {Map<string, ManagedProcess>} */ (new Map())
+    this.ports = /** @type {Record<string, number>} */ ({})
+    this.servicePorts = servicePorts
+    this.portsAllocated = false
+    this.drainStartedAt = /** @type {string | undefined} */ (undefined)
+    this.activatedAt = /** @type {string | undefined} */ (undefined)
+    this.stoppedAt = /** @type {string | undefined} */ (undefined)
+  }
+
+  /** @returns {Promise<void>} Starts release-owned processes and health checks the proxied process. */
+  async start() {
+    this.state = "starting"
+
+    try {
+      await this.allocatePorts()
+
+      for (const processConfig of this.releaseProcessStartOrder()) {
+        const processInstance = this.buildProcess(processConfig)
+        this.processes.set(processConfig.id, processInstance)
+        await processInstance.start()
+
+        if (processConfig.policy === "proxied" && processConfig.port && processConfig.health) {
+          await waitForHealth({
+            health: processConfig.health,
+            host: this.config.proxy.host,
+            port: this.ports[processConfig.id]
+          })
+        }
+      }
+    } catch (error) {
+      this.state = "failed"
+      await this.stop()
+      throw error
+    }
+  }
+
+  /**
+   * Starts companions before the proxied process so release-local dependencies are available before health checks.
+   * @returns {import("./config.js").ProcessConfig[]} Ordered process configs.
+   */
+  releaseProcessStartOrder() {
+    const releaseProcesses = this.config.processes.filter((processConfig) => !["singleton", "service"].includes(processConfig.policy))
+    const companionProcesses = releaseProcesses.filter((processConfig) => processConfig.policy === "companion")
+    const proxiedProcesses = releaseProcesses.filter((processConfig) => processConfig.policy === "proxied")
+
+    return [...companionProcesses, ...proxiedProcesses]
+  }
+
+  /** @returns {void} Marks this release active. */
+  activate() {
+    this.state = "active"
+    this.activatedAt = new Date().toISOString()
+  }
+
+  /** @returns {Promise<void>} Allocates all configured per-process ports. */
+  async allocatePorts() {
+    if (this.portsAllocated) return
+
+    const usedPorts = /** @type {Set<number>} */ (new Set())
+
+    for (const processConfig of this.config.processes) {
+      if (!processConfig.port) continue
+      if (processConfig.policy === "service" && this.servicePorts[processConfig.id] !== undefined) {
+        this.ports[processConfig.id] = this.servicePorts[processConfig.id]
+        usedPorts.add(this.servicePorts[processConfig.id])
+        continue
+      }
+
+      this.ports[processConfig.id] = await findAvailablePort({
+        host: this.config.proxy.host,
+        range: processConfig.port,
+        usedPorts
+      })
+    }
+
+    this.portsAllocated = true
+  }
+
+  /**
+   * Builds a managed process from config.
+   * @param {import("./config.js").ProcessConfig} processConfig - Process config.
+   * @param {BuildProcessOptions} [options] - Build options.
+   * @returns {ManagedProcess} Managed process.
+   */
+  buildProcess(processConfig, options = {}) {
+    const context = this.contextForProcess(processConfig)
+    const renderedEnv = /** @type {Record<string, string>} */ (renderObject(processConfig.env, context))
+    const processEnv = {
+      ...this.baseEnvironment(processConfig),
+      ...renderedEnv
+    }
+
+    return new ManagedProcess({
+      command: renderTemplate(processConfig.command, context),
+      cwd: processConfig.cwd ? renderTemplate(processConfig.cwd, context) : this.releasePath,
+      env: processEnv,
+      id: processConfig.id,
+      logger: (message, data = {}) => this.logger(message, {processId: processConfig.id, releaseId: this.releaseId, ...data}),
+      restartDelayMs: processConfig.restartDelayMs,
+      shouldRestart: options.shouldRestart || (() => this.state === "active" || this.state === "starting"),
+      stopTimeoutMs: processConfig.gracefulStopMs
+    })
+  }
+
+  /**
+   * @param {import("./config.js").ProcessConfig} processConfig - Process config.
+   * @returns {Record<string, string>} Base environment.
+   */
+  baseEnvironment(processConfig) {
+    /** @type {Record<string, string>} */
+    const env = {
+      ROLLBRIDGE_APPLICATION: this.config.application,
+      ROLLBRIDGE_PROCESS_ID: processConfig.id,
+      ROLLBRIDGE_RELEASE_ID: this.releaseId,
+      ROLLBRIDGE_RELEASE_PATH: this.releasePath,
+      ROLLBRIDGE_REVISION: this.revision
+    }
+
+    if (this.ports[processConfig.id] !== undefined) {
+      env.ROLLBRIDGE_PORT = String(this.ports[processConfig.id])
+    }
+
+    for (const [processId, port] of Object.entries(this.ports)) {
+      env[`ROLLBRIDGE_${envId(processId)}_PORT`] = String(port)
+    }
+
+    return env
+  }
+
+  /**
+   * @param {import("./config.js").ProcessConfig} processConfig - Process config.
+   * @returns {Record<string, JsonValue>} Template context.
+   */
+  contextForProcess(processConfig) {
+    return {
+      application: this.config.application,
+      port: this.ports[processConfig.id],
+      ports: this.ports,
+      processId: processConfig.id,
+      proxy: {
+        host: this.config.proxy.host,
+        port: this.config.proxy.port
+      },
+      releaseId: this.releaseId,
+      releasePath: this.releasePath,
+      revision: this.revision
+    }
+  }
+
+  /**
+   * @returns {{process: ManagedProcess, target: string}} Proxied process target.
+   */
+  proxyTarget() {
+    const processConfig = this.config.processes.find((candidate) => candidate.policy === "proxied")
+
+    if (!processConfig) throw new Error("No proxied process configured")
+
+    const processInstance = this.processes.get(processConfig.id)
+    const port = this.ports[processConfig.id]
+
+    if (!processInstance || !port) {
+      throw new Error(`Proxied process ${processConfig.id} is not running`)
+    }
+
+    return {
+      process: processInstance,
+      target: `http://${this.config.proxy.host}:${port}`
+    }
+  }
+
+  /**
+   * @param {"http" | "websocket"} type - Connection type.
+   * @returns {() => void} Release callback.
+   */
+  retainConnection(type) {
+    this.connectionCount += 1
+    this.connections[type] += 1
+    let released = false
+
+    return () => {
+      if (released) return
+
+      released = true
+      this.connectionCount -= 1
+      this.connections[type] -= 1
+
+      if (this.connectionCount === 0) {
+        this.emit("drained")
+      }
+    }
+  }
+
+  /**
+   * Starts draining and stops once existing connections close or timeout.
+   * @param {number} timeoutMs - Drain timeout.
+   * @returns {Promise<void>} Resolves when stopped.
+   */
+  async drainAndStop(timeoutMs) {
+    if (this.state === "stopped") return
+
+    this.state = "draining"
+    this.drainStartedAt = new Date().toISOString()
+
+    if (this.connectionCount > 0) {
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, timeoutMs)
+        this.once("drained", () => {
+          clearTimeout(timer)
+          resolve(undefined)
+        })
+      })
+    }
+
+    await this.stop()
+  }
+
+  /** @returns {Promise<void>} Stops all release-owned processes. */
+  async stop() {
+    const stopTasks = [...this.processes.values()].map((processInstance) => processInstance.stop())
+
+    await Promise.allSettled(stopTasks)
+    this.state = "stopped"
+    this.stoppedAt = new Date().toISOString()
+  }
+
+  /** @returns {ReleaseStatus} Status payload. */
+  status() {
+    return {
+      activatedAt: this.activatedAt,
+      connectionCount: this.connectionCount,
+      connections: {...this.connections},
+      drainStartedAt: this.drainStartedAt,
+      ports: {...this.ports},
+      processes: [...this.processes.values()].map((processInstance) => processInstance.status()),
+      releaseId: this.releaseId,
+      releasePath: this.releasePath,
+      revision: this.revision,
+      state: this.state,
+      stoppedAt: this.stoppedAt
+    }
+  }
+}

package/src/template.js

@@ -0,0 +1,74 @@
+// @ts-check
+
+/**
+ * @typedef {import("./json.js").JsonValue} JsonValue
+ * @typedef {Record<string, JsonValue>} TemplateContext
+ */
+
+/**
+ * Resolves a dotted template key against the context.
+ * @param {string} key - Dotted key from a template expression.
+ * @param {TemplateContext} context - Template context.
+ * @returns {JsonValue} Resolved value.
+ */
+export function resolveTemplateValue(key, context) {
+  const parts = key.split(".")
+  let current = /** @type {JsonValue} */ (context)
+
+  for (const part of parts) {
+    if (!current || typeof current !== "object") {
+      return undefined
+    }
+
+    current = /** @type {Record<string, JsonValue>} */ (current)[part]
+  }
+
+  return current
+}
+
+/**
+ * Renders `{{key}}` placeholders in a string.
+ * @param {string} value - Template string.
+ * @param {TemplateContext} context - Template context.
+ * @returns {string} Rendered string.
+ */
+export function renderTemplate(value, context) {
+  return value.replace(/\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g, (match, key) => {
+    const resolved = resolveTemplateValue(key, context)
+
+    if (resolved === undefined || resolved === null) {
+      throw new Error(`Missing template value for ${match}`)
+    }
+
+    return String(resolved)
+  })
+}
+
+/**
+ * Renders all string values in a plain JSON-like object.
+ * @param {JsonValue} value - Value to render.
+ * @param {TemplateContext} context - Template context.
+ * @returns {JsonValue} Rendered value.
+ */
+export function renderObject(value, context) {
+  if (typeof value === "string") {
+    return renderTemplate(value, context)
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => renderObject(entry, context))
+  }
+
+  if (value && typeof value === "object") {
+    /** @type {Record<string, JsonValue>} */
+    const rendered = {}
+
+    for (const [key, entry] of Object.entries(value)) {
+      rendered[key] = renderObject(entry, context)
+    }
+
+    return rendered
+  }
+
+  return value
+}

package/tensorbuzz.yml

@@ -0,0 +1,4 @@
+before_script:
+  - npm install
+script:
+  - npm run all-checks