mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
* fix(cli): preview --stop signals only a process the system says owns the port * style(cli): format the preview stop tests
792 lines
27 KiB
TypeScript
792 lines
27 KiB
TypeScript
import { spawn as nodeSpawn } from "node:child_process";
|
|
import { createHash } from "node:crypto";
|
|
import {
|
|
closeSync,
|
|
existsSync,
|
|
mkdirSync,
|
|
openSync,
|
|
readFileSync,
|
|
readdirSync,
|
|
renameSync,
|
|
rmSync,
|
|
writeFileSync,
|
|
} from "node:fs";
|
|
import { devNull, homedir } from "node:os";
|
|
import { dirname, join, resolve } from "node:path";
|
|
import { stripVTControlCharacters } from "node:util";
|
|
import {
|
|
activeServerOnPort,
|
|
MAX_PORT_SCAN,
|
|
scanActiveServers,
|
|
type ActiveServer,
|
|
} from "../server/portUtils.js";
|
|
import { namedCacheDir } from "@hyperframes/core/cache-dir";
|
|
import type { BrowserGpuMode } from "../browser/gpuPolicy.js";
|
|
import { windowsLocalAppData } from "../utils/windowsAppData.js";
|
|
import { isProcessDescendant, processIdentity } from "../utils/orphanCleanup.js";
|
|
import { terminateProcessTree } from "../utils/processTree.js";
|
|
import { PreviewServerPortMismatchError } from "../utils/studioSelectionClient.js";
|
|
|
|
export class PreviewPortUnavailableError extends Error {
|
|
readonly requestedPort: number;
|
|
readonly boundPort: number;
|
|
|
|
constructor(requestedPort: number, boundPort: number) {
|
|
super(
|
|
`Port ${requestedPort} is already in use; the background preview would have started on port ${boundPort} instead. Free port ${requestedPort}, pick another --port, or omit --port to accept the next free port.`,
|
|
);
|
|
this.name = "PreviewPortUnavailableError";
|
|
this.requestedPort = requestedPort;
|
|
this.boundPort = boundPort;
|
|
}
|
|
}
|
|
|
|
export interface PreviewSession {
|
|
pid: number;
|
|
wrapperIdentity?: string;
|
|
port: number;
|
|
projectDir: string;
|
|
logPath: string;
|
|
}
|
|
|
|
type PreviewStatus = Pick<PreviewSession, "port" | "projectDir"> & {
|
|
pid: number | null;
|
|
logPath?: string;
|
|
};
|
|
|
|
type SpawnResult = {
|
|
pid?: number;
|
|
unref(): void;
|
|
once?(event: "exit", listener: (code: number | null, signal: string | null) => void): unknown;
|
|
};
|
|
type SpawnPreview = (
|
|
command: string,
|
|
args: string[],
|
|
options: {
|
|
detached: boolean;
|
|
windowsHide: boolean;
|
|
stdio: ["ignore", number, number];
|
|
env: NodeJS.ProcessEnv;
|
|
},
|
|
) => SpawnResult;
|
|
|
|
interface LifecycleDependencies {
|
|
argv?: string[];
|
|
execPath?: string;
|
|
scan?: (startPort?: number) => Promise<ActiveServer[]>;
|
|
spawn?: SpawnPreview;
|
|
sleep?: (ms: number) => Promise<void>;
|
|
kill?: (pid: number) => void | Promise<void>;
|
|
isDescendant?: (childPid: number, ancestorPid: number) => boolean;
|
|
identity?: (pid: number) => string | null;
|
|
isSignalable?: (pid: number) => boolean;
|
|
probe?: (port: number) => Promise<ActiveServer | null>;
|
|
stateHome?: string;
|
|
forceNew?: boolean;
|
|
browserGpuMode?: BrowserGpuMode;
|
|
/** Set only when the caller explicitly passed --port, not the CLI default. */
|
|
preferredPort?: number;
|
|
}
|
|
|
|
function defaultStateHome(): string {
|
|
return (
|
|
namedCacheDir("state") ||
|
|
process.env.XDG_STATE_HOME ||
|
|
windowsLocalAppData() ||
|
|
join(homedir(), ".local", "state")
|
|
);
|
|
}
|
|
|
|
function normalized(path: string): string {
|
|
const resolved = resolve(path).replace(/\\/g, "/");
|
|
return process.platform === "win32" ? resolved.toLowerCase() : resolved;
|
|
}
|
|
|
|
function sessionDirectory(stateHome = defaultStateHome()): string {
|
|
return join(stateHome, "hyperframes", "previews");
|
|
}
|
|
|
|
export function previewSessionPath(projectDir: string, stateHome = defaultStateHome()): string {
|
|
const key = createHash("sha256").update(normalized(projectDir)).digest("hex").slice(0, 16);
|
|
return join(sessionDirectory(stateHome), `${key}.json`);
|
|
}
|
|
|
|
function previewLogPath(projectDir: string, stateHome = defaultStateHome()): string {
|
|
return previewSessionPath(projectDir, stateHome).replace(/\.json$/, ".log");
|
|
}
|
|
|
|
export function writePreviewSession(session: PreviewSession, stateHome = defaultStateHome()): void {
|
|
const path = previewSessionPath(session.projectDir, stateHome);
|
|
mkdirSync(dirname(path), { recursive: true });
|
|
// Written through a temp file and renamed: every reader deletes this record
|
|
// when it fails to parse, so a concurrent reader catching a half-written file
|
|
// would destroy a live server's only ownership proof. `rename` is atomic
|
|
// within a directory, so a reader sees either the old record or the new one.
|
|
const temporary = `${path}.${process.pid}.tmp`;
|
|
try {
|
|
writeFileSync(temporary, `${JSON.stringify(session, null, 2)}\n`, { mode: 0o600 });
|
|
renameSync(temporary, path);
|
|
} finally {
|
|
// A failed rename would otherwise orphan the temp file. The `.json` filter
|
|
// hides it from the lister, so it accumulates silently.
|
|
rmSync(temporary, { force: true });
|
|
}
|
|
}
|
|
|
|
function readPreviewSession(
|
|
projectDir: string,
|
|
stateHome = defaultStateHome(),
|
|
): PreviewSession | null {
|
|
const path = previewSessionPath(projectDir, stateHome);
|
|
if (!existsSync(path)) return null;
|
|
try {
|
|
const parsed = JSON.parse(readFileSync(path, "utf8")) as PreviewSession;
|
|
if (
|
|
!Number.isInteger(parsed.pid) ||
|
|
parsed.pid <= 0 ||
|
|
normalized(parsed.projectDir) !== normalized(projectDir)
|
|
) {
|
|
throw new Error("invalid preview session");
|
|
}
|
|
return parsed;
|
|
} catch {
|
|
rmSync(path, { force: true });
|
|
return null;
|
|
}
|
|
}
|
|
|
|
function hasValidPreviewProcess(session: PreviewSession): boolean {
|
|
return Number.isInteger(session.pid) && session.pid > 0;
|
|
}
|
|
|
|
function hasValidPreviewEndpoint(session: PreviewSession): boolean {
|
|
return Number.isInteger(session.port) && session.port > 0 && session.port <= 65535;
|
|
}
|
|
|
|
function matchesPreviewSessionFile(
|
|
session: PreviewSession,
|
|
path: string,
|
|
stateHome: string,
|
|
): boolean {
|
|
return (
|
|
typeof session.projectDir === "string" &&
|
|
typeof session.logPath === "string" &&
|
|
previewSessionPath(session.projectDir, stateHome) === path
|
|
);
|
|
}
|
|
|
|
function readPreviewSessionFile(path: string, stateHome: string): PreviewSession | null {
|
|
try {
|
|
const parsed = JSON.parse(readFileSync(path, "utf8")) as PreviewSession;
|
|
if (
|
|
!hasValidPreviewProcess(parsed) ||
|
|
!hasValidPreviewEndpoint(parsed) ||
|
|
!matchesPreviewSessionFile(parsed, path, stateHome)
|
|
) {
|
|
throw new Error("invalid preview session");
|
|
}
|
|
return parsed;
|
|
} catch {
|
|
rmSync(path, { force: true });
|
|
return null;
|
|
}
|
|
}
|
|
|
|
function removePreviewSession(projectDir: string, stateHome = defaultStateHome()): void {
|
|
rmSync(previewSessionPath(projectDir, stateHome), { force: true });
|
|
}
|
|
|
|
function matchingServer(
|
|
servers: ActiveServer[],
|
|
projectDir: string,
|
|
browserGpuMode?: BrowserGpuMode,
|
|
): ActiveServer | null {
|
|
return policyMatchingServers(servers, projectDir, browserGpuMode)[0] ?? null;
|
|
}
|
|
|
|
function policyMatchingServers(
|
|
servers: ActiveServer[],
|
|
projectDir: string,
|
|
browserGpuMode?: BrowserGpuMode,
|
|
): ActiveServer[] {
|
|
return sameProjectServers(servers, projectDir).filter(
|
|
(server) => browserGpuMode === undefined || server.browserGpuMode === browserGpuMode,
|
|
);
|
|
}
|
|
|
|
function matchingServerAtPort(
|
|
servers: ActiveServer[],
|
|
projectDir: string,
|
|
port: number,
|
|
): ActiveServer | null {
|
|
return matchingServer(
|
|
servers.filter((server) => server.port === port),
|
|
projectDir,
|
|
);
|
|
}
|
|
|
|
function sameProjectServers(servers: ActiveServer[], projectDir: string): ActiveServer[] {
|
|
const project = normalized(projectDir);
|
|
return servers.filter((server) => normalized(server.projectDir) === project);
|
|
}
|
|
|
|
function sameProjectPorts(servers: ActiveServer[], projectDir: string): Set<number> {
|
|
return new Set(sameProjectServers(servers, projectDir).map((server) => server.port));
|
|
}
|
|
|
|
async function stopProcess(pid: number): Promise<void> {
|
|
await terminateProcessTree(pid);
|
|
}
|
|
|
|
const delay = (ms: number): Promise<void> => new Promise((done) => setTimeout(done, ms));
|
|
|
|
function openLog(logPath: string): number {
|
|
try {
|
|
mkdirSync(dirname(logPath), { recursive: true });
|
|
return openSync(logPath, "a", 0o600);
|
|
} catch (error) {
|
|
console.warn(
|
|
`[hyperframes] background preview log not written: cannot open ${logPath} (${error})`,
|
|
);
|
|
return openSync(devNull, "a");
|
|
}
|
|
}
|
|
|
|
function spawnDetachedPreview(
|
|
projectDir: string,
|
|
stateHome: string,
|
|
dependencies: LifecycleDependencies,
|
|
): {
|
|
pid: number;
|
|
wrapperIdentity: string | undefined;
|
|
logPath: string;
|
|
exitedWith: () => string | null;
|
|
} {
|
|
const logPath = previewLogPath(projectDir, stateHome);
|
|
const logFd = openLog(logPath);
|
|
const spawn = dependencies.spawn ?? (nodeSpawn as unknown as SpawnPreview);
|
|
let child: SpawnResult;
|
|
try {
|
|
child = spawn(
|
|
dependencies.execPath ?? process.execPath,
|
|
buildBackgroundPreviewArgs(dependencies.argv ?? process.argv.slice(1)),
|
|
{
|
|
detached: true,
|
|
windowsHide: true,
|
|
stdio: ["ignore", logFd, logFd],
|
|
env: process.env,
|
|
},
|
|
);
|
|
} finally {
|
|
closeSync(logFd);
|
|
}
|
|
if (!child.pid) throw new Error("background preview child did not report a PID");
|
|
let exit: string | null = null;
|
|
child.once?.("exit", (code, signal) => {
|
|
exit = signal ? `signal ${signal}` : `exit code ${code}`;
|
|
});
|
|
child.unref();
|
|
return {
|
|
pid: child.pid,
|
|
wrapperIdentity: (dependencies.identity ?? processIdentity)(child.pid) ?? undefined,
|
|
logPath,
|
|
exitedWith: () => exit,
|
|
};
|
|
}
|
|
|
|
function startedServer(
|
|
servers: ActiveServer[],
|
|
projectDir: string,
|
|
preLaunchPorts: Set<number>,
|
|
launchedPid: number,
|
|
dependencies: LifecycleDependencies,
|
|
): ActiveServer | null {
|
|
const isDescendant = dependencies.isDescendant ?? isProcessDescendant;
|
|
const ours = (server: ActiveServer) => {
|
|
const pid = Number(server.pid);
|
|
return pid === launchedPid || isDescendant(pid, launchedPid);
|
|
};
|
|
const candidates = servers.filter((server) => !preLaunchPorts.has(server.port) && ours(server));
|
|
return matchingServer(candidates, projectDir, dependencies.browserGpuMode);
|
|
}
|
|
|
|
export function buildBackgroundPreviewArgs(argv: string[]): string[] {
|
|
const filtered = argv.filter(
|
|
(arg) =>
|
|
arg !== "--background" &&
|
|
!arg.startsWith("--background=") &&
|
|
arg !== "--foreground" &&
|
|
!arg.startsWith("--foreground=") &&
|
|
arg !== "--open" &&
|
|
arg !== "--no-open" &&
|
|
arg !== "--force-new" &&
|
|
arg !== "--json",
|
|
);
|
|
return [...filtered, "--foreground", "--no-open", "--force-new"];
|
|
}
|
|
|
|
function statusServer(
|
|
servers: ActiveServer[],
|
|
projectDir: string,
|
|
saved: PreviewSession | null,
|
|
preferredPort: number | undefined,
|
|
): ActiveServer | null {
|
|
const candidates = sameProjectServers(servers, projectDir);
|
|
return (
|
|
candidates.find((server) => server.port === preferredPort) ??
|
|
candidates.find((server) => server.port === saved?.port) ??
|
|
candidates[0] ??
|
|
null
|
|
);
|
|
}
|
|
|
|
function isCurrentPreviewWrapper(
|
|
saved: PreviewSession,
|
|
dependencies: LifecycleDependencies,
|
|
): boolean {
|
|
return (
|
|
!!saved.wrapperIdentity &&
|
|
(dependencies.identity ?? processIdentity)(saved.pid) === saved.wrapperIdentity
|
|
);
|
|
}
|
|
|
|
function managedStatusLogPath(
|
|
server: ActiveServer,
|
|
saved: PreviewSession | null,
|
|
pid: number,
|
|
dependencies: LifecycleDependencies,
|
|
): string | undefined {
|
|
if (!saved || saved.port !== server.port || server.pidSource !== "os") {
|
|
return undefined;
|
|
}
|
|
if (!isCurrentPreviewWrapper(saved, dependencies)) {
|
|
return undefined;
|
|
}
|
|
const isDescendant = dependencies.isDescendant ?? isProcessDescendant;
|
|
return pid === saved.pid || isDescendant(pid, saved.pid) ? saved.logPath : undefined;
|
|
}
|
|
|
|
export async function readBackgroundPreviewStatus(
|
|
projectDir: string,
|
|
startPort: number,
|
|
dependencies: LifecycleDependencies = {},
|
|
): Promise<PreviewStatus | null> {
|
|
const { stateHome, saved, scanned } = await readPreviewLifecycleState(
|
|
projectDir,
|
|
startPort,
|
|
dependencies,
|
|
);
|
|
const server = statusServer(scanned, projectDir, saved, dependencies.preferredPort);
|
|
if (server) {
|
|
const listenerPid = Number(server.pid);
|
|
const pid = Number.isInteger(listenerPid) && listenerPid > 0 ? listenerPid : null;
|
|
const logPath =
|
|
pid === null ? undefined : managedStatusLogPath(server, saved, pid, dependencies);
|
|
return {
|
|
pid,
|
|
port: server.port,
|
|
projectDir: resolve(projectDir),
|
|
...(logPath ? { logPath } : {}),
|
|
};
|
|
}
|
|
|
|
// A missed probe is not proof the preview is gone: a server whose event loop
|
|
// is momentarily blocked (a Puppeteer thumbnail capture will do it) answers
|
|
// nothing for a second or two. Deleting the record on that would destroy the
|
|
// wrapperIdentity that is the only PID-reuse guard `--stop` has, and it never
|
|
// comes back. Only a wrapper process that is provably gone retires a record.
|
|
if (saved && wrapperProcessIsAlive(saved, dependencies)) return null;
|
|
removePreviewSession(projectDir, stateHome);
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Whether the recorded wrapper process is still the process we launched.
|
|
*
|
|
* `processIdentity` returns a birth token, so a recycled PID reads as a
|
|
* different process and the record is correctly retired. A null token (no such
|
|
* process, or the platform lookup failed) is only treated as "gone" when the
|
|
* record has no token to compare against — failing closed there would pin dead
|
|
* records forever on platforms where the lookup is unavailable.
|
|
*/
|
|
/**
|
|
* Whether a PID exists at all. `kill(pid, 0)` sends no signal; it only asks the
|
|
* kernel. `EPERM` means the process is there but owned by someone else — still
|
|
* alive, which is the question being asked.
|
|
*/
|
|
function processIsSignalable(pid: number): boolean {
|
|
try {
|
|
process.kill(pid, 0);
|
|
return true;
|
|
} catch (error) {
|
|
return (error as NodeJS.ErrnoException | undefined)?.code === "EPERM";
|
|
}
|
|
}
|
|
|
|
function wrapperProcessIsAlive(
|
|
saved: PreviewSession,
|
|
dependencies: LifecycleDependencies,
|
|
): boolean {
|
|
if (!saved.wrapperIdentity) return false;
|
|
|
|
// Cheap and decisive first: a PID nothing can signal is gone, and no birth
|
|
// token is needed to say so. This also keeps the identity subprocess off the
|
|
// path for exactly the stale records that make `--list` slow.
|
|
const signalable = dependencies.isSignalable ?? processIsSignalable;
|
|
if (!signalable(saved.pid)) return false;
|
|
|
|
const identity = (dependencies.identity ?? processIdentity)(saved.pid);
|
|
// No answer is NOT the same as a different answer. `processIdentity` catches
|
|
// every failure into `null`, and on two of three platforms that failure is a
|
|
// subprocess timeout on a live process — `ps -o lstart=` and PowerShell's CIM
|
|
// query both run on a 2 s budget, under the very load that made the HTTP
|
|
// probe miss in the first place. Treating that as "recycled" would destroy
|
|
// the only PID-reuse guard `--stop` has, which is the loss this whole path
|
|
// exists to prevent. The PID is signalable, so keep the record.
|
|
if (identity === null) return true;
|
|
|
|
return identity === saved.wrapperIdentity;
|
|
}
|
|
|
|
export async function listBackgroundPreviewStatuses(
|
|
dependencies: LifecycleDependencies = {},
|
|
): Promise<PreviewStatus[]> {
|
|
const stateHome = dependencies.stateHome ?? defaultStateHome();
|
|
const directory = sessionDirectory(stateHome);
|
|
let files: string[];
|
|
try {
|
|
files = readdirSync(directory)
|
|
.filter((name) => name.endsWith(".json"))
|
|
.map((name) => join(directory, name));
|
|
} catch {
|
|
return [];
|
|
}
|
|
|
|
const saved = files
|
|
.map((path) => readPreviewSessionFile(path, stateHome))
|
|
.filter((session): session is PreviewSession => session !== null);
|
|
const statuses = await Promise.all(
|
|
saved.map((session) =>
|
|
readBackgroundPreviewStatus(session.projectDir, session.port, {
|
|
...dependencies,
|
|
stateHome,
|
|
}),
|
|
),
|
|
);
|
|
return statuses.filter((status): status is PreviewStatus => status !== null);
|
|
}
|
|
|
|
function readyPreviewSession(
|
|
server: ActiveServer,
|
|
pid: number,
|
|
wrapperIdentity: string | undefined,
|
|
projectDir: string,
|
|
logPath: string,
|
|
dependencies: LifecycleDependencies,
|
|
): { session: PreviewSession; publicPid: number } {
|
|
const identity = wrapperIdentity ?? (dependencies.identity ?? processIdentity)(pid) ?? undefined;
|
|
const liveServerPid = Number(server.pid);
|
|
return {
|
|
session: {
|
|
pid,
|
|
wrapperIdentity: identity,
|
|
port: server.port,
|
|
projectDir: resolve(projectDir),
|
|
logPath,
|
|
},
|
|
publicPid: Number.isInteger(liveServerPid) && liveServerPid > 0 ? liveServerPid : pid,
|
|
};
|
|
}
|
|
|
|
function ownedStopTargetPid(
|
|
saved: PreviewSession | null,
|
|
liveServerPid: number,
|
|
dependencies: LifecycleDependencies,
|
|
): number {
|
|
if (!saved?.wrapperIdentity) return liveServerPid;
|
|
const identity = dependencies.identity ?? processIdentity;
|
|
if (identity(saved.pid) !== saved.wrapperIdentity) return liveServerPid;
|
|
if (saved.pid === liveServerPid) return saved.pid;
|
|
const isDescendant = dependencies.isDescendant ?? isProcessDescendant;
|
|
return isDescendant(liveServerPid, saved.pid) ? saved.pid : liveServerPid;
|
|
}
|
|
|
|
function provenStopTargetPid(
|
|
projectDir: string,
|
|
server: ActiveServer,
|
|
saved: PreviewSession | null,
|
|
liveServerPid: number,
|
|
dependencies: LifecycleDependencies,
|
|
): number {
|
|
if (server.pidSource === "os") return ownedStopTargetPid(saved, liveServerPid, dependencies);
|
|
if (saved && isCurrentPreviewWrapper(saved, dependencies)) return saved.pid;
|
|
throw new Error(
|
|
`preview ownership could not be proven for ${resolve(projectDir)}: the system did not say which process listens on port ${server.port}. ` +
|
|
"Stop that preview from the terminal it runs in.",
|
|
);
|
|
}
|
|
|
|
async function stopOwnedPreviewBeforeReplacement(
|
|
owned: ActiveServer | null,
|
|
projectDir: string,
|
|
dependencies: LifecycleDependencies,
|
|
): Promise<void> {
|
|
if (!owned) return;
|
|
// `false` means "there was nothing left to stop" — the server went away
|
|
// between the outer scan and this one. That is the goal state for a
|
|
// replacement, not a failure; treating it as fatal refused to start any
|
|
// preview at all until the user deleted the session record by hand.
|
|
// A server that is still listening throws from inside stopBackgroundPreview.
|
|
await stopBackgroundPreview(projectDir, owned.port, dependencies);
|
|
}
|
|
|
|
function savedOwnedPreview(
|
|
servers: ActiveServer[],
|
|
saved: PreviewSession | null,
|
|
projectDir: string,
|
|
): ActiveServer | null {
|
|
if (!saved) return null;
|
|
// Ownership comes from the saved project+port, not the replacement's GPU
|
|
// policy. Filtering here would miss an owned hardware→software replacement
|
|
// and overwrite the only session record while leaving the old listener live.
|
|
const savedPortServers = servers.filter((server) => server.port === saved.port);
|
|
return matchingServer(savedPortServers, projectDir);
|
|
}
|
|
|
|
function isPortInScanRange(port: number, scanStart: number): boolean {
|
|
return port >= scanStart && port < scanStart + MAX_PORT_SCAN;
|
|
}
|
|
|
|
async function addSavedPortServer(
|
|
scanned: ActiveServer[],
|
|
savedPort: number | undefined,
|
|
scanStart: number,
|
|
dependencies: LifecycleDependencies,
|
|
): Promise<void> {
|
|
if (savedPort === undefined || isPortInScanRange(savedPort, scanStart)) return;
|
|
const server = await (dependencies.probe ?? activeServerOnPort)(savedPort);
|
|
if (server) scanned.push(server);
|
|
}
|
|
|
|
async function readPreviewLifecycleState(
|
|
projectDir: string,
|
|
startPort: number,
|
|
dependencies: LifecycleDependencies,
|
|
) {
|
|
const scan = dependencies.scan ?? scanActiveServers;
|
|
const stateHome = dependencies.stateHome ?? defaultStateHome();
|
|
const saved = readPreviewSession(projectDir, stateHome);
|
|
const scanStart = dependencies.preferredPort ?? saved?.port ?? startPort;
|
|
const scanned = await scan(scanStart);
|
|
await addSavedPortServer(scanned, saved?.port, scanStart, dependencies);
|
|
return { scan, stateHome, saved, scanned };
|
|
}
|
|
|
|
function unmetPreferredPort(port: number, preferredPort: number | undefined): number | undefined {
|
|
return preferredPort !== undefined && port !== preferredPort ? preferredPort : undefined;
|
|
}
|
|
|
|
type BackgroundPreviewResult =
|
|
| { type: "reused"; port: number; pid: number | null; logPath: string | null }
|
|
| { type: "started"; port: number; pid: number; logPath: string };
|
|
|
|
function reuseExistingPreview(
|
|
reusableExisting: ActiveServer | null,
|
|
candidates: ActiveServer[],
|
|
dependencies: LifecycleDependencies,
|
|
): Extract<BackgroundPreviewResult, { type: "reused" }> | null {
|
|
if (!reusableExisting || dependencies.forceNew) return null;
|
|
const unmet = unmetPreferredPort(reusableExisting.port, dependencies.preferredPort);
|
|
if (unmet !== undefined) {
|
|
throw new PreviewServerPortMismatchError(
|
|
unmet,
|
|
candidates,
|
|
` To start one on port ${unmet} instead, add --force-new or run --stop first.`,
|
|
);
|
|
}
|
|
return {
|
|
type: "reused",
|
|
port: reusableExisting.port,
|
|
pid: reusableExisting.pid ? Number(reusableExisting.pid) : null,
|
|
logPath: null,
|
|
};
|
|
}
|
|
|
|
export async function startBackgroundPreview(
|
|
projectDir: string,
|
|
startPort: number,
|
|
dependencies: LifecycleDependencies = {},
|
|
): Promise<BackgroundPreviewResult> {
|
|
const launchStart = dependencies.preferredPort ?? startPort;
|
|
const { scan, stateHome, saved, scanned } = await readPreviewLifecycleState(
|
|
projectDir,
|
|
startPort,
|
|
dependencies,
|
|
);
|
|
// A saved custom port stays eligible for replacement even outside the scan
|
|
// window, or overwriting the ownership record would orphan its listener.
|
|
const candidates = policyMatchingServers(scanned, projectDir, dependencies.browserGpuMode);
|
|
// A policy-matching server on the explicit --port satisfies it even when it is not the owned one,
|
|
// so `--port 3003` reuses the 3003 sibling instead of reporting a mismatch against the owned 3002.
|
|
const onPreferredPort =
|
|
candidates.find((server) => server.port === dependencies.preferredPort) ?? null;
|
|
const requestedExisting = candidates[0] ?? null;
|
|
const ownedExisting = savedOwnedPreview(scanned, saved, projectDir);
|
|
// Otherwise a saved managed preview is the authoritative same-project
|
|
// instance. An explicit GPU-policy change replaces it; it must not silently
|
|
// adopt an unmanaged sibling that happens to match the new policy.
|
|
const reusableOwned = ownedExisting
|
|
? matchingServer([ownedExisting], projectDir, dependencies.browserGpuMode)
|
|
: null;
|
|
const reusableExisting =
|
|
onPreferredPort ?? reusableOwned ?? (ownedExisting ? null : requestedExisting);
|
|
const reused = reuseExistingPreview(reusableExisting, candidates, dependencies);
|
|
if (reused) return reused;
|
|
await stopOwnedPreviewBeforeReplacement(ownedExisting, projectDir, dependencies);
|
|
// Snapshot every same-project listener in the prospective launch range only
|
|
// after the owned listener is gone. Readiness must identify a newly appeared
|
|
// server, never a pre-existing unmanaged sibling.
|
|
const preLaunchPorts = sameProjectPorts(await scan(launchStart), projectDir);
|
|
|
|
const { pid, wrapperIdentity, logPath, exitedWith } = spawnDetachedPreview(
|
|
projectDir,
|
|
stateHome,
|
|
dependencies,
|
|
);
|
|
|
|
const kill = dependencies.kill ?? stopProcess;
|
|
const server = await awaitStartedServer(
|
|
projectDir,
|
|
launchStart,
|
|
preLaunchPorts,
|
|
pid,
|
|
exitedWith,
|
|
dependencies,
|
|
);
|
|
if (!server) {
|
|
const exit = exitedWith();
|
|
if (exit) {
|
|
throw new Error(
|
|
`background preview exited (${exit}) before it was ready; see ${logPath}${logTail(logPath)}`,
|
|
);
|
|
}
|
|
await kill(pid);
|
|
throw new Error(`background preview did not become ready; see ${logPath}`);
|
|
}
|
|
// The child scans upward from --port; one that missed an explicit --port is reaped, never recorded.
|
|
const unmet = unmetPreferredPort(server.port, dependencies.preferredPort);
|
|
if (unmet !== undefined) {
|
|
// Wait until it stops answering so a concurrent launch or --status cannot adopt a dying server.
|
|
await kill(pid);
|
|
if (!(await awaitServerGone(projectDir, server.port, dependencies))) {
|
|
throw new Error(
|
|
`background preview on port ${server.port} did not stop after failing to bind port ${unmet}; see ${logPath}`,
|
|
);
|
|
}
|
|
throw new PreviewPortUnavailableError(unmet, server.port);
|
|
}
|
|
const ready = readyPreviewSession(
|
|
server,
|
|
pid,
|
|
wrapperIdentity,
|
|
projectDir,
|
|
logPath,
|
|
dependencies,
|
|
);
|
|
writePreviewSession(ready.session, stateHome);
|
|
return {
|
|
type: "started",
|
|
...ready.session,
|
|
pid: ready.publicPid,
|
|
};
|
|
}
|
|
|
|
function logTail(logPath: string): string {
|
|
try {
|
|
const text = stripVTControlCharacters(readFileSync(logPath, "utf8"));
|
|
const lines = text.trimEnd().split("\n").slice(-5);
|
|
return lines.join("").trim() ? `\n${lines.join("\n")}` : "";
|
|
} catch {
|
|
return "";
|
|
}
|
|
}
|
|
|
|
async function awaitStartedServer(
|
|
projectDir: string,
|
|
startPort: number,
|
|
preLaunchPorts: Set<number>,
|
|
launchedPid: number,
|
|
exitedWith: () => string | null,
|
|
dependencies: LifecycleDependencies,
|
|
): Promise<ActiveServer | null> {
|
|
const scan = dependencies.scan ?? scanActiveServers;
|
|
const sleep = dependencies.sleep ?? delay;
|
|
for (let attempt = 0; attempt < 50 && !exitedWith(); attempt++) {
|
|
const server = startedServer(
|
|
await scan(startPort),
|
|
projectDir,
|
|
preLaunchPorts,
|
|
launchedPid,
|
|
dependencies,
|
|
);
|
|
if (server) return server;
|
|
await sleep(200);
|
|
}
|
|
return null;
|
|
}
|
|
|
|
export async function stopBackgroundPreview(
|
|
projectDir: string,
|
|
startPort: number,
|
|
dependencies: LifecycleDependencies = {},
|
|
): Promise<boolean> {
|
|
const stateHome = dependencies.stateHome ?? defaultStateHome();
|
|
const saved = readPreviewSession(projectDir, stateHome);
|
|
const scan = dependencies.scan ?? scanActiveServers;
|
|
const server = saved
|
|
? await probeMatchingServerAtPort(projectDir, saved.port, dependencies)
|
|
: matchingServer(await scan(dependencies.preferredPort ?? startPort), projectDir);
|
|
if (!server) {
|
|
removePreviewSession(projectDir, stateHome);
|
|
return false;
|
|
}
|
|
// A saved PID can be reused after a crashed preview. The HTTP probe proves
|
|
// the project, but only the live server's own metadata proves which process
|
|
// owns it; never substitute the saved wrapper PID here.
|
|
const pid = Number(server.pid);
|
|
if (!Number.isInteger(pid) || pid <= 0) {
|
|
throw new Error(`preview ownership could not be proven for ${resolve(projectDir)}`);
|
|
}
|
|
|
|
const kill = dependencies.kill ?? stopProcess;
|
|
await kill(provenStopTargetPid(projectDir, server, saved, pid, dependencies));
|
|
|
|
if (!(await awaitServerGone(projectDir, server.port, dependencies))) {
|
|
throw new Error(`background preview did not stop for ${resolve(projectDir)}`);
|
|
}
|
|
removePreviewSession(projectDir, stateHome);
|
|
return true;
|
|
}
|
|
|
|
async function probeMatchingServerAtPort(
|
|
projectDir: string,
|
|
port: number,
|
|
dependencies: LifecycleDependencies,
|
|
): Promise<ActiveServer | null> {
|
|
const server = await (dependencies.probe ?? activeServerOnPort)(port);
|
|
return matchingServerAtPort(server ? [server] : [], projectDir, port);
|
|
}
|
|
|
|
async function awaitServerGone(
|
|
projectDir: string,
|
|
port: number,
|
|
dependencies: LifecycleDependencies,
|
|
): Promise<boolean> {
|
|
const sleep = dependencies.sleep ?? delay;
|
|
for (let attempt = 0; attempt < 25; attempt++) {
|
|
if (!(await probeMatchingServerAtPort(projectDir, port, dependencies))) return true;
|
|
await sleep(100);
|
|
}
|
|
return false;
|
|
}
|