Skip to content

Commit 5e34471

Browse files
committed
fix: preserve bundle-url mount prefix and broadcast expo reloads over /message
Maintainer review follow-ups (PR #1199): - Reload/message endpoint URLs keep the bound bundle URL's mount prefix (e.g. /tenant-42/index.bundle -> /tenant-42/reload) instead of collapsing to the host root. The Expo virtual entry (.expo/.virtual-metro-entry.bundle) is an entry-module path, not a server mount, so it maps to the server-root endpoints (verified live: Expo serves /message at the root). - When the dev server has no HTTP /reload route and answers with the app page (Expo), metro reload now broadcasts {"version":2,"method":"reload"} over the server's /message websocket (the channel dev-server CLIs use for the r key) instead of reporting the app-page 200 as a successful reload. The result carries a transport field (http | message-socket). Live-verified: a flagless metro reload against the running Expo server made the app re-fetch its JS bundle. - Endpoint resolution moved to src/metro/metro-reload-endpoints.ts so the seam tests use is production-imported (keeps the new production-unused-exports ratchet clean). - Docs reconciled: help metro and website commands.md describe the single session binding store, open's hint flags, prefix preservation, and the message-socket fallback.
1 parent f8e187d commit 5e34471

6 files changed

Lines changed: 426 additions & 99 deletions

File tree

‎src/__tests__/cli-client-commands.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -348,6 +348,7 @@ test('metro reload forwards host, port, bundle URL, and timeout to client.metro.
348348
reloadUrl: 'http://127.0.0.1:9090/reload',
349349
status: 200,
350350
body: 'OK',
351+
transport: 'http',
351352
};
352353
},
353354
});
@@ -1227,6 +1228,7 @@ function createStubClient(params: {
12271228
reloadUrl: 'http://127.0.0.1:8081/reload',
12281229
status: 200,
12291230
body: 'OK',
1231+
transport: 'http' as const,
12301232
})),
12311233
},
12321234
capture: {

‎src/__tests__/client-metro.test.ts‎

Lines changed: 211 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
import { test } from 'vitest';
22
import assert from 'node:assert/strict';
33
import { once } from 'node:events';
4-
import { randomUUID } from 'node:crypto';
4+
import { createHash, randomUUID } from 'node:crypto';
55
import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
66
import { createServer } from 'node:http';
77
import type { Socket } from 'node:net';
88
import net from 'node:net';
99
import os from 'node:os';
1010
import path from 'node:path';
11-
import { prepareMetroRuntime, reloadMetro, resolveMetroReloadUrl } from '../metro/client-metro.ts';
11+
import { prepareMetroRuntime, reloadMetro } from '../metro/client-metro.ts';
12+
import { resolveMetroReloadEndpoints } from '../metro/metro-reload-endpoints.ts';
1213
import { createAgentDeviceClient } from '../client/client.ts';
1314
import { readMetroSessionHints } from '../metro/metro-session-hints.ts';
1415
import { resolveDaemonPaths } from '../daemon/config.ts';
@@ -605,6 +606,7 @@ test('reloadMetro preserves the bundle URL route prefix', async () => {
605606
reloadUrl: `http://127.0.0.1:${address.port}/metro/runtime-1/reload`,
606607
status: 200,
607608
body: 'OK',
609+
transport: 'http',
608610
});
609611
} finally {
610612
await closeServer(server);
@@ -635,36 +637,90 @@ test('reloadMetro defaults to local Metro host and port', async () => {
635637
}
636638
});
637639

