Skip to content

Commit 7a715b1

Browse files
fix(cli): scope explicit preview port discovery
1 parent fcec26e commit 7a715b1

3 files changed

Lines changed: 211 additions & 36 deletions

File tree

‎docs/guides/troubleshooting.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,19 @@ Run `docker info`.
7878

7979
Confirm Docker is installed, its daemon is running, your user has permission, and the first image download can reach the registry.
8080

81+
### Preview checks an unexpected port range
82+
83+
For a managed background preview, choose the discovery range with an explicit port:
84+
85+
```bash
86+
npx hyperframes preview --background --port 4567
87+
```
88+
89+
Discovery checks ports 4567–4666. If this project has a saved preview on another
90+
port outside that range, only that saved port is checked separately. When moving
91+
an existing managed preview to the requested port, add `--force-new` to stop and
92+
replace it. Without `--port`, discovery starts at the saved preview's port.
93+
8194
## Media problems
8295

8396
### Video is black in preview but renders

‎packages/cli/src/commands/previewLifecycle.test.ts‎

Lines changed: 165 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -137,10 +137,160 @@ describe("background preview lifecycle", () => {
137137
});
138138

139139
expect(result).toMatchObject({ type: "reused", port: 41402, pid: 4321 });
140-
expect(scan).toHaveBeenCalledWith(41402);
140+
expect(scan).toHaveBeenCalledExactlyOnceWith(41402);
141141
expect(spawn).not.toHaveBeenCalled();
142142
});
143143

