sailfork / t3code-github / apps/ server/ src/ preview/ PortScanner.test.ts

// @effect-diagnostics nodeBuiltinImport:off -- the stop test drives real server processes.
import * as NodeChildProcess from "node:child_process";

import { it as effectIt } from "@effect/vitest";
import * as NodeServices from "@effect/platform-node/NodeServices";
import {
  CONFIGURED_LOCAL_SERVER_URLS_MAX_ITEMS,
  PREVIEW_URL_MAX_LENGTH,
  type DiscoveredLocalServer,
} from "@t3tools/contracts";
import * as ProcessGroup from "@t3tools/provider-core/server/processGroup";
import * as HostProcess from "@t3tools/shared/HostProcess";
import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as PlatformError from "effect/PlatformError";
import * as Scope from "effect/Scope";
import * as TestClock from "effect/testing/TestClock";
import { expect, vi } from "vite-plus/test";
import { FetchHttpClient } from "effect/http";

import * as ProcessRunner from "../processRunner.ts";
import * as PortScanner from "./PortScanner.ts";

vi.mock("@t3tools/provider-core/server/processGroup", { spy: true });

const processProbeFailure: ProcessRunner.ProcessRunner["Service"]["run"] = (input) =>
  Effect.fail(
    new ProcessRunner.ProcessSpawnError({
      command: input.command,
      argumentCount: input.args.length,
      cwd: input.cwd,
      cause: PlatformError.systemError({
        _tag: "NotFound",
        module: "ChildProcess",
        method: "spawn",
        description: "PowerShell is not installed in the test environment",
      }),
    }),
  );

const layerNoProc = FileSystem.layerNoop({});

const layerProbeFailure = (
  run: ProcessRunner.ProcessRunner["Service"]["run"],
  fetch: typeof globalThis.fetch = globalThis.fetch,
  fileSystem: Layer.Layer<FileSystem.FileSystem> = layerNoProc,
) =>
  PortScanner.layer.pipe(
    Layer.provide(
      Layer.mergeAll(
        fileSystem,
        Layer.succeed(ProcessRunner.ProcessRunner, { run }),
        Layer.succeed(HostProcess.Platform, "linux"),
        FetchHttpClient.layer.pipe(Layer.provide(Layer.succeed(FetchHttpClient.Fetch, fetch))),
      ),
    ),
  );

const LSOF_TEST_PORT = 43_123;

const processOutput = (stdout: string): ProcessRunner.ProcessRunOutput => ({
  stdout,
  stderr: "",
  code: ChildProcessSpawner.ExitCode(0),
  timedOut: false,
  stdoutTruncated: false,
  stderrTruncated: false,
  stdoutInvalidUtf8: false,
  stderrInvalidUtf8: false,
});

const ownedScanner = (processIds: ReadonlyArray<number> = [1234]) =>
  Effect.tap(PortScanner.PortDiscovery, (scanner) =>
    scanner.registerTerminalProcesses({
      threadId: "scanner-thread",
      terminalId: "scanner-terminal",
      processIds,
    }),
  );

const layerLsofScanner = (input: {
  readonly pid: () => number;
  readonly fetch: typeof globalThis.fetch;
  readonly stdout?: () => string;
}) =>
  PortScanner.layer.pipe(
    Layer.provide(
      Layer.mergeAll(
        layerNoProc,
        Layer.succeed(ProcessRunner.ProcessRunner, {
          run: () =>
            Effect.succeed({
              stdout: input.stdout?.() ?? `p${input.pid()}\ncnode\nn*:${LSOF_TEST_PORT}\n`,
              stderr: "",
              code: null,
              timedOut: false,
              stdoutTruncated: false,
              stderrTruncated: false,
              stdoutInvalidUtf8: false,
              stderrInvalidUtf8: false,
            }),
        }),
        Layer.succeed(HostProcess.Platform, "linux"),
        FetchHttpClient.layer.pipe(
          Layer.provide(Layer.succeed(FetchHttpClient.Fetch, input.fetch)),
        ),
      ),
    ),
  );

effectIt.effect("keeps a full configured URL when the discovered server root fails", () => {
  const requests: string[] = [];
  const configuredUrl = `http://localhost:${LSOF_TEST_PORT}/docs`;
  const fetchFn = ((input: Parameters<typeof globalThis.fetch>[0]) => {
    const url = String(input);
    requests.push(url);
    return Promise.resolve(
      url === configuredUrl
        ? new Response("docs", { headers: { "content-type": "text/html" } })
        : new Response("not found", {
            status: 404,
            headers: { "content-type": "text/html" },
          }),
    );
  }) as typeof globalThis.fetch;
  const layer = layerLsofScanner({ pid: () => 1234, fetch: fetchFn });

  return Effect.gen(function* () {
    const scanner = yield* PortScanner.PortDiscovery;
    const servers = yield* scanner.scan([configuredUrl]);
    expect(servers).toHaveLength(1);
    expect(servers[0]?.url).toBe(configuredUrl);
    expect(requests).toContain(configuredUrl);
  }).pipe(Effect.provide(layer));
});

