rollbridge 0.1.28 → 0.1.30

package/test/fixtures/pre-split3-guardian-client.js

@@ -0,0 +1,293 @@
+// @ts-nocheck
+
+import crypto from "node:crypto"
+import {spawn} from "node:child_process"
+import net from "node:net"
+import {fileURLToPath} from "node:url"
+import ManagedProcess from "../../src/managed-process.js"
+
+const guardianPath = fileURLToPath(new URL("./pre-split3-process-guardian.js", import.meta.url))
+
+export default class GuardianClient {
+  /** @param {{pid?: number, socketPath: string, token: string}} identity - Durable guardian identity. */
+  constructor({pid, socketPath, token}) {
+    this.pid = pid
+    this.socketPath = socketPath
+    this.token = token
+    this.socket = /** @type {net.Socket | undefined} */ (undefined)
+    this.buffer = ""
+    this.nextId = 0
+    this.pending = /** @type {Map<number, {command: string, reject: (error: Error) => void, resolve: (value: import("./json.js").JsonValue) => void}>} */ (new Map())
+    this.idleWaiters = /** @type {(() => void)[]} */ ([])
+    this.guardianExitPromise = /** @type {Promise<void> | undefined} */ (undefined)
+    this.processes = /** @type {Map<string, GuardianProcess>} */ (new Map())
+  }
+
+  /** Launches a new detached guardian and connects to it after its bind acknowledgement. */
+  async launch() {
+    const child = spawn(process.execPath, [guardianPath, this.socketPath], {detached: true, stdio: ["ignore", "ignore", "ignore", "ipc"]})
+
+    this.pid = child.pid
+    this.guardianExitPromise = new Promise((resolve) => child.once("exit", () => resolve(undefined)))
+
+    await new Promise((resolve, reject) => {
+      child.once("error", reject)
+      child.once("exit", (code) => reject(new Error(`Process guardian exited before readiness with status ${code}`)))
+      child.once("message", (message) => {
+        if (message && typeof message === "object" && "error" in message) reject(new Error(String(message.error)))
+        else resolve(undefined)
+      })
+      child.send({token: this.token}, (error) => {
+        if (error) reject(error)
+      })
+    })
+    if (child.connected) await new Promise((resolve) => child.once("disconnect", () => resolve(undefined)))
+    child.unref()
+    await this.connect()
+  }
+
+  /** Connects to an existing guardian. */
+  async connect() {
+    if (this.socket && !this.socket.destroyed) return
+    const socket = net.createConnection(this.socketPath)
+
+    socket.setEncoding("utf8")
+    await new Promise((resolve, reject) => {
+      socket.once("connect", resolve)
+      socket.once("error", reject)
+    })
+    socket.on("data", (chunk) => this.onData(String(chunk)))
+    socket.once("close", () => {
+      for (const {command, reject} of this.pending.values()) reject(new Error(`Process guardian connection closed while awaiting ${command}`))
+      this.pending.clear()
+      this.resolveIdleWaiters()
+    })
+    this.socket = socket
+  }
+
+  /**
+   * @param {string} key - Stable process identity.
+   * @param {ConstructorParameters<typeof ManagedProcess>[0]} definition - Process definition.
+   * @returns {GuardianProcess} Remote managed process.
+   */
+  process(key, definition) {
+    const processInstance = new GuardianProcess({client: this, definition, key})
+
+    this.processes.set(key, processInstance)
+    return processInstance
+  }
+
+  /**
+   * @param {Record<string, import("./json.js").JsonValue>} command - Command.
+   * @returns {Promise<import("./json.js").JsonValue>} Guardian response.
+   */
+  async request(command) {
+    if (!this.socket || this.socket.destroyed) throw new Error("Process guardian is not connected")
+    this.nextId += 1
+    const id = this.nextId
+    const response = new Promise((resolve, reject) => this.pending.set(id, {command: String(command.command), reject, resolve}))
+
+    this.socket.write(`${JSON.stringify({...command, id, token: this.token})}\n`)
+    return await response
+  }
+
+  /** Stops the guardian after every owned process has stopped. */
+  async shutdown() {
+    if (this.pending.size > 0) {
+      await new Promise((resolve) => {
+        this.idleWaiters.push(() => { resolve(undefined) })
+      })
+    }
+    await this.request({command: "shutdown"})
+    const socket = this.socket
+
+    if (!socket || socket.destroyed) throw new Error("Process guardian disconnected before shutdown acknowledgement")
+    const closed = new Promise((resolve) => socket.once("close", () => resolve(undefined)))
+
+    socket.end()
+    await closed
+  }
+
+  /** Waits for a guardian launched by this client to exit. */
+  async guardianExit() {
+    if (!this.guardianExitPromise) throw new Error("Guardian exit is observable only from the launching client")
+    await this.guardianExitPromise
+  }
+
+  /** @param {number} graceMs - Event-driven handoff grace while the prior owner disconnects. */
+  async claimOwner(graceMs) {
+    await this.request({command: "claim-owner", graceMs})
+  }
+
+  /** @returns {Promise<{key: string, provenance: string, status: import("./managed-process.js").ManagedProcessStatus}[]>} Exact guardian-owned inventory. */
+  async inventory() {
+    return /** @type {{key: string, provenance: string, status: import("./managed-process.js").ManagedProcessStatus}[]} */ (await this.request({command: "inventory"}))
+  }
+
+  /**
+   * Stops and forgets one exact guardian-owned registration.
+   * @param {string} key - Stable guardian registration key.
+   * @param {string} provenance - Exact expected process-definition provenance.
+   */
+  async remove(key, provenance) {
+    await this.request({command: "remove", key, provenance})
+    this.processes.delete(key)
+  }
+
+  /** Stops guardian registrations absent from the reconstructed durable snapshot. */
+  async reconcileInventory() {
+    const unexpected = (await this.inventory()).filter((entry) => !this.processes.has(entry.key))
+    const results = await Promise.allSettled(unexpected.map((entry) => this.remove(entry.key, entry.provenance)))
+    const errors = results.filter((result) => result.status === "rejected").map((result) => result.reason)
+
+    if (errors.length > 0) {
+      throw new AggregateError(errors, `Guardian inventory reconciliation failed for ${errors.length} registration${errors.length === 1 ? "" : "s"}: ${errors.map((error) => errorMessage(error instanceof Error ? error : String(error))).join("; ")}`)
+    }
+  }
+
+  /** Disconnects a fenced startup loser without changing guardian-owned processes. */
+  disconnect() {
+    this.socket?.destroy()
+  }
+
+  /** Resolves shutdown barriers after every earlier request settles. */
+  resolveIdleWaiters() {
+    if (this.pending.size > 0) return
+    for (const resolve of this.idleWaiters.splice(0)) resolve()
+  }
+
+  /** @param {string} chunk - Protocol bytes. */
+  onData(chunk) {
+    this.buffer += chunk
+    let newline = this.buffer.indexOf("\n")
+
+    while (newline >= 0) {
+      const line = this.buffer.slice(0, newline)
+      const message = JSON.parse(line)
+
+      this.buffer = this.buffer.slice(newline + 1)
+      if (message.event) {
+        this.processes.get(message.key)?.onGuardianEvent(message)
+      } else {
+        const pending = this.pending.get(message.id)
+
+        this.pending.delete(message.id)
+        this.resolveIdleWaiters()
+        if (message.error) pending?.reject(new Error(message.error))
+        else pending?.resolve(message.result)
+      }
+      newline = this.buffer.indexOf("\n")
+    }
+  }
+}
+
+class GuardianProcess extends ManagedProcess {
+  /** @param {{client: GuardianClient, definition: ConstructorParameters<typeof ManagedProcess>[0], key: string}} args - Remote process args. */
+  constructor({client, definition, key}) {
+    super(definition)
+    this.client = client
+    this.key = key
+    this.definition = serializableDefinition(definition)
+    this.provenance = crypto.createHash("sha256").update(JSON.stringify(this.definition)).digest("hex")
+    this.cachedStatus = super.status()
+    this.registration = /** @type {Promise<void> | undefined} */ (undefined)
+    this.pendingUpdate = Promise.resolve()
+  }
+
+  async ensureRegistered() {
+    if (!this.registration) {
+      this.registration = this.client.request({command: "register", definition: this.definition, key: this.key, provenance: this.provenance})
+        .then((status) => { this.cachedStatus = asProcessStatus(status) })
+    }
+    await this.registration
+  }
+
+  /** Reconnects to an already registered guardian process without changing its desired state. */
+  async recover() {
+    await this.ensureRegistered()
+  }
+
+  async start(reason = "deploy") {
+    await this.ensureRegistered()
+    await this.pendingUpdate
+    this.cachedStatus = asProcessStatus(await this.client.request({command: "start", key: this.key, reason}))
+  }
+
+  /** @param {import("./managed-process.js").ManagedProcessDefinition} definition - Updated definition. */
+  updateDefinition(definition) {
+    const previousProvenance = this.provenance
+    const registration = this.ensureRegistered()
+
+    super.updateDefinition(definition)
+    this.definition = serializableDefinition(this)
+    this.provenance = crypto.createHash("sha256").update(JSON.stringify(this.definition)).digest("hex")
+    this.pendingUpdate = registration.then(async () => {
+      this.cachedStatus = asProcessStatus(await this.client.request({command: "update", definition: this.definition, key: this.key, previousProvenance, provenance: this.provenance}))
+    })
+  }
+
+  async quiesce() {
+    await this.ensureRegistered()
+    await this.pendingUpdate
+    this.cachedStatus = asProcessStatus(await this.client.request({command: "quiesce", key: this.key}))
+  }
+
+  async quiesceStrict() {
+    await this.quiesce()
+  }
+
+  async stop(options = {}) {
+    await this.ensureRegistered()
+    await this.pendingUpdate
+    this.cachedStatus = asProcessStatus(await this.client.request({command: "stop", key: this.key, options}))
+  }
+
+  status() {
+    return this.cachedStatus
+  }
+
+  /** @param {Record<string, import("./json.js").JsonValue>} event - Guardian event. */
+  onGuardianEvent(event) {
+    if (event.status) this.cachedStatus = asProcessStatus(event.status)
+    if (event.message === "process started") this.emit("started")
+    if (event.message === "process exited") this.emit("exit", event.data)
+    this.logger(typeof event.message === "string" ? event.message : "guardian process status", event.data && typeof event.data === "object" && !Array.isArray(event.data) ? event.data : {})
+  }
+}
+
+/**
+ * @param {ConstructorParameters<typeof ManagedProcess>[0] | ManagedProcess} definition - Managed definition.
+ * @returns {Record<string, import("./json.js").JsonValue>} Serializable definition.
+ */
+function serializableDefinition(definition) {
+  return {
+    command: definition.command,
+    cwd: definition.cwd,
+    env: definition.env,
+    id: definition.id,
+    lifecycle: definition.lifecycle,
+    memory: definition.memory,
+    outputLines: definition.outputLines,
+    restart: definition.restart,
+    restartDelayMs: definition.restartDelayMs,
+    stopSignal: definition.stopSignal,
+    stopTimeoutMs: definition.stopTimeoutMs
+  }
+}
+
+/**
+ * @param {import("./json.js").JsonValue} value - Protocol value.
+ * @returns {import("./managed-process.js").ManagedProcessStatus} Process status.
+ */
+function asProcessStatus(value) {
+  return JSON.parse(JSON.stringify(value))
+}
+
+/**
+ * @param {Error | string} error - Error-like value.
+ * @returns {string} Error message.
+ */
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+

