rollbridge 0.1.1

package/test/config-examples.test.js

@@ -0,0 +1,59 @@
+// @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 {fileURLToPath} from "node:url"
+import {loadConfig} from "../src/config.js"
+
+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]),
+    [
+      ["beacon", "service"],
+      ["background-jobs-main", "service"],
+      ["background-jobs-worker", "companion"],
+      ["web", "proxied"]
+    ]
+  )
+  assert.equal(config.processes[3].env.VELOCIOUS_BACKGROUND_JOBS_PORT, "{{ports.background-jobs-main}}")
+})
+
+test("loadConfig resolves a config module that exports a function", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-fn-config-"))
+  const configPath = path.join(dir, "rollbridge.js")
+  const moduleSource = [
+    "module.exports = () => ({",
+    "  application: process.env.ROLLBRIDGE_TEST_APP || \"fn-demo\",",
+    "  control: {path: \"/tmp/rollbridge-fn-demo.sock\"},",
+    "  proxy: {host: \"127.0.0.1\", port: 8190},",
+    "  processes: [{id: \"web\", policy: \"proxied\", command: \"run web\", port: {from: 18000, to: 18099}}]",
+    "})",
+    ""
+  ].join("\n")
+
+  await fs.writeFile(configPath, moduleSource)
+  process.env.ROLLBRIDGE_TEST_APP = "computed-app"
+
+  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")
+  } finally {
+    delete process.env.ROLLBRIDGE_TEST_APP
+    await fs.rm(dir, {force: true, recursive: true})
+  }
+})

package/test/config-path.test.js

@@ -0,0 +1,90 @@
+// @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 {resolveConfigPath} from "../src/config.js"
+import {runCli} from "../src/cli.js"
+
+const validConfig = {
+  application: "demo",
+  control: {path: "/tmp/rollbridge-config-path.sock"},
+  processes: [
+    {command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}
+  ],
+  proxy: {host: "127.0.0.1", port: 8182}
+}
+
+/**
+ * @param {string} dir - Directory to write the module into.
+ * @returns {Promise<string>} The written config module path.
+ */
+async function writeConfigModule(dir) {
+  const configPath = path.join(dir, "rollbridge.js")
+
+  // CommonJS so the module loads from a temp dir (no package.json) on any supported Node version.
+  await fs.writeFile(configPath, `module.exports = ${JSON.stringify(validConfig, null, 2)}\n`)
+
+  return configPath
+}
+
+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")
+  } finally {
+    await fs.rm(dir, {force: true, recursive: true})
+  }
+})
+
+test("resolveConfigPath resolves rollbridge.js in the working directory", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-cfgpath-"))
+
+  try {
+    await writeConfigModule(dir)
+
+    assert.equal(await resolveConfigPath(undefined, dir), path.join(dir, "rollbridge.js"))
+  } finally {
+    await fs.rm(dir, {force: true, recursive: true})
+  }
+})
+
+test("resolveConfigPath throws an actionable error when no default config exists", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-cfgpath-"))
+
+  try {
+    await assert.rejects(
+      () => resolveConfigPath(undefined, dir),
+      /No config file found.*rollbridge\.js/
+    )
+  } finally {
+    await fs.rm(dir, {force: true, recursive: true})
+  }
+})
+
+test("validate CLI command resolves the default config when --config is omitted", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-cfgpath-"))
+  const originalCwd = process.cwd()
+
+  await writeConfigModule(dir)
+
+  const originalLog = console.log
+  /** @type {string[]} */
+  const lines = []
+
+  console.log = (/** @type {string[]} */ ...args) => { lines.push(args.map((arg) => String(arg)).join(" ")) }
+
+  try {
+    process.chdir(dir)
+    await runCli(["node", "rollbridge", "validate"])
+  } finally {
+    console.log = originalLog
+    process.chdir(originalCwd)
+    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\./)
+})

package/test/config-validation.test.js