effectIt.effect("probes configured custom ports through a canonical loopback host", () => {
  const customPort = 43_124;
  const configuredUrl = `http://0.0.0.0:${customPort}/docs`;
  const expectedUrl = `http://localhost:${customPort}/docs`;
  const requests: string[] = [];
  const fetchFn = ((input: Parameters<typeof globalThis.fetch>[0]) => {
    requests.push(String(input));
    return Promise.resolve(new Response("docs", { headers: { "content-type": "text/html" } }));
  }) as typeof globalThis.fetch;
  const layer = layerProbeFailure(processProbeFailure, fetchFn);

  return Effect.gen(function* () {
    const scanner = yield* PortScanner.PortDiscovery;
    const servers = yield* scanner.scan([configuredUrl]);
    expect(servers).toHaveLength(1);
    expect(servers[0]?.host).toBe("localhost");
    expect(servers[0]?.port).toBe(customPort);
    expect(servers[0]?.url).toBe(expectedUrl);
    expect(requests).toEqual([expectedUrl]);
  }).pipe(Effect.provide(layer));
});

effectIt.effect("preserves explicit loopback hosts and bounds wildcard rewrites", () => {
  const ipv4Url = "https://127.0.0.1:43125/docs";
  const ipv6Url = "http://[::1]:43126/docs";
  const wildcardPrefix = "http://0.0.0.0/";
  const maximumWildcardUrl = `${wildcardPrefix}${"a".repeat(
    PREVIEW_URL_MAX_LENGTH - wildcardPrefix.length,
  )}`;
  const requests: string[] = [];
  const fetchFn = ((input: Parameters<typeof globalThis.fetch>[0]) => {
    requests.push(String(input));
    return Promise.resolve(new Response("docs", { headers: { "content-type": "text/html" } }));
  }) as typeof globalThis.fetch;
  const layer = layerProbeFailure(processProbeFailure, fetchFn);

  return Effect.gen(function* () {
    const scanner = yield* PortScanner.PortDiscovery;
    const servers = yield* scanner.scan([ipv4Url, ipv6Url, maximumWildcardUrl]);
    expect(servers.map((server) => server.url)).toEqual([ipv4Url, ipv6Url]);
    expect(requests).toEqual([ipv4Url, ipv6Url]);
  }).pipe(Effect.provide(layer));
});

effectIt.effect("projects configured paths independently for simultaneous subscribers", () => {
  const docsUrl = `http://localhost:${LSOF_TEST_PORT}/docs`;
  const adminUrl = `http://localhost:${LSOF_TEST_PORT}/admin`;
  let ready = true;
  const fetchFn = ((input: Parameters<typeof globalThis.fetch>[0]) => {
    const url = String(input);
    return Promise.resolve(
      ready && (url === docsUrl || url === adminUrl)
        ? new Response("app", { headers: { "content-type": "text/html" } })
        : new Response("not found", { status: 404 }),
    );
  }) as typeof globalThis.fetch;
  const layer = layerLsofScanner({ pid: () => 1234, fetch: fetchFn });

  return Effect.gen(function* () {
    const scanner = yield* ownedScanner();
    const docsSnapshots: ReadonlyArray<DiscoveredLocalServer>[] = [];
    const adminSnapshots: ReadonlyArray<DiscoveredLocalServer>[] = [];
    yield* scanner.subscribe({ configuredUrls: [docsUrl], initialSnapshot: [] }, (servers) =>
      Effect.sync(() => docsSnapshots.push(servers)),
    );
    yield* scanner.subscribe({ configuredUrls: [adminUrl], initialSnapshot: [] }, (servers) =>
      Effect.sync(() => adminSnapshots.push(servers)),
    );
    yield* scanner.retain;

    expect(docsSnapshots.at(-1)?.[0]?.url).toBe(docsUrl);
    expect(adminSnapshots.at(-1)?.[0]?.url).toBe(adminUrl);

    ready = false;
    yield* TestClock.adjust(Duration.seconds(15));
    expect(docsSnapshots.at(-1)?.[0]?.url).toBe(docsUrl);
    expect(adminSnapshots.at(-1)?.[0]?.url).toBe(adminUrl);
  }).pipe(Effect.scoped, Effect.provide(layer));
});