package/test/fixtures/pre-split3-process-guardian.js

@@ -0,0 +1,292 @@
+// @ts-check
+
+import fs from "node:fs/promises"
+import net from "node:net"
+import ManagedProcess from "../../src/managed-process.js"
+
+/**
+ * @typedef {object} GuardianRequest
+ * @property {string} command - Operation name.
+ * @property {ConstructorParameters<typeof ManagedProcess>[0]} [definition] - Managed process definition.
+ * @property {number} [graceMs] - Owner reconnection grace.
+ * @property {number} id - Request id.
+ * @property {string} [key] - Stable process key.
+ * @property {{timeoutMs?: number}} [options] - Stop options.
+ * @property {string} [previousProvenance] - Expected current provenance.
+ * @property {string} [provenance] - New or registered provenance.
+ * @property {import("../../src/managed-process.js").ManagedProcessStartReason} [reason] - Start reason.
+ * @property {string} token - Authentication token.
+ */
+
+const [socketPath] = process.argv.slice(2)
+
+if (!socketPath || !process.send) throw new Error("process-guardian requires socket path and a private bootstrap channel")
+
+const token = await new Promise((resolve, reject) => {
+  process.once("disconnect", () => reject(new Error("Guardian bootstrap channel closed before authentication capability arrived")))
+  process.once("message", (message) => {
+    if (!message || typeof message !== "object" || !("token" in message) || typeof message.token !== "string" || !message.token) {
+      reject(new Error("Guardian bootstrap authentication capability is invalid"))
+      return
+    }
+    resolve(message.token)
+  })
+})
+
+/** @type {Map<string, {desired: boolean, process: ManagedProcess, provenance: string}>} */
+const processes = new Map()
+/** @type {Set<net.Socket>} */
+const clients = new Set()
+/** @type {net.Socket | undefined} */
+let ownerClient
+let shuttingDown = false
+/** @type {net.Socket | undefined} */
+let shutdownClient
+let shutdownFinalizing = false
+/** @type {Promise<void> | undefined} */
+let serverClosed
+/** @type {{reject: (error: Error) => void, resolve: (value: {claimed: boolean}) => void, socket: net.Socket, timer: ReturnType<typeof setTimeout>}[]} */
+const claimWaiters = []
+
+const server = net.createServer((socket) => {
+  clients.add(socket)
+  socket.setEncoding("utf8")
+  let buffer = ""
+
+  socket.once("close", () => {
+    clients.delete(socket)
+    const waiterIndex = claimWaiters.findIndex((waiter) => waiter.socket === socket)
+
+    if (waiterIndex >= 0) {
+      const [waiter] = claimWaiters.splice(waiterIndex, 1)
+      clearTimeout(waiter.timer)
+      waiter.reject(new Error("Owner claimant disconnected"))
+    }
+    if (ownerClient === socket) {
+      ownerClient = undefined
+      if (!shuttingDown) grantNextOwner()
+    }
+    if (shutdownClient === socket) void finishShutdown()
+  })
+  socket.on("data", (chunk) => {
+    buffer += chunk
+    let newline = buffer.indexOf("\n")
+
+    while (newline >= 0) {
+      const line = buffer.slice(0, newline)
+
+      buffer = buffer.slice(newline + 1)
+      void handleLine(socket, line)
+      newline = buffer.indexOf("\n")
+    }
+  })
+})
+
+server.on("error", (error) => {
+  if (process.send) process.send({error: error.message})
+  else throw error
+})
+
+server.listen(socketPath, async () => {
+  await fs.chmod(socketPath, 0o600)
+  if (process.send) {
+    process.send({ready: true})
+    process.disconnect?.()
+  }
+})
+
+/**
+ * @param {net.Socket} socket - Client.
+ * @param {string} line - JSON request.
+ * @returns {Promise<void>} Request completion.
+ */
+async function handleLine(socket, line) {
+  /** @type {GuardianRequest | undefined} */
+  let request
+
+  try {
+    request = /** @type {GuardianRequest} */ (JSON.parse(line))
+    if (request.token !== token) throw new Error("Guardian authentication failed")
+    const result = await execute(request, socket)
+
+    socket.write(`${JSON.stringify({id: request.id, result})}\n`)
+  } catch (error) {
+    if (!socket.destroyed) socket.write(`${JSON.stringify({error: error instanceof Error ? error.message : String(error), id: request?.id})}\n`)
+  }
+}
+
+/**
+ * @param {GuardianRequest} request - Authenticated request.
+ * @param {net.Socket} socket - Requesting client.
+ * @returns {Promise<import("../../src/json.js").JsonValue>} Command result.
+ */
+async function execute(request, socket) {
+  if (shuttingDown) throw new Error("Process guardian is shutting down")
+
+  if (request.command === "claim-owner") {
+    if (!ownerClient) {
+      ownerClient = socket
+      return {claimed: true}
+    }
+    if (ownerClient === socket) return {claimed: true}
+
+    return await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        const index = claimWaiters.findIndex((waiter) => waiter.socket === socket)
+        if (index >= 0) claimWaiters.splice(index, 1)
+        reject(new Error("Durable owner is already claimed by another matching daemon"))
+      }, request.graceMs ?? 30000)
+
+      claimWaiters.push({reject, resolve, socket, timer})
+    })
+  }
+
+  if (request.command === "shutdown") {
+    shuttingDown = true
+    try {
+      const results = await Promise.allSettled([...processes.values()].map((entry) => entry.process.stop()))
+      const errors = results.filter((result) => result.status === "rejected").map((result) => result.reason)
+
+      if (errors.length > 0) throw new AggregateError(errors, `Guardian failed to stop ${errors.length} owned process${errors.length === 1 ? "" : "es"}: ${errors.map((error) => errorMessage(error instanceof Error ? error : String(error))).join("; ")}`)
+      beginSuccessfulShutdown(socket)
+      return {stopped: true}
+    } catch (error) {
+      shutdownClient = undefined
+      shuttingDown = false
+      throw error
+    }
+  }
+
+  if (request.command === "inventory") {
+    return [...processes.entries()].map(([key, entry]) => ({key, provenance: entry.provenance, status: entry.process.status()}))
+  }
+
+  if (request.command === "remove") {
+    if (!request.key || !request.provenance) throw new Error("Guardian remove requires key and provenance")
+    const existing = processes.get(request.key)
+
+    if (!existing) throw new Error(`Guardian process ${request.key} is not registered`)
+    if (existing.provenance !== request.provenance) throw new Error(`Guardian provenance mismatch for ${request.key}`)
+    existing.desired = false
+    await existing.process.stop()
+    processes.delete(request.key)
+    return {removed: true}
+  }
+
+  if (request.command === "register") {
+    if (!request.key || !request.definition || !request.provenance) throw new Error("Guardian register requires key, definition, and provenance")
+    const existing = processes.get(request.key)
+
+    if (existing) {
+      if (existing.provenance !== request.provenance) throw new Error(`Guardian provenance mismatch for ${request.key}`)
+      return existing.process.status()
+    }
+
+    const record = /** @type {{desired: boolean, process?: ManagedProcess, provenance: string}} */ ({desired: true, provenance: request.provenance})
+    const definition = request.definition
+    const managedProcess = new ManagedProcess({
+      ...definition,
+      logger: (message, data = {}) => broadcast({event: "process", key: request.key, message, data, status: managedProcess.status()}),
+      shouldRestart: () => record.desired
+    })
+
+    record.process = managedProcess
+    processes.set(request.key, /** @type {{desired: boolean, process: ManagedProcess, provenance: string}} */ (record))
+    return managedProcess.status()
+  }
+
+  if (!request.key) throw new Error(`Guardian ${request.command} requires a process key`)
+  const record = processes.get(request.key)
+
+  if (!record) throw new Error(`Guardian process ${request.key} is not registered`)
+
+  if (request.command === "start") {
+    record.desired = true
+    await record.process.start(request.reason)
+  } else if (request.command === "quiesce") {
+    record.desired = false
+    await record.process.quiesceStrict()
+  } else if (request.command === "stop") {
+    record.desired = false
+    await record.process.stop(request.options)
+  } else if (request.command === "update") {
+    if (!request.definition || !request.provenance) throw new Error("Guardian update requires definition and provenance")
+    if (record.provenance !== request.previousProvenance) throw new Error(`Guardian provenance mismatch for ${request.key}`)
+    record.process.updateDefinition({
+      ...request.definition,
+      lifecycle: request.definition.lifecycle || {drainTimeoutMs: 0},
+      logger: record.process.logger,
+      memory: request.definition.memory,
+      restart: request.definition.restart || {backoffFactor: 1, maxDelayMs: 0, maxRestarts: undefined, windowMs: 0},
+      shouldRestart: () => record.desired,
+      stopSignal: request.definition.stopSignal || "SIGTERM"
+    })
+    record.provenance = request.provenance
+  } else if (request.command === "status") {
+    return record.process.status()
+  } else {
+    throw new Error(`Unknown guardian command: ${request.command}`)
+  }
+
+  const status = record.process.status()
+
+  broadcast({event: "status", key: request.key, status})
+  return status
+}
+
+/**
+ * Stops accepting connections and closes every authority channel except the response caller.
+ * @param {net.Socket} caller - Shutdown requester retained until it receives the response.
+ */
+function beginSuccessfulShutdown(caller) {
+  shutdownClient = caller
+  serverClosed = new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error) reject(error)
+      else resolve(undefined)
+    })
+  })
+
+  for (const client of clients) {
+    if (client !== caller) client.destroy()
+  }
+  if (caller.destroyed) void finishShutdown()
+}
+
+/** Completes shutdown after the caller has received success and closed its side. */
+async function finishShutdown() {
+  if (shutdownFinalizing) return
+  shutdownFinalizing = true
+  for (const client of clients) client.destroy()
+  await serverClosed
+  await fs.rm(socketPath, {force: true})
+}
+
+/** @param {Record<string, import("../../src/json.js").JsonValue>} event - Event payload. */
+function broadcast(event) {
+  const line = `${JSON.stringify(event)}\n`
+
+  for (const client of clients) if (!client.destroyed) client.write(line)
+}
+
+/** @returns {void} Grants the next queued owner claim. */
+function grantNextOwner() {
+  const next = claimWaiters.shift()
+
+  if (!next) return
+  clearTimeout(next.timer)
+  ownerClient = next.socket
+  next.resolve({claimed: true})
+  for (const waiter of claimWaiters.splice(0)) {
+    clearTimeout(waiter.timer)
+    waiter.reject(new Error("Durable owner was claimed by another matching daemon"))
+  }
+}
+
+/**
+ * @param {Error | string} error - Error-like value.
+ * @returns {string} Error message.
+ */
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error)
+}