144+
it.each([3021, 32521, 32522, 32620, 32621])(
145+
"bounds the explicit-port scan when the saved port is %s",
146+
async (savedPort) => {
147+
const stateHome = tempDir("hf-preview-state-");
148+
const requestedPort = 32521;
149+
const owned = { ...server, port: savedPort };
150+
const requested = { ...server, port: requestedPort, pid: "5555" };
151+
const servers = savedPort === requestedPort ? [requested] : [owned, requested];
152+
writePreviewSession(
153+
{ pid: 4321, port: savedPort, projectDir, logPath: "/tmp/preview.log" },
154+
stateHome,
155+
);
156+
const scan = vi.fn(async (start = 3002) =>
157+
servers.filter((candidate) => candidate.port >= start && candidate.port < start + 100),
158+
);
159+
const probe = vi.fn(
160+
async (port: number) => servers.find((candidate) => candidate.port === port) ?? null,
161+
);
162+
const spawn = vi.fn();
163+
const kill = vi.fn();
164+
165+
const result = await startBackgroundPreview(projectDir, requestedPort, {
166+
scan,
167+
probe,
168+
spawn,
169+
kill,
170+
stateHome,
171+
preferredPort: requestedPort,
172+
});
173+
174+
expect(result).toMatchObject({ type: "reused", port: requestedPort, pid: 5555 });
175+
expect(scan).toHaveBeenCalledExactlyOnceWith(requestedPort);
176+
expect(probe.mock.calls).toEqual(
177+
savedPort < requestedPort || savedPort > 32620 ? [[savedPort]] : [],
178+
);
179+
expect(spawn).not.toHaveBeenCalled();
180+
expect(kill).not.toHaveBeenCalled();
181+
},
182+
);
183+
184+
it.each([true, false])(
185+
"bounds the explicit-port replacement scan through shutdown (force-new: %s)",
186+
async (forceNew) => {
187+
const stateHome = tempDir("hf-preview-state-");
188+
const owned = { ...server, port: 3021, browserGpuMode: "hardware" as const };
189+
const replacement = {
190+
...server,
191+
port: 32521,
192+
pid: "5432",
193+
browserGpuMode: "software" as const,
194+
};
195+
const sibling = { ...replacement, port: 32522, pid: "8765" };
196+
writePreviewSession(
197+
{ pid: 4321, port: owned.port, projectDir, logPath: "/tmp/preview.log" },
198+
stateHome,
199+
);
200+
let ownedRunning = true;
201+
let replacementRunning = false;
202+
let stopping = false;
203+
const scan = vi.fn(async (start = 3002) =>
204+
[
205+
sibling,
206+
...(ownedRunning ? [owned] : []),
207+
...(replacementRunning ? [replacement] : []),
208+
].filter((candidate) => candidate.port >= start && candidate.port < start + 100),
209+
);
210+
const probe = vi.fn(async (port: number) =>
211+
ownedRunning && port === owned.port ? owned : null,
212+
);
213+
const kill = vi.fn((pid: number) => {
214+
expect(pid).toBe(4321);
215+
stopping = true;
216+
});
217+
const sleep = vi.fn(async () => {
218+
if (stopping) ownedRunning = false;
219+
});
220+
const spawn = vi.fn(() => {
221+
expect(ownedRunning).toBe(false);
222+
replacementRunning = true;
223+
return { pid: 5432, unref: vi.fn() };
224+
});
225+
226+
const result = await startBackgroundPreview(projectDir, replacement.port, {
227+
browserGpuMode: "software",
228+
forceNew,
229+
preferredPort: replacement.port,
230+
kill,
231+
probe,
232+
scan,
233+
sleep,
234+
spawn,
235+
stateHome,
236+
});
237+
238+
expect(result).toMatchObject({ type: "started", port: replacement.port, pid: 5432 });
239+
expect(scan.mock.calls.length).toBeGreaterThan(1);
240+
expect(scan.mock.calls.every(([port]) => port === replacement.port)).toBe(true);
241+
expect(probe.mock.calls.length).toBeGreaterThanOrEqual(4);
242+
expect(probe.mock.calls.every(([port]) => port === owned.port)).toBe(true);
243+
expect(kill).toHaveBeenCalledExactlyOnceWith(4321);
244+
expect(sleep).toHaveBeenCalledOnce();
245+
expect(spawn).toHaveBeenCalledOnce();
246+
expect(
247+
JSON.parse(readFileSync(previewSessionPath(projectDir, stateHome), "utf8")),
248+
).toMatchObject({
249+
port: replacement.port,
250+
pid: 5432,
251+
});
252+
},
253+
);
254+
255+
it("keeps explicit-port replacement blocked while the saved listener is still running", async () => {
256+
const stateHome = tempDir("hf-preview-state-");
257+
const owned = { ...server, port: 3021 };
258+
writePreviewSession(
259+
{ pid: 4321, port: owned.port, projectDir, logPath: "/tmp/preview.log" },
260+
stateHome,
261+
);
262+
const scan = vi.fn(async (start = 3002) =>
263+
owned.port >= start && owned.port < start + 100 ? [owned] : [],
264+
);
265+
const probe = vi.fn(async (port: number) => (port === owned.port ? owned : null));
266+
const spawn = vi.fn();
267+
const kill = vi.fn();
268+
269+
await expect(
270+
startBackgroundPreview(projectDir, 32521, {
271+
forceNew: true,
272+
preferredPort: 32521,
273+
scan,
274+
probe,
275+
spawn,
276+
kill,
277+
sleep: async () => {},
278+
stateHome,
279+
}),
280+
).rejects.toThrow("background preview did not stop");
281+
282+
expect(scan.mock.calls.every(([port]) => port === 32521)).toBe(true);
283+
expect(probe.mock.calls.every(([port]) => port === owned.port)).toBe(true);
284+
expect(kill).toHaveBeenCalledExactlyOnceWith(4321);
285+
expect(spawn).not.toHaveBeenCalled();
286+
expect(
287+
JSON.parse(readFileSync(previewSessionPath(projectDir, stateHome), "utf8")),
288+
).toMatchObject({
289+
port: owned.port,
290+
pid: 4321,
291+
});
292+
});
293+
144294
it("throws a port-mismatch error when the caller explicitly requests a port the reused server isn't on", async () => {
145295
const spawn = vi.fn();
146296
const scan = vi.fn(async () => [server]);
@@ -586,9 +736,10 @@ describe("background preview lifecycle", () => {
586736
const spawn = vi.fn();
587737
const kill = vi.fn();
588738

589-
const result = await startBackgroundPreview(projectDir, 3002, {
739+
const result = await startBackgroundPreview(projectDir, sibling.port, {
590740
kill,
591-
scan: async () => [owned, sibling],
741+
scan: async () => [sibling],
742+
probe: async (port) => (port === owned.port ? owned : null),
592743
spawn,
593744
stateHome,
594745
preferredPort: sibling.port,
@@ -602,10 +753,10 @@ describe("background preview lifecycle", () => {
602753
it("lists every same-project server in the port-mismatch error, not just the reuse candidate", async () => {
603754
const stateHome = mkdtempSync(join(tmpdir(), "hf-preview-state-"));
604755
const owned = { ...server, port: 3002 };
605-
const sibling = { ...server, port: 3003, pid: "5555" };
756+
const sibling = { ...server, port: 3004, pid: "5555" };
606757
const foreign = {
607758
...server,
608-
port: 3004,
759+
port: 3003,
609760
projectDir: resolve("/tmp/hyperframes-preview-lifecycle-other"),
610761
pid: "7777",
611762
};
@@ -615,18 +766,19 @@ describe("background preview lifecycle", () => {
615766
);
616767
const spawn = vi.fn();
617768

618-
const failure = await startBackgroundPreview(projectDir, 3002, {
619-
scan: async () => [owned, sibling, foreign],
769+
const failure = await startBackgroundPreview(projectDir, foreign.port, {
770+
scan: async () => [sibling, foreign],
771+
probe: async (port) => (port === owned.port ? owned : null),
620772
spawn,
621773
stateHome,
622-
preferredPort: 3004,
774+
preferredPort: foreign.port,
623775
}).then(
624776
() => null,
625777
(error: unknown) => error,
626778
);
627779

628780
expect(failure).toBeInstanceOf(PreviewServerPortMismatchError);
629-
expect(failure).toMatchObject({ requestedPort: 3004, ports: [3002, 3003] });
781+
expect(failure).toMatchObject({ requestedPort: 3003, ports: [3002, 3004] });
630782
expect((failure as Error).message).toContain("add --force-new or run --stop first");
631783
expect(spawn).not.toHaveBeenCalled();
632784
});
@@ -640,18 +792,18 @@ describe("background preview lifecycle", () => {
640792
stateHome,
641793
);
642794
const spawn = vi.fn();
643-
const probe = vi.fn(async (port: number) => (port === farSibling.port ? farSibling : null));
795+
const probe = vi.fn(async (port: number) => (port === owned.port ? owned : null));
644796

645797
const result = await startBackgroundPreview(projectDir, farSibling.port, {
646-
scan: async () => [owned],
798+
scan: async () => [farSibling],
647799
probe,
648800
spawn,
649801
stateHome,
650802
preferredPort: farSibling.port,
651803
});
652804

653805
expect(result).toMatchObject({ type: "reused", port: farSibling.port, pid: 5555 });
654-
expect(probe).toHaveBeenCalledExactlyOnceWith(farSibling.port);
806+
expect(probe).toHaveBeenCalledExactlyOnceWith(owned.port);
655807
expect(spawn).not.toHaveBeenCalled();
656808
});
657809

@@ -863,7 +1015,7 @@ describe("background preview lifecycle", () => {
8631015
});
8641016

8651017
expect(status?.port).toBe(3210);
866-
expect(scan).toHaveBeenCalledWith(3210);
1018+
expect(scan).toHaveBeenCalledExactlyOnceWith(3210);
8671019
});
8681020

8691021
it("stops only the matching project server and waits until it is unreachable", async () => {

‎packages/cli/src/commands/previewLifecycle.ts‎

Lines changed: 33 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -471,6 +471,21 @@ function savedOwnedPreview(
471471
return matchingServer(savedPortServers, projectDir);
472472
}
473473

474+
function isPortInScanRange(port: number, scanStart: number): boolean {
475+
return port >= scanStart && port < scanStart + MAX_PORT_SCAN;
476+
}
477+
478+
async function addSavedPortServer(
479+
scanned: ActiveServer[],
480+
savedPort: number | undefined,
481+
scanStart: number,
482+
dependencies: LifecycleDependencies,
483+
): Promise<void> {
484+
if (savedPort === undefined || isPortInScanRange(savedPort, scanStart)) return;
485+
const server = await (dependencies.probe ?? activeServerOnPort)(savedPort);
486+
if (server) scanned.push(server);
487+
}
488+
474489
async function readPreviewLifecycleState(
475490
projectDir: string,
476491
startPort: number,
@@ -479,8 +494,9 @@ async function readPreviewLifecycleState(
479494
const scan = dependencies.scan ?? scanActiveServers;
480495
const stateHome = dependencies.stateHome ?? defaultStateHome();
481496
const saved = readPreviewSession(projectDir, stateHome);
482-
const scanStart = saved?.port ?? startPort;
497+
const scanStart = dependencies.preferredPort ?? saved?.port ?? startPort;
483498
const scanned = await scan(scanStart);
499+
await addSavedPortServer(scanned, saved?.port, scanStart, dependencies);
484500
return { scan, stateHome, saved, scanStart, scanned };
485501
}
486502

@@ -514,33 +530,19 @@ function reuseExistingPreview(
514530
};
515531
}
516532

517-
// The scan only covers scanStart..+MAX_PORT_SCAN-1; an explicit --port outside it is probed directly.
518-
async function addPreferredPortServer(
519-
scanned: ActiveServer[],
520-
scanStart: number,
521-
dependencies: LifecycleDependencies,
522-
): Promise<void> {
523-
const preferred = dependencies.preferredPort;
524-
if (preferred === undefined) return;
525-
if (preferred >= scanStart && preferred < scanStart + MAX_PORT_SCAN) return;
526-
const server = await (dependencies.probe ?? activeServerOnPort)(preferred);
527-
if (server) scanned.push(server);
528-
}
529-
530533
export async function startBackgroundPreview(
531534
projectDir: string,
532535
startPort: number,
533536
dependencies: LifecycleDependencies = {},
534537
): Promise<BackgroundPreviewResult> {
535-
const { scan, stateHome, saved, scanStart, scanned } = await readPreviewLifecycleState(
538+
const launchStart = dependencies.preferredPort ?? startPort;
539+
const { scan, stateHome, saved, scanned } = await readPreviewLifecycleState(
536540
projectDir,
537541
startPort,
538542
dependencies,
539543
);
540-
await addPreferredPortServer(scanned, scanStart, dependencies);
541-
// Always inspect a saved custom port first. `--force-new --port <new>` must
542-
// replace that owned server before recording the replacement, otherwise the
543-
// single per-project ownership record would orphan the old listener.
544+
// A saved custom port stays eligible for replacement even outside the scan
545+
// window, or overwriting the ownership record would orphan its listener.
544546
const candidates = policyMatchingServers(scanned, projectDir, dependencies.browserGpuMode);
545547
// A policy-matching server on the explicit --port satisfies it even when it is not the owned one,
546548
// so `--port 3003` reuses the 3003 sibling instead of reporting a mismatch against the owned 3002.
@@ -562,7 +564,7 @@ export async function startBackgroundPreview(
562564
// Snapshot every same-project listener in the prospective launch range only
563565
// after the owned listener is gone. Readiness must identify a newly appeared
564566
// server, never a pre-existing unmanaged sibling.
565-
const preLaunchPorts = sameProjectPorts(await scan(startPort), projectDir);
567+
const preLaunchPorts = sameProjectPorts(await scan(launchStart), projectDir);
566568

567569
const { pid, wrapperIdentity, logPath, exitedWith } = spawnDetachedPreview(
568570
projectDir,
@@ -573,7 +575,7 @@ export async function startBackgroundPreview(
573575
const kill = dependencies.kill ?? stopProcess;
574576
const server = await awaitStartedServer(
575577
projectDir,
576-
startPort,
578+
launchStart,
577579
preLaunchPorts,
578580
pid,
579581
exitedWith,
@@ -594,7 +596,7 @@ export async function startBackgroundPreview(
594596
if (unmet !== undefined) {
595597
// Wait until it stops answering so a concurrent launch or --status cannot adopt a dying server.
596598
await kill(pid);
597-
if (!(await awaitServerGone(projectDir, startPort, server.port, dependencies))) {
599+
if (!(await awaitServerGone(projectDir, launchStart, server.port, dependencies))) {
598600
throw new Error(
599601
`background preview on port ${server.port} did not stop after failing to bind port ${unmet}; see ${logPath}`,
600602
);
@@ -693,9 +695,17 @@ async function awaitServerGone(
693695
dependencies: LifecycleDependencies,
694696
): Promise<boolean> {
695697
const scan = dependencies.scan ?? scanActiveServers;
698+
const probe = dependencies.probe ?? activeServerOnPort;
696699
const sleep = dependencies.sleep ?? delay;
697700
for (let attempt = 0; attempt < 25; attempt++) {
698-
if (!matchingServerAtPort(await scan(scanStart), projectDir, port)) return true;
701+
let servers: ActiveServer[];
702+
if (dependencies.preferredPort === undefined || isPortInScanRange(port, scanStart)) {
703+
servers = await scan(scanStart);
704+
} else {
705+
const server = await probe(port);
706+
servers = server ? [server] : [];
707+
}
708+
if (!matchingServerAtPort(servers, projectDir, port)) return true;
699709
await sleep(100);
700710
}
701711
return false;

0 commit comments

Comments
 (0)