From 1564686791929a172827247ab490aed19bb2901a Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Sun, 25 Oct 2026 07:15:19 -0700 Subject: [PATCH] fix(cli): keep the service's XDG_STATE_HOME out of tool shells and name the port owner (#58815) --- packages/cli/src/server-process.ts | 6 +- packages/cli/src/services/port-owner.ts | 48 +++++++++++ packages/cli/src/services/service-config.ts | 11 ++- packages/cli/test/service-lifecycle.test.ts | 6 +- packages/cli/test/service.test.ts | 89 ++++++++++++++++++++- 5 files changed, 153 insertions(+), 7 deletions(-) create mode 100644 packages/cli/src/services/port-owner.ts diff --git a/packages/cli/src/server-process.ts b/packages/cli/src/server-process.ts index 1078218d91a..2f64e3ec7b8 100644 --- a/packages/cli/src/server-process.ts +++ b/packages/cli/src/server-process.ts @@ -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 ` and start the service again.", { cause: error }, ), diff --git a/packages/cli/src/services/port-owner.ts b/packages/cli/src/services/port-owner.ts new file mode 100644 index 00000000000..539632e6d83 --- /dev/null +++ b/packages/cli/src/services/port-owner.ts @@ -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) => + 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 +} diff --git a/packages/cli/src/services/service-config.ts b/packages/cli/src/services/service-config.ts index 8c389a51a7d..ae11239839e 100644 --- a/packages/cli/src/services/service-config.ts +++ b/packages/cli/src/services/service-config.ts @@ -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", diff --git a/packages/cli/test/service-lifecycle.test.ts b/packages/cli/test/service-lifecycle.test.ts index f0b0223e3d5..4af0a73c03d 100644 --- a/packages/cli/test/service-lifecycle.test.ts +++ b/packages/cli/test/service-lifecycle.test.ts @@ -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 ") expect(await servers(home)).toEqual([]) expect(await Bun.file(home.registration).exists()).toBe(false) diff --git a/packages/cli/test/service.test.ts b/packages/cli/test/service.test.ts index 400bc1e4c43..d69cfd86c60 100644 --- a/packages/cli/test/service.test.ts +++ b/packages/cli/test/service.test.ts @@ -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")