effectIt.effect(
  "keeps each subscriber's candidates when their combined union exceeds the per-client cap",
  () => {
    const firstSubscriberUrls = Array.from(
      { length: CONFIGURED_LOCAL_SERVER_URLS_MAX_ITEMS },
      (_, index) => `http://localhost:${LSOF_TEST_PORT}/app-${index}`,
    );
    const secondSubscriberUrl = `http://localhost:${LSOF_TEST_PORT}/app-${CONFIGURED_LOCAL_SERVER_URLS_MAX_ITEMS}`;
    const fetchFn = ((input: Parameters<typeof globalThis.fetch>[0]) =>
      Promise.resolve(
        String(input) === secondSubscriberUrl
          ? new Response("app", { headers: { "content-type": "text/html" } })
          : new Response("not found", { status: 404 }),
      )) as typeof globalThis.fetch;
    const layer = layerLsofScanner({ pid: () => 1234, fetch: fetchFn });

    return Effect.gen(function* () {
      const scanner = yield* PortScanner.PortDiscovery;
      const secondSnapshots: ReadonlyArray<DiscoveredLocalServer>[] = [];
      yield* scanner.subscribe(
        { configuredUrls: firstSubscriberUrls, initialSnapshot: [] },
        () => Effect.void,
      );
      yield* scanner.subscribe(
        { configuredUrls: [secondSubscriberUrl], initialSnapshot: [] },
        (servers) => Effect.sync(() => secondSnapshots.push(servers)),
      );
      yield* scanner.retain;

      expect(secondSnapshots.at(-1)?.[0]?.url).toBe(secondSubscriberUrl);
    }).pipe(Effect.scoped, Effect.provide(layer));
  },
);

effectIt.effect("stops probing a subscriber's configured paths after its scope closes", () => {
  const docsUrl = `http://localhost:${LSOF_TEST_PORT}/docs`;
  const adminUrl = `http://localhost:${LSOF_TEST_PORT}/admin`;
  const requests: string[] = [];
  const fetchFn = ((input: Parameters<typeof globalThis.fetch>[0]) => {
    const url = String(input);
    requests.push(url);
    return Promise.resolve(
      url === docsUrl || url === adminUrl
        ? new Response("app", { headers: { "content-type": "text/html" } })
        : new Response("not found", { status: 404 }),
    );
  }) as typeof globalThis.fetch;
  const layer = layerLsofScanner({ pid: () => 1234, fetch: fetchFn });

  return Effect.gen(function* () {
    const scanner = yield* PortScanner.PortDiscovery;
    const docsScope = yield* Scope.make();
    yield* scanner
      .subscribe({ configuredUrls: [docsUrl], initialSnapshot: [] }, () => Effect.void)
      .pipe(Effect.provideService(Scope.Scope, docsScope));
    yield* scanner.subscribe(
      { configuredUrls: [adminUrl], initialSnapshot: [] },
      () => Effect.void,
    );
    yield* scanner.retain;
    yield* Scope.close(docsScope, Exit.void);

    requests.length = 0;
    yield* TestClock.adjust(Duration.seconds(15));
    expect(requests).toContain(adminUrl);
    expect(requests).not.toContain(docsUrl);
  }).pipe(Effect.scoped, Effect.provide(layer));
});

effectIt.effect("uses the current configured fragment when readiness comes from cache", () => {
  const requests: string[] = [];
  const fetchFn = ((input: Parameters<typeof globalThis.fetch>[0]) => {
    requests.push(String(input));
    return Promise.resolve(new Response("docs", { headers: { "content-type": "text/html" } }));
  }) as typeof globalThis.fetch;
  const layer = layerLsofScanner({ pid: () => 1234, fetch: fetchFn });
  const oldUrl = `http://localhost:${LSOF_TEST_PORT}/docs#old`;
  const newUrl = `http://localhost:${LSOF_TEST_PORT}/docs#new`;

  return Effect.gen(function* () {
    const scanner = yield* PortScanner.PortDiscovery;
    expect((yield* scanner.scan([oldUrl]))[0]?.url).toBe(oldUrl);
    const requestCount = requests.length;
    expect((yield* scanner.scan([newUrl]))[0]?.url).toBe(newUrl);
    expect(requests).toHaveLength(requestCount);
  }).pipe(Effect.provide(layer));
});

