rollbridge 0.1.54 → 0.1.56

package/AGENTS.md

@@ -61,6 +61,11 @@ external-supervisor migration path, not that atomic handoff.
 
 ## Validation and publication
 
+All tests use `@velocious/testing` declarations, hooks, and `expect` matchers.
+Do not import `node:test` or `node:assert`, or add assertion compatibility wrappers.
+Run every changed test file locally with `npx --no-install velocious-test test/<name>.test.js`
+and require it to pass before committing or pushing; lint or CI is not a substitute.
+
 The project is ESM JavaScript with JSDoc type checking. Package scripts are the
 source of truth: `npm run typecheck`, `npm run lint`, `npm test`, and the combined
 `npm run all-checks`. Run focused checks for the files changed; documentation-only

package/changelog.d/20260909120000-velocious-testing.md

@@ -0,0 +1 @@
+- Migrated all Rollbridge tests to `@velocious/testing` declarations, lifecycle APIs, and native `expect` matchers. Lint now rejects Node test and assertion imports in tests.

package/changelog.d/20261008-stale-stopped-connection-count.md

@@ -0,0 +1,14 @@
+### Fixed
+
+- Stopped releases no longer carry a stale connection count into owner
+  replacement. When a drain times out the release's local connection count was
+  frozen non-zero, persisted into the daemon state, and replayed into every
+  successor daemon's owner-replace handoff. The successor daemon does not
+  retain the stopped release, so the replay failed the candidate with
+  `Incumbent listener reported unknown release <id>` and deadlocked every
+  subsequent deployment. A release that reaches terminal `stopped` now
+  abandons its local connection count (it owns no live proxy listener),
+  `restore()` no longer re-adopts a persisted count for a stopped release,
+  the serialized owner handoff skips stopped releases, and a non-zero report
+  for a release the daemon does not retain is reconciled to zero with a log
+  line instead of throwing, so a stale count can never wedge the node again.

package/eslint.config.js

@@ -81,6 +81,14 @@ export default defineConfig([
       "no-unused-vars": ["error", {argsIgnorePattern: "^_", varsIgnorePattern: "^_", caughtErrorsIgnorePattern: "^_"}]
     }
   },
