@pyric/cli 0.1.0-alpha.30.1 → 0.1.0-alpha.31

package/src/serve/app-ports.ts

@@ -0,0 +1,119 @@
+/**
+ * The ports a page of this app may name in its `Origin` when it opens the
+ * bridge socket or calls a control route.
+ *
+ * A page this server serves names the server's own port. Under a dev server
+ * that proxies `/__pyric/*` to this one, such as `withPyric`'s rewrite under
+ * `pyric sandbox -- next dev`, the page loads from the dev server, so its
+ * Origin names the dev server's port instead. The proxy says which port that
+ * is: it forwards each request with `x-forwarded-host` set to the host the
+ * browser asked it for. A socket the proxy forwards (the Node host's page)
+ * carries that header itself. A socket that comes straight to this server
+ * (the SharedWorker sandbox) does not, but the page's `/__pyric/init.json`
+ * went through the proxy before the page learned the bridge URL, so the
+ * port was learned from that request.
+ *
+ * Only a same-origin request teaches a port: one whose `sec-fetch-site` is
+ * `same-origin`, which the browser sets and a page cannot change. The page
+ * Next serves fetches `/__pyric/*` from Next's own origin, and the proxy
+ * passes the header through. A page on another port that sends the request
+ * itself, even with an `x-forwarded-host` it chose, is `same-site` at most,
+ * so it teaches nothing. A proxy names its own host, never the page's, so a
+ * page on another port that goes through the proxy is still refused. Only
+ * loopback names and the bound host are learned; a name allowed through
+ * `--allowed-host` (a tunnel) is never port-checked in the first place.
+ *
+ * Only the standalone server learns (`learnsProxyPorts`). A mount inside a
+ * dev server, such as the Vite plugin's, serves the page on the connection's
+ * own port, and that dev server may answer cross-origin preflights for
+ * `/__pyric/*` paths it does not handle.
+ */
+import type { IncomingMessage } from 'node:http';
+import { getHeader, isAllowedHost } from './server.js';
+
+/** A dev server proxies from one port; a handful covers restarts on new ports. */
+const MAX_LEARNED_PORTS = 8;
+
+export interface AppPorts {
+  /** Records the proxy port a same-origin forwarded request names. */
+  learn(req: IncomingMessage): void;
+  /** The ports a page's Origin may name on this request's connection. */
+  forRequest(req: IncomingMessage): number[];
+  /**
+   * The same, plus the proxy's port when a proxy forwarded this WebSocket
+   * upgrade from the page it serves: the Origin names the host the proxy
+   * names in `x-forwarded-host`. A browser cannot put a header on a
+   * WebSocket handshake, so only a proxy can name that host, and it names
+   * its own. The page may open its socket before any same-origin request
+   * has gone through the proxy, as the Node host's page under Next does.
+   */
+  forUpgrade(req: IncomingMessage): number[];
+}
+
+export function createAppPorts(boundHost: string): AppPorts {
+  const learned = new Set<number>();
+  const forRequest = (req: IncomingMessage): number[] => {
+    const ports = [...learned];
+    const localPort = req.socket?.localPort;
+    const hasLocalPort = typeof localPort === 'number';
+    if (hasLocalPort) ports.unshift(localPort);
+    return ports;
+  };
+  return {
+    learn(req) {
+      const isSameOrigin = getHeader(req, 'sec-fetch-site') === 'same-origin';
+      if (!isSameOrigin) return;
+      const port = forwardedLoopbackPort(getHeader(req, 'x-forwarded-host'), boundHost);
+      const namesNoPort = port === undefined;
+      if (namesNoPort) return;
+      learned.delete(port);
+      learned.add(port);
+      const isOverCapacity = learned.size > MAX_LEARNED_PORTS;
+      if (isOverCapacity) learned.delete(learned.values().next().value as number);
+    },
+    forRequest,
+    forUpgrade(req) {
+      const ports = forRequest(req);
+      const proxyPort = proxiedPagePort(req, boundHost);
+      const isProxiedFromItsPage = proxyPort !== undefined;
+      if (isProxiedFromItsPage) ports.push(proxyPort);
+      return ports;
+    },
+  };
+}
+
+/** The proxy's port when the Origin names the host `x-forwarded-host` names, else `undefined`. */
+function proxiedPagePort(req: IncomingMessage, boundHost: string): number | undefined {
+  const forwardedHost = getHeader(req, 'x-forwarded-host');
+  const originHeader = getHeader(req, 'origin');
+  const lacksEither = forwardedHost === undefined || originHeader === undefined;
+  if (lacksEither) return undefined;
+  let origin: URL;
+  try {
+    origin = new URL(originHeader);
+  } catch {
+    return undefined;
+  }
+  const namesTheProxy = origin.host.toLowerCase() === forwardedHost.trim().toLowerCase();
+  if (!namesTheProxy) return undefined;
+  return forwardedLoopbackPort(forwardedHost, boundHost);
+}
+
+/** The port in a single loopback `x-forwarded-host`, else `undefined`. */
+function forwardedLoopbackPort(forwardedHost: string | undefined, boundHost: string): number | undefined {
+  const hasNoForwardedHost = forwardedHost === undefined || forwardedHost.trim() === '';
+  if (hasNoForwardedHost) return undefined;
+  const namesSeveralHosts = forwardedHost.includes(',');
+  if (namesSeveralHosts) return undefined;
+  let forwarded: URL;
+  try {
+    forwarded = new URL(`http://${forwardedHost.trim()}`);
+  } catch {
+    return undefined;
+  }
+  const isLoopback = isAllowedHost(forwarded.hostname, boundHost);
+  if (!isLoopback) return undefined;
+  const namesNoPort = forwarded.port === '';
+  if (namesNoPort) return 80;
+  return Number(forwarded.port);
+}

