mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:00:07 +00:00
* fix: honor explicit --port when reusing a background preview server startBackgroundPreview never compared a reuse candidate's actual bound port against the caller's explicitly requested --port before returning it, so a second `preview --port <N>` call could silently return an existing server on a different port instead of honoring the request. Reuses the existing PreviewServerPortMismatchError (already used by findPreviewServerForProject for the same discipline) instead of adding a new error type: an explicit --port that doesn't match the reuse candidate now throws a clear conflict rather than substituting the wrong port silently. A bare launch with no --port keeps reusing any project-matching server, unchanged. Deliberately out of scope: the interactive/embedded launch path (runEmbeddedMode -> findPortAndServe) has the same silent-substitution shape when a same-project server is found mid-scan at a port other than the one requested. That path's output isn't the JSON lifecycle schema this bug was reported against, and fixing it would mean touching the interactive dev-server bind/scan loop rather than a simple pre-return check, so it's left as a follow-up candidate. Co-Authored-By: Miguel Angel <miguel.sierra@heygen.com> * fix: honor explicit --port on every background preview exit path `startBackgroundPreview` already refused to reuse a same-project server on the wrong port when --port was explicit, but the fresh-launch path still trusted whatever port the detached child bound. The child scans upward from --port and takes the first free port, so `--background --port N` with N busy reported `{ type: "started", port: N+1 }` and recorded ownership of it. - After the child comes up, compare its port with the explicit --port. On a mismatch, reap the wrapper, wait until the substitute stops answering, and throw `PreviewPortUnavailableError` (JSON code `preview-port-unavailable`). If the substitute never stops, fail loudly instead of reporting it. - Share one `unmetPreferredPort` predicate between the reuse and launch paths, and one `awaitServerGone` wait between the reap path and `stopBackgroundPreview`. - When several same-project servers are running, prefer the one on the explicit --port as the reuse candidate instead of the lowest port. - Map launch failures to JSON codes in one place (`backgroundStartFailureCode`). Tests: preferred port bound → reported as-is; preferred port taken → reaped and rejected with both ports, no session record; substitute that keeps serving → distinct error; bare launch keeps the next free port; explicit port picks the matching sibling. Deleting the launch-path check, the candidate ordering, or the post-kill wait each turns its test red. Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com> * fix(cli): reuse the same-project server on the explicit --port `startBackgroundPreview` picked its reuse candidate before honouring `--port`, so with an owned server on 3002 and an unmanaged same-project server on 3003, `--port 3003` rejected with "No Studio preview server … on port 3003. Matching server port: 3002" even though 3003 was running. - A policy-matching same-project server already on the explicit port is now the reuse candidate, owned or not; the owned server stays authoritative otherwise, and an explicit GPU-policy change on the requested port still replaces it. - `PreviewServerPortMismatchError` receives every policy-matching same-project server, so the ports it reports are the ones running. - `policyMatchingServers` is the single owner of the same-project + GPU-policy predicate; `matchingServer` derives from it. - `BackgroundPreviewResult` names the launch result union once; `PREVIEW_PORT_MISMATCH_CODE` replaces three literal error codes. Tests: unmanaged sibling on the explicit port is reused without touching the owned server; mismatch error lists every same-project port and no foreign-project port; owned server on the explicit port is replaced on a GPU-policy change. Each new check fails when its guard is removed. Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com> * refactor(cli): keep the --port honour comments short * fix(cli): drop the scan binding stopBackgroundPreview no longer reads * refactor(cli): keep comment share at base in the preview lifecycle files * fix(cli): reuse a same-project server on an explicit --port beyond the scan window * test(cli): pin the JSON codes for a background start that misses --port * refactor(cli): probe an out-of-window --port in its own helper --------- Co-authored-by: Miguel Angel <miguel.sierra@heygen.com>
159 lines
5.4 KiB
TypeScript
159 lines
5.4 KiB
TypeScript
import { existsSync, realpathSync } from "node:fs";
|
|
import { resolve } from "node:path";
|
|
import { scanActiveServers, type ActiveServer } from "../server/portUtils.js";
|
|
import type {
|
|
LintResult,
|
|
ResolvedProject,
|
|
StudioSelectionResponse,
|
|
} from "@hyperframes/studio-server";
|
|
|
|
export type StudioLintResponse = LintResult;
|
|
|
|
const VITE_STUDIO_DISCOVERY_PORTS = [5190] as const;
|
|
|
|
interface StudioProjectsResponse {
|
|
projects?: ResolvedProject[];
|
|
}
|
|
|
|
interface FindPreviewServerOptions {
|
|
preferredPort?: number;
|
|
}
|
|
|
|
export class AmbiguousPreviewServerError extends Error {
|
|
readonly ports: number[];
|
|
|
|
constructor(servers: ActiveServer[]) {
|
|
const ports = servers.map((server) => server.port).sort((a, b) => a - b);
|
|
super(
|
|
`Multiple Studio preview servers match this project (${ports.join(", ")}). Pass --port <port> to choose one.`,
|
|
);
|
|
this.name = "AmbiguousPreviewServerError";
|
|
this.ports = ports;
|
|
}
|
|
}
|
|
|
|
export class PreviewServerPortMismatchError extends Error {
|
|
readonly requestedPort: number;
|
|
readonly ports: number[];
|
|
|
|
constructor(requestedPort: number, servers: ActiveServer[], hint = "") {
|
|
const ports = servers.map((server) => server.port).sort((a, b) => a - b);
|
|
super(
|
|
`No Studio preview server for this project is running on port ${requestedPort}. Matching server port${ports.length === 1 ? "" : "s"}: ${ports.join(", ")}. Rerun with --port ${ports[0]}${ports.length > 1 ? " or omit --port to see all candidates" : ""}.${hint}`,
|
|
);
|
|
this.name = "PreviewServerPortMismatchError";
|
|
this.requestedPort = requestedPort;
|
|
this.ports = ports;
|
|
}
|
|
}
|
|
|
|
function normalizePath(path: string): string {
|
|
const resolved = resolve(path);
|
|
try {
|
|
if (existsSync(resolved)) {
|
|
return realpathSync(resolved).replace(/\\/g, "/").toLowerCase();
|
|
}
|
|
} catch {
|
|
// Fall through to resolved-path normalization.
|
|
}
|
|
return resolved.replace(/\\/g, "/").toLowerCase();
|
|
}
|
|
|
|
export async function findPreviewServerForProject(
|
|
projectDir: string,
|
|
startPort = 3002,
|
|
scan: (startPort?: number) => Promise<ActiveServer[]> = scanActiveServers,
|
|
fetchImpl: typeof fetch = fetch,
|
|
options: FindPreviewServerOptions = {},
|
|
): Promise<ActiveServer | null> {
|
|
const normalizedProjectDir = normalizePath(projectDir);
|
|
const servers = await scan(startPort);
|
|
const embeddedServers = servers.filter(
|
|
(server) => normalizePath(server.projectDir) === normalizedProjectDir,
|
|
);
|
|
if (options.preferredPort !== undefined) {
|
|
const preferred = embeddedServers.find((server) => server.port === options.preferredPort);
|
|
if (preferred) return preferred;
|
|
const viteServer = await findViteStudioServerForProject(normalizedProjectDir, fetchImpl, [
|
|
options.preferredPort,
|
|
]);
|
|
if (viteServer) return viteServer;
|
|
if (embeddedServers.length > 0) {
|
|
throw new PreviewServerPortMismatchError(options.preferredPort, embeddedServers);
|
|
}
|
|
return null;
|
|
}
|
|
if (embeddedServers.length === 1) return embeddedServers[0]!;
|
|
if (embeddedServers.length > 1) throw new AmbiguousPreviewServerError(embeddedServers);
|
|
return findViteStudioServerForProject(normalizedProjectDir, fetchImpl);
|
|
}
|
|
|
|
export function studioSelectionUrl(server: ActiveServer): string {
|
|
return studioApiUrl(server, "selection");
|
|
}
|
|
|
|
export function studioApiUrl(server: ActiveServer, route: string): string {
|
|
const host = server.host ?? "127.0.0.1";
|
|
return `http://${host}:${server.port}/api/projects/${encodeURIComponent(server.projectName)}/${route}`;
|
|
}
|
|
|
|
// Vite dev servers bind IPv6 loopback (`::1`) by default while embedded servers
|
|
// bind IPv4 (`127.0.0.1`), so probe both — a single family misses the other and
|
|
// is exactly why `--selection`/`--context` failed against a local-studio preview.
|
|
const LOOPBACK_HOSTS = ["127.0.0.1", "[::1]"] as const;
|
|
|
|
async function findViteStudioServerForProject(
|
|
normalizedProjectDir: string,
|
|
fetchImpl: typeof fetch,
|
|
ports: readonly number[] = VITE_STUDIO_DISCOVERY_PORTS,
|
|
): Promise<ActiveServer | null> {
|
|
for (const port of ports) {
|
|
for (const host of LOOPBACK_HOSTS) {
|
|
try {
|
|
const response = await fetchImpl(`http://${host}:${port}/api/projects`);
|
|
if (!response.ok) continue;
|
|
const payload = (await response.json()) as StudioProjectsResponse;
|
|
const project = payload.projects?.find(
|
|
(candidate) => normalizePath(candidate.dir) === normalizedProjectDir,
|
|
);
|
|
if (!project) continue;
|
|
return {
|
|
port,
|
|
host,
|
|
projectName: project.id,
|
|
projectDir: project.dir,
|
|
version: "studio-dev",
|
|
pid: null,
|
|
};
|
|
} catch {
|
|
// Not a Vite-served Studio on this host/port, or unreachable. Try next.
|
|
}
|
|
}
|
|
}
|
|
return null;
|
|
}
|
|
|
|
export async function fetchStudioSelection(
|
|
server: ActiveServer,
|
|
fetchImpl: typeof fetch = fetch,
|
|
): Promise<StudioSelectionResponse> {
|
|
const url = studioSelectionUrl(server);
|
|
const response = await fetchImpl(url);
|
|
if (!response.ok) {
|
|
throw new Error(`selection endpoint returned ${response.status}`);
|
|
}
|
|
return (await response.json()) as StudioSelectionResponse;
|
|
}
|
|
|
|
export async function fetchStudioLint(
|
|
server: ActiveServer,
|
|
fetchImpl: typeof fetch = fetch,
|
|
): Promise<StudioLintResponse> {
|
|
const url = studioApiUrl(server, "lint");
|
|
const response = await fetchImpl(url);
|
|
if (!response.ok) {
|
|
throw new Error(`lint endpoint returned ${response.status}`);
|
|
}
|
|
return (await response.json()) as StudioLintResponse;
|
|
}
|