Simplify preview URL core module

Move proxy metadata, forwarding request construction, and token helpers
behind focused preview utilities so PreviewService stays centered on
preview URL state and lifecycle decisions.

Author: ghostwriternr

packages/sandbox/src/preview/protocol.ts

@@ -1,3 +1,5 @@
+import { validatePort } from '../security';
+
 /** @internal */
 export const PREVIEW_PROXY_HEADER = 'x-sandbox-preview-proxy';
 /** @internal */
@@ -14,3 +16,48 @@ export const PREVIEW_PROXY_HEADERS = [
   PREVIEW_PROXY_TOKEN_HEADER,
   PREVIEW_PROXY_SANDBOX_ID_HEADER
 ] as const;
+
+export interface PreviewProxyMetadata {
+  port: number;
+  token: string;
+  sandboxId: string;
+}
+
+export function isPreviewProxyRequest(request: Request): boolean {
+  return request.headers.get(PREVIEW_PROXY_HEADER) === '1';
+}
+
+export function readPreviewProxyMetadata(
+  request: Request
+): PreviewProxyMetadata | null {
+  if (!isPreviewProxyRequest(request)) {
+    return null;
+  }
+
+  const portValue = request.headers.get(PREVIEW_PROXY_PORT_HEADER);
+  const token = request.headers.get(PREVIEW_PROXY_TOKEN_HEADER);
+  const sandboxId = request.headers.get(PREVIEW_PROXY_SANDBOX_ID_HEADER);
+  const port = portValue === null ? Number.NaN : Number.parseInt(portValue, 10);
+
+  if (!Number.isFinite(port) || !validatePort(port) || !token || !sandboxId) {
+    return null;
+  }
+
+  return { port, token, sandboxId };
+}
+
+export function withPreviewProxyMetadata(
+  request: Request,
+  { port, token, sandboxId }: PreviewProxyMetadata
+): Request {
+  const headers = new Headers(request.headers);
+  for (const header of PREVIEW_PROXY_HEADERS) {
+    headers.delete(header);
+  }
+  headers.set(PREVIEW_PROXY_HEADER, '1');
+  headers.set(PREVIEW_PROXY_PORT_HEADER, port.toString());
+  headers.set(PREVIEW_PROXY_TOKEN_HEADER, token);
+  headers.set(PREVIEW_PROXY_SANDBOX_ID_HEADER, sandboxId);
+
+  return new Request(request, { headers });
+}

packages/sandbox/src/preview/proxy-request.ts

@@ -0,0 +1,46 @@
+import { PREVIEW_PROXY_HEADERS } from './protocol';
+
+export interface BuildPreviewProxyRequestOptions {
+  port: number;
+  sandboxId: string;
+  sandboxName: string | null;
+}
+
+export function buildPreviewProxyRequest(
+  request: Request,
+  { port, sandboxId, sandboxName }: BuildPreviewProxyRequestOptions
+): Request {
+  const url = new URL(request.url);
+  const proxyURL = `http://localhost:${port}${url.pathname}${url.search}`;
+  const headers = stripPreviewProxyHeaders(request.headers);
+
+  headers.set('X-Original-URL', request.url);
+  headers.set('X-Forwarded-Host', url.hostname);
+  headers.set('X-Forwarded-Proto', url.protocol.replace(':', ''));
+  headers.set('X-Sandbox-Name', sandboxName ?? sandboxId);
+
+  const upgradeHeader = request.headers.get('Upgrade');
+  if (upgradeHeader?.toLowerCase() === 'websocket') {
+    return new Request(request, {
+      headers,
+      redirect: 'manual'
+    });
+  }
+
+  return new Request(proxyURL, {
+    method: request.method,
+    headers,
+    body: request.body,
+    // @ts-expect-error - duplex required for body streaming in modern runtimes
+    duplex: 'half',
+    redirect: 'manual'
+  });
+}
+
+function stripPreviewProxyHeaders(source: Headers): Headers {
+  const headers = new Headers(source);
+  for (const header of PREVIEW_PROXY_HEADERS) {
+    headers.delete(header);
+  }
+  return headers;
+}