package/src/serve/bridge-mount.ts

@@ -29,8 +29,10 @@ import { getBridgeToolSurface } from '../bridge/server/mcp-contract.js';
 import { createAuditWriter } from '../bridge/server/audit.js';
 import { attachPeer, collectBody, BODY_TOO_LARGE_CODE } from '../bridge/server/peer.js';
 import { pointerHeldByAnotherHost } from './discovery.js';
+import { boundedFetch } from '../bounded-request.js';
 import { pyricVersion } from './standalone-assets.js';
 import { getHeader, isAllowedHost, isAllowedLoopbackRequest, isAllowedOrigin, isAllowedUpgrade } from './server.js';
+import { createAppPorts, type AppPorts } from './app-ports.js';
 import { MAX_BRIDGE_FRAME_BYTES, MAX_MOUNTED_MCP_SESSIONS, STORAGE_BYTE_ROUTE_CAPABILITY, WORKER_PORT_CAPABILITY, WORKER_RELAY_CAPABILITY } from '../bridge/protocol.js';
 import { STORAGE_ROUTE_PREFIX } from './worker/protocol/storage.js';
 import type { DatabaseRulesDestination, InitPayload } from './init-payload.js';
@@ -40,9 +42,15 @@ import { MCP_PROJECT_HEADER, MCP_INSTANCE_HEADER, mcpProjectError } from './mcp-
 
 const WS_PATH = '/__pyric/sandbox';
 const MCP_PATH = '/__pyric/mcp';
-const HEALTH_PATH = '/__pyric/health';
+export const HEALTH_PATH = '/__pyric/health';
 const BRIDGE_VERSION = pyricVersion();
 
+/** The 503 a closed mount answers its routes with, so a client knows the host is going away. */
+export function answerMountClosed(res: ServerResponse): void {
+  res.writeHead(503, { 'content-type': 'application/json' });
+  res.end(JSON.stringify({ error: 'pyric bridge: mount is closed' }));
+}
+
 /**
  * Test-only: `PYRIC_TEST_PEER_LIVENESS_MS` shortens the host's peer liveness
  * window so app scenarios (`test/apps/host-closes-silent-page`) need not wait
@@ -68,6 +76,15 @@ export interface BridgeMountOptions {
    *  `allowedHosts: true` = the caller (vite `server.allowedHosts: true`) opted
    *  into all hosts. Omit ⇒ loopback-only. */
   upgradeGuard?: { boundHost: string; allowedHosts?: string[] | true };