effectIt.effect(
  "probes only a configured HTTPS URL, keeps it for an owned listener when the check fails, and does not follow redirects",
  () => {
    const configuredUrl = `https://localhost:${LSOF_TEST_PORT}/app`;
    const requests: Array<readonly [string, string | undefined]> = [];
    let respond = async () =>
      new Response(null, { status: 302, headers: { location: "https://example.com" } });
    const fetchFn = (async (
      input: Parameters<typeof globalThis.fetch>[0],
      init?: Parameters<typeof globalThis.fetch>[1],
    ) => {
      requests.push([String(input), init?.redirect]);
      return respond();
    }) as typeof globalThis.fetch;
    const layer = layerLsofScanner({ pid: () => 1234, fetch: fetchFn });

    return Effect.gen(function* () {
      const scanner = yield* ownedScanner();
      expect(yield* scanner.scan([configuredUrl])).toMatchObject([
        { pid: 1234, url: configuredUrl },
      ]);

      respond = async () => new Response("unavailable", { status: 503 });
      yield* TestClock.adjust(Duration.seconds(15));
      expect(yield* scanner.scan([configuredUrl])).toMatchObject([
        { pid: 1234, url: configuredUrl },
      ]);

      respond = () => Promise.reject(new TypeError("fetch failed"));
      yield* TestClock.adjust(Duration.seconds(15));
      expect(yield* scanner.scan([configuredUrl])).toMatchObject([
        { pid: 1234, url: configuredUrl },
      ]);
      expect(requests).toEqual(Array.from({ length: 3 }, () => [configuredUrl, "manual"]));
    }).pipe(Effect.provide(layer));
  },
);

effectIt.effect("discovers owned listeners without sending HTTP or TLS probes", () => {
  const owned = `p1234\ncnode\nn[::1]:${LSOF_TEST_PORT}\n`;
  const unowned = `p5678\ncrpc\nn127.0.0.1:${LSOF_TEST_PORT}\n`;
  let stdout = unowned;
  const requests: string[] = [];
  const fetchFn = ((input: Parameters<typeof globalThis.fetch>[0]) => {
    requests.push(String(input));
    return Promise.resolve(new Response("app", { headers: { "content-type": "text/html" } }));
  }) as typeof globalThis.fetch;
  const layer = layerLsofScanner({ pid: () => 1234, fetch: fetchFn, stdout: () => stdout });

  return Effect.gen(function* () {
    const scanner = yield* ownedScanner();
    expect(yield* scanner.scan()).toHaveLength(0);
    stdout = `${owned}${unowned}`;
    expect(yield* scanner.scan()).toHaveLength(0);
    expect(requests).toEqual([]);

    stdout = owned;
    expect(yield* scanner.scan()).toHaveLength(1);
    expect(requests).toEqual([]);

    yield* scanner.unregisterTerminal({
      threadId: "scanner-thread",
      terminalId: "scanner-terminal",
    });
    expect(yield* scanner.scan()).toHaveLength(0);
    expect(requests).toEqual([]);
  }).pipe(Effect.provide(layer));
});

effectIt.effect(
  "excludes configured URLs answering with HTTP errors, non-navigation responses, or non-documents",
  () => {
    let pid = 1;
    let makeResponse = () =>
      new Response("not found", { status: 404, headers: { "content-type": "text/html" } });
    const fetchFn = ((_input: Parameters<typeof globalThis.fetch>[0]) =>
      Promise.resolve(makeResponse())) as typeof globalThis.fetch;
    const layer = layerLsofScanner({ pid: () => pid, fetch: fetchFn });
    const configuredUrl = `http://localhost:${LSOF_TEST_PORT}/`;

    return Effect.gen(function* () {
      const scanner = yield* PortScanner.PortDiscovery;
      const scan = () => scanner.scan([configuredUrl]);
      expect(yield* scan()).toHaveLength(0);

      pid += 1;
      makeResponse = () =>
        new Response("{}", { status: 200, headers: { "content-type": "application/json" } });
      expect(yield* scan()).toHaveLength(0);

      pid += 1;
      makeResponse = () =>
        new Response("ready", { status: 200, headers: { "content-type": "text/plain" } });
      expect(yield* scan()).toHaveLength(0);

      pid += 1;
      makeResponse = () => new Response(null, { status: 304, headers: { location: "/cached" } });
      expect(yield* scan()).toHaveLength(0);

      pid += 1;
      makeResponse = () =>
        new Response(null, { status: 204, headers: { "content-type": "text/html" } });
      expect(yield* scan()).toHaveLength(0);

      pid += 1;
      makeResponse = () => new Response(null, { status: 302 });
      expect(yield* scan()).toHaveLength(0);

      pid += 1;
      makeResponse = () =>
        new Response("<html />", {
          status: 200,
          headers: { "content-type": "application/xhtml+xml; charset=utf-8" },
        });
      expect(yield* scan()).toHaveLength(1);
    }).pipe(Effect.provide(layer));
  },
);

const PROC_NET_TCP = `  sl  local_address rem_address   st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode
   0: 0100007F:223D 00000000:0000 0A 00000000:00000000 00:00000000 00000000  1000        0 5001 1 0000000000000000 100 0 0 10 0
   1: 00000000:0016 00000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 5002 1 0000000000000000 100 0 0 10 0
   2: 0100007F:223D 0100007F:C350 01 00000000:00000000 00:00000000 00000000  1000        0 5003 1 0000000000000000 20 4 30 10 -1
   3: 0A00000F:1F90 00000000:0000 0A 00000000:00000000 00:00000000 00000000  1000        0 5005 1 0000000000000000 100 0 0 10 0
`;
const PROC_NET_TCP6 = `  sl  local_address                         remote_address                        st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode
   0: 00000000000000000000000000000000:0BB9 00000000000000000000000000000000:0000 0A 00000000:00000000 00:00000000 00000000  1000        0 5004 1 0000000000000000 100 0 0 10 0
`;

