TypeScript
fix(server): WSL servers avoid ports already used by Windows (#22962)
Tyler Jenningsef99d3f26ffb
diff --git a/apps/server/src/cli/automaticPort.test.ts b/apps/server/src/cli/automaticPort.test.tsnew file mode 100644index 00000000000..1f780556974--- /dev/null+++ b/apps/server/src/cli/automaticPort.test.ts@@ -0,0 +1,165 @@+import { describe, expect, it } from "@effect/vitest";+import * as NetService from "@t3tools/shared/Net";+import * as Effect from "effect/Effect";+import * as CliError from "effect/cli/CliError";+import * as FileSystem from "effect/FileSystem";+import * as Layer from "effect/Layer";+import * as PlatformError from "effect/PlatformError";+import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";++import * as ProcessRunner from "../processRunner.ts";+import * as AutomaticPort from "./automaticPort.ts";++const WSL_KERNEL = "6.6.87.2-microsoft-standard-WSL2\n";+const NETSTAT_PATH = "/windows/c/Windows/System32/netstat.exe";++const output = (stdout: string, code: number | null = null): ProcessRunner.ProcessRunOutput => ({+ stdout,+ stderr: "",+ code: code === null ? null : ChildProcessSpawner.ExitCode(code),+ timedOut: false,+ stdoutTruncated: false,+ stderrTruncated: false,+ stdoutInvalidUtf8: false,+ stderrInvalidUtf8: false,+});++const listening = (ports: ReadonlyArray<number>, host = "127.0.0.1", foreign = "0.0.0.0:0") =>+ ports.map((port) => ` TCP ${host}:${port} ${foreign} ABHÖREN 4242`).join("\r\n");++interface Scenario {+ readonly kernelRelease?: string;+ readonly windowsPorts?: ReadonlyArray<number>;+ readonly windowsPortsV6?: ReadonlyArray<number>;+ readonly tcpv6ExitCode?: number;+ readonly wslpathMissing?: boolean;+ readonly reservedPorts?: ReadonlyArray<number>;+}++const select = (scenario: Scenario) => {+ const commands: string[] = [];+ const reserved = [...(scenario.reservedPorts ?? [50_001])];+ const net: NetService.NetServiceShape = {+ canListenOnHost: () => Effect.succeed(true),+ hasListenerOnHost: () => Effect.succeed(false),+ isPortAvailableOnLoopback: () => Effect.succeed(true),+ reserveLoopbackPort: () => Effect.sync(() => reserved.shift() ?? 60_000),+ findAvailablePort: Effect.succeed,+ };+ const run: ProcessRunner.ProcessRunner["Service"]["run"] = (input) => {+ commands.push(input.command);+ if (input.command === "wslpath") {+ if (scenario.wslpathMissing) {+ return Effect.fail(+ new ProcessRunner.ProcessSpawnError({+ command: input.command,+ argumentCount: input.args.length,+ cause: PlatformError.systemError({+ _tag: "NotFound",+ module: "ChildProcess",+ method: "spawn",+ }),+ }),+ );+ }+ return Effect.succeed(output(`${NETSTAT_PATH}\n`));+ }+ if (input.args.includes("tcpv6")) {+ return Effect.succeed(+ output(+ listening(scenario.windowsPortsV6 ?? [], "[::1]", "[::]:0"),+ scenario.tcpv6ExitCode ?? null,+ ),+ );+ }+ return Effect.succeed(output(listening(scenario.windowsPorts ?? [])));+ };+ const layer = Layer.mergeAll(+ Layer.succeed(NetService.NetService, net),+ Layer.succeed(ProcessRunner.ProcessRunner, { run }),+ FileSystem.layerNoop({+ readFileString: (path) =>+ path === "/proc/sys/kernel/osrelease" && scenario.kernelRelease !== undefined+ ? Effect.succeed(scenario.kernelRelease)+ : Effect.fail(+ PlatformError.systemError({+ _tag: "NotFound",+ module: "FileSystem",+ method: "readFileString",+ }),+ ),+ }),+ );+ return Effect.gen(function* () {+ const selectAutomaticPort = yield* AutomaticPort.make;+ const port = yield* selectAutomaticPort(3773);+ return { port, commands };+ }).pipe(Effect.provide(layer));+};++describe("automatic port selection", () => {+ it.effect("moves off the default port only when Windows already listens on it", () =>+ Effect.gen(function* () {+ const free = yield* select({ kernelRelease: WSL_KERNEL, windowsPorts: [8080] });+ expect(free.port).toBe(3773);+ expect(free.commands).toEqual(["wslpath", NETSTAT_PATH, NETSTAT_PATH]);++ const owned = yield* select({ kernelRelease: WSL_KERNEL, windowsPorts: [3773] });+ expect(owned.port).toBe(50_001);+ }),+ );++ it.effect("retries a fallback port that Windows already listens on", () =>+ Effect.gen(function* () {+ const result = yield* select({+ kernelRelease: WSL_KERNEL,+ windowsPorts: [3773],+ windowsPortsV6: [50_001],+ reservedPorts: [50_001, 50_002],+ });+ expect(result.port).toBe(50_002);+ }),+ );++ it.effect("fails with an actionable error when every fallback belongs to Windows", () =>+ Effect.gen(function* () {+ const ports = Array.from({ length: 8 }, (_, index) => 50_001 + index);+ const error = yield* select({+ kernelRelease: WSL_KERNEL,+ windowsPorts: [3773],+ windowsPortsV6: ports,+ reservedPorts: ports,+ }).pipe(Effect.flip);+ expect(error).toBeInstanceOf(CliError.UserError);+ expect(error.cause).toContain("--port");+ }),+ );++ it.effect("keeps the local choice when the Windows snapshot is unavailable", () =>+ Effect.gen(function* () {+ const partial = yield* select({+ kernelRelease: WSL_KERNEL,+ windowsPorts: [3773],+ tcpv6ExitCode: 1,+ });+ expect(partial.port).toBe(3773);++ const noInterop = yield* select({ kernelRelease: WSL_KERNEL, wslpathMissing: true });+ expect(noInterop.port).toBe(3773);+ }),+ );++ it.effect("never queries Windows outside WSL", () =>+ Effect.gen(function* () {+ for (const scenario of [+ { kernelRelease: "6.8.0-45-generic\n" },+ // macOS and Windows have no kernel release file.+ {},+ ] satisfies ReadonlyArray<Scenario>) {+ const result = yield* select(scenario);+ expect(result.port).toBe(3773);+ expect(result.commands).toEqual([]);+ }+ }),+ );+});diff --git a/apps/server/src/cli/automaticPort.ts b/apps/server/src/cli/automaticPort.tsnew file mode 100644index 00000000000..354de65d251--- /dev/null+++ b/apps/server/src/cli/automaticPort.ts@@ -0,0 +1,69 @@+import * as NetService from "@t3tools/shared/Net";+import * as Duration from "effect/Duration";+import * as Effect from "effect/Effect";+import * as FileSystem from "effect/FileSystem";+import * as CliError from "effect/cli/CliError";++import { queryWindowsTcpListeners } from "../process/windowsTcpListeners.ts";+import * as ProcessRunner from "../processRunner.ts";++const KERNEL_RELEASE_PATH = "/proc/sys/kernel/osrelease";+const WINDOWS_NETSTAT_PATH = String.raw`C:\Windows\System32\netstat.exe`;+const FALLBACK_ATTEMPTS = 8;++/**+ * Picks the startup port when none was configured. Under WSL's default NAT networking, Windows+ * reaches the server through localhost forwarding, which fails for a port a Windows process+ * already listens on even though WSL can bind it.+ */+export const make = Effect.gen(function* () {+ const net = yield* NetService.NetService;+ const fs = yield* FileSystem.FileSystem;+ const processRunner = yield* ProcessRunner.ProcessRunner;++ // Services started by systemd lack WSL_DISTRO_NAME and WSL_INTEROP; the kernel release does not.+ // Hosts without this file (macOS, Windows) are not WSL.+ const isWsl = fs.readFileString(KERNEL_RELEASE_PATH).pipe(+ Effect.map((release) => release.toLowerCase().includes("microsoft")),+ Effect.orElseSucceed(() => false),+ );++ const readWindowsHostListeners = Effect.gen(function* () {+ // The automount root is configurable, so `/mnt/c` is not guaranteed.+ const netstat = yield* processRunner.run({+ command: "wslpath",+ args: ["-u", WINDOWS_NETSTAT_PATH],+ timeout: Duration.seconds(5),+ });+ const netstatPath = netstat.stdout.trim();+ if ((netstat.code !== null && netstat.code !== 0) || netstatPath.length === 0) {+ return null;+ }+ const listeners = yield* queryWindowsTcpListeners(processRunner, netstatPath);+ if (listeners === null) return null;+ return new Set(listeners.map((listener) => listener.port));+ }).pipe(Effect.orElseSucceed(() => null));++ return Effect.fn("automaticPort.select")(function* (preferred: number) {+ if (!(yield* isWsl)) return yield* net.findAvailablePort(preferred);+ const windows = yield* readWindowsHostListeners;+ if (windows === null) {+ yield* Effect.logWarning(+ "Could not list Windows TCP listeners from WSL; Windows may be unable to reach the selected port. Pass --port to choose one.",+ );+ return yield* net.findAvailablePort(preferred);+ }+ if (!windows.has(preferred) && (yield* net.isPortAvailableOnLoopback(preferred))) {+ return preferred;+ }+ // Linux and Windows ephemeral ranges overlap, so fallback ports can collide too.+ for (let attempt = 0; attempt < FALLBACK_ATTEMPTS; attempt += 1) {+ const port = yield* net.reserveLoopbackPort();+ if (!windows.has(port)) return port;+ }+ return yield* new CliError.UserError({+ cause:+ "Windows is already using every port T3 Code tried. Pass --port or set T3CODE_PORT to a port Windows is not using.",+ });+ });+});diff --git a/apps/server/src/cli/config.test.ts b/apps/server/src/cli/config.test.tsindex 297b225b6ad..5e09dda2c16 100644--- a/apps/server/src/cli/config.test.ts+++ b/apps/server/src/cli/config.test.ts@@ -754,6 +754,43 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {lan: Option.none<boolean>(),});+ it.effect("uses the automatic port selector only when no port is configured", () =>+ Effect.gen(function* () {+ const baseDir = yield* FileSystem.FileSystem.pipe(+ Effect.flatMap((fs) => fs.makeTempDirectoryScoped({ prefix: "t3-cli-auto-port-" })),+ );+ const selected: number[] = [];+ const selectAutomaticPort = (preferred: number) =>+ Effect.sync(() => {+ selected.push(preferred);+ return 50_123;+ });+ const resolvePort = (flags: {+ readonly mode?: Option.Option<"web" | "desktop">;+ readonly port: Option.Option<number>;+ }) =>+ resolveServerConfig({ ...minimalWebFlags(baseDir), ...flags }, Option.none(), {+ selectAutomaticPort,+ }).pipe(+ Effect.map((config) => config.port),+ Effect.provide(+ Layer.merge(+ NetService.layer,+ ConfigProvider.layer(ConfigProvider.fromEnv({ env: {} })),+ ),+ ),+ );++ expect(yield* resolvePort({ port: Option.none() })).toBe(50_123);+ expect(selected).toEqual([3773]);+ expect(yield* resolvePort({ port: Option.some(8788) })).toBe(8788);+ expect(+ yield* resolvePort({ mode: Option.some("desktop" as const), port: Option.none() }),+ ).toBe(3773);+ expect(selected).toEqual([3773]);+ }),+ );+it.effect("resolves each signal's endpoint through T3CODE_OTLP_*_URL, an OTEL endpoint, the bootstrap envelope, and persisted Settings, in that order",() =>diff --git a/apps/server/src/cli/config.ts b/apps/server/src/cli/config.tsindex f86fde0f597..00aae0f3133 100644--- a/apps/server/src/cli/config.ts+++ b/apps/server/src/cli/config.ts@@ -267,9 +267,13 @@ export const resolveServerConfig = Effect.fn("config.resolveServerConfig")(functreadonly startupPresentation?: ServerConfig.StartupPresentation;readonly forceAutoBootstrapProjectFromCwd?: boolean;readonly rejectRunningServer?: boolean;+ readonly selectAutomaticPort?: (+ preferred: number,+ ) => Effect.Effect<number, NetService.NetError | CliError.UserError>;},) {const { findAvailablePort } = yield* NetService.NetService;+ const selectAutomaticPort = options?.selectAutomaticPort ?? findAvailablePort;const path = yield* Path.Path;const fs = yield* FileSystem.FileSystem;const env = yield* EnvServerConfig;@@ -316,7 +320,7 @@ export const resolveServerConfig = Effect.fn("config.resolveServerConfig")(functif (mode === "desktop") {return Effect.succeed(ServerConfig.DEFAULT_PORT);}- return findAvailablePort(ServerConfig.DEFAULT_PORT);+ return selectAutomaticPort(ServerConfig.DEFAULT_PORT);},},);diff --git a/apps/server/src/cli/server.ts b/apps/server/src/cli/server.tsindex cb21a08140e..3b2768499fd 100644--- a/apps/server/src/cli/server.ts+++ b/apps/server/src/cli/server.ts@@ -8,6 +8,8 @@ import * as CliError from "effect/cli/CliError";import * as ServerConfig from "../config.ts";import { awaitLauncherLoss } from "../launcherWatch.ts";+import * as ProcessRunner from "../processRunner.ts";+import * as AutomaticPort from "./automaticPort.ts";import { type CliServerFlags, resolveServerConfig, sharedServerCommandFlags } from "./config.ts";const encodeCommand = Schema.encodeEffect(Schema.fromJsonString(Schema.String));@@ -30,7 +32,8 @@ const runServerCommand = Effect.fn("server.runServerCommand")(function* (// Before config resolution, which claims a port and creates directories.const { runServer } = yield* Effect.promise(() => import("../server.ts"));const logLevel = yield* GlobalFlag.LogLevel;- const config = yield* resolveServerConfig(flags, logLevel, options);+ const selectAutomaticPort = yield* AutomaticPort.make.pipe(Effect.provide(ProcessRunner.layer));+ const config = yield* resolveServerConfig(flags, logLevel, { ...options, selectAutomaticPort });const run = runServer.pipe(Effect.provideService(ServerConfig.ServerConfig, config));if (config.mode !== "desktop" || config.desktopBootstrapToken === undefined) return yield* run;yield* Effect.sync(() => {diff --git a/apps/server/src/preview/PortScanner.ts b/apps/server/src/preview/PortScanner.tsindex e026b204c03..b2b6e1ac9fb 100644--- a/apps/server/src/preview/PortScanner.ts+++ b/apps/server/src/preview/PortScanner.ts@@ -24,6 +24,7 @@ import * as Scope from "effect/Scope";import * as Semaphore from "effect/Semaphore";import { FetchHttpClient, HttpClient } from "effect/http";+import * as WindowsTcpListeners from "../process/windowsTcpListeners.ts";import * as ProcessRunner from "../processRunner.ts";export class PortDiscovery extends Context.Service<@@ -76,8 +77,6 @@ const LSOF_TIMEOUT_MS = 5_000;const PROC_FD_WALK_LIMIT = 50_000;const SOCKET_OWNER_ATTEMPTS = 3;const WINDOWS_LISTENER_TIMEOUT_MS = 5_000;-/** `netstat -ano` lists every connection, not just listeners; ~80 bytes per row, sized for ~200k rows. */-const WINDOWS_NETSTAT_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;const WEB_PROBE_TIMEOUT = Duration.seconds(1);const WEB_PROBE_CACHE_TTL_MS = Duration.toMillis(Duration.seconds(15));/** Bounds how long a cached Windows image name can outlive its process if Windows reuses the PID. */@@ -272,53 +271,6 @@ const parsePortFromLsofName = (name: string): number | null => {return port;};-const parseWindowsListenerLine = (- line: string,-): {- readonly host: string;- readonly port: number;- readonly pid: number | null;- readonly processName: string | null;-} | null => {- const trimmed = line.trim();- if (trimmed.length === 0) return null;-- if (trimmed.includes("|")) {- const [hostRaw, portRaw, pidRaw, processNameRaw] = trimmed.split("|", 4);- const host = hostRaw?.trim() ?? "";- if (!LSOF_LOCAL_HOST_TOKENS.has(host) && host !== "::") return null;- const port = Number(portRaw);- const pid = Number(pidRaw);- if (!Number.isInteger(port) || port <= 0 || port >= 65536) return null;- return {- host,- port,- pid: Number.isInteger(pid) && pid > 0 ? pid : null,- processName: processNameRaw?.trim() || null,- };- }-- // Foreign port `:0` identifies a listening TCP socket regardless of Windows locale.- const fields = trimmed.split(/\s+/);- if (fields.length < 4 || fields[0]?.toUpperCase() !== "TCP") return null;- const localEndpoint = fields[1] ?? "";- const foreignEndpoint = fields[2] ?? "";- if (!foreignEndpoint.endsWith(":0")) return null;- const lastColon = localEndpoint.lastIndexOf(":");- if (lastColon <= 0) return null;- const host = localEndpoint.slice(0, lastColon);- if (!LSOF_LOCAL_HOST_TOKENS.has(host) && host !== "::") return null;- const port = Number(localEndpoint.slice(lastColon + 1));- if (!Number.isInteger(port) || port <= 0 || port >= 65536) return null;- const pid = Number(fields.at(-1));- return {- host,- port,- pid: Number.isInteger(pid) && pid > 0 ? pid : null,- processName: null,- };-};-const exitedWithError = (result: ProcessRunner.ProcessRunOutput): boolean =>result.code !== null && result.code !== 0;@@ -330,16 +282,13 @@ const parseTasklistProcessName = (raw: string, pid: number): string | null => {return null;};-const parseWindowsListenerOutput = (- raw: string,- owners: ReadonlyMap<number, ServerOwner> = new Map(),+const discoveredWindowsListeners = (+ listeners: ReadonlyArray<WindowsTcpListeners.WindowsTcpListener>,+ owners: ReadonlyMap<number, ServerOwner>,): ReadonlyArray<DiscoveredLocalServer> => {const seen = new Map<number, DiscoveredLocalServer>();- for (const line of raw.split(/\r?\n/g)) {- const parsed = parseWindowsListenerLine(line);- if (!parsed) continue;- const { port, pid: normalizedPid, processName } = parsed;- const owner = normalizedPid === null ? undefined : owners.get(normalizedPid);+ for (const { port, pid } of listeners) {+ const owner = pid === null ? undefined : owners.get(pid);const existing = seen.get(port);if (existing) {if (owner === undefined) seen.set(port, { ...existing, ...UNOWNED });@@ -349,8 +298,8 @@ const parseWindowsListenerOutput = (host: "localhost",port,url: `http://localhost:${port}`,- processName,- pid: normalizedPid,+ processName: null,+ pid,...(owner ?? UNOWNED),});}@@ -857,21 +806,12 @@ export const make = Effect.gen(function* PortDiscoveryMake() {agentsPossible ? withAgentOwners(terminalOwners, pids) : Effect.succeed(terminalOwners);if (hostPlatform === "win32") {const recoverWindowsProbeFailure = recoverProcessProbeFailure("windows-listeners");- const runNetstat = (protocol: "tcp" | "tcpv6") =>- processRunner.run({- command: "netstat.exe",- args: ["-ano", "-p", protocol],- timeout: Duration.millis(WINDOWS_LISTENER_TIMEOUT_MS),- maxOutputBytes: WINDOWS_NETSTAT_MAX_OUTPUT_BYTES,- });- const listeners = yield* Effect.all([runNetstat("tcp"), runNetstat("tcpv6")], {- concurrency: 2,- }).pipe(- // Failed queries can hide other IPv4/IPv6 listeners on the port; fall back to configured URLs.- Effect.map(([tcp4, tcp6]) =>- exitedWithError(tcp4) || exitedWithError(tcp6)- ? null- : parseWindowsListenerOutput(`${tcp4.stdout}\n${tcp6.stdout}`, terminalOwners),+ const listeners = yield* WindowsTcpListeners.queryWindowsTcpListeners(+ processRunner,+ "netstat.exe",+ ).pipe(+ Effect.map((snapshot) =>+ snapshot === null ? null : discoveredWindowsListeners(snapshot, terminalOwners),),Effect.catchTags({ProcessSpawnError: recoverWindowsProbeFailure,diff --git a/apps/server/src/process/windowsTcpListeners.ts b/apps/server/src/process/windowsTcpListeners.tsnew file mode 100644index 00000000000..789915fa4b1--- /dev/null+++ b/apps/server/src/process/windowsTcpListeners.ts@@ -0,0 +1,61 @@+import { LSOF_LOCAL_HOST_TOKENS } from "@t3tools/shared/preview";+import * as Duration from "effect/Duration";+import * as Effect from "effect/Effect";++import type * as ProcessRunner from "../processRunner.ts";++const NETSTAT_TIMEOUT = Duration.seconds(5);+/** `netstat -ano` lists every connection, not just listeners; ~80 bytes per row, sized for ~200k rows. */+const NETSTAT_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;++export interface WindowsTcpListener {+ readonly port: number;+ readonly pid: number | null;+}++const parseWindowsTcpListenerLine = (line: string): WindowsTcpListener | null => {+ // Foreign port `:0` identifies a listening TCP socket regardless of Windows locale.+ const fields = line.trim().split(/\s+/);+ if (fields.length < 4 || fields[0]?.toUpperCase() !== "TCP") return null;+ const localEndpoint = fields[1] ?? "";+ const foreignEndpoint = fields[2] ?? "";+ if (!foreignEndpoint.endsWith(":0")) return null;+ const lastColon = localEndpoint.lastIndexOf(":");+ if (lastColon <= 0) return null;+ const host = localEndpoint.slice(0, lastColon);+ if (!LSOF_LOCAL_HOST_TOKENS.has(host) && host !== "::") return null;+ const port = Number(localEndpoint.slice(lastColon + 1));+ if (!Number.isInteger(port) || port <= 0 || port >= 65536) return null;+ const pid = Number(fields.at(-1));+ return { port, pid: Number.isInteger(pid) && pid > 0 ? pid : null };+};++const parseWindowsTcpListeners = (raw: string): ReadonlyArray<WindowsTcpListener> =>+ raw.split(/\r?\n/g).flatMap((line) => {+ const listener = parseWindowsTcpListenerLine(line);+ return listener === null ? [] : [listener];+ });++const exitedWithError = (result: ProcessRunner.ProcessRunOutput): boolean =>+ result.code !== null && result.code !== 0;++/** Resolves to `null` when either query exits nonzero. */+export const queryWindowsTcpListeners = Effect.fn("windowsTcpListeners.query")(function* (+ processRunner: ProcessRunner.ProcessRunner["Service"],+ netstatCommand: string,+) {+ const runNetstat = (protocol: "tcp" | "tcpv6") =>+ processRunner.run({+ command: netstatCommand,+ args: ["-ano", "-p", protocol],+ timeout: NETSTAT_TIMEOUT,+ maxOutputBytes: NETSTAT_MAX_OUTPUT_BYTES,+ });+ const [tcp4, tcp6] = yield* Effect.all([runNetstat("tcp"), runNetstat("tcpv6")], {+ concurrency: 2,+ });+ // One failed query leaves a partial snapshot that could hide another process sharing a+ // port across IPv4/IPv6.+ if (exitedWithError(tcp4) || exitedWithError(tcp6)) return null;+ return parseWindowsTcpListeners(`${tcp4.stdout}\n${tcp6.stdout}`);+});