+  /** Accept a page on the port of a dev server that proxies `/__pyric/*` to
+   *  this one (`pyric sandbox -- next dev`). Only the standalone server sets
+   *  it. A mount inside a dev server, such as the Vite plugin's, serves the
+   *  page on its own port, which the connection's port already covers. */
+  learnsProxyPorts?: boolean;
+  /** The app's ports, shared with the namespace's guarded routes. The caller
+   *  that passes them teaches them from each request, so the mount does not.
+   *  Absent, the mount keeps its own and learns when `learnsProxyPorts`. */
+  appPorts?: AppPorts;
 }
 
 export interface BridgeMount {
@@ -131,6 +148,10 @@ export interface BridgeHostAttachment {
 
 export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
   const peerOptions = { livenessTimeoutMs: testPeerLivenessMs() };
+  // The ports a page of this app may name in its Origin (see app-ports.ts).
+  const sharesPorts = opts.appPorts !== undefined;
+  const appPorts = opts.appPorts ?? createAppPorts(opts.upgradeGuard?.boundHost ?? 'localhost');
+  const learnsHere = opts.learnsProxyPorts === true && !sharesPorts;
   let hostedRuntime: Awaited<ReturnType<typeof createHostedRuntime>> | undefined;
   let hostedStartup: Promise<void> | undefined;
   let disconnectHosted: (() => void) | undefined;
@@ -313,6 +334,7 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
     instanceId: bridge.instanceId,
 
     async handler(req, res, url) {
+      if (learnsHere) appPorts.learn(req);
       const isHealthRequest = url.pathname === HEALTH_PATH;
       const isMcpRequest = url.pathname === MCP_PATH;
       const isHostedRepro = url.pathname === HOSTED_REPRO_PATH;
@@ -321,8 +343,7 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
       const isStorageBytes = url.pathname.startsWith(STORAGE_ROUTE_PREFIX);
       const rejectsClosedRequest = closed && (isHealthRequest || isMcpRequest || isHostedMethod || isStorageBytes);
       if (rejectsClosedRequest) {
-        res.writeHead(503, { 'content-type': 'application/json' });
-        res.end(JSON.stringify({ error: 'pyric bridge: mount is closed' }));
+        answerMountClosed(res);
         return true;
       }
       if (isHealthRequest) {
@@ -338,7 +359,7 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
           const allowedHosts = guard?.allowedHosts;
           const hasNamedHosts = Array.isArray(allowedHosts);
           const extra = hasNamedHosts ? allowedHosts : [];
-          const isForbidden = !isAllowedLoopbackRequest(req, boundHost, extra);
+          const isForbidden = !isAllowedLoopbackRequest(req, boundHost, extra, appPorts.forRequest(req));
           if (isForbidden) {
             res.writeHead(403, { 'content-type': 'application/json' });
             res.end(JSON.stringify({ error: 'Forbidden: invalid host or origin' }));
@@ -534,7 +555,9 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
           const allowedHosts = guard.allowedHosts;
           const hasNamedHosts = Array.isArray(allowedHosts);
           const extra = hasNamedHosts ? allowedHosts : [];
-          const isForbidden = !isAllowedUpgrade(req.headers, boundHost, extra);
+          const acceptsProxiedPage = opts.learnsProxyPorts === true;
+          const ports = acceptsProxiedPage ? appPorts.forUpgrade(req) : appPorts.forRequest(req);
+          const isForbidden = !isAllowedUpgrade(req.headers, boundHost, extra, ports);
           if (isForbidden) {
             socket.destroy();
             return;
@@ -583,11 +606,16 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
         if (hasNoCollisionProbe) return;
         const cannotProbe = !currentOrigin?.port || attachmentClosed;
         if (cannotProbe) return;
+        // By default a bounded request, connect included, so a family whose
+        // connect never completes leaves no socket pending past 1 s (#1167).
+        const probeHealth = (url: string): Promise<Response> => {
+          const injected = collision.fetchImpl;
+          if (injected) return injected(url, { signal: AbortSignal.any([collisionAbort.signal, AbortSignal.timeout(1000)]) });
+          return boundedFetch(url, { deadlineMs: 1000, signal: collisionAbort.signal });
+        };
         for (const probe of [`http://127.0.0.1:${currentOrigin.port}`, `http://[::1]:${currentOrigin.port}`]) {
           try {
-            const response = await (collision.fetchImpl ?? fetch)(`${probe}${HEALTH_PATH}`, {
-              signal: AbortSignal.any([collisionAbort.signal, AbortSignal.timeout(1000)]),
-            });
+            const response = await probeHealth(`${probe}${HEALTH_PATH}`);
             if (attachmentClosed) return;
             const isUnavailable = response.status !== 200;
             if (isUnavailable) continue;

package/src/serve/bundler.ts

@@ -27,6 +27,15 @@ import { homedir } from 'node:os';
 import { dirname, join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as esbuild from 'esbuild';
+import { withWorkerBuildLock, type WorkerBuildLock } from './worker-build-lock.js';
+import {
+  WORKER_EPOCH_FILE,
+  WORKER_FILE,
+  publishWorkerBundle,
+  readCompletedWorkerBundle,
+  removeBuildLeftovers,
+  stagingPathPrefix,
+} from './worker-bundle-cache.js';
 
 import { bridgeImportEntryKey, REAL_SDK_ENTRIES } from './firebase-module-swap.js';
 
@@ -524,19 +533,11 @@ export interface WorkerBundleOptions {
   entryPath?: string;
   /** Restart-required boot identity mixed into the baked worker epoch. */
   epochSalt?: string;
+  /** Test seam around the build into the staging directory; `build` is the real one. */
+  buildInto?: (stagingDir: string, build: () => Promise<string>) => Promise<string>;
 }
 
 const WORKER_EPOCH_PLACEHOLDER = 'PYRIC_EPOCH_HERE';
-const WORKER_EPOCH_FILE = '.worker-epoch';
-
-/** Read the executable epoch written alongside a completed worker bundle. */
-function readWorkerBundleEpoch(outDir: string): string {
-  const epoch = readFileSync(join(outDir, WORKER_EPOCH_FILE), 'utf8').trim();
-  if (!/^[a-f0-9]{16}$/.test(epoch)) {
-    throw new Error(`pyric sandbox: invalid SharedWorker epoch in ${join(outDir, WORKER_EPOCH_FILE)}`);
-  }
-  return epoch;
-}
 
 /**
  * Conservative worker CACHE key. The worker bundle shares the SDK `outDir`
@@ -601,6 +602,10 @@ export function sourceTreeHash(root: string): string {
  * while `cacheKey()` includes the complete CLI source graph. A worker/client
  * or protocol edit therefore invalidates the shared SDK generation too, so
  * the page and worker halves cannot come from different source generations.
+ *
+ * Builders sharing `outDir` (every project on the machine shares
+ * `~/.pyric/vite-worker/<hash>`) take turns under a lock and publish from a
+ * staging directory; see `worker-bundle-cache.ts`.
  */
 export interface WorkerBundleResult {
   outFile: string;
@@ -608,24 +613,78 @@ export interface WorkerBundleResult {
 }
 
 export async function bundleWorker(opts: WorkerBundleOptions): Promise<WorkerBundleResult> {
-  const outFile = join(opts.outDir, 'worker.js');
-  const marker = join(opts.outDir, '.worker-complete');
-  const sourceHash = workerSourceHash();
-  const hash = opts.epochSalt
-    ? createHash('sha256').update(sourceHash).update('\0').update(opts.epochSalt).digest('hex')
-    : sourceHash;
-  if (
-    !opts.noCache &&
-    existsSync(outFile) &&
-    existsSync(marker) &&
-    existsSync(join(opts.outDir, WORKER_EPOCH_FILE)) &&
-    readFileSync(marker, 'utf8') === hash
-  ) {
-    return { outFile, epoch: readWorkerBundleEpoch(opts.outDir) };
+  const outFile = join(opts.outDir, WORKER_FILE);
+  const hash = workerBundleHash(opts.epochSalt);
+  const reusesCache = !opts.noCache;
+  const cachedEpoch = reusesCache ? readCompletedWorkerBundle(opts.outDir, hash) : null;
+  if (cachedEpoch) return { outFile, epoch: cachedEpoch };
+
+  for (let attempt = 1; ; attempt++) {
+    const epoch = await withWorkerBuildLock(opts.outDir, (lock) => buildUnderLock(opts, hash, lock));
+    if (epoch) return { outFile, epoch };
+    const isLastAttempt = attempt >= MAX_WORKER_PUBLISH_ATTEMPTS;
+    if (isLastAttempt) {
+      throw new Error(`pyric sandbox: another process kept replacing the SharedWorker bundle in ${opts.outDir}`);
+    }
   }
+}
 
-  mkdirSync(opts.outDir, { recursive: true });
-  const root = pyricPackageRoot();
+const MAX_WORKER_PUBLISH_ATTEMPTS = 3;
+
+/**
+ * Build and publish while holding the lock, then return the epoch of the
+ * bundle on disk. That is the bundle the page is served, even when another
+ * process published over ours, or null when what is on disk is torn.
+ */
+async function buildUnderLock(opts: WorkerBundleOptions, hash: string, lock: WorkerBuildLock): Promise<string | null> {
+  // Another process may have finished this bundle while we waited.
+  const builtMeanwhile = opts.noCache ? null : readCompletedWorkerBundle(opts.outDir, hash);
+  if (builtMeanwhile) return builtMeanwhile;
+  removeBuildLeftovers(opts.outDir);
+  const stagingDir = mkdtempSync(stagingPathPrefix(opts.outDir));
+  try {
+    const built = await buildWhileHeld(stagingDir, opts, lock);
+    if (!built) return null;
+    // A builder whose lock was taken over as abandoned leaves the directory to the new holder.
+    if (lock.isHeld()) publishWorkerBundle(stagingDir, opts.outDir, hash);
+  } finally {
+    rmSync(stagingDir, { recursive: true, force: true });
+  }
+  return readCompletedWorkerBundle(opts.outDir, hash);
+}
+
+/**
+ * Build into `stagingDir`, or report false when the build failed after another
+ * process took the lock over. A builder in another pid namespace looks exited,
+ * so its lock can be taken while it still builds, and the new holder may remove
+ * its staging directory. That build's failure is not this caller's error: it
+ * retries under the lock and reads what the new holder published.
+ */
+async function buildWhileHeld(stagingDir: string, opts: WorkerBundleOptions, lock: WorkerBuildLock): Promise<boolean> {
+  const build = () => buildWorkerInto(stagingDir, opts);
+  try {
+    await (opts.buildInto ? opts.buildInto(stagingDir, build) : build());
+    return true;
+  } catch (error) {
+    if (lock.isHeld()) throw error;
+    return false;
+  }
+}
+
+/** The marker hash: the worker source graph, plus the boot salt when one is given. */
+function workerBundleHash(epochSalt: string | undefined): string {
+  const sourceHash = workerSourceHash();
+  if (!epochSalt) return sourceHash;
+  return createHash('sha256').update(sourceHash).update('\0').update(epochSalt).digest('hex');
+}
+
+/**
+ * Build the worker into a private staging directory and bake its epoch.
+ * The staging directory is a sibling of `outDir`, so the sourcemap's relative
+ * source paths stay correct after the files move.
+ */
+async function buildWorkerInto(stagingDir: string, opts: WorkerBundleOptions): Promise<string> {
+  const outFile = join(stagingDir, WORKER_FILE);
   const result = await esbuild.build({
     entryPoints: [opts.entryPath ?? workerEntryPath()],
     outfile: outFile,
@@ -658,7 +717,6 @@ export async function bundleWorker(opts: WorkerBundleOptions): Promise<WorkerBun
   if (opts.epochSalt) epochHash.update('\0').update(opts.epochSalt);
   const epoch = epochHash.digest('hex').slice(0, 16);
   writeFileSync(outFile, canonicalSource.replaceAll(WORKER_EPOCH_PLACEHOLDER, epoch));
-  writeFileSync(join(opts.outDir, WORKER_EPOCH_FILE), epoch);
-  writeFileSync(marker, hash);
-  return { outFile, epoch };
+  writeFileSync(join(stagingDir, WORKER_EPOCH_FILE), epoch);
+  return epoch;
 }