@@ -0,0 +1,156 @@
+// @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 {normalizeConfig, validateConfig} from "../src/config.js"
+import {runCli} from "../src/cli.js"
+
+test("validateConfig collects duplicate ids, proxied ports, and policy combinations", () => {
+  const {issues} = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [
+      {command: "run web", id: "web", policy: "proxied"},
+      {command: "run worker", id: "web", policy: "companion"}
+    ],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+  const messages = issues.map((issue) => issue.message)
+
+  assert.ok(messages.includes("Duplicate process id: web"), `expected duplicate id issue in ${JSON.stringify(messages)}`)
+  assert.ok(messages.includes("Proxied process web must define a port range"), `expected missing proxied port issue in ${JSON.stringify(messages)}`)
+  assert.ok(issues.every((issue) => typeof issue.fix === "string" && issue.fix.length > 0), "every issue should include an example fix")
+})
+
+test("validateConfig reports invalid ranges and missing proxied process without throwing", () => {
+  const {issues} = validateConfig({
+    application: "demo",
+    processes: [
+      {command: "run worker", id: "worker", policy: "companion", port: {from: 200, to: 100}}
+    ],
+    proxy: {port: 8182}
+  })
+  const messages = issues.map((issue) => issue.message)
+
+  assert.ok(messages.includes("processes[0].port must be a positive port or valid {from, to} range"), `expected invalid range issue in ${JSON.stringify(messages)}`)
+  assert.ok(messages.includes("Config must define exactly one proxied process; found 0"), `expected missing proxied process issue in ${JSON.stringify(messages)}`)
+})
+
+test("validateConfig returns a normalized config and no issues for a valid config", () => {
+  const {config, issues} = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [
+      {command: "run web", health: {path: "/ping"}, id: "web", policy: "proxied", port: {from: 18000, to: 18099}}
+    ],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  assert.deepEqual(issues, [])
+  assert.equal(config.processes.length, 1)
+  assert.equal(config.processes[0].policy, "proxied")
+  assert.equal(config.proxy.port, 8182)
+})
+
+test("normalizeConfig throws an aggregated error listing every issue", () => {
+  assert.throws(
+    () => normalizeConfig({
+      application: "demo",
+      processes: [
+        {command: "run web", id: "web", policy: "proxied"},
+        {command: "run web", id: "web", policy: "proxied"}
+      ],
+      proxy: {port: 8182}
+    }),
+    (error) => {
+      assert.ok(error instanceof Error)
+      assert.match(error.message, /Duplicate process id: web/)
+      assert.match(error.message, /exactly one proxied process; found 2/)
+
+      return true
+    }
+  )
+})
+
+test("validate CLI command reports every issue with a fix and exits non-zero", async () => {
+  const configPath = await writeConfig({
+    application: "demo",
+    processes: [
+      {command: "run web", id: "web", policy: "proxied"}
+    ],
+    proxy: {port: 8182}
+  })
+
+  try {
+    const {output} = await captureCli(["node", "rollbridge", "validate", "-c", configPath])
+
+    assert.equal(process.exitCode, 1)
+    assert.match(output, /Proxied process web must define a port range/)
+    assert.match(output, /Fix: Add a port range to the proxied process "web"/)
+  } finally {
+    process.exitCode = 0
+    await fs.rm(path.dirname(configPath), {force: true, recursive: true})
+  }
+})
+
+test("validate CLI command accepts a valid config without setting a failure exit code", async () => {
+  const configPath = await writeConfig({
+    application: "demo",
+    control: {path: "/tmp/rollbridge-cli-valid.sock"},
+    processes: [
+      {command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}
+    ],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  try {
+    const {output} = await captureCli(["node", "rollbridge", "validate", "-c", configPath])
+
+    assert.notEqual(process.exitCode, 1)
+    assert.match(output, /is valid: 1 process, proxy on 127\.0\.0\.1:8182\./)
+  } finally {
+    await fs.rm(path.dirname(configPath), {force: true, recursive: true})
+  }
+})
+
+/**
+ * @param {Record<string, import("../src/json.js").JsonValue>} config - Raw config object.
+ * @returns {Promise<string>} Path to the written config module.
+ */
+async function writeConfig(config) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-validate-"))
+  const configPath = path.join(dir, "rollbridge.js")
+
+  // CommonJS so the module loads from a temp dir (no package.json) on any supported Node version.
+  await fs.writeFile(configPath, `module.exports = ${JSON.stringify(config, null, 2)}\n`)
+
+  return configPath
+}
+
+/**
+ * Runs the CLI while capturing console output.
+ * @param {string[]} argv - Process argv.
+ * @returns {Promise<{output: string}>} Captured stdout and stderr lines joined by newlines.
+ */
+async function captureCli(argv) {
+  const originalLog = console.log
+  const originalError = console.error
+  /** @type {string[]} */
+  const lines = []
+  const collect = (/** @type {string[]} */ ...args) => { lines.push(args.map((arg) => String(arg)).join(" ")) }
+
+  console.log = collect
+  console.error = collect
+
+  try {
+    await runCli(argv)
+  } finally {
+    console.log = originalLog
+    console.error = originalError
+  }
+
+  return {output: lines.join("\n")}
+}

package/test/fixtures/dependent-app.js

@@ -0,0 +1,57 @@
+// @ts-check
+
+import http from "node:http"
+
+const port = Number(requiredEnv("ROLLBRIDGE_PORT"))
+const servicePort = Number(requiredEnv("ROLLBRIDGE_BEACON_PORT"))
+const releaseId = process.env.ROLLBRIDGE_RELEASE_ID || "unknown"
+
+await waitForService()
+
+const server = http.createServer((request, response) => {
+  if (request.url === "/ping") {
+    response.writeHead(200, {"Content-Type": "application/json"})
+    response.end(JSON.stringify({message: "Pong", releaseId}))
+    return
+  }
+
+  response.writeHead(200, {"Content-Type": "text/plain; charset=utf-8"})
+  response.end(`${releaseId}\n`)
+})
+
+process.on("SIGTERM", () => {
+  server.close(() => process.exit(0))
+})
+
+server.listen(port, "127.0.0.1")
+
+/** @returns {Promise<void>} Resolves when the service responds. */
+async function waitForService() {
+  const deadline = Date.now() + 3000
+
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(`http://127.0.0.1:${servicePort}/ping`)
+
+      if (response.ok) return
+    } catch (_error) {
+      // The dependency may still be binding its port.
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 25))
+  }
+
+  throw new Error("Service did not become ready")
+}
+
+/**
+ * @param {string} key - Environment variable name.
+ * @returns {string} Environment variable value.
+ */
+function requiredEnv(key) {
+  const value = process.env[key]
+
+  if (!value) throw new Error(`${key} is required`)
+
+  return value
+}