effectIt.effect(
  "reads Linux listeners from /proc when lsof is missing, and stops spawning it",
  () => {
    let lsofSpawns = 0;
    const fdWalks: string[] = [];
    const procFiles: Record<string, string> = {
      "/proc/net/tcp": PROC_NET_TCP,
      "/proc/net/tcp6": PROC_NET_TCP6,
      "/proc/4242/comm": "python3\n",
    };
    const procFds: Record<string, Record<string, string>> = {
      "4242": { "0": "/dev/null", "3": "socket:[5001]" },
      "77": { "5": "socket:[9999]" },
    };
    const missing = FileSystem.makeNoop({});
    const fileSystem = FileSystem.layerNoop({
      readFileString: (path) => {
        const content = procFiles[path];
        return content === undefined ? missing.readFileString(path) : Effect.succeed(content);
      },
      readDirectory: (path) => {
        if (path === "/proc") return Effect.succeed(["self", "77", "4242"]);
        const pid = /^\/proc\/(\d+)\/fd$/.exec(path)?.[1];
        const fds = pid === undefined ? undefined : procFds[pid];
        if (pid === undefined || fds === undefined) return missing.readDirectory(path);
        fdWalks.push(pid);
        return Effect.succeed(Object.keys(fds));
      },
      readLink: (path) => {
        const [, pid, fd] = /^\/proc\/(\d+)\/fd\/(\d+)$/.exec(path) ?? [];
        const target = pid && fd ? procFds[pid]?.[fd] : undefined;
        return target === undefined ? missing.readLink(path) : Effect.succeed(target);
      },
    });
    const requests: string[] = [];
    const fetchFn = ((input: Parameters<typeof globalThis.fetch>[0]) => {
      requests.push(String(input));
      return Promise.resolve(new Response("hello", { headers: { "content-type": "text/html" } }));
    }) as typeof globalThis.fetch;
    const layer = layerProbeFailure(
      (input) => {
        lsofSpawns += 1;
        return processProbeFailure(input);
      },
      fetchFn,
      fileSystem,
    );

    return Effect.gen(function* () {
      const scanner = yield* ownedScanner([4242]);
      const first = yield* scanner.scan();
      expect(
        first.map(({ port, pid, processName, url }) => ({ port, pid, processName, url })),
      ).toEqual([{ port: 8765, pid: 4242, processName: "python3", url: "http://localhost:8765" }]);
      yield* scanner.scan();
      expect(lsofSpawns).toBe(1);
      expect(fdWalks).toEqual(["77", "4242", "77", "4242"]);
      yield* scanner.scan();
      yield* scanner.scan();
      expect(fdWalks).toEqual(["77", "4242", "77", "4242", "77", "4242"]);
      expect(requests).toEqual([]);
    }).pipe(Effect.provide(layer));
  },
);

effectIt.effect("ignores a partial Windows netstat snapshot when one query exits nonzero", () => {
  let ipv6Fails = true;
  const requests: string[] = [];
  const fetchFn = ((input: Parameters<typeof globalThis.fetch>[0]) => {
    requests.push(String(input));
    return Promise.resolve(new Response("hello", { headers: { "content-type": "text/html" } }));
  }) as typeof globalThis.fetch;
  const layer = PortScanner.layer.pipe(
    Layer.provide(
      Layer.mergeAll(
        layerNoProc,
        Layer.succeed(ProcessRunner.ProcessRunner, {
          run: (input) => {
            if (input.command === "tasklist.exe") {
              return Effect.succeed(
                processOutput('"node.exe","1234","Console","1","50,000 K"\r\n'),
              );
            }
            const isIpv6 = input.args.includes("tcpv6");
            return Effect.succeed({
              stdout: isIpv6
                ? ""
                : "  TCP    127.0.0.1:5173         0.0.0.0:0              LISTENING       1234\r\n",
              stderr: "",
              code: isIpv6 && ipv6Fails ? ChildProcessSpawner.ExitCode(1) : null,
              timedOut: false,
              stdoutTruncated: false,
              stderrTruncated: false,
              stdoutInvalidUtf8: false,
              stderrInvalidUtf8: false,
            });
          },
        }),
        Layer.succeed(HostProcess.Platform, "win32"),
        FetchHttpClient.layer.pipe(Layer.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn))),
      ),
    ),
  );

  return Effect.gen(function* () {
    const scanner = yield* PortScanner.PortDiscovery;
    yield* scanner.registerTerminalProcesses({
      threadId: "scanner-thread",
      terminalId: "scanner-terminal",
      processIds: [1234],
    });
    expect(yield* scanner.scan()).toEqual([]);
    ipv6Fails = false;
    expect(yield* scanner.scan()).toMatchObject([
      { port: 5173, pid: 1234, processName: "node", url: "http://localhost:5173" },
    ]);
    expect(requests).toEqual([]);
  }).pipe(Effect.provide(layer));
});