package/test/fixtures/service-app.js

@@ -2,10 +2,15 @@
 
 import fs from "node:fs"
 import http from "node:http"
+import path from "node:path"
 
 const logPath = requiredEnv("ROLLBRIDGE_SERVICE_LOG")
 const port = Number(requiredEnv("ROLLBRIDGE_PORT"))
 const releaseId = process.env.ROLLBRIDGE_RELEASE_ID || "unknown"
+const bindGatePath = process.env.ROLLBRIDGE_SERVICE_BIND_GATE
+const bindWaitingPath = process.env.ROLLBRIDGE_SERVICE_BIND_WAITING
+/** @type {fs.FSWatcher | undefined} */
+let bindWatcher
 
 writeEvent("start")
 
@@ -16,10 +21,35 @@ const server = http.createServer((_request, response) => {
 
 process.on("SIGTERM", () => {
   writeEvent("stop")
-  server.close(() => process.exit(0))
+  bindWatcher?.close()
+  if (server.listening) server.close(() => process.exit(0))
+  else process.exit(0)
 })
 
-server.listen(port, "127.0.0.1")
+listenWhenReleased()
+
+/** Starts listening immediately or after the release-local test gate opens. */
+function listenWhenReleased() {
+  if (!bindGatePath) {
+    server.listen(port, "127.0.0.1")
+    return
+  }
+
+  let bindStarted = false
+  const bind = () => {
+    if (bindStarted || !fs.existsSync(bindGatePath)) return
+    bindStarted = true
+    bindWatcher?.close()
+    bindWatcher = undefined
+    server.listen(port, "127.0.0.1")
+  }
+
+  bindWatcher = fs.watch(path.dirname(bindGatePath), (_event, filename) => {
+    if (filename === path.basename(bindGatePath)) bind()
+  })
+  if (fs.existsSync(bindGatePath)) bind()
+  else if (bindWaitingPath) fs.writeFileSync(bindWaitingPath, `${process.pid}\n`)
+}
 
 /**
  * @param {"start" | "stop"} event - Event.