package/test/fixtures/dummy-app.js

@@ -0,0 +1,69 @@
+// @ts-check
+
+import crypto from "node:crypto"
+import http from "node:http"
+
+const port = Number(process.env.ROLLBRIDGE_PORT)
+const releaseId = process.env.ROLLBRIDGE_RELEASE_ID || "unknown"
+const healthFails = releaseId.includes("bad")
+const sockets = new Set()
+
+const server = http.createServer((request, response) => {
+  if (request.url === "/ping") {
+    if (healthFails) {
+      response.writeHead(500, {"Content-Type": "application/json"})
+      response.end(JSON.stringify({message: "bad release"}))
+      return
+    }
+
+    response.writeHead(200, {"Content-Type": "application/json"})
+    response.end(JSON.stringify({message: "Pong", releaseId}))
+    return
+  }
+
+  if (request.url === "/release") {
+    response.writeHead(200, {"Content-Type": "text/plain; charset=utf-8"})
+    response.end(`${releaseId}\n`)
+    return
+  }
+
+  response.writeHead(404, {"Content-Type": "text/plain; charset=utf-8"})
+  response.end("Not found\n")
+})
+
+server.on("upgrade", (request, socket) => {
+  const key = request.headers["sec-websocket-key"]
+
+  if (typeof key !== "string") {
+    socket.end("HTTP/1.1 400 Bad Request\r\n\r\n")
+    return
+  }
+
+  const accept = crypto
+    .createHash("sha1")
+    .update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
+    .digest("base64")
+
+  sockets.add(socket)
+  socket.once("close", () => sockets.delete(socket))
+  socket.on("data", () => {
+    socket.end()
+  })
+  socket.write([
+    "HTTP/1.1 101 Switching Protocols",
+    "Upgrade: websocket",
+    "Connection: Upgrade",
+    `Sec-WebSocket-Accept: ${accept}`,
+    "\r\n"
+  ].join("\r\n"))
+})
+
+process.on("SIGTERM", () => {
+  server.close(() => process.exit(0))
+
+  if (sockets.size === 0) {
+    setTimeout(() => process.exit(0), 10)
+  }
+})
+
+server.listen(port, "127.0.0.1")

package/test/fixtures/service-app.js