effectIt.effect("rechecks the socket owner before stopping a Linux server without lsof", () => {
  let holder = "4242";
  const missing = FileSystem.makeNoop({});
  const layer = layerProbeFailure(
    (input) =>
      input.command === "lsof"
        ? processProbeFailure(input)
        : Effect.succeed(processOutput("4242 1 4300\n5000 1 5300\n")),
    () => Promise.resolve(new Response("app", { headers: { "content-type": "text/html" } })),
    FileSystem.layerNoop({
      readFileString: (path) => {
        if (path === "/proc/net/tcp") {
          return Effect.succeed(PROC_NET_TCP.split("\n").slice(0, 2).join("\n"));
        }
        if (/^\/proc\/(4242|5000)\/comm$/.test(path)) return Effect.succeed("node\n");
        if (/^\/proc\/(4242|5000)\/environ$/.test(path)) {
          return Effect.succeed(`${PortScanner.AGENT_THREAD_ENV}=thread-agent\0`);
        }
        return missing.readFileString(path);
      },
      readDirectory: (path) => {
        if (path === "/proc") return Effect.succeed(["4242", "5000"]);
        if (/^\/proc\/(4242|5000)\/fd$/.test(path)) {
          return Effect.succeed(path === `/proc/${holder}/fd` ? ["3"] : []);
        }
        return missing.readDirectory(path);
      },
      readLink: (path) =>
        path === `/proc/${holder}/fd/3` ? Effect.succeed("socket:[5001]") : missing.readLink(path),
    }),
  );

  return Effect.gen(function* () {
    const signal = vi.spyOn(ProcessGroup, "signalProcessGroup").mockImplementation(() => {
      throw Object.assign(new Error("No such process"), { code: "ESRCH" });
    });
    yield* Effect.addFinalizer(() => Effect.sync(() => signal.mockRestore()));
    const scanner = yield* PortScanner.PortDiscovery;
    expect(yield* scanner.scan()).toMatchObject([{ pid: 4242, port: 8765 }]);

    // The socket outlives its original holder. Its old pid now belongs to another agent job.
    holder = "5000";
    const result = yield* scanner
      .stopServer({ pid: 4242, port: 8765 })
      .pipe(Effect.match({ onFailure: (error) => error.reason, onSuccess: () => null }));
    expect(signal).not.toHaveBeenCalled();
    expect(result).toBe("not-found");
    expect(yield* scanner.scan()).toMatchObject([{ pid: 5000, port: 8765 }]);
    yield* scanner.stopServer({ pid: 5000, port: 8765 });
    expect(signal).toHaveBeenCalledExactlyOnceWith(5300, "SIGTERM");
  }).pipe(Effect.provide(layer));
});

effectIt.effect.each(["linux", "darwin", "win32"] as const)(
  "reads no listeners on %s while T3CODE_PORT_DISCOVERY=0, and still probes configured URLs",
  (platform) => {
    const configuredUrl = `http://localhost:${LSOF_TEST_PORT}/docs`;
    const commands: string[] = [];
    const fileReads: string[] = [];
    const requests: string[] = [];
    const missing = FileSystem.makeNoop({});
    const layer = PortScanner.layer.pipe(
      Layer.provide(
        Layer.mergeAll(
          FileSystem.layerNoop({
            readFileString: (path) => {
              fileReads.push(path);
              return missing.readFileString(path);
            },
            readDirectory: (path) => {
              fileReads.push(path);
              return missing.readDirectory(path);
            },
          }),
          Layer.succeed(ProcessRunner.ProcessRunner, {
            run: (input) => {
              commands.push(input.command);
              return Effect.succeed(processOutput(`p1234\ncnode\nn*:${LSOF_TEST_PORT}\n`));
            },
          }),
          Layer.succeed(HostProcess.Platform, platform),
          Layer.succeed(HostProcess.Environment, { T3CODE_PORT_DISCOVERY: "0" }),
          FetchHttpClient.layer.pipe(
            Layer.provide(
              Layer.succeed(FetchHttpClient.Fetch, (input) => {
                requests.push(String(input));
                return Promise.resolve(
                  new Response("docs", { headers: { "content-type": "text/html" } }),
                );
              }),
            ),
          ),
        ),
      ),
    );

    return Effect.gen(function* () {
      const scanner = yield* ownedScanner();
      scanner.trackAgent();
      expect(yield* scanner.scan()).toEqual([]);
      expect(yield* scanner.scan([configuredUrl])).toMatchObject([
        { port: LSOF_TEST_PORT, pid: null, terminal: null, url: configuredUrl },
      ]);
      expect(requests).toEqual([configuredUrl]);
      expect(commands).toEqual([]);
      expect(fileReads).toEqual([]);
    }).pipe(Effect.provide(layer));
  },
);

