rollbridge 0.1.39 → 0.1.40

package/src/guardian-client.js

@@ -32,7 +32,7 @@ export default class GuardianClient {
    * @param {{legacyGuardian?: {pid?: number, socketPath: string, token: string}, ownerState?: import("./json.js").JsonValue}} [options] - Optional authenticated legacy backend migration.
    */
   async launch(options = {}) {
-    const child = spawn(process.execPath, [guardianPath, this.socketPath], {detached: true, stdio: ["ignore", "ignore", "ignore", "ipc"]})
+    const child = spawn(process.execPath, [guardianPath, this.socketPath], {detached: true, stdio: ["ignore", "inherit", "inherit", "ipc"]})
 
     this.pid = child.pid
     this.guardianExitPromise = new Promise((resolve) => child.once("exit", () => resolve(undefined)))
@@ -176,7 +176,17 @@ export default class GuardianClient {
    * @param {import("./json.js").JsonValue} authority - Exact owner authority.
    */
   async claimOwner(graceMs, authority) {
-    await this.request({authority, command: "claim-owner", graceMs})
+    await this.request({authority, command: "claim-owner", graceMs, ownerPid: process.pid})
+  }
+
+  /** Confirms that the claimed daemon has completed startup and published its listeners. */
+  async ownerReady() {
+    await this.request({command: "owner-ready", ownerPid: process.pid})
+  }
+
+  /** @returns {Promise<{daemonRecovery: number}>} Guardian protocol capabilities. */
+  async capabilities() {
+    return /** @type {{daemonRecovery: number}} */ (await this.request({command: "capabilities"}))
   }
 
   /** Starts graceful process retirement and relinquishes committed owner authority. */
@@ -221,7 +231,7 @@ export default class GuardianClient {
    * @returns {Promise<{ownerState: import("./json.js").JsonValue, replacementId: string}>} Prepared transaction.
    */
   async prepareOwnerReplacement(authority, nextAuthority) {
-    return /** @type {{ownerState: import("./json.js").JsonValue, replacementId: string}} */ (await this.request({authority, command: "prepare-owner-replacement", nextAuthority}))
+    return /** @type {{ownerState: import("./json.js").JsonValue, replacementId: string}} */ (await this.request({authority, command: "prepare-owner-replacement", nextAuthority, ownerPid: process.pid}))
   }
 
   /**
@@ -251,13 +261,24 @@ export default class GuardianClient {
     await this.request({command: "commit-retired-owner-replacement", key, replacementId})
   }
 
+  /**
+   * Yields a control-less incumbent's listeners while it still owns authority.
+   * @param {string} replacementId - Same-authority staged transaction.
+   * @param {string} key - Exact recovered guardian process proving candidate reconstruction.
+   */
+  async prepareRetiredOwnerListenerHandoff(replacementId, key) {
+    await this.request({command: "prepare-retired-owner-listener-handoff", key, replacementId})
+  }
+
   /**
    * Begins acquiring the authenticated legacy backend owner channel at the disruptive boundary.
    * @param {string} replacementId - Exact prepared candidate transaction.
    * @param {number} graceMs - Event-driven incumbent disconnect grace.
+   * @param {string} statePath - Durable public recovery state path.
+   * @param {import("./json.js").JsonValue} recoverySnapshot - Discoverable coordinator state.
    */
-  async beginLegacyOwnerClaim(replacementId, graceMs) {
-    await this.request({command: "begin-legacy-owner-claim", graceMs, replacementId})
+  async beginLegacyOwnerClaim(replacementId, graceMs, statePath, recoverySnapshot) {
+    await this.request({command: "begin-legacy-owner-claim", graceMs, recoverySnapshot, replacementId, statePath})
   }
 
   /**
@@ -273,6 +294,22 @@ export default class GuardianClient {
     await this.request({command: "finalize-owner-replacement", replacementId})
   }
 
+  /** @param {string} replacementId - Committed transaction with complete listener state. */
+  async completeOwnerListenerRetirement(replacementId) {
+    await this.request({command: "complete-owner-listener-retirement", replacementId})
+  }
+
+  /**
+   * @param {string} replacementId - Committed control-less replacement transaction.
+   * @param {string} sourceId - Stable listener source identity.
+   * @param {string} releaseId - Retained release identity.
+   * @param {{http: number, websocket: number}} connections - Exact incumbent listener counts.
+   * @param {boolean} [localSource] - Whether the sender physically owns this source.
+   */
+  async publishOwnerConnectionState(replacementId, sourceId, releaseId, connections, localSource = false) {
+    await this.request({command: "publish-owner-connection-state", connections, localSource, releaseId, replacementId, sourceId})
+  }
+
   /** @param {string} replacementId - Prepared transaction to validate for listener yield. */
   async validateOwnerReplacement(replacementId) {
     await this.request({command: "validate-owner-replacement", replacementId})
@@ -294,9 +331,9 @@ export default class GuardianClient {
     await this.request({command: "end-owner-mutation", mutationId})
   }
 
-  /** @returns {Promise<{committedReplacementId: string | null, ownerClaimed: boolean}>} Transaction status. */
+  /** @returns {Promise<{committedReplacementId: string | null, ownerClaimed: boolean, retirementFailed?: boolean, retirementPending?: boolean, retirementReady?: boolean}>} Transaction status. */
   async replacementStatus() {
-    return /** @type {{committedReplacementId: string | null, ownerClaimed: boolean}} */ (await this.request({command: "replacement-status"}))
+    return /** @type {{committedReplacementId: string | null, ownerClaimed: boolean, retirementFailed?: boolean, retirementPending?: boolean, retirementReady?: boolean}} */ (await this.request({command: "replacement-status"}))
   }
 
   /** @returns {Promise<import("./json.js").JsonValue>} Current private transfer state. */
@@ -444,17 +481,29 @@ class GuardianProcess extends ManagedProcess {
     this.cachedStatus = asProcessStatus(await this.client.request({command: "start", key: this.key, lifecycleRole, reason}))
   }
 
-  /** @param {import("./managed-process.js").ManagedProcessDefinition} definition - Updated definition. */
-  updateDefinition(definition) {
-    const previousProvenance = this.provenance
+  /**
+   * @param {import("./managed-process.js").ManagedProcessDefinition} definition - Updated definition.
+   * @param {import("./json.js").JsonValue} [ownerState] - Private owner state to commit with the definition.
+   * @returns {Promise<void>} Resolves once the guardian commits the replacement definition.
+   */
+  updateDefinition(definition, ownerState) {
     const registration = this.ensureRegistered()
+    const previousUpdate = this.pendingUpdate
+    const nextDefinition = serializableDefinition({...definition, id: this.id})
+    const nextProvenance = crypto.createHash("sha256").update(JSON.stringify(nextDefinition)).digest("hex")
 
-    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}))
+    const previousUpdateSettled = previousUpdate.catch(() => {
+      // The prior caller received the update failure and local provenance stayed unchanged,
+      // so a later explicit update may retry from the last guardian-committed definition.
     })
+
+    this.pendingUpdate = Promise.all([registration, previousUpdateSettled]).then(async () => {
+      this.cachedStatus = asProcessStatus(await this.client.request({command: "update", definition: nextDefinition, key: this.key, ownerState, previousProvenance: this.provenance, provenance: nextProvenance}))
+      super.updateDefinition(definition)
+      this.definition = nextDefinition
+      this.provenance = nextProvenance
+    })
+    return this.pendingUpdate
   }
 
   async quiesce() {
@@ -502,7 +551,10 @@ class GuardianProcess extends ManagedProcess {
   onGuardianEvent(event) {
     if (event.status) this.cachedStatus = asProcessStatus(event.status)
     if (event.event === "process-log") {
-      this.emit("log", asProcessLog(event.entry))
+      const entry = asProcessLog(event.entry)
+
+      this.cachedStatus = {...this.cachedStatus, logs: [...this.cachedStatus.logs, entry].slice(-this.outputLines)}
+      this.emit("log", entry)
       return
     }
     if (event.message === "process started") this.emit("started")

package/src/managed-process.js

@@ -5,6 +5,7 @@ import {spawn} from "node:child_process"
 import {processGroupHasLiveMembers, processGroupMembers} from "./process-memory.js"
 
 const ACTIVATION_HOOK_TIMEOUT_MS = 30000
+const MAX_BUFFERED_OUTPUT_CHARACTERS = 64 * 1024
 
 /**
  * @typedef {import("./json.js").JsonValue} JsonValue
@@ -54,6 +55,7 @@ export default class ManagedProcess extends EventEmitter {
     this.state = /** @type {ManagedProcessState} */ ("stopped")
     this.lastStartReason = /** @type {ManagedProcessStartReason | undefined} */ (undefined)
     this.logs = /** @type {ManagedProcessLog[]} */ ([])
+    this.outputBuffers = {stderr: "", stdout: ""}
     this.restarts = 0
     this.recentRestarts = /** @type {number[]} */ ([])
     this.rssBytes = /** @type {number | undefined} */ (undefined)
@@ -67,9 +69,11 @@ export default class ManagedProcess extends EventEmitter {
     this.intentionalStop = false
     this.lifecycleRole = /** @type {LifecycleRole} */ ("candidate")
     this.intentionalStopSignal = /** @type {ProcessExitSignal | undefined} */ (undefined)
+    this.lifecycleRestoreBarrier = /** @type {Promise<void> | undefined} */ (undefined)
     this.quiescePromise = /** @type {Promise<void> | undefined} */ (undefined)
     this.quiesceError = /** @type {Error | undefined} */ (undefined)
     this.stopPromise = /** @type {Promise<void> | undefined} */ (undefined)
+    this.operationRevision = 0
     this.restartTimer = undefined
     this.child = undefined
     this.exitPromise = undefined
@@ -84,6 +88,10 @@ export default class ManagedProcess extends EventEmitter {
    * @returns {Promise<void>} Resolves after spawn and lifecycle-role restoration.
    */
   async start(reason = "deploy", lifecycleRole) {
+    const operationRevision = ++this.operationRevision
+
+    if (this.stopPromise) await this.stopPromise
+    if (operationRevision !== this.operationRevision) return
     if (lifecycleRole) this.lifecycleRole = lifecycleRole
     if (this.child) return
 
@@ -97,6 +105,7 @@ export default class ManagedProcess extends EventEmitter {
     this.state = "starting"
 
     await new Promise((resolve, reject) => {
+      const outputBuffers = {stderr: "", stdout: ""}
       const child = spawn(this.command, {
         cwd: this.cwd,
         detached: true,
@@ -118,18 +127,28 @@ export default class ManagedProcess extends EventEmitter {
         void (async () => {
           this.startedAtMs = Date.now()
           this.lastStartReason = reason
+          const lifecycleRestore = this.restoreLifecycleRole()
+          const lifecycleRestoreBarrier = lifecycleRestore.then(() => undefined, () => undefined)
+
+          this.lifecycleRestoreBarrier = lifecycleRestoreBarrier
           try {
-            await this.restoreLifecycleRole()
+            await lifecycleRestore
           } catch (error) {
             this.state = "failed"
             this.logger("process lifecycle role restoration failed", {error: error instanceof Error ? error.message : String(error), id: this.id, role: this.lifecycleRole})
             reject(error)
             return
+          } finally {
+            if (this.lifecycleRestoreBarrier === lifecycleRestoreBarrier) this.lifecycleRestoreBarrier = undefined
           }
           if (this.child !== child) {
             reject(new Error(`Process ${this.id} exited before lifecycle role ${this.lifecycleRole} was restored`))
             return
           }
+          if (this.intentionalStop || this.state !== "starting") {
+            reject(new Error(`Process ${this.id} was quiesced before lifecycle role ${this.lifecycleRole} was restored`))
+            return
+          }
           this.state = "running"
           this.logger("process started", {command: this.command, id: this.id, pid: child.pid || null, reason})
           this.startMemoryMonitor()
@@ -148,17 +167,20 @@ export default class ManagedProcess extends EventEmitter {
       })
       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))
+      child.stdout.on("data", (chunk) => this.appendLog("stdout", chunk, outputBuffers))
+      child.stdout.on("end", () => this.flushLogBuffer("stdout", outputBuffers))
+      child.stderr.on("data", (chunk) => this.appendLog("stderr", chunk, outputBuffers))
+      child.stderr.on("end", () => this.flushLogBuffer("stderr", outputBuffers))
     })
   }
 
   /**
    * Updates the command template used for future restarts without touching the currently running child.
    * @param {ManagedProcessDefinition} definition - Replacement process definition.
-   * @returns {void}
+   * @param {import("./json.js").JsonValue} [_ownerState] - Private owner state committed atomically by remote implementations.
+   * @returns {void | Promise<void>} Definition replacement completion for remote implementations.
    */
-  updateDefinition(definition) {
+  updateDefinition(definition, _ownerState) {
     this.command = definition.command
     this.cwd = definition.cwd
     this.env = definition.env
@@ -176,10 +198,19 @@ export default class ManagedProcess extends EventEmitter {
   /**
    * @param {"stdout" | "stderr"} stream - Stream name.
    * @param {string} chunk - Output chunk.
+   * @param {{stderr: string, stdout: string}} [buffers] - Per-process stream fragments.
    * @returns {void}
    */
-  appendLog(stream, chunk) {
-    for (const line of String(chunk).split(/\r?\n/)) {
+  appendLog(stream, chunk, buffers = this.outputBuffers) {
+    const lines = `${buffers[stream]}${String(chunk)}`.split(/\r?\n/)
+    let fragment = lines.pop() ?? ""
+
+    while (fragment.length > MAX_BUFFERED_OUTPUT_CHARACTERS) {
+      lines.push(fragment.slice(0, MAX_BUFFERED_OUTPUT_CHARACTERS))
+      fragment = fragment.slice(MAX_BUFFERED_OUTPUT_CHARACTERS)
+    }
+    buffers[stream] = fragment
+    for (const line of lines) {
       if (!line) continue
 
       const entry = {at: new Date().toISOString(), line, stream}
@@ -193,6 +224,15 @@ export default class ManagedProcess extends EventEmitter {
     }
   }
 
+  /**
+   * Retains a final output line that did not end with a newline.
+   * @param {"stdout" | "stderr"} stream - Stream name.
+   * @param {{stderr: string, stdout: string}} buffers - Per-process stream fragments.
+   */
+  flushLogBuffer(stream, buffers) {
+    if (buffers[stream]) this.appendLog(stream, "\n", buffers)
+  }
+
   /**
    * @param {number | null} code - Exit code.
    * @param {ProcessExitSignal} signal - Exit signal.
@@ -375,6 +415,7 @@ export default class ManagedProcess extends EventEmitter {
    * @returns {Promise<void>} Resolves when stopped.
    */
   async stop(options = {}) {
+    this.operationRevision += 1
     if (!this.stopPromise) this.stopPromise = this.performStop(options)
     return await this.stopPromise
   }
@@ -442,6 +483,7 @@ export default class ManagedProcess extends EventEmitter {
         clearTimeout(this.restartTimer)
         this.restartTimer = undefined
       }
+      if (this.lifecycleRestoreBarrier) await this.lifecycleRestoreBarrier
       if (!this.child?.pid) {
         this.state = "stopped"
         if (this.lifecycle.activateCommand) this.lifecycleRole = "retired"
@@ -475,9 +517,14 @@ export default class ManagedProcess extends EventEmitter {
     const command = this.lifecycle.activateCommand
 
     if (!command) return
-    const error = await this.runHook(command, ACTIVATION_HOOK_TIMEOUT_MS, "activate command", this.pid)
+    const child = this.child
+    const pid = this.pid
+
+    if (!child?.pid || child.pid !== pid || this.state !== "running") throw new Error(`Process ${this.id} is not running for activation`)
+    const error = await this.runHook(command, ACTIVATION_HOOK_TIMEOUT_MS, "activate command", pid)
 
     if (error) throw error
+    if (this.child !== child || this.pid !== pid || this.state !== "running") throw new Error(`Process ${this.id} exited before activation completed`)
     this.lifecycleRole = "active"
   }