@@ -0,0 +1,42 @@
+// @ts-check
+
+import fs from "node:fs"
+import http from "node:http"
+
+const logPath = requiredEnv("ROLLBRIDGE_SERVICE_LOG")
+const port = Number(requiredEnv("ROLLBRIDGE_PORT"))
+const releaseId = process.env.ROLLBRIDGE_RELEASE_ID || "unknown"
+
+writeEvent("start")
+
+const server = http.createServer((_request, response) => {
+  response.writeHead(200, {"Content-Type": "application/json"})
+  response.end(JSON.stringify({releaseId}))
+})
+
+process.on("SIGTERM", () => {
+  writeEvent("stop")
+  server.close(() => process.exit(0))
+})
+
+server.listen(port, "127.0.0.1")
+
+/**
+ * @param {"start" | "stop"} event - Event.
+ * @returns {void}
+ */
+function writeEvent(event) {
+  fs.appendFileSync(logPath, `${JSON.stringify({event, pid: process.pid, releaseId})}\n`)
+}
+
+/**
+ * @param {string} key - Environment variable name.
+ * @returns {string} Environment variable value.
+ */
+function requiredEnv(key) {
+  const value = process.env[key]
+
+  if (!value) throw new Error(`${key} is required`)
+
+  return value
+}

package/test/fixtures/singleton-app.js

@@ -0,0 +1,35 @@
+// @ts-check
+
+import fs from "node:fs"
+
+const logPath = requiredEnv("ROLLBRIDGE_SINGLETON_LOG")
+const releaseId = process.env.ROLLBRIDGE_RELEASE_ID || "unknown"
+
+writeEvent("start")
+
+process.on("SIGTERM", () => {
+  writeEvent("stop")
+  setTimeout(() => process.exit(0), 50)
+})
+
+setInterval(() => {}, 1000)
+
+/**
+ * @param {"start" | "stop"} event - Event.
+ * @returns {void}
+ */
+function writeEvent(event) {
+  fs.appendFileSync(logPath, `${JSON.stringify({event, pid: process.pid, releaseId})}\n`)
+}
+
+/**
+ * @param {string} key - Environment variable name.
+ * @returns {string} Environment variable value.
+ */
+function requiredEnv(key) {
+  const value = process.env[key]
+
+  if (!value) throw new Error(`${key} is required`)
+
+  return value
+}

package/test/port-allocator.test.js

@@ -0,0 +1,76 @@
+// @ts-check
+
+import assert from "node:assert/strict"
+import net from "node:net"
+import test from "node:test"
+import {findAvailablePort} from "../src/port-allocator.js"
+
+const host = "127.0.0.1"
+
+/**
+ * Binds a server to an ephemeral port so that port is occupied for the test.
+ * @returns {Promise<{port: number, server: import("node:net").Server}>} Occupied port and its server.
+ */
+async function occupyPort() {
+  const server = net.createServer()
+  const port = await new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(0, host, () => {
+      const address = server.address()
+
+      resolve(address && typeof address === "object" ? address.port : 0)
+    })
+  })
+
+  return {port, server}
+}
+
+/**
+ * @param {import("node:net").Server} server - Server to close.
+ * @returns {Promise<void>} Resolves once closed.
+ */
+async function closeServer(server) {
+  await new Promise((resolve) => server.close(() => resolve(undefined)))
+}
+
+test("findAvailablePort reports reserved and in-use counts when a range is exhausted", async () => {
+  const {port, server} = await occupyPort()
+  // Use the occupied port as the upper bound so the range stays within valid TCP bounds.
+  const reservedPort = port - 1
+  const range = {from: reservedPort, to: port}
+
+  try {
+    await assert.rejects(
+      () => findAvailablePort({host, range, usedPorts: new Set([reservedPort])}),
+      (error) => {
+        assert.ok(error instanceof Error)
+        assert.match(error.message, new RegExp(`No available ports in range ${reservedPort}-${port}`))
+        assert.match(error.message, /2 ports on 127\.0\.0\.1/)
+        assert.match(error.message, /1 reserved by this deploy/)
+        assert.match(error.message, /1 already in use/)
+
+        return true
+      }
+    )
+  } finally {
+    await closeServer(server)
+  }
+})
+
+test("findAvailablePort skips the occupied port and records the allocated one", async () => {
+  const {port, server} = await occupyPort()
+  const usedPorts = /** @type {Set<number>} */ (new Set())
+  // Keep the upper bound at or below 65535 while still including the occupied port.
+  const from = Math.min(port, 65515)
+  const to = from + 20
+
+  try {
+    const allocated = await findAvailablePort({host, range: {from, to}, usedPorts})
+
+    assert.notEqual(allocated, port)
+    assert.ok(allocated >= from && allocated <= to)
+    assert.ok(usedPorts.has(allocated))
+  } finally {
+    await closeServer(server)
+  }
+})