+  {
+    files: ["test/**/*.js"],
+    rules: {
+      "no-restricted-imports": ["error", {
+        patterns: [{group: ["node:test", "node:test/*", "test", "node:assert", "node:assert/*", "assert", "assert/*"], message: "Use @velocious/testing declarations and expect matchers."}]
+      }]
+    }
+  },
   jsdoc({
     config: "flat/recommended",
     files: ["**/*.{js,mjs,cjs}", "**/bin/rollbridge"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rollbridge",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "description": "Zero-downtime process supervisor and local traffic switcher for deploy-managed apps.",
   "keywords": [
     "deploy",
@@ -29,7 +29,7 @@
     "all-checks": "npm run typecheck && npm run lint && npm test",
     "lint": "npm run eslint && npm run typecheck",
     "release:patch": "release-patch",
-    "test": "node --test test/*.test.js",
+    "test": "velocious-test test/*.test.js",
     "typecheck": "tsc --noEmit",
     "eslint": "eslint"
   },
@@ -44,6 +44,7 @@
     "@eslint/js": "^10.0.1",
     "@types/http-proxy": "^1.17.17",
     "@types/node": "^25.9.1",
+    "@velocious/testing": "^0.0.12",
     "eslint": "^10.4.0",
     "eslint-plugin-jsdoc": "^62.9.0",
     "globals": "^17.6.0",

package/src/daemon.js

@@ -832,7 +832,22 @@ export default class RollbridgeDaemon {
   setListenerConnectionSource(sourceId, releaseId, connections) {
     const release = this.releases.get(releaseId)
 
-    if (!release && (connections.http > 0 || connections.websocket > 0)) throw new Error(`Incumbent listener reported unknown release ${releaseId}`)
+    if (!release) {
+      if (connections.http + connections.websocket > 0) {
+        // A live proxy connection is always attributed to a release that still listens. A
+        // non-zero report for a release this daemon does not retain is a stale count frozen by
+        // a drain timeout in an earlier owner; accounting for it here would deadlock every
+        // future handoff, so reconcile it to zero instead of failing the owner replacement.
+        this.logger("dropping stale connection state for unretained release", {connections, releaseId, sourceId})
+      }
+      const sourceReleases = this.listenerConnectionSources.get(sourceId)
+
+      if (sourceReleases) {
+        sourceReleases.delete(releaseId)
+        if (sourceReleases.size === 0) this.listenerConnectionSources.delete(sourceId)
+      }
+      return
+    }
     const sourceReleases = this.listenerConnectionSources.get(sourceId) || new Map()
 
     if (connections.http + connections.websocket === 0) sourceReleases.delete(releaseId)
@@ -855,10 +870,23 @@ export default class RollbridgeDaemon {
 
   /** @returns {Record<string, Record<string, {http: number, websocket: number}>>} Exact live listener sources. */
   serializedListenerConnectionSources() {
-    const sources = new Map([...this.listenerConnectionSources].map(([sourceId, releases]) => [sourceId, new Map(releases)]))
+    const sources = new Map()
+
+    for (const [sourceId, releases] of this.listenerConnectionSources) {
+      const retained = new Map()
+
+      for (const [releaseId, connections] of releases) {
+        // A stopped release owns no live listener; its count is a stale drain timeout. Carrying
+        // it into a successor daemon would report a connection the successor cannot attribute.
+        if (this.releases.get(releaseId)?.state === "stopped") continue
+        retained.set(releaseId, connections)
+      }
+      if (retained.size > 0) sources.set(sourceId, retained)
+    }
     const local = new Map()
 
     for (const release of this.releases.values()) {
+      if (release.state === "stopped") continue
       const connections = release.localConnections()
 
       if (connections.http + connections.websocket > 0) local.set(release.releaseId, connections)

package/src/release-group.js

@@ -196,7 +196,9 @@ export default class ReleaseGroup extends EventEmitter {
     this.drainStartedAt = snapshot.drainStartedAt
     this.retirementError = snapshot.retirementError
     this.stoppedAt = snapshot.stoppedAt
-    this.setTransferredConnections(snapshot.connections)
+    // A stopped release no longer owns a proxy listener, so a persisted nonzero count is a
+    // stale drain timeout; re-adopting it would poison this daemon's handoff to the next one.
+    if (snapshot.state !== "stopped") this.setTransferredConnections(snapshot.connections)
 
     for (const processStatus of snapshot.processes) {
       const baseId = processStatus.id.replace(/#\d+$/, "")
@@ -625,6 +627,22 @@ export default class ReleaseGroup extends EventEmitter {
     }
   }
 
+  /**
+   * Abandons every connection this daemon still counts for the release. A release that
+   * reaches terminal `stopped` owns no live proxy listener, so any remaining local count
+   * is a stale drain timeout. Clearing it here (rather than relying on each in-flight
+   * connection to release) keeps the invariant "a stopped release holds no connections"
+   * intact for state persistence, owner-replacement handoff, and future daemons.
+   */
+  abandonLocalConnections() {
+    if (this.state !== "stopped") return
+    if (this.connectionCount === 0 && this.transferredConnections.http + this.transferredConnections.websocket === 0) return
+    this.connections = {http: 0, websocket: 0}
+    this.transferredConnections = {http: 0, websocket: 0}
+    this.connectionCount = 0
+    this.emit("drained")
+  }
+
   /**
    * Reconciles connections still owned by a prior daemon listener.
    * @param {ReleaseConnections} connections - Exact incumbent listener counts.
@@ -721,6 +739,7 @@ export default class ReleaseGroup extends EventEmitter {
     this.state = "stopped"
     this.stoppedAt = new Date().toISOString()
     this.releasePortReservations()
+    this.abandonLocalConnections()
   }
 
   /**
@@ -763,6 +782,7 @@ export default class ReleaseGroup extends EventEmitter {
     this.state = "stopped"
     this.stoppedAt = new Date().toISOString()
     this.releasePortReservations()
+    this.abandonLocalConnections()
   }
 
   /** @returns {Promise<void>} Quiesces every release process without waiting for its drain. */

package/test/completion.test.js

@@ -1,9 +1,10 @@
 // @ts-check
 
-import assert from "node:assert/strict"
-import test from "node:test"
+import {describe, expect, test} from "@velocious/testing"
 import {runCli} from "../src/cli.js"
 
+describe("completion", () => {
+
 /**
  * Runs the CLI while capturing stdout, stderr, and the resulting exit code.
  * @param {string[]} argv - Process argv.
@@ -39,29 +40,30 @@ async function capture(argv) {
 test("completion bash prints a sourceable script with commands and option flags", async () => {
   const {code, output} = await capture(["node", "rollbridge", "completion", "bash"])
 
-  assert.notEqual(code, 1)
-  assert.match(output, /complete -F _rollbridge rollbridge/)
-  assert.match(output, /compgen -W "daemon deploy rollback recover-generation-transition ensure-daemon status stop restart shutdown validate doctor logs events predeploy-cleanup recover completion"/)
+  expect(code).not.toBe(1)
+  expect(output).toMatch(/complete -F _rollbridge rollbridge/)
+  expect(output).toMatch(/compgen -W "daemon deploy rollback recover-generation-transition ensure-daemon status stop restart shutdown validate doctor logs events predeploy-cleanup recover completion"/)
   // A command's own options are completed after the command.
-  assert.match(output, /deploy\)\n\s+opts="[^"]*--release-path[^"]*"/)
-  assert.match(output, /recover-generation-transition\)\n\s+opts="--config --release-path --release-id --revision --previous-release-id --accept-retired-incumbent"/)
-  assert.match(output, /ensure-daemon\)\n\s+opts="[^"]*--daemon-runtime-path[^"]*"/)
-  assert.match(output, /restart\)\n\s+opts="[^"]*--policy[^"]*"/)
+  expect(output).toMatch(/deploy\)\n\s+opts="[^"]*--release-path[^"]*"/)
+  expect(output).toMatch(/recover-generation-transition\)\n\s+opts="--config --release-path --release-id --revision --previous-release-id --accept-retired-incumbent"/)
+  expect(output).toMatch(/ensure-daemon\)\n\s+opts="[^"]*--daemon-runtime-path[^"]*"/)
+  expect(output).toMatch(/restart\)\n\s+opts="[^"]*--policy[^"]*"/)
 })
 
 test("completion zsh prints a #compdef script with per-command options", async () => {
   const {output} = await capture(["node", "rollbridge", "completion", "zsh"])
 
-  assert.match(output, /^#compdef rollbridge/)
-  assert.match(output, /compdef _rollbridge rollbridge/)
-  assert.match(output, /commands=\(daemon deploy rollback recover-generation-transition ensure-daemon status stop restart shutdown validate doctor logs events predeploy-cleanup recover completion\)/)
-  assert.match(output, /recover-generation-transition\) compadd -- --config --release-path --release-id --revision --previous-release-id --accept-retired-incumbent/)
-  assert.match(output, /events\) compadd -- [^\n]*--limit/)
+  expect(output).toMatch(/^#compdef rollbridge/)
+  expect(output).toMatch(/compdef _rollbridge rollbridge/)
+  expect(output).toMatch(/commands=\(daemon deploy rollback recover-generation-transition ensure-daemon status stop restart shutdown validate doctor logs events predeploy-cleanup recover completion\)/)
+  expect(output).toMatch(/recover-generation-transition\) compadd -- --config --release-path --release-id --revision --previous-release-id --accept-retired-incumbent/)
+  expect(output).toMatch(/events\) compadd -- [^\n]*--limit/)
 })
 
 test("completion rejects an unsupported shell with a non-zero exit code", async () => {
   const {code, errorOutput} = await capture(["node", "rollbridge", "completion", "fish"])
 
-  assert.equal(code, 1)
-  assert.match(errorOutput, /Unsupported shell "fish"\. Supported shells: bash, zsh\./)
+  expect(code).toBe(1)
+  expect(errorOutput).toMatch(/Unsupported shell "fish"\. Supported shells: bash, zsh\./)
+})
 })

package/test/config-examples.test.js

@@ -1,34 +1,32 @@
 // @ts-check
 
-import assert from "node:assert/strict"
 import fs from "node:fs/promises"
 import os from "node:os"
 import path from "node:path"
-import test from "node:test"
+import {describe, expect, test} from "@velocious/testing"
 import {fileURLToPath} from "node:url"
 import {loadConfig} from "../src/config.js"
 
+describe("config-examples", () => {
+
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
 
 test("TensorBuzz example config loads", async () => {
   const config = await loadConfig(path.join(repoRoot, "examples", "tensorbuzz.com.js"))
 
-  assert.equal(config.application, "tensorbuzz")
-  assert.equal(config.control.path, "/tmp/rollbridge-tensorbuzz.sock")
-  assert.equal(config.proxy.host, "127.0.0.1")
-  assert.equal(config.proxy.port, 4500)
-  assert.equal(config.proxy.healthPath, "/ping")
-  assert.deepEqual(
-    config.processes.map((processConfig) => [processConfig.id, processConfig.policy]),
-    [
+  expect(config.application).toBe("tensorbuzz")
+  expect(config.control.path).toBe("/tmp/rollbridge-tensorbuzz.sock")
+  expect(config.proxy.host).toBe("127.0.0.1")
+  expect(config.proxy.port).toBe(4500)
+  expect(config.proxy.healthPath).toBe("/ping")
+  expect(config.processes.map((processConfig) => [processConfig.id, processConfig.policy])).toEqual([
       ["beacon", "service"],
       ["background-jobs-main", "service"],
       ["background-jobs-worker", "companion"],
       ["web", "proxied"]
-    ]
-  )
-  assert.equal(config.processes[2].lifecycle.reactivateCommand, "appctl jobs-worker-reactivate --pid $ROLLBRIDGE_PID")
-  assert.equal(config.processes[3].env.VELOCIOUS_BACKGROUND_JOBS_PORT, "{{ports.background-jobs-main}}")
+    ])
+  expect(config.processes[2].lifecycle.reactivateCommand).toBe("appctl jobs-worker-reactivate --pid $ROLLBRIDGE_PID")
+  expect(config.processes[3].env.VELOCIOUS_BACKGROUND_JOBS_PORT).toBe("{{ports.background-jobs-main}}")
 })
 
 test("loadConfig resolves a config module that exports a function", async () => {
@@ -50,11 +48,12 @@ test("loadConfig resolves a config module that exports a function", async () =>
   try {
     const config = await loadConfig(configPath)
 
-    assert.equal(config.application, "computed-app")
-    assert.equal(config.proxy.port, 8190)
-    assert.equal(config.processes[0].id, "web")
+    expect(config.application).toBe("computed-app")
+    expect(config.proxy.port).toBe(8190)
+    expect(config.processes[0].id).toBe("web")
   } finally {
     delete process.env.ROLLBRIDGE_TEST_APP
     await fs.rm(dir, {force: true, recursive: true})
   }
 })
+})

package/test/config-path.test.js

@@ -1,13 +1,14 @@
 // @ts-check
 
-import assert from "node:assert/strict"
 import fs from "node:fs/promises"
 import os from "node:os"
 import path from "node:path"
-import test from "node:test"
+import {describe, expect, test} from "@velocious/testing"
 import {loadConfig, resolveConfigPath} from "../src/config.js"
 import {runCli} from "../src/cli.js"
 
+describe("config-path", () => {
+
 const validConfig = {
   application: "demo",
   control: {path: "/tmp/rollbridge-config-path.sock"},
@@ -34,7 +35,7 @@ test("resolveConfigPath returns an explicit path unchanged", async () => {
   const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-cfgpath-"))
 
   try {
-    assert.equal(await resolveConfigPath("/somewhere/custom.js", dir), "/somewhere/custom.js")
+    expect(await resolveConfigPath("/somewhere/custom.js", dir)).toBe("/somewhere/custom.js")
   } finally {
     await fs.rm(dir, {force: true, recursive: true})
   }
@@ -46,7 +47,7 @@ test("resolveConfigPath resolves rollbridge.js in the working directory", async
   try {
     await writeConfigModule(dir)
 
-    assert.equal(await resolveConfigPath(undefined, dir), path.join(dir, "rollbridge.js"))
+    expect(await resolveConfigPath(undefined, dir)).toBe(path.join(dir, "rollbridge.js"))
   } finally {
     await fs.rm(dir, {force: true, recursive: true})
   }
@@ -56,10 +57,7 @@ test("resolveConfigPath throws an actionable error when no default config exists
   const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-cfgpath-"))
 
   try {
-    await assert.rejects(
-      () => resolveConfigPath(undefined, dir),
-      /No config file found.*rollbridge\.js/
-    )
+    await expect(resolveConfigPath(undefined, dir)).rejects.toThrow(/No config file found.*rollbridge\.js/)
   } finally {
     await fs.rm(dir, {force: true, recursive: true})
   }
@@ -70,11 +68,11 @@ test("loadConfig reloads a changed CommonJS module", async () => {
   const configPath = await writeConfigModule(dir)
 
   try {
-    assert.equal((await loadConfig(configPath)).application, "demo")
+    expect((await loadConfig(configPath)).application).toBe("demo")
 
     await fs.writeFile(configPath, `module.exports = ${JSON.stringify({...validConfig, application: "updated"}, null, 2)}\n`)
 
-    assert.equal((await loadConfig(configPath)).application, "updated")
+    expect((await loadConfig(configPath)).application).toBe("updated")
   } finally {
     await fs.rm(dir, {force: true, recursive: true})
   }
@@ -101,5 +99,6 @@ test("validate CLI command resolves the default config when --config is omitted"
     await fs.rm(dir, {force: true, recursive: true})
   }
 
-  assert.match(lines.join("\n"), /rollbridge\.js is valid: 1 process, proxy on 127\.0\.0\.1:8182\./)
+  expect(lines.join("\n")).toMatch(/rollbridge\.js is valid: 1 process, proxy on 127\.0\.0\.1:8182\./)
+})
 })