effectIt.effect.each(["linux", "darwin"] as const)(
  "attributes listeners to the agent thread in their environment on %s, after the agent exits",
  (platform) => {
    const agentPort = 43_124;
    const otherPort = 43_125;
    const agentListener = `p4242\ncnode\nn127.0.0.1:${agentPort}\n`;
    const otherListener = `p5000\ncpostgres\nn127.0.0.1:${otherPort}\n`;
    let lsofStdout = otherListener;
    let lsofFails = false;
    let environmentFails = false;
    let lsofCalls = 0;
    let environmentReads = 0;
    const requests: string[] = [];
    const missing = FileSystem.makeNoop({});
    const procEnviron: Record<string, string> = {
      "/proc/4242/environ": `PATH=/usr/bin\0${PortScanner.AGENT_THREAD_ENV}=thread-agent\0`,
      "/proc/5000/environ": "PATH=/usr/bin\0",
    };
    const layer = PortScanner.layer.pipe(
      Layer.provide(
        Layer.mergeAll(
          FileSystem.layerNoop({
            readFileString: (path) => {
              const content = procEnviron[path];
              if (content === undefined) return missing.readFileString(path);
              environmentReads += 1;
              return Effect.succeed(content);
            },
          }),
          Layer.succeed(ProcessRunner.ProcessRunner, {
            run: (input) => {
              if (input.command === "lsof") {
                lsofCalls += 1;
                return lsofFails
                  ? Effect.fail(
                      new ProcessRunner.ProcessTimeoutError({
                        command: input.command,
                        argumentCount: input.args.length,
                        cwd: input.cwd,
                        timeoutMs: 5_000,
                      }),
                    )
                  : Effect.succeed(processOutput(lsofStdout));
              }
              // A direct child of this process, so stop refuses it without signaling anything.
              if (input.args[0] === "-A") {
                return Effect.succeed(processOutput(`4242 ${process.pid} 4242\n`));
              }
              if (environmentFails) {
                return Effect.fail(
                  new ProcessRunner.ProcessTimeoutError({
                    command: input.command,
                    argumentCount: input.args.length,
                    timeoutMs: 5_000,
                  }),
                );
              }
              environmentReads += 1;
              return Effect.succeed(
                processOutput(
                  `  4242 node server.js PATH=/usr/bin ${PortScanner.AGENT_THREAD_ENV}=thread-agent HOME=/Users/dev\n` +
                    "  5000 postgres -D /data PATH=/usr/bin\n",
                ),
              );
            },
          }),
          Layer.succeed(HostProcess.Platform, platform),
          FetchHttpClient.layer.pipe(
            Layer.provide(
              Layer.succeed(FetchHttpClient.Fetch, (input) => {
                requests.push(String(input));
                return Promise.resolve(
                  new Response("app", { headers: { "content-type": "text/html" } }),
                );
              }),
            ),
          ),
        ),
      ),
    );

    return Effect.gen(function* () {
      const scanner = yield* PortScanner.PortDiscovery;
      // Startup reads listeners once. With none marked, later scans stay idle.
      expect(yield* scanner.scan()).toEqual([]);
      expect(yield* scanner.scan()).toEqual([]);
      expect(lsofCalls).toBe(1);

      // The agent exits before any client looks, and the first read fails; its server is still
      // found.
      lsofStdout = `${agentListener}${otherListener}`;
      scanner.trackAgent()();
      lsofFails = true;
      expect(yield* scanner.scan()).toEqual([]);
      lsofFails = false;
      if (platform === "darwin") {
        environmentFails = true;
        expect(yield* scanner.scan()).toEqual([]);
        environmentFails = false;
      }
      expect(yield* scanner.scan()).toMatchObject([
        { port: agentPort, pid: 4242, terminal: null, agent: { threadId: "thread-agent" } },
      ]);
      expect(requests).toEqual([]);

      expect(yield* scanner.scan()).toHaveLength(1);
      expect(environmentReads).toBe(2);

      // Stop reads its target's environment again rather than trust the cache, and still finds it.
      const stop = yield* Effect.flip(scanner.stopServer({ pid: 4242, port: agentPort }));
      expect(stop.reason).toBe("shared-group");
      expect(environmentReads).toBe(3);

      lsofStdout = otherListener;
      expect(yield* scanner.scan()).toEqual([]);
      const lsofCallsAfterExit = lsofCalls;
      expect(yield* scanner.scan()).toEqual([]);
      expect(lsofCalls).toBe(lsofCallsAfterExit);
    }).pipe(Effect.provide(layer));
  },
);

