import {
CONFIGURED_LOCAL_SERVER_URLS_MAX_ITEMS,
PREVIEW_URL_MAX_LENGTH,
PreviewStopLocalServerError,
ThreadId,
type DiscoveredLocalServer,
type PreviewStopLocalServerInput,
} from "@t3tools/contracts";
import { signalProcessGroup } from "@t3tools/provider-core/server/processGroup";
import * as HostProcess from "@t3tools/shared/HostProcess";
import { isLoopbackHost, LSOF_LOCAL_HOST_TOKENS } from "@t3tools/shared/preview";
import * as Cause from "effect/Cause";
import * as Clock from "effect/Clock";
import * as Context from "effect/Context";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as PlatformError from "effect/PlatformError";
import * as Ref from "effect/Ref";
import * as Schedule from "effect/Schedule";
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<
PortDiscovery,
{
readonly scan: (
configuredUrls?: ReadonlyArray<string>,
) => Effect.Effect<ReadonlyArray<DiscoveredLocalServer>>;
readonly subscribe: (
input: {
readonly configuredUrls: ReadonlyArray<string>;
readonly initialSnapshot: ReadonlyArray<DiscoveredLocalServer>;
},
listener: (servers: ReadonlyArray<DiscoveredLocalServer>) => Effect.Effect<void>,
) => Effect.Effect<void, never, Scope.Scope>;
readonly retain: Effect.Effect<void, never, Scope.Scope>;
readonly registerTerminalProcesses: (input: {
readonly threadId: string;
readonly terminalId: string;
readonly processIds: ReadonlyArray<number>;
}) => Effect.Effect<void>;
readonly unregisterTerminal: (input: {
readonly threadId: string;
readonly terminalId: string;
}) => Effect.Effect<void>;
/**
* Counts a running agent until the returned function is called. While one runs, any
* listener may be a server it started. Synchronous because provider spawn callbacks run
* outside Effect.
*/
readonly trackAgent: () => () => void;
/** Stops a listed server's process group, never this server, an agent CLI, or a shell. */
readonly stopServer: (
input: PreviewStopLocalServerInput,
) => Effect.Effect<void, PreviewStopLocalServerError>;
}
>()("t3/preview/PortScanner/PortDiscovery") {}
/**
* Agents launch with this set to their thread, and every job they start inherits it, so a
* server stays attributed after its launching shell exits or the agent settles.
*/
export const AGENT_THREAD_ENV = "T3CODE_THREAD_ID";
/** `0` turns off listener discovery; configured preview URLs are still probed. */
const PORT_DISCOVERY_ENV = "T3CODE_PORT_DISCOVERY";
const POLL_INTERVAL = Duration.seconds(3);
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;
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. */
const WINDOWS_PROCESS_NAME_TTL_MS = Duration.toMillis(Duration.seconds(60));
const WINDOWS_PROCESS_NAME_CONCURRENCY = 4;
const WEB_PROBE_CONCURRENCY = 16;
const NAVIGATION_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
const PS_TIMEOUT_MS = 5_000;
const PS_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
const STOP_GRACE_MS = 3_000;
const STOP_POLL_INTERVAL = Duration.millis(250);
type Listener = (servers: ReadonlyArray<DiscoveredLocalServer>) => Effect.Effect<void>;
interface ListenerSubscription {
readonly configuredUrls: ReadonlyArray<string>;
readonly lastSnapshot: ReadonlyArray<DiscoveredLocalServer>;
}
interface ScannerState {
readonly listeners: ReadonlyMap<Listener, ListenerSubscription>;
readonly terminalProcesses: ReadonlyMap<
string,
{
readonly owner: TerminalProcessOwner;
readonly processIds: ReadonlySet<number>;
}
>;
readonly retainCount: number;
}
interface TerminalProcessOwner {
readonly threadId: ThreadId;
readonly terminalId: string;
}
type ServerOwner = Pick<DiscoveredLocalServer, "terminal" | "agent">;
const UNOWNED: ServerOwner = { terminal: null, agent: null };
const isOwned = (server: DiscoveredLocalServer): boolean =>
server.terminal !== null || (server.agent ?? null) !== null;
interface ProcessTableRow {
readonly pid: number;
readonly ppid: number;
readonly pgid: number;
}
interface WebProbeCacheEntry {
readonly pid: number | null;
readonly isWeb: boolean;
readonly expiresAtMillis: number;
}
interface WebProbeGroup {
readonly server: DiscoveredLocalServer;
readonly url: string;
readonly configuredKey: string;
}
interface WebProbeSnapshot {
readonly discovered: ReadonlyArray<DiscoveredLocalServer>;
readonly configured: ReadonlyMap<string, DiscoveredLocalServer>;
}
const terminalOwnerKey = (owner: {
readonly threadId: string;
readonly terminalId: string;
}): string => `${owner.threadId}\u0000${owner.terminalId}`;
const parseConfiguredUrl = (raw: string): URL | null => {
try {
const url = new URL(raw);
if (url.protocol !== "http:" && url.protocol !== "https:") return null;
if (!isLoopbackHost(url.hostname)) return null;
return url;
} catch {
return null;
}
};
const localServerKey = (host: string, port: number): string =>
`${isLoopbackHost(host) ? "loopback" : host.toLowerCase()}:${port}`;
const urlPort = (url: URL): number =>
url.port.length > 0 ? Number.parseInt(url.port, 10) : url.protocol === "http:" ? 80 : 443;
const webProbeCacheKey = (raw: string): string => {
const url = new URL(raw);
url.hash = "";
return url.href;
};
const normalizeConfiguredUrls = (urls: ReadonlyArray<string>): ReadonlyArray<string> => [
...new Set(
urls
.slice(0, CONFIGURED_LOCAL_SERVER_URLS_MAX_ITEMS)
.filter((raw) => raw.length <= PREVIEW_URL_MAX_LENGTH)
.map(parseConfiguredUrl)
.filter((url): url is URL => url !== null && url.href.length <= PREVIEW_URL_MAX_LENGTH)
.map((url) => {
if (url.hostname === "0.0.0.0") url.hostname = "localhost";
return url.href;
})
.filter((url) => url.length <= PREVIEW_URL_MAX_LENGTH),
),
];
const projectWebProbeSnapshot = (
snapshot: WebProbeSnapshot,
configuredUrls: ReadonlyArray<string>,
): ReadonlyArray<DiscoveredLocalServer> => {
const visibleByServer = new Map<string, DiscoveredLocalServer>();
const firstConfiguredByServer = new Map<string, string>();
for (const raw of normalizeConfiguredUrls(configuredUrls)) {
const url = new URL(raw);
const port = urlPort(url);
const serverKey = localServerKey(url.hostname, port);
if (!firstConfiguredByServer.has(serverKey)) firstConfiguredByServer.set(serverKey, raw);
if (visibleByServer.has(serverKey)) continue;
const configured = snapshot.configured.get(webProbeCacheKey(raw));
if (configured) visibleByServer.set(serverKey, { ...configured, url: raw });
}
// An owned listener whose configured check failed still opens at this caller's configured URL.
for (const server of snapshot.discovered) {
const key = localServerKey(server.host, server.port);
if (visibleByServer.has(key)) continue;
const configuredUrl = firstConfiguredByServer.get(key);
visibleByServer.set(key, configuredUrl ? { ...server, url: configuredUrl } : server);
}
return [...visibleByServer.values()].toSorted((left, right) => left.port - right.port);
};
const parseLsofOutput = (
raw: string,
owners: ReadonlyMap<number, ServerOwner> = new Map(),
): ReadonlyArray<DiscoveredLocalServer> => {
const seen = new Map<string, DiscoveredLocalServer>();
let pid: number | null = null;
let processName: string | null = null;
for (const line of raw.split("\n")) {
if (line.length === 0) continue;
const tag = line.charAt(0);
const value = line.slice(1);
if (tag === "p") {
const parsed = Number.parseInt(value, 10);
pid = Number.isFinite(parsed) && parsed > 0 ? parsed : null;
processName = null;
continue;
}
if (tag === "c") {
processName = value.trim() || null;
continue;
}
if (tag === "n") {
const portMatch = parsePortFromLsofName(value);
if (portMatch == null) continue;
const url = `http://localhost:${portMatch}`;
const key = `localhost:${portMatch}`;
const owner = pid === null ? undefined : owners.get(pid);
const existing = seen.get(key);
if (existing) {
if (owner === undefined) seen.set(key, { ...existing, ...UNOWNED });
continue;
}
seen.set(key, {
host: "localhost",
port: portMatch,
url,
processName,
pid,
...(owner ?? UNOWNED),
});
}
}
return Array.from(seen.values()).toSorted((a, b) => a.port - b.port);
};
const parsePortFromLsofName = (name: string): number | null => {
const trimmed = name.split(" ", 1)[0]?.trim() ?? "";
if (trimmed.length === 0) return null;
const lastColon = trimmed.lastIndexOf(":");
if (lastColon < 0) return null;
const hostPart = trimmed.slice(0, lastColon);
const portPart = trimmed.slice(lastColon + 1);
if (!LSOF_LOCAL_HOST_TOKENS.has(hostPart)) return null;
const port = Number.parseInt(portPart, 10);
if (!Number.isFinite(port) || port <= 0 || port >= 65536) return null;
return port;
};
const exitedWithError = (result: ProcessRunner.ProcessRunOutput): boolean =>
result.code !== null && result.code !== 0;
const parseTasklistProcessName = (raw: string, pid: number): string | null => {
for (const line of raw.split(/\r?\n/g)) {
const match = /^"([^"]*)","(\d+)"/.exec(line.trim());
if (match && Number(match[2]) === pid) return match[1]!.replace(/\.exe$/i, "") || null;
}
return null;
};
const discoveredWindowsListeners = (
listeners: ReadonlyArray<WindowsTcpListeners.WindowsTcpListener>,
owners: ReadonlyMap<number, ServerOwner>,
): ReadonlyArray<DiscoveredLocalServer> => {
const seen = new Map<number, DiscoveredLocalServer>();
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 });
continue;
}
seen.set(port, {
host: "localhost",
port,
url: `http://localhost:${port}`,
processName: null,
pid,
...(owner ?? UNOWNED),
});
}
return [...seen.values()].toSorted((left, right) => left.port - right.port);
};
const PROC_TCP_LISTEN = "0A";
/** Each 32-bit word of the hex address is little-endian. */
const procLocalAddress = (hex: string): boolean => {
if (hex.length === 8) {
return hex === "00000000" || hex.endsWith("7F");
}
if (hex.length !== 32) return false;
if (hex === "0".repeat(32) || hex === `${"0".repeat(24)}01000000`) return true;
return hex.startsWith(`${"0".repeat(16)}FFFF0000`) && procLocalAddress(hex.slice(24));
};
const parseProcNetTcp = (
raw: string,
): ReadonlyArray<{ readonly port: number; readonly inode: string }> => {
const listeners: Array<{ port: number; inode: string }> = [];
for (const line of raw.split("\n").slice(1)) {
const fields = line.trim().split(/\s+/);
const [address, portHex] = fields[1]?.split(":") ?? [];
if (fields[3] !== PROC_TCP_LISTEN || !address || !portHex) continue;
if (!procLocalAddress(address.toUpperCase())) continue;
const port = Number.parseInt(portHex, 16);
const inode = fields[9];
if (!Number.isInteger(port) || port <= 0 || port >= 65536 || !inode) continue;
listeners.push({ port, inode });
}
return listeners;
};
/** Processes holding a loopback or wildcard listener in `lsof -F pcn` output. */
const lsofProcessIds = (raw: string): ReadonlyArray<number> => {
const pids = new Set<number>();
let pid: number | null = null;
for (const line of raw.split("\n")) {
if (line.startsWith("p")) {
const parsed = Number.parseInt(line.slice(1), 10);
pid = Number.isFinite(parsed) && parsed > 0 ? parsed : null;
} else if (
line.startsWith("n") &&
pid !== null &&
parsePortFromLsofName(line.slice(1)) !== null
) {
pids.add(pid);
}
}
return [...pids];
};
const AGENT_THREAD_ASSIGNMENT = new RegExp(`(?:^|\\s)${AGENT_THREAD_ENV}=(\\S+)`);
/** Reads `/proc/<pid>/environ`, whose entries are NUL-separated. */
const parseProcEnvironThread = (raw: string): ThreadId | null => {
const prefix = `${AGENT_THREAD_ENV}=`;
const value = raw
.split("\0")
.find((entry) => entry.startsWith(prefix))
?.slice(prefix.length)
.trim();
return value ? ThreadId.make(value) : null;
};
/**
* Reads macOS `ps -E -o pid=,command=`, which appends each process's launch environment to its
* argv with spaces, so an argument that spells the assignment out also matches.
*/
const parsePsEnvironmentThreads = (raw: string): ReadonlyMap<number, ThreadId | null> => {
const threads = new Map<number, ThreadId | null>();
for (const line of raw.split("\n")) {
const match = /^\s*(\d+)\s(.*)$/.exec(line);
if (!match) continue;
const value = AGENT_THREAD_ASSIGNMENT.exec(match[2]!)?.[1];
threads.set(Number(match[1]), value ? ThreadId.make(value) : null);
}
return threads;
};
const parseProcessTable = (raw: string): ReadonlyMap<number, ProcessTableRow> => {
const rows = new Map<number, ProcessTableRow>();
for (const line of raw.split("\n")) {
const [pid, ppid, pgid] = line.trim().split(/\s+/).map(Number);
if (Number.isInteger(pid) && Number.isInteger(ppid) && Number.isInteger(pgid)) {
rows.set(pid!, { pid: pid!, ppid: ppid!, pgid: pgid! });
}
}
return rows;
};
/**
* The process group stopping `pid` signals. Shells with job control and agent tool shells give
* every job its own group, so the group is the job. Null when the group also holds this server,
* a direct child of it (agent CLIs and terminal shells), or one of its ancestors.
*/
export const stoppableProcessGroup = (
table: ReadonlyMap<number, ProcessTableRow>,
pid: number,
serverPid: number,
): number | null => {
const group = table.get(pid)?.pgid;
if (group === undefined || group <= 1) return null;
const guarded = new Set([serverPid]);
for (
let parent = table.get(serverPid)?.ppid;
parent !== undefined && parent > 1 && !guarded.has(parent);
parent = table.get(parent)?.ppid
) {
guarded.add(parent);
}
for (const row of table.values()) {
if (row.pgid === group && (guarded.has(row.pid) || row.ppid === serverPid)) return null;
}
return group;
};
const serversEqual = (
left: ReadonlyArray<DiscoveredLocalServer>,
right: ReadonlyArray<DiscoveredLocalServer>,
): boolean => {
if (left.length !== right.length) return false;
for (let i = 0; i < left.length; i += 1) {
const a = left[i];
const b = right[i];
if (!a || !b) return false;
if (
a.host !== b.host ||
a.port !== b.port ||
a.url !== b.url ||
a.processName !== b.processName ||
a.pid !== b.pid ||
a.terminal?.threadId !== b.terminal?.threadId ||
a.terminal?.terminalId !== b.terminal?.terminalId ||
a.agent?.threadId !== b.agent?.threadId
) {
return false;
}
}
return true;
};
const isNoSuchProcess = (cause: unknown): boolean =>
typeof cause === "object" && cause !== null && "code" in cause && cause.code === "ESRCH";
const isCommandNotFound = (error: ProcessRunner.ProcessSpawnError): boolean =>
PlatformError.isPlatformError(error.cause) && error.cause.reason._tag === "NotFound";
/** @public */
export const make = Effect.gen(function* PortDiscoveryMake() {
const processRunner = yield* ProcessRunner.ProcessRunner;
const fileSystem = yield* FileSystem.FileSystem;
const hostPlatform = yield* HostProcess.Platform;
const listenerDiscovery = (yield* HostProcess.Environment)[PORT_DISCOVERY_ENV] !== "0";
const httpClient = (yield* HttpClient.HttpClient).pipe(HttpClient.withScope);
const stateRef = yield* Ref.make<ScannerState>({
listeners: new Map(),
terminalProcesses: new Map(),
retainCount: 0,
});
const webProbeCacheRef = yield* Ref.make<ReadonlyMap<string, WebProbeCacheEntry>>(new Map());
const scanSemaphore = yield* Semaphore.make(1);
const lsofMissingRef = yield* Ref.make(false);
const windowsProcessNamesRef = yield* Ref.make<
ReadonlyMap<number, { readonly name: string | null; readonly expiresAtMillis: number }>
>(new Map());
const socketOwnersRef = yield* Ref.make<
ReadonlyMap<string, { readonly pid: number; readonly processName: string | null }>
>(new Map());
const socketOwnerMissesRef = yield* Ref.make<ReadonlyMap<string, number>>(new Map());
// Each current listener pid's agent thread, or null without one. A process keeps its launch
// environment, so a pid is read once while it listens. Cleared while no client retains the
// scanner, since unscanned pids can be reused.
const agentThreadsRef = yield* Ref.make<ReadonlyMap<number, ThreadId | null>>(new Map());
let runningAgents = 0;
// An agent that exited, or a cache cleared with a marked listener, owes one listener read: the
// servers it left may still run. So does startup, for agents that ran before a restart.
let agentScanPending = true;
const readAgentThreads = Effect.fn("PortDiscovery.readAgentThreads")(function* (
pids: ReadonlyArray<number>,
) {
const cached = yield* Ref.get(agentThreadsRef);
const unread = pids.filter((pid) => !cached.has(pid));
const read: ReadonlyMap<number, ThreadId | null> =
unread.length === 0
? new Map()
: hostPlatform === "linux"
? new Map(
yield* Effect.forEach(
unread,
(pid) =>
fileSystem.readFileString(`/proc/${pid}/environ`).pipe(
Effect.map(parseProcEnvironThread),
Effect.orElseSucceed(() => null),
Effect.map((threadId) => [pid, threadId] as const),
),
{ concurrency: 16 },
),
)
: yield* processRunner
.run({
command: "ps",
args: ["-E", "-ww", "-o", "pid=,command=", "-p", unread.join(",")],
timeout: Duration.millis(PS_TIMEOUT_MS),
maxOutputBytes: PS_MAX_OUTPUT_BYTES,
})
.pipe(
Effect.map((result) => parsePsEnvironmentThreads(result.stdout)),
Effect.orElseSucceed(() => {
agentScanPending = true;
return new Map();
}),
);
const next = new Map<number, ThreadId | null>();
for (const pid of pids) {
const threadId = cached.has(pid) ? cached.get(pid) : read.get(pid);
if (threadId !== undefined) next.set(pid, threadId);
}
yield* Ref.set(agentThreadsRef, next);
return next;
});
const withAgentOwners = Effect.fn("PortDiscovery.withAgentOwners")(function* (
terminalOwners: ReadonlyMap<number, ServerOwner>,
pids: ReadonlyArray<number>,
) {
// Runs only once a listener snapshot exists, so a failed read leaves the scan pending.
agentScanPending = false;
const threads = yield* readAgentThreads(pids.filter((pid) => !terminalOwners.has(pid)));
const owners = new Map(terminalOwners);
for (const [pid, threadId] of threads) {
if (threadId !== null) owners.set(pid, { terminal: null, agent: { threadId } });
}
return owners;
});
const findSocketOwners = Effect.fn("PortDiscovery.findSocketOwners")(function* (
inodes: ReadonlySet<string>,
) {
const owners = new Map<string, { pid: number; processName: string | null }>();
const pids = (yield* fileSystem
.readDirectory("/proc")
.pipe(Effect.orElseSucceed((): ReadonlyArray<string> => []))).filter((entry) =>
/^\d+$/.test(entry),
);
let budget = PROC_FD_WALK_LIMIT;
for (const pidText of pids) {
if (owners.size === inodes.size || budget <= 0) break;
const fds = yield* fileSystem
.readDirectory(`/proc/${pidText}/fd`)
.pipe(Effect.orElseSucceed((): ReadonlyArray<string> => []));
const walked = fds.slice(0, budget);
budget -= walked.length;
const links = yield* Effect.forEach(
walked,
(fd) =>
fileSystem.readLink(`/proc/${pidText}/fd/${fd}`).pipe(Effect.orElseSucceed(() => "")),
{ concurrency: 16 },
);
const held = links.flatMap((link) => /^socket:\[(\d+)\]$/.exec(link)?.[1] ?? []);
const matched = held.filter((inode) => inodes.has(inode) && !owners.has(inode));
if (matched.length === 0) continue;
const processName = yield* fileSystem.readFileString(`/proc/${pidText}/comm`).pipe(
Effect.map((name) => name.trim() || null),
Effect.orElseSucceed(() => null),
);
for (const inode of matched) owners.set(inode, { pid: Number(pidText), processName });
}
return owners;
});
const scanProcListeners = Effect.fn("PortDiscovery.scanProcListeners")(function* (
resolveOwners: (pids: ReadonlyArray<number>) => Effect.Effect<ReadonlyMap<number, ServerOwner>>,
) {
if (hostPlatform !== "linux") return null;
const tables = yield* Effect.forEach(["/proc/net/tcp", "/proc/net/tcp6"], (path) =>
fileSystem.readFileString(path).pipe(Effect.option),
);
if (tables.every(Option.isNone)) return null;
const listeners = tables.flatMap((table) =>
Option.isSome(table) ? parseProcNetTcp(table.value) : [],
);
const known = yield* Ref.get(socketOwnersRef);
const knownMisses = yield* Ref.get(socketOwnerMissesRef);
const inodes = new Set(listeners.map((listener) => listener.inode));
// Walk fds only for unowned sockets; stop after repeated misses for inaccessible or exited processes.
const unseen = new Set(
[...inodes].filter(
(inode) => !known.has(inode) && (knownMisses.get(inode) ?? 0) < SOCKET_OWNER_ATTEMPTS,
),
);
const found = unseen.size === 0 ? new Map() : yield* findSocketOwners(unseen);
const owners = new Map([...known, ...found].filter(([inode]) => inodes.has(inode)));
const misses = new Map([...knownMisses].filter(([inode]) => inodes.has(inode)));
for (const inode of unseen) {
if (!found.has(inode)) misses.set(inode, (misses.get(inode) ?? 0) + 1);
}
yield* Ref.set(socketOwnersRef, owners);
yield* Ref.set(socketOwnerMissesRef, misses);
const serverOwners = yield* resolveOwners([
...new Set([...owners.values()].map(({ pid }) => pid)),
]);
const seen = new Map<number, DiscoveredLocalServer>();
for (const { port, inode } of listeners) {
const socketOwner = owners.get(inode) ?? null;
const owner = socketOwner === null ? undefined : serverOwners.get(socketOwner.pid);
const existing = seen.get(port);
if (existing && (existing.pid !== null || socketOwner === null)) {
if (owner === undefined) seen.set(port, { ...existing, ...UNOWNED });
continue;
}
seen.set(port, {
host: "localhost",
port,
url: `http://localhost:${port}`,
processName: socketOwner?.processName ?? null,
pid: socketOwner?.pid ?? null,
...(existing ? UNOWNED : (owner ?? UNOWNED)),
});
}
return [...seen.values()].toSorted((left, right) => left.port - right.port);
});
const probeWebUrl = Effect.fn("PortDiscovery.probeWebUrl")((url: string) =>
httpClient.get(url).pipe(
Effect.map((response) => {
const location = response.headers.location?.trim();
if (NAVIGATION_REDIRECT_STATUSES.has(response.status) && location) return url;
if (response.status < 200 || response.status >= 300) return null;
if (response.status === 204 || response.status === 205) return null;
const contentType = response.headers["content-type"]
?.split(";", 1)[0]
?.trim()
.toLowerCase();
return contentType === "text/html" || contentType === "application/xhtml+xml" ? url : null;
}),
Effect.scoped,
Effect.timeoutOption(WEB_PROBE_TIMEOUT),
Effect.map(Option.getOrNull),
Effect.orElseSucceed(() => null),
Effect.provideService(FetchHttpClient.RequestInit, { redirect: "manual" }),
),
);
const makeWebProbeGroups = (
servers: ReadonlyArray<DiscoveredLocalServer>,
configuredUrls: ReadonlyArray<string>,
): ReadonlyArray<WebProbeGroup> => {
const serversByKey = new Map(
servers.map((server) => [localServerKey(server.host, server.port), server] as const),
);
const groups: WebProbeGroup[] = [];
const configuredResources = new Set<string>();
for (const raw of configuredUrls) {
const url = new URL(raw);
const port = urlPort(url);
const key = localServerKey(url.hostname, port);
const resourceKey = webProbeCacheKey(raw);
if (configuredResources.has(resourceKey)) continue;
configuredResources.add(resourceKey);
groups.push({
server: serversByKey.get(key) ?? {
host: url.hostname,
port,
url: raw,
processName: null,
pid: null,
terminal: null,
},
url: raw,
configuredKey: resourceKey,
});
}
return groups;
};
// Only configured URLs are requested. Owned listeners are listed as plain HTTP without a
// request: owning a process says nothing about its protocol, and HTTP or TLS bytes break
// binary ones such as Unity's test runner or Steam's IPC.
// Idle polls omit this span; requested scans and uncached probes retain their own spans.
const probeWebServers = Effect.fnUntraced(function* (
servers: ReadonlyArray<DiscoveredLocalServer>,
configuredUrls: ReadonlyArray<string>,
) {
const nowMillis = yield* Clock.currentTimeMillis;
const cached = yield* Ref.get(webProbeCacheRef);
const groups = makeWebProbeGroups(servers, configuredUrls);
const probed = yield* Effect.forEach(
groups,
(group) => {
const { pid } = group.server;
const cachedProbe = cached.get(group.configuredKey);
return cachedProbe?.pid === pid && cachedProbe.expiresAtMillis > nowMillis
? Effect.succeed({ group, probe: cachedProbe, fresh: false })
: probeWebUrl(group.url).pipe(
Effect.map((result) => ({
group,
probe: { pid, isWeb: result !== null, expiresAtMillis: 0 },
fresh: true,
})),
);
},
{ concurrency: WEB_PROBE_CONCURRENCY },
);
const completedAtMillis = yield* Clock.currentTimeMillis;
const nextCache = new Map(
[...cached].filter(([, probe]) => probe.expiresAtMillis > completedAtMillis),
);
const configured = new Map<string, DiscoveredLocalServer>();
for (const { group, probe, fresh } of probed) {
nextCache.set(
group.configuredKey,
fresh ? { ...probe, expiresAtMillis: completedAtMillis + WEB_PROBE_CACHE_TTL_MS } : probe,
);
if (probe.isWeb) configured.set(group.configuredKey, { ...group.server, url: group.url });
}
yield* Ref.set(webProbeCacheRef, nextCache);
return { discovered: servers.filter(isOwned), configured } satisfies WebProbeSnapshot;
});
// tasklist costs 200-300ms per PID; query visible servers with bounded concurrency and cache names.
const withWindowsProcessNames = Effect.fn("PortDiscovery.withWindowsProcessNames")(function* (
snapshot: WebProbeSnapshot,
) {
const servers = [...snapshot.discovered, ...snapshot.configured.values()];
const pids = new Set(servers.flatMap((server) => (server.pid === null ? [] : [server.pid])));
const nowMillis = yield* Clock.currentTimeMillis;
const cached = [...(yield* Ref.get(windowsProcessNamesRef))].filter(
([pid, entry]) => pids.has(pid) && entry.expiresAtMillis > nowMillis,
);
const cachedPids = new Set(cached.map(([pid]) => pid));
const expiresAtMillis = nowMillis + WINDOWS_PROCESS_NAME_TTL_MS;
const fetched = yield* Effect.forEach(
[...pids].filter((pid) => !cachedPids.has(pid)),
(pid) =>
processRunner
.run({
command: "tasklist.exe",
args: ["/FO", "CSV", "/NH", "/FI", `PID eq ${pid}`],
timeout: Duration.millis(WINDOWS_LISTENER_TIMEOUT_MS),
maxOutputBytes: 64 * 1024,
})
.pipe(
Effect.map((result) =>
exitedWithError(result)
? []
: [
[
pid,
{ name: parseTasklistProcessName(result.stdout, pid), expiresAtMillis },
] as const,
],
),
Effect.orElseSucceed(() => []),
),
{ concurrency: WINDOWS_PROCESS_NAME_CONCURRENCY },
);
const names = new Map([...cached, ...fetched.flat()]);
yield* Ref.set(windowsProcessNamesRef, names);
const withName = (server: DiscoveredLocalServer): DiscoveredLocalServer =>
server.pid === null || server.processName !== null
? server
: { ...server, processName: names.get(server.pid)?.name ?? null };
return {
discovered: snapshot.discovered.map(withName),
configured: new Map([...snapshot.configured].map(([key, server]) => [key, withName(server)])),
} satisfies WebProbeSnapshot;
});
const recoverProcessProbeFailure =
(probe: "lsof" | "windows-listeners") => (error: ProcessRunner.ProcessRunError) =>
Effect.logDebug("preview port process probe failed; probing configured URLs only", {
cause: error,
probe,
platform: hostPlatform,
}).pipe(Effect.as(null));
// Routine polling helpers share operation/probe spans instead of tracing every tick.
const scanUnlocked = Effect.fnUntraced(function* (configuredUrls: ReadonlyArray<string>) {
if (!listenerDiscovery) return yield* probeWebServers([], configuredUrls);
const state = yield* Ref.get(stateRef);
const terminalOwners = new Map<number, ServerOwner>();
for (const registration of state.terminalProcesses.values()) {
for (const processId of registration.processIds) {
terminalOwners.set(processId, { terminal: registration.owner, agent: null });
}
}
// A server an agent started can outlive the agent, so listeners are read while the last scan
// still found one.
const agentsPossible =
hostPlatform !== "win32" &&
(runningAgents > 0 ||
agentScanPending ||
[...(yield* Ref.get(agentThreadsRef)).values()].some((threadId) => threadId !== null));
if (terminalOwners.size === 0 && configuredUrls.length === 0 && !agentsPossible) {
return { discovered: [], configured: new Map() } satisfies WebProbeSnapshot;
}
const resolveOwners = (pids: ReadonlyArray<number>) =>
agentsPossible ? withAgentOwners(terminalOwners, pids) : Effect.succeed(terminalOwners);
if (hostPlatform === "win32") {
const recoverWindowsProbeFailure = recoverProcessProbeFailure("windows-listeners");
const listeners = yield* WindowsTcpListeners.queryWindowsTcpListeners(
processRunner,
"netstat.exe",
).pipe(
Effect.map((snapshot) =>
snapshot === null ? null : discoveredWindowsListeners(snapshot, terminalOwners),
),
Effect.catchTags({
ProcessSpawnError: recoverWindowsProbeFailure,
ProcessStdinError: recoverWindowsProbeFailure,
ProcessOutputLimitError: recoverWindowsProbeFailure,
ProcessReadError: recoverWindowsProbeFailure,
ProcessTimeoutError: recoverWindowsProbeFailure,
}),
);
return yield* withWindowsProcessNames(
yield* probeWebServers(listeners ?? [], configuredUrls),
);
}
const recoverLsofProbeFailure = recoverProcessProbeFailure("lsof");
if (yield* Ref.get(lsofMissingRef)) {
const fromProc = yield* scanProcListeners(resolveOwners);
return yield* probeWebServers(fromProc ?? [], configuredUrls);
}
const lsofResult = yield* processRunner
.run({
command: "lsof",
args: ["-iTCP", "-sTCP:LISTEN", "-P", "-n", "-F", "pcn"],
timeout: Duration.millis(LSOF_TIMEOUT_MS),
// Partial output could hide another app's listener on an owned port.
maxOutputBytes: 1024 * 1024,
})
.pipe(
Effect.flatMap((result) =>
resolveOwners(lsofProcessIds(result.stdout)).pipe(
Effect.map((owners) => parseLsofOutput(result.stdout, owners)),
),
),
Effect.catchTags({
ProcessSpawnError: (error) =>
(isCommandNotFound(error) ? Ref.set(lsofMissingRef, true) : Effect.void).pipe(
Effect.andThen(recoverLsofProbeFailure(error)),
),
ProcessStdinError: recoverLsofProbeFailure,
ProcessOutputLimitError: recoverLsofProbeFailure,
ProcessReadError: recoverLsofProbeFailure,
ProcessTimeoutError: recoverLsofProbeFailure,
}),
);
if (lsofResult !== null) return yield* probeWebServers(lsofResult, configuredUrls);
const fromProc = yield* scanProcListeners(resolveOwners);
return yield* probeWebServers(fromProc ?? [], configuredUrls);
});
const scanSnapshot = (configuredUrls: ReadonlyArray<string>) =>
scanSemaphore.withPermits(1)(scanUnlocked(configuredUrls));
const scanOnce: PortDiscovery["Service"]["scan"] = (configuredUrls = []) => {
const normalized = normalizeConfiguredUrls(configuredUrls);
return scanSnapshot(normalized).pipe(
Effect.map((snapshot) => projectWebProbeSnapshot(snapshot, normalized)),
Effect.withSpan("PortDiscovery.scan"),
);
};
const pollTick = Effect.fnUntraced(
function* () {
const configuredUrls = [
...new Set(
[...(yield* Ref.get(stateRef)).listeners.values()].flatMap(
(subscription) => subscription.configuredUrls,
),
),
];
const snapshot = yield* scanSnapshot(configuredUrls);
const notifications = yield* Ref.modify(stateRef, (state) => {
const listeners = new Map(state.listeners);
const changed: Array<readonly [Listener, ReadonlyArray<DiscoveredLocalServer>]> = [];
for (const [listener, subscription] of listeners) {
const next = projectWebProbeSnapshot(snapshot, subscription.configuredUrls);
if (serversEqual(subscription.lastSnapshot, next)) continue;
listeners.set(listener, { ...subscription, lastSnapshot: next });
changed.push([listener, next]);
}
return [changed, { ...state, listeners }];
});
yield* Effect.forEach(notifications, ([listener, servers]) => listener(servers), {
discard: true,
});
},
Effect.catchCause((cause: Cause.Cause<never>) =>
Effect.logWarning("preview port scan failed", Cause.pretty(cause)),
),
);
const pollIfRetained = Ref.get(stateRef).pipe(
Effect.flatMap((state) => (state.retainCount > 0 ? pollTick() : Effect.void)),
);
yield* Effect.forkScoped(pollIfRetained.pipe(Effect.repeat(Schedule.spaced(POLL_INTERVAL))));
const acquireRetention = Effect.fn("PortDiscovery.retain")(function* () {
const wasIdle = yield* Ref.modify(stateRef, (state) => [
state.retainCount === 0,
{ ...state, retainCount: state.retainCount + 1 },
]);
if (wasIdle) {
yield* pollTick();
}
});
const releaseRetention = Effect.gen(function* () {
const idle = yield* Ref.modify(stateRef, (state) => {
const retainCount = Math.max(0, state.retainCount - 1);
return [retainCount === 0, { ...state, retainCount }];
});
if (!idle) return;
const threads = yield* Ref.getAndSet(agentThreadsRef, new Map());
if ([...threads.values()].some((threadId) => threadId !== null)) agentScanPending = true;
});
const retain: PortDiscovery["Service"]["retain"] = Effect.acquireRelease(
acquireRetention(),
() => releaseRetention,
);
const subscribe: PortDiscovery["Service"]["subscribe"] = Effect.fn("PortDiscovery.subscribe")(
(input, listener) =>
Effect.acquireRelease(
Ref.update(stateRef, (state) => {
const listeners = new Map(state.listeners);
listeners.set(listener, {
configuredUrls: normalizeConfiguredUrls(input.configuredUrls),
lastSnapshot: input.initialSnapshot,
});
return { ...state, listeners };
}),
() =>
Ref.update(stateRef, (state) => {
const listeners = new Map(state.listeners);
listeners.delete(listener);
return { ...state, listeners };
}),
),
);
const registerTerminalProcesses: PortDiscovery["Service"]["registerTerminalProcesses"] =
Effect.fn("PortDiscovery.registerTerminalProcesses")(function* (input) {
const owner = {
threadId: ThreadId.make(input.threadId),
terminalId: input.terminalId,
};
const processIds = new Set(
input.processIds.filter((processId) => Number.isInteger(processId) && processId > 0),
);
yield* Ref.update(stateRef, (state) => {
const terminalProcesses = new Map(state.terminalProcesses);
const key = terminalOwnerKey(owner);
if (processIds.size === 0) {
terminalProcesses.delete(key);
} else {
terminalProcesses.set(key, { owner, processIds });
}
return { ...state, terminalProcesses };
});
});
const unregisterTerminal: PortDiscovery["Service"]["unregisterTerminal"] = Effect.fn(
"PortDiscovery.unregisterTerminal",
)(function* (input) {
yield* Ref.update(stateRef, (state) => {
const terminalProcesses = new Map(state.terminalProcesses);
terminalProcesses.delete(terminalOwnerKey(input));
return { ...state, terminalProcesses };
});
});
const trackAgent: PortDiscovery["Service"]["trackAgent"] = () => {
runningAgents += 1;
let released = false;
return () => {
if (released) return;
released = true;
runningAgents -= 1;
agentScanPending = true;
};
};
// Fails when `ps` does, so an empty table never reads as every process having exited.
const readProcessTable = Effect.suspend(() =>
processRunner.run({
command: "ps",
args: ["-A", "-o", "pid=,ppid=,pgid="],
timeout: Duration.millis(PS_TIMEOUT_MS),
maxOutputBytes: PS_MAX_OUTPUT_BYTES,
}),
).pipe(
Effect.mapError((cause) => new PreviewStopLocalServerError({ reason: "signal-failed", cause })),
Effect.filterOrFail(
(result) => !exitedWithError(result),
() => new PreviewStopLocalServerError({ reason: "signal-failed" }),
),
Effect.map((result) => parseProcessTable(result.stdout)),
);
const signalUntilStopped = Effect.fn("PortDiscovery.signalUntilStopped")(function* (
input: PreviewStopLocalServerInput,
) {
if (hostPlatform === "win32") {
return yield* new PreviewStopLocalServerError({ reason: "unsupported" });
}
// A socket can outlive its cached owner. Wait for any in-flight scan before invalidating
// that owner, so the /proc fallback confirms who holds it before a signal is sent.
yield* scanSemaphore.withPermits(1)(
Ref.update(
socketOwnersRef,
(owners) => new Map([...owners].filter(([, owner]) => owner.pid !== input.pid)),
),
);
// The pid comes from a client, so only a server this scan attributes to a thread is signaled,
// from its environment as read now.
yield* Ref.update(agentThreadsRef, (threads) => {
const next = new Map(threads);
next.delete(input.pid);
return next;
});
agentScanPending = true;
const listed = (yield* scanOnce()).some(
(server) => server.pid === input.pid && server.port === input.port && isOwned(server),
);
if (!listed) return yield* new PreviewStopLocalServerError({ reason: "not-found" });
const table = yield* readProcessTable;
// It exited after the scan, so there is nothing left to stop.
if (!table.has(input.pid)) return;
const group = stoppableProcessGroup(table, input.pid, process.pid);
if (group === null) return yield* new PreviewStopLocalServerError({ reason: "shared-group" });
// False when the whole group already exited.
const signalGroup = (signal: "SIGTERM" | "SIGKILL") =>
Effect.suspend(() => {
try {
signalProcessGroup(group, signal);
return Effect.succeed(true);
} catch (cause) {
return isNoSuchProcess(cause)
? Effect.succeed(false)
: Effect.fail(new PreviewStopLocalServerError({ reason: "signal-failed", cause }));
}
});
if (!(yield* signalGroup("SIGTERM"))) return;
// While one of the group's original members is still in it, the group has not been reused,
// so SIGKILL goes only to the job that ignored SIGTERM.
const members = [...table.values()].filter((row) => row.pgid === group).map((row) => row.pid);
const jobRunning = readProcessTable.pipe(
Effect.map((current) => members.some((pid) => current.get(pid)?.pgid === group)),
Effect.orElseSucceed(() => false),
);
const deadline = (yield* Clock.currentTimeMillis) + STOP_GRACE_MS;
while ((yield* Clock.currentTimeMillis) < deadline) {
yield* Effect.sleep(STOP_POLL_INTERVAL);
if (!(yield* jobRunning)) return;
}
yield* signalGroup("SIGKILL");
});
const stopServer: PortDiscovery["Service"]["stopServer"] = (input) =>
// Subscribers see the server leave now rather than on the next poll.
signalUntilStopped(input).pipe(Effect.andThen(pollIfRetained));
return PortDiscovery.of({
scan: scanOnce,
subscribe,
retain,
registerTerminalProcesses,
unregisterTerminal,
trackAgent,
stopServer,
});
}).pipe(Effect.withSpan("PortDiscovery.make"));
export const layer = Layer.effect(PortDiscovery, make);
/** A scanner that tracks nothing, for tests that build provider runners without a host. */
export const layerTest = Layer.mock(PortDiscovery)({ trackAgent: () => () => undefined });