638-
test('resolveMetroReloadUrl prioritizes explicit flags, then session runtime hints, then defaults', () => {
640+
test('reload endpoint resolution prioritizes explicit flags, then session runtime hints, then defaults', () => {
639641
// no-hint default: neither an explicit flag nor a runtime hint is present.
640-
assert.equal(resolveMetroReloadUrl({}), 'http://localhost:8081/reload');
642+
assert.equal(resolveMetroReloadEndpoints({}).reloadUrl, 'http://localhost:8081/reload');
641643

642644
// hint-only: a session runtime hint resolves the target when no flag is given.
643645
assert.equal(
644-
resolveMetroReloadUrl({ runtime: { metroHost: '127.0.0.1', metroPort: 9200 } }),
646+
resolveMetroReloadEndpoints({ runtime: { metroHost: '127.0.0.1', metroPort: 9200 } }).reloadUrl,
645647
'http://127.0.0.1:9200/reload',
646648
);
647649

648650
// flag-overrides-hint: an explicit flag wins over a conflicting session runtime hint.
649651
assert.equal(
650-
resolveMetroReloadUrl({
652+
resolveMetroReloadEndpoints({
651653
metroHost: '10.0.0.5',
652654
metroPort: 9300,
653655
runtime: { metroHost: '127.0.0.1', metroPort: 9200 },
654-
}),
656+
}).reloadUrl,
655657
'http://10.0.0.5:9300/reload',
656658
);
657659

658660
// A single explicit flag still overrides only its own field; the hint fills the rest.
659661
assert.equal(
660-
resolveMetroReloadUrl({
662+
resolveMetroReloadEndpoints({
661663
metroPort: 9400,
662664
runtime: { metroHost: '192.168.1.5', metroPort: 9200 },
663-
}),
665+
}).reloadUrl,
664666
'http://192.168.1.5:9400/reload',
665667
);
666668
});
667669

670+
test('resolveMetroReloadEndpoints keeps the bundle URL mount prefix instead of collapsing to the host root', () => {
671+
// Expo virtual entry at the server root: the entry-module path is not a mount prefix, so the
672+
// endpoints live at the root (verified live: Expo serves /message at the server root).
673+
assert.deepEqual(
674+
resolveMetroReloadEndpoints({
675+
runtime: {
676+
metroHost: '127.0.0.1',
677+
metroPort: 8082,
678+
bundleUrl:
679+
'http://127.0.0.1:8082/.expo/.virtual-metro-entry.bundle?platform=ios&dev=true&minify=false',
680+
},
681+
}),
682+
{
683+
reloadUrl: 'http://127.0.0.1:8082/reload',
684+
messageSocketUrl: 'ws://127.0.0.1:8082/message',
685+
},
686+
);
687+
688+
// Proxy/mount prefix carrying the Expo virtual entry keeps the mount prefix only.
689+
assert.deepEqual(
690+
resolveMetroReloadEndpoints({
691+
bundleUrl:
692+
'http://proxy.example.test/tenant-42/.expo/.virtual-metro-entry.bundle?platform=android',
693+
}),
694+
{
695+
reloadUrl: 'http://proxy.example.test/tenant-42/reload',
696+
messageSocketUrl: 'ws://proxy.example.test/tenant-42/message',
697+
},
698+
);
699+
700+
// Proxy/mount prefix carrying a plain index.bundle keeps the prefix (Re.Pack/RN over a proxy);
701+
// https maps the message socket to wss.
702+
assert.deepEqual(
703+
resolveMetroReloadEndpoints({
704+
bundleUrl: 'https://proxy.example.test/metro/runtime-1/index.bundle?platform=ios',
705+
}),
706+
{
707+
reloadUrl: 'https://proxy.example.test/metro/runtime-1/reload',
708+
messageSocketUrl: 'wss://proxy.example.test/metro/runtime-1/message',
709+
},
710+
);
711+
712+
// Root index.bundle still reloads at the host root.
713+
assert.deepEqual(
714+
resolveMetroReloadEndpoints({
715+
bundleUrl: 'http://127.0.0.1:8081/index.bundle?platform=ios',
716+
}),
717+
{
718+
reloadUrl: 'http://127.0.0.1:8081/reload',
719+
messageSocketUrl: 'ws://127.0.0.1:8081/message',
720+
},
721+
);
722+
});
723+
668724
test('metro reload targets the dev server bound by metro prepare in the same session', async () => {
669725
const tempRoot = path.join(os.tmpdir(), `agent-device-metro-session-${randomUUID()}`);
670726
const projectRoot = path.join(tempRoot, 'project');
@@ -736,14 +792,158 @@ test('metro reload targets the dev server bound by metro prepare in the same ses
736792
}),
737793
undefined,
738794
);
739-
assert.equal(resolveMetroReloadUrl({}), 'http://localhost:8081/reload');
795+
assert.equal(resolveMetroReloadEndpoints({}).reloadUrl, 'http://localhost:8081/reload');
796+
} finally {
797+
process.env.PATH = previousPath;
798+
await stopProcess(pid);
799+
rmSync(tempRoot, { recursive: true, force: true });
800+
}
801+
});
802+
803+
test('metro reload for an expo session resolves the bound virtual-entry bundle URL to root endpoints', async () => {
804+
const tempRoot = path.join(os.tmpdir(), `agent-device-metro-expo-session-${randomUUID()}`);
805+
const projectRoot = path.join(tempRoot, 'project');
806+
const binDir = path.join(tempRoot, 'bin');
807+
const stateDir = path.join(tempRoot, 'state');
808+
const metroPort = await findFreePort();
809+
810+
mkdirSync(projectRoot, { recursive: true });
811+
mkdirSync(binDir, { recursive: true });
812+
writeFileSync(
813+
path.join(projectRoot, 'package.json'),
814+
JSON.stringify({
815+
name: 'metro-expo-session-test',
816+
private: true,
817+
dependencies: { expo: '51.0.0', 'react-native': '0.0.0-test' },
818+
}),
819+
);
820+
writeFakeNpx(binDir);
821+
822+
const client = createAgentDeviceClient(
823+
{ session: 'metro-expo-session', stateDir, cwd: projectRoot },
824+
{
825+
transport: async () => {
826+
throw new Error('metro prepare/reload must stay local and never call the daemon');
827+
},
828+
},
829+
);
830+
831+
const previousPath = process.env.PATH;
832+
process.env.PATH = `${binDir}${path.delimiter}${previousPath ?? ''}`;
833+
834+
let pid = 0;
835+
try {
836+
const prepared = await client.metro.prepare({
837+
projectRoot,
838+
kind: 'expo',
839+
publicBaseUrl: `http://127.0.0.1:${metroPort}`,
840+
port: metroPort,
841+
reuseExisting: false,
842+
installDependenciesIfNeeded: false,
843+
});
844+
pid = prepared.pid;
845+
846+
const storedHints = readMetroSessionHints({
847+
stateDir: resolveDaemonPaths(stateDir).baseDir,
848+
session: 'metro-expo-session',
849+
});
850+
assert.deepEqual(storedHints, {
851+
metroHost: '127.0.0.1',
852+
metroPort,
853+
bundleUrl: `http://127.0.0.1:${metroPort}/.expo/.virtual-metro-entry.bundle?platform=ios&dev=true&minify=false`,
854+
});
855+
856+
// A flagless reload resolves from the stored virtual-entry bundle URL: the entry-module path
857+
// maps to the server root, not to a phantom /.expo mount.
858+
const hintedReload = await client.metro.reload();
859+
assert.equal(hintedReload.reloadUrl, `http://127.0.0.1:${metroPort}/reload`);
860+
assert.equal(hintedReload.body, 'RELOADED');
861+
assert.equal(hintedReload.transport, 'http');
740862
} finally {
741863
process.env.PATH = previousPath;
742864
await stopProcess(pid);
743865
rmSync(tempRoot, { recursive: true, force: true });
744866
}
745867
});
746868

