fix(cli): keep the service's XDG_STATE_HOME out of tool shells and name the port owner (#58815)

This commit is contained in:
Kit Langton
2026-10-25 07:15:19 -07:00
committed by GitHub
Unverified
parent 585b5a449d
commit 1564686791
5 changed files with 153 additions and 7 deletions
+4 -2
View File
@@ -12,6 +12,7 @@ import { PersistentPty } from "@opencode/schema/persistent-pty"
import { HttpServer } from "effect/http"
import { NetAddress } from "effect/net"
import { Env } from "./env"
import { PortOwner } from "./services/port-owner"
import { ServiceConfig } from "./services/service-config"
import { RetainedImage } from "./services/retained-image"
import { ServiceRegistration } from "./services/service-registration"
@@ -76,7 +77,7 @@ const processEffect = Effect.fnUntraced(function* (options: Options) {
: undefined
if (findIncumbent !== undefined && (yield* findIncumbent) !== undefined) return
// Desktop can launch the service directly without injecting its saved environment.
Object.assign(process.env, config.env)
Object.assign(process.env, ServiceConfig.processEnv(config.env))
// Keep a package-manager or curl install replaceable while the service runs; Desktop updates its own copy.
if (options.mode === "service" && process.platform === "win32" && RetainedImage.installed(global.home))
yield* RetainedImage.retain(global.cache, "service")
@@ -174,9 +175,10 @@ const processEffect = Effect.fnUntraced(function* (options: Options) {
const server = yield* launch.pipe(Effect.catchIf(addressInUse, () => Effect.void))
if (server !== undefined) return server
}
const owner = port === undefined ? undefined : yield* PortOwner.describe(port, hostname)
return yield* Effect.fail(
new Error(
`Managed service port ${port} on ${hostname} is already in use by another process. ` +
`Managed service port ${port} on ${hostname} is already in use by ${owner ?? "another process"}. ` +
"Configure another port with `opencode service set port <port>` and start the service again.",
{ cause: error },
),
+48
View File
@@ -0,0 +1,48 @@
import { AppProcess } from "@opencode/util/process"
import { Effect } from "effect"
import { ChildProcess } from "effect/process"
import net from "node:net"
export * as PortOwner from "./port-owner"
// Best effort: names the process listening on a TCP port so a failed bind can say who holds it.
// Windows has no cheap equivalent of lsof, so it keeps the generic message.
export const describe = Effect.fnUntraced(function* (port: number, hostname?: string) {
if (process.platform === "win32") return undefined
const appProcess = yield* AppProcess.Service
const run = (command: string, args: ReadonlyArray<string>) =>
appProcess
.run(ChildProcess.make(command, args, { stdin: "ignore", killSignal: "SIGKILL" }), {
timeout: "1 second",
maxOutputBytes: 4096,
})
.pipe(
Effect.map((result) => (result.exitCode === 0 ? result.stdout.toString("utf8").trim() : "")),
Effect.orElseSucceed(() => ""),
)
const pid = listeners(yield* run("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-Fpn"])).find((listener) =>
matches(listener.address, hostname),
)?.pid
if (pid === undefined) return undefined
const command = (yield* run("ps", ["-o", "command=", "-p", pid])).replace(/\s+/g, " ")
if (!command) return `PID ${pid}`
return `PID ${pid} (${command.length > 200 ? command.slice(0, 199) + "…" : command})`
})
function listeners(output: string) {
const found: { pid: string; address: string }[] = []
let pid: string | undefined
for (const line of output.split("\n")) {
if (line.startsWith("p")) pid = /^\d+$/.test(line.slice(1)) ? line.slice(1) : undefined
if (line.startsWith("n") && pid !== undefined)
found.push({ pid, address: line.slice(1, line.lastIndexOf(":")).replace(/^\[(.*)\]$/, "$1") })
}
return found
}
// lsof shows wildcard listeners as `*`; those also hold the port for any specific address.
function matches(address: string, hostname: string | undefined) {
const host = hostname?.replace(/^\[(.*)\]$/, "$1")
if (host === undefined || net.isIP(host) === 0 || host === "0.0.0.0" || host === "::") return true
return address === "*" || address === host
}
+10 -1
View File
@@ -131,13 +131,22 @@ const paths = Effect.gen(function* () {
}
})
// Clients find the service at its registration under XDG_STATE_HOME. A saved value would move the
// registration away from them, and children of the service (tool shells, a relaunched Desktop) would
// look for it in the wrong place, so the service keeps the state directory it was launched with.
export function processEnv(env: Info["env"]) {
if (env === undefined) return undefined
const { XDG_STATE_HOME: _state, ...rest } = env
return rest
}
export const options = Effect.fnUntraced(function* (input: { readonly checkVersion?: boolean } = {}) {
const { file, legacyRegistrationFiles } = yield* paths
yield* Effect.forEach(legacyRegistrationFiles, (legacy) => migrateRegistration(legacy, file))
return {
file,
version: input.checkVersion ? OPENCODE_VERSION : undefined,
env: (yield* read()).env,
env: processEnv((yield* read()).env),
command: [
...selfCommand(),
"serve",
+5 -1
View File
@@ -116,7 +116,11 @@ serviceTest(
() => undefined,
(error: Error) => error.message,
)
expect(conflict).toContain(`Managed service port ${home.port} on 127.0.0.1 is already in use by another process`)
expect(conflict).toContain(
`Managed service port ${home.port} on 127.0.0.1 is already in use by ${
process.platform !== "win32" && Bun.which("lsof") ? `PID ${process.pid} (` : "another process"
}`,
)
expect(conflict).toContain("opencode service set port <port>")
expect(await servers(home)).toEqual([])
expect(await Bun.file(home.registration).exists()).toBe(false)
+86 -3
View File
@@ -10,6 +10,9 @@ import { TestClock } from "effect/testing"
import fs from "node:fs/promises"
import os from "node:os"
import path from "node:path"
import { LayerNode } from "@opencode/util/effect/layer-node"
import { AppProcess } from "@opencode/util/process"
import { PortOwner } from "../src/services/port-owner"
import { ServiceConfig } from "../src/services/service-config"
import { ServiceRegistration } from "../src/services/service-registration"
import { isolatedEnv, transpilerCache } from "./fixture/environment"
@@ -192,6 +195,72 @@ test("service config manages environment variables", async () => {
}
})
test("saved service environment cannot move the registration's state directory", async () => {
expect(ServiceConfig.processEnv(undefined)).toBeUndefined()
expect(ServiceConfig.processEnv({ XDG_STATE_HOME: "/custom/state", XDG_DATA_HOME: "/custom/data", A: "1" })).toEqual({
XDG_DATA_HOME: "/custom/data",
A: "1",
})
const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-service-env-state-"))
const layer = Global.layerWith({ config: path.join(root, "config"), state: path.join(root, "state") })
try {
await fs.mkdir(path.join(root, "config"), { recursive: true })
await Bun.write(
path.join(root, "config", ServiceConfig.filename()),
JSON.stringify({ env: { XDG_STATE_HOME: path.join(root, "elsewhere"), A: "1" } }),
)
const options = await Effect.runPromise(
ServiceConfig.options().pipe(Effect.provide(layer), Effect.provide(NodeFileSystem.layer)),
)
expect(options.env).toEqual({ A: "1" })
expect(options.file).toBe(path.join(root, "state", ServiceConfig.filename()))
} finally {
await fs.rm(root, { recursive: true, force: true })
}
})
test.skipIf(process.platform === "win32" || !Bun.which("lsof"))("port owner names the listening process", async () => {
using listener = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: () => new Response() })
using wildcard = Bun.serve({ hostname: "0.0.0.0", port: 0, fetch: () => new Response() })
const describe = (port: number | undefined, hostname?: string) =>
Effect.runPromise(PortOwner.describe(port ?? 0, hostname).pipe(Effect.provide(LayerNode.compile(AppProcess.node))))
expect(await describe(listener.port)).toStartWith(`PID ${process.pid} (`)
expect(await describe(listener.port, "127.0.0.1")).toStartWith(`PID ${process.pid} (`)
expect(await describe(listener.port, "localhost")).toStartWith(`PID ${process.pid} (`)
expect(await describe(listener.port, "127.0.0.2")).toBeUndefined()
expect(await describe(wildcard.port, "127.0.0.2")).toStartWith(`PID ${process.pid} (`)
})
test.skipIf(process.platform === "win32")("port owner gives up on a lookup that ignores SIGTERM", async () => {
const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-port-owner-stuck-"))
const PATH = process.env.PATH
try {
await Bun.write(path.join(root, "lsof"), "#!/bin/sh\ntrap '' TERM\nsleep 10\n")
await fs.chmod(path.join(root, "lsof"), 0o755)
process.env.PATH = `${root}${path.delimiter}${PATH}`
const started = Date.now()
const owner = await Promise.race([
Effect.runPromise(PortOwner.describe(1).pipe(Effect.provide(LayerNode.compile(AppProcess.node)))),
Bun.sleep(4_000).then(() => "hung"),
])
expect(owner).toBeUndefined()
expect(Date.now() - started).toBeLessThan(3_000)
} finally {
process.env.PATH = PATH
await fs.rm(root, { recursive: true, force: true })
}
})
test.skipIf(process.platform === "win32")("port owner is unknown for a free port", async () => {
const free = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: () => new Response() })
const port = free.port ?? 0
free.stop(true)
expect(
await Effect.runPromise(PortOwner.describe(port).pipe(Effect.provide(LayerNode.compile(AppProcess.node)))),
).toBeUndefined()
})
test("service filenames share release channels and identify preview channels", () => {
expect(ServiceConfig.filename("latest")).toBe("service.json")
expect(ServiceConfig.filename("dev")).toBe("service.json")
@@ -548,7 +617,7 @@ test("unresponsive managed port occupancy reports a bounded conflict", async ()
await fs.mkdir(path.dirname(registration), { recursive: true })
await fs.writeFile(
path.join(root, "config", "opencode", "service-local.json"),
JSON.stringify({ port: listener.port }),
JSON.stringify({ port: listener.port, env: { XDG_STATE_HOME: path.join(root, "elsewhere") } }),
)
const stale = {
id: "stale",
@@ -558,8 +627,17 @@ test("unresponsive managed port occupancy reports a bounded conflict", async ()
password: "stale",
}
await fs.writeFile(registration, JSON.stringify(stale))
// The port lookup is a child of the service, so it shows the state directory tools would inherit.
const lsof = process.platform === "win32" ? null : Bun.which("lsof")
if (lsof) {
await Bun.write(
path.join(root, "bin", "lsof"),
`#!/bin/sh\nprintf %s "$XDG_STATE_HOME" > "${path.join(root, "inherited-state")}"\nexec "${lsof}" "$@"\n`,
)
await fs.chmod(path.join(root, "bin", "lsof"), 0o755)
}
const contender = Bun.spawn([process.execPath, path.join(import.meta.dir, "../src/index.ts"), "serve", "--service"], {
env: serviceEnv(root),
env: { ...serviceEnv(root), PATH: `${path.join(root, "bin")}${path.delimiter}${process.env.PATH}` },
stderr: "pipe",
stdout: "pipe",
})
@@ -569,7 +647,12 @@ test("unresponsive managed port occupancy reports a bounded conflict", async ()
const exitCode = await Promise.race([contender.exited, Bun.sleep(20_000).then(() => undefined)])
expect(exitCode).toBe(1)
const output = (await new Response(contender.stdout).text()) + (await new Response(contender.stderr).text())
expect(output).toContain(`Managed service port ${listener.port} on 127.0.0.1 is already in use by another process`)
expect(output).toContain(
`Managed service port ${listener.port} on 127.0.0.1 is already in use by ${
lsof ? `PID ${process.pid} (` : "another process"
}`,
)
if (lsof) expect(await Bun.file(path.join(root, "inherited-state")).text()).toBe(path.join(root, "state"))
expect(await Bun.file(registration).json()).toEqual(stale)
} finally {
contender.kill("SIGTERM")