effectIt.effect("stops only a job's own process group", () =>
  Effect.sync(() => {
    const serverPid = 100;
    const rows = [
      { pid: 10, ppid: 1, pgid: 10 }, // `vp run dev`, whose job holds this server
      { pid: 20, ppid: 10, pgid: 10 }, // the web dev server in the same job
      { pid: serverPid, ppid: 10, pgid: 10 },
      { pid: 200, ppid: serverPid, pgid: 200 }, // agent CLI
      { pid: 210, ppid: 200, pgid: 200 }, // a server it spawned without a group of its own
      { pid: 300, ppid: 200, pgid: 300 }, // agent tool shell
      { pid: 400, ppid: 300, pgid: 400 }, // `npm run dev &`
      { pid: 401, ppid: 400, pgid: 400 },
      { pid: 500, ppid: serverPid, pgid: 500 }, // terminal shell
      { pid: 600, ppid: 500, pgid: 600 }, // terminal job
    ];
    const table = new Map(rows.map((row) => [row.pid, row]));
    expect(PortScanner.stoppableProcessGroup(table, 401, serverPid)).toBe(400);
    expect(PortScanner.stoppableProcessGroup(table, 600, serverPid)).toBe(600);
    for (const pid of [20, 210, 500, 999]) {
      expect(PortScanner.stoppableProcessGroup(table, pid, serverPid)).toBeNull();
    }
  }),
);

const AGENT_SERVER_SCRIPT = `
const server = require("node:http").createServer((_, response) => {
  response.writeHead(200, { "content-type": "text/html" });
  response.end("<html></html>");
});
server.listen(0, "127.0.0.1", () => {
  process.stdout.write(process.pid + " " + server.address().port + "\\n");
});
`;

/**
 * A real HTML server with an agent's environment, started the way an agent's tool shell starts a
 * job: under a detached shell with job control, in a group of its own. Release kills only the pids
 * it started.
 */
const agentServer = () =>
  Effect.acquireRelease(
    Effect.callback<{
      readonly child: NodeChildProcess.ChildProcess;
      readonly pid: number;
      readonly port: number;
      readonly exited: Promise<void>;
    }>((resume) => {
      const env = { ...process.env, [PortScanner.AGENT_THREAD_ENV]: "thread-live" };
      // dash ignores `set -m` without a terminal; bash, like agent tool shells, honors it.
      const child = NodeChildProcess.spawn(
        "bash",
        ["-c", 'set -m; "$0" -e "$1" & wait', process.execPath, AGENT_SERVER_SCRIPT],
        { detached: true, env, stdio: ["ignore", "pipe", "ignore"] },
      );
      const exited = new Promise<void>((resolve) => child.once("exit", () => resolve()));
      child.once("error", (error) => resume(Effect.die(error)));
      child.stdout?.once("data", (chunk) => {
        const [pid, port] = String(chunk).trim().split(" ").map(Number);
        resume(Effect.succeed({ child, pid: pid!, port: port!, exited }));
      });
    }),
    ({ child, pid }) =>
      Effect.sync(() => {
        for (const target of [pid, child.pid]) {
          try {
            if (target !== undefined) process.kill(target, "SIGKILL");
          } catch {}
        }
      }),
  );

const isRunning = (pid: number): boolean => {
  try {
    process.kill(pid, 0);
    return true;
  } catch {
    return false;
  }
};

effectIt.live.skipIf(HostProcess.Platform.defaultValue() === "win32")(
  "stops an agent's server through its job's group, and only a listed server",
  () =>
    Effect.gen(function* () {
      const scanner = yield* PortScanner.PortDiscovery;
      yield* Effect.acquireRelease(Effect.sync(scanner.trackAgent), (release) =>
        Effect.sync(release),
      );
      const job = yield* agentServer();

      expect(yield* scanner.scan()).toEqual(
        expect.arrayContaining([
          expect.objectContaining({
            pid: job.pid,
            port: job.port,
            agent: { threadId: "thread-live" },
          }),
        ]),
      );

      const unlisted = yield* Effect.flip(scanner.stopServer({ pid: process.pid, port: job.port }));
      expect(unlisted.reason).toBe("not-found");

      yield* scanner.stopServer({ pid: job.pid, port: job.port });
      // The shell waits on its job, so it exits once the job has.
      yield* Effect.promise(() => job.exited);
      expect(isRunning(job.pid)).toBe(false);
    }).pipe(
      Effect.scoped,
      Effect.provide(
        PortScanner.layer.pipe(
          Layer.provide(ProcessRunner.layer),
          Layer.provide(Layer.mergeAll(NodeServices.layer, FetchHttpClient.layer)),
        ),
      ),
    ),
);