869+
test('reloadMetro falls back to the /message websocket when the HTTP route answers with the app page', async () => {
870+
const receivedMessages: string[] = [];
871+
const upgradedSockets = new Set<import('node:stream').Duplex>();
872+
const server = createServer((req, res) => {
873+
if (req.url === '/reload') {
874+
// Expo-style: no HTTP reload route; the SPA fallback answers with the app page.
875+
res.statusCode = 200;
876+
res.setHeader('content-type', 'text/html');
877+
res.end('<!DOCTYPE html>\n<html><body>app page</body></html>');
878+
return;
879+
}
880+
res.statusCode = 404;
881+
res.end('not found');
882+
});
883+
server.on('upgrade', (req, socket) => {
884+
if (req.url !== '/message') {
885+
socket.destroy();
886+
return;
887+
}
888+
// Upgraded sockets leave the server's connection tracking; keep them for teardown.
889+
upgradedSockets.add(socket);
890+
socket.on('close', () => upgradedSockets.delete(socket));
891+
const key = req.headers['sec-websocket-key'] ?? '';
892+
const accept = createHash('sha1')
893+
.update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
894+
.digest('base64');
895+
socket.write(
896+
'HTTP/1.1 101 Switching Protocols\r\n' +
897+
'Upgrade: websocket\r\n' +
898+
'Connection: Upgrade\r\n' +
899+
`Sec-WebSocket-Accept: ${accept}\r\n\r\n`,
900+
);
901+
socket.on('data', (frame: Buffer) => {
902+
const text = decodeMaskedTextFrame(frame);
903+
if (text) receivedMessages.push(text);
904+
});
905+
});
906+
server.listen(0, '127.0.0.1');
907+
await once(server, 'listening');
908+
const address = server.address();
909+
assert.ok(address && typeof address !== 'string');
910+
911+
try {
912+
const result = await reloadMetro({
913+
bundleUrl: `http://127.0.0.1:${address.port}/.expo/.virtual-metro-entry.bundle?platform=ios`,
914+
timeoutMs: 3_000,
915+
});
916+
917+
assert.equal(result.transport, 'message-socket');
918+
assert.equal(result.reloadUrl, `ws://127.0.0.1:${address.port}/message`);
919+
assert.deepEqual(
920+
receivedMessages.map((message) => JSON.parse(message)),
921+
[{ version: 2, method: 'reload' }],
922+
);
923+
} finally {
924+
for (const socket of upgradedSockets) {
925+
socket.destroy();
926+
}
927+
await closeServer(server);
928+
}
929+
});
930+
931+
// Minimal RFC 6455 decode for one small (<126 byte) masked client text frame; enough for the
932+
// single broadcast message this suite sends without adding a websocket-server dependency.
933+
function decodeMaskedTextFrame(frame: Buffer): string | null {
934+
if (frame.length < 6) return null;
935+
const opcode = frame[0]! & 0x0f;
936+
if (opcode !== 0x1) return null;
937+
const length = frame[1]! & 0x7f;
938+
if (length > 125 || frame.length < 6 + length) return null;
939+
const mask = frame.subarray(2, 6);
940+
const payload = Buffer.from(frame.subarray(6, 6 + length));
941+
for (let i = 0; i < payload.length; i += 1) {
942+
payload[i] = payload[i]! ^ mask[i % 4]!;
943+
}
944+
return payload.toString('utf8');
945+
}
946+
747947
function writeFakePackageManager(binDir: string, name: string, argsFile: string): void {
748948
const filePath = path.join(binDir, name);
749949
writeFileSync(
@@ -793,7 +993,7 @@ const server = http.createServer((req, res) => {
793993
res.end("packager-status:running")
794994
return
795995
}
796-
if (req.url && req.url.startsWith("/index.bundle")) {
996+
if (req.url && (req.url.startsWith("/index.bundle") || req.url.includes(".virtual-metro-entry.bundle"))) {
797997
res.statusCode = 200
798998
res.setHeader("content-type", "application/javascript")
799999
res.end("console.log('metro-runtime-test')")

‎src/commands/metro/index.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,10 @@ const metroCliSchema = {
7979
"this session last bound via metro prepare or open's metro hint flags (falling back to " +
8080
'localhost:8081 only when the session never bound one), so it never silently reloads a ' +
8181
"different project's server on the default port; pass an explicit flag to override the " +
82-
'session hint for one call. The binding is cleared when the session closes, and a fresh ' +
82+
'session hint for one call. The reload URL keeps the bound bundle URL mount prefix instead ' +
83+
'of collapsing to the host root, and when the server has no HTTP /reload route (Expo) the ' +
84+
'reload is broadcast over its /message websocket instead of trusting the app-page fallback. ' +
85+
'The binding is cleared when the session closes, and a fresh ' +
8386
'open without hint flags also clears any leftover binding from a previous same-name session. ' +
8487
'--kind expo (detected or forced) requests the virtual-entry bundle URL ' +
8588
'(.expo/.virtual-metro-entry.bundle) instead of index.bundle, since index.bundle 404s/500s ' +

0 commit comments

Comments
 (0)