@claxedo/workspace-relay 0.10.0 → 0.10.1

package/dist/cloudflare.d.ts

@@ -1,5 +1,7 @@
 import { type AuthorizedWorkspaceRelayRequest, type WorkspaceRelayOptions } from "./server";
 import { type SessionHostNamespace } from "./session-host-forwarding";
+import { type WorkspaceRelayTraceLogEvent } from "./relay-trace";
+export type { WorkspaceRelayTraceLogEvent } from "./relay-trace";
 export type WorkspaceRelayDurableObjectId = unknown;
 export type WorkspaceRelayDurableObjectStub = {
     fetch: (request: Request) => Promise<Response>;
@@ -94,17 +96,6 @@ export type WorkspaceRelayDurableObjectRoomOptions = WorkspaceRelayOptions & {
     traceLog?: (event: WorkspaceRelayTraceLogEvent) => void;
     now?: () => number;
 };
-export type WorkspaceRelayTraceLogEvent = {
-    event: "workspace_relay_request";
-    traceId: string;
-    workspaceId?: string;
-    routeKind: string;
-    method: string;
-    path: string;
-    status: number;
-    totalMs: number;
-    phases: Record<string, number>;
-};
 export type WorkspaceRelayDurableObjectHibernation = {
     acceptWebSocket: (socket: WorkspaceRelayDurableObjectSocket) => void;
     getWebSockets: () => WorkspaceRelayDurableObjectSocket[];
@@ -199,4 +190,3 @@ export declare function createWorkspaceRelayDurableObjectRoom(options: Workspace
     };
     drain: WorkspaceRelayDurableObjectDrainController;
 };
-export {};

package/dist/index.mjs

@@ -525,7 +525,7 @@ function hostTunnelFailureResponse(error) {
 }
 
 // src/cloudflare.ts
-import { trimToUndefined as trimToUndefined4 } from "@claxedo/helpers/string";
+import { trimToUndefined as trimToUndefined5 } from "@claxedo/helpers/string";
 
 // src/http.ts
 import { bearerToken, trimToUndefined } from "@claxedo/helpers/string";
@@ -549,6 +549,8 @@ function workspaceIdsFromSearch(url) {
 
 // src/cloudflare.ts
 import {
+  closeCode,
+  closeReason,
   makeTunnelPong,
   TUNNEL_PROTOCOL_VERSION,
   validateTunnelMessage
@@ -1425,30 +1427,11 @@ function workspaceRelayRoomPlacement(request, env, workspaceId) {
   });
 }
 
-// src/cloudflare.ts
-var TUNNEL_PENDING_HTTP_CAP_DEFAULT = 32;
-var TUNNEL_STARTED_STREAM_CAP_DEFAULT = 16;
-var TUNNEL_CHANNEL_CAP_DEFAULT = 16;
-var TUNNEL_REQUEST_BODY_MAX_BYTES_DEFAULT = 16 * 1024 * 1024;
-var TUNNEL_RESPONSE_BODY_MAX_BYTES_DEFAULT = 16 * 1024 * 1024;
-var SLOW_CONSUMER_HIGH_WATER_MARK_BYTES_DEFAULT = 8 * 1024 * 1024;
-var SLOW_CONSUMER_TIMEOUT_MS_DEFAULT = 3e4;
-var UPSTREAM_WS_PRE_OPEN_QUEUE_MAX_FRAMES_DEFAULT = 8192;
-var UPSTREAM_WS_PRE_OPEN_QUEUE_MAX_BYTES_DEFAULT = 8 * 1024 * 1024;
-var UPSTREAM_WS_PRE_OPEN_QUEUE_FRAME_OVERHEAD_BYTES = 64;
-var WORKSPACE_TARGET_ACTIVE_CHECK_INTERVAL_MS_DEFAULT = 3e4;
-var RESOLVER_OUTAGE_GRACE_ATTEMPTS_DEFAULT = 3;
-var HIBERNATED_REVOCATION_ALARM_INTERVAL_MS_DEFAULT = 3e4;
-var HOST_GENERATION_CHECK_INTERVAL_MS_DEFAULT = 3e4;
+// src/relay-trace.ts
+import { trimToUndefined as trimToUndefined4 } from "@claxedo/helpers/string";
 var TRACE_ID_HEADER = "x-claxedo-trace-id";
 var TRACE_FORCE_HEADER = "x-claxedo-relay-trace";
 var TRACE_SAMPLED_RESPONSE_HEADER = "x-claxedo-relay-sampled";
-function unrefTimer(timer) {
-  if (typeof timer.unref === "function") timer.unref();
-}
-function isHostTunnelClient(client) {
-  return "channelId" in client && typeof client.channelId === "string";
-}
 function clampRate(input) {
   if (input === void 0 || !Number.isFinite(input)) return 0;
   if (input <= 0) return 0;
@@ -1492,13 +1475,21 @@ function tracedRequest(request, trace, forwarded = request) {
 function roundedMs(value) {
   return Math.round(value * 100) / 100;
 }
-function serverTiming(trace) {
-  return trace.phases.map((phase) => `${phase.name};dur=${roundedMs(phase.ms)}`).join(", ");
+function serverTiming(phases) {
+  return phases.map((phase) => `${phase.name};dur=${roundedMs(phase.ms)}`).join(", ");
+}
+function webSocketTraceFrame(upstreamStartedAt, queueTimes, openedAt) {
+  return {
+    type: "relay.trace",
+    wsUpstreamOpenMs: roundedMs(openedAt - upstreamStartedAt),
+    queuedFrames: queueTimes.length,
+    maxQueuedDelayMs: roundedMs(queueTimes.reduce((max, at) => Math.max(max, openedAt - at), 0))
+  };
 }
 function withTraceHeaders(response, trace) {
   const headers = new Headers(response.headers);
   headers.set(TRACE_ID_HEADER, trace.id);
-  const timing = trace.sampled ? serverTiming(trace) : "";
+  const timing = trace.sampled ? serverTiming(trace.phases) : "";
   if (timing) {
     const existing = headers.get("server-timing");
     headers.set("server-timing", existing ? `${existing}, ${timing}` : timing);
@@ -1531,6 +1522,28 @@ function logTrace(options, request, workspaceId, trace, response) {
   }
   console.log(JSON.stringify(event));
 }
+
+// src/cloudflare.ts
+var TUNNEL_PENDING_HTTP_CAP_DEFAULT = 32;
+var TUNNEL_STARTED_STREAM_CAP_DEFAULT = 16;
+var TUNNEL_CHANNEL_CAP_DEFAULT = 16;
+var TUNNEL_REQUEST_BODY_MAX_BYTES_DEFAULT = 16 * 1024 * 1024;
+var TUNNEL_RESPONSE_BODY_MAX_BYTES_DEFAULT = 16 * 1024 * 1024;
+var SLOW_CONSUMER_HIGH_WATER_MARK_BYTES_DEFAULT = 8 * 1024 * 1024;
+var SLOW_CONSUMER_TIMEOUT_MS_DEFAULT = 3e4;
+var UPSTREAM_WS_PRE_OPEN_QUEUE_MAX_FRAMES_DEFAULT = 8192;
+var UPSTREAM_WS_PRE_OPEN_QUEUE_MAX_BYTES_DEFAULT = 8 * 1024 * 1024;
+var UPSTREAM_WS_PRE_OPEN_QUEUE_FRAME_OVERHEAD_BYTES = 64;
+var WORKSPACE_TARGET_ACTIVE_CHECK_INTERVAL_MS_DEFAULT = 3e4;
+var RESOLVER_OUTAGE_GRACE_ATTEMPTS_DEFAULT = 3;
+var HIBERNATED_REVOCATION_ALARM_INTERVAL_MS_DEFAULT = 3e4;
+var HOST_GENERATION_CHECK_INTERVAL_MS_DEFAULT = 3e4;
+function unrefTimer(timer) {
+  if (typeof timer.unref === "function") timer.unref();
+}
+function isHostTunnelClient(client) {
+  return "channelId" in client && typeof client.channelId === "string";
+}
 function workspaceIdFromRelayPath(pathname) {
   return /^\/workspaces\/([^/]+)(?:\/|$)/.exec(pathname)?.[1];
 }
@@ -1680,20 +1693,15 @@ async function readRequestBodyCapped(request, maxBytes) {
   }
   return concatBytes(chunks);
 }
-function safeCloseCode(code, fallback = 1011) {
-  if (code === void 0) return fallback;
-  if (code >= 1e3 && code <= 4999 && ![1004, 1005, 1006].includes(code)) return code;
-  return fallback;
-}
 function workspaceRelayDurableObjectRoomName(workspaceId) {
   return `workspace:${workspaceId}`;
 }
 function workspaceRelayDurableObjectWorkspaceId(request) {
   const url = new URL(request.url);
-  const workspaceId = trimToUndefined4(workspaceIdFromRelayPath(url.pathname));
+  const workspaceId = trimToUndefined5(workspaceIdFromRelayPath(url.pathname));
   if (workspaceId) return decodeURIComponent(workspaceId);
   if (!hostIdFromTunnelPath(url.pathname)) return void 0;
-  return trimToUndefined4(url.searchParams.get("workspaceId")) ?? trimToUndefined4(url.searchParams.get("workspace_id"));
+  return trimToUndefined5(url.searchParams.get("workspaceId")) ?? trimToUndefined5(url.searchParams.get("workspace_id"));
 }
 function namespaceFromEnv(env, options) {
   if (options.namespace) return options.namespace;
@@ -1743,7 +1751,7 @@ function createWorkspaceRelayDurableObjectGateway(options = {}) {
   return {
     async fetch(request, env = {}) {
       const gatewayStartedAt = performance.now();
-      const gatewayTraceId = trimToUndefined4(request.headers.get(TRACE_ID_HEADER)) ?? crypto.randomUUID();
+      const gatewayTraceId = trimToUndefined5(request.headers.get(TRACE_ID_HEADER)) ?? crypto.randomUUID();
       const url = new URL(request.url);
       if (request.method === "OPTIONS" && (url.pathname.startsWith("/workspaces/") || url.pathname.startsWith("/host-tunnels/"))) {
         return corsPreflight(request);
@@ -1804,12 +1812,12 @@ function createWorkspaceRelayDurableObjectGateway(options = {}) {
       tracedResponse.headers.delete(TRACE_SAMPLED_RESPONSE_HEADER);
       const roomTiming = tracedResponse.headers.get("server-timing") ?? "";
       if (sampled) {
-        const gatewayTiming = [
-          `relay-gateway-route;dur=${roundedMs(routeFinishedAt - gatewayStartedAt)}`,
-          `relay-gateway-do-fetch;dur=${roundedMs(fetchFinishedAt - routeFinishedAt)}`,
-          `relay-gateway-response;dur=${roundedMs(gatewayFinishedAt - gatewayResponseStartedAt)}`,
-          `relay-gateway;dur=${roundedMs(gatewayFinishedAt - gatewayStartedAt)}`
-        ].join(", ");
+        const gatewayTiming = serverTiming([
+          { name: "relay-gateway-route", ms: routeFinishedAt - gatewayStartedAt },
+          { name: "relay-gateway-do-fetch", ms: fetchFinishedAt - routeFinishedAt },
+          { name: "relay-gateway-response", ms: gatewayFinishedAt - gatewayResponseStartedAt },
+          { name: "relay-gateway", ms: gatewayFinishedAt - gatewayStartedAt }
+        ]);
         tracedResponse.headers.set("server-timing", `${roomTiming}, ${gatewayTiming}`);
       }
       return url.pathname.startsWith("/workspaces/") ? withRelayResponseHeaders(request, tracedResponse) : tracedResponse;
@@ -1845,7 +1853,7 @@ function createWorkspaceRelayDurableObjectRoom(options) {
   };
   const closeSocket = (socket, code, reason) => {
     try {
-      socket.close?.(code, reason);
+      socket.close?.(code, closeReason(reason));
     } catch {
     }
   };
@@ -2446,7 +2454,7 @@ function createWorkspaceRelayDurableObjectRoom(options) {
       if (!channel) return;
       tunnel.channels.delete(message.channel_id);
       clients.delete(channel);
-      closeSocket(channel.socket, safeCloseCode(message.code), message.reason ?? "");
+      closeSocket(channel.socket, closeCode(message.code), message.reason ?? "");
       return;
     }
     if (parsed.message.type === "error" && parsed.message.channel_id) {
@@ -2484,7 +2492,7 @@ function createWorkspaceRelayDurableObjectRoom(options) {
         type: "ws.close",
         protocol: TUNNEL_PROTOCOL_VERSION,
         channel_id: channelId,
-        code: safeCloseCode(event?.code, 1e3),
+        code: closeCode(event?.code, 1e3),
         reason: event?.reason ?? "Client WebSocket closed"
       }));
       return;
@@ -2492,7 +2500,7 @@ function createWorkspaceRelayDurableObjectRoom(options) {
   };
   const admitHostTunnel = async (request, roomWorkspaceId, url) => {
     if (!websocketRequest(request)) return json("websocket_upgrade_required", "Workspace Relay requires a WebSocket upgrade", 426);
-    const hostId = trimToUndefined4(hostIdFromTunnelPath(url.pathname));
+    const hostId = trimToUndefined5(hostIdFromTunnelPath(url.pathname));
     if (!hostId) return json("host_tunnel_host_required", "Host tunnel id is required", 400);
     const workspaceIds = workspaceIdsFromSearch(url);
     if (!workspaceIds.includes(roomWorkspaceId)) {
@@ -2594,12 +2602,7 @@ function createWorkspaceRelayDurableObjectRoom(options) {
     const emitTrace = (openedAt) => {
       if (!trace || trace.emitted) return;
       trace.emitted = true;
-      sendSocket(pair.server, JSON.stringify({
-        type: "relay.trace",
-        wsUpstreamOpenMs: roundedMs(openedAt - trace.upstreamStartedAt),
-        queuedFrames: trace.queueTimes.length,
-        maxQueuedDelayMs: roundedMs(trace.queueTimes.reduce((max, at) => Math.max(max, openedAt - at), 0))
-      }));
+      sendSocket(pair.server, JSON.stringify(webSocketTraceFrame(trace.upstreamStartedAt, trace.queueTimes, openedAt)));
     };
     const activeTokenTimer = watchRuntimeAccessToken(client, (reason) => {
       closeSocket(pair.server, 1008, reason);
@@ -2609,14 +2612,14 @@ function createWorkspaceRelayDurableObjectRoom(options) {
       closed = true;
       if (activeTokenTimer) clearInterval(activeTokenTimer);
       clients.delete(client);
-      closeSocket(upstream, safeCloseCode(event?.code, 1e3), event?.reason ?? "Client WebSocket closed");
+      closeSocket(upstream, closeCode(event?.code, 1e3), event?.reason ?? "Client WebSocket closed");
     };
     const cleanupUpstream = (event) => {
       if (closed) return;
       closed = true;
       if (activeTokenTimer) clearInterval(activeTokenTimer);
       clients.delete(client);
-      closeSocket(pair.server, safeCloseCode(event?.code), event?.reason ?? "");
+      closeSocket(pair.server, closeCode(event?.code), event?.reason ?? "");
     };
     const flushQueue = () => {
       upstreamOpen = true;
@@ -2896,6 +2899,7 @@ function createWorkspaceRelayDurableObjectRoom(options) {
     },
     webSocketClose(socket, code, reason) {
       ensureHibernatedSocketsRebuilt();
+      closeSocket(socket, closeCode(code, 1e3), reason);
       const attachment = socketAttachment(socket);
       if (!attachment) return;
       if (attachment.kind === "host-tunnel") {

package/dist/relay-trace.d.ts

@@ -0,0 +1,54 @@
+export declare const TRACE_ID_HEADER = "x-claxedo-trace-id";
+/**
+ * Set by a room on a sampled trace's response and consumed by the gateway: the
+ * gateway appends its own phases only behind this marker, never behind an
+ * upstream's `server-timing`, which a session host answers on every response.
+ */
+export declare const TRACE_SAMPLED_RESPONSE_HEADER = "x-claxedo-relay-sampled";
+export type WorkspaceRelayTraceLogEvent = {
+    event: "workspace_relay_request";
+    traceId: string;
+    workspaceId?: string;
+    routeKind: string;
+    method: string;
+    path: string;
+    status: number;
+    totalMs: number;
+    phases: Record<string, number>;
+};
+export type RelayTraceSampling = {
+    traceSampleRate?: number;
+    traceForceHeaderSecret?: string;
+    random?: () => number;
+};
+export type RelayTrace = {
+    id: string;
+    sampled: boolean;
+    startedAt: number;
+    routeKind: string;
+    phases: Array<{
+        name: string;
+        ms: number;
+    }>;
+};
+export declare function traceRequest(request: Request, routeKind: string, options: RelayTraceSampling): RelayTrace;
+export declare function traceSpan<T>(trace: RelayTrace | undefined, name: string, fn: () => Promise<T>): Promise<T>;
+export declare function tracedRequest(request: Request, trace: RelayTrace, forwarded?: {
+    url: string;
+    headers: Headers;
+}): Request;
+export declare function serverTiming(phases: ReadonlyArray<{
+    name: string;
+    ms: number;
+}>): string;
+/** The `relay.trace` frame a client that opted in with `x-claxedo-relay-ws-trace` receives once the upstream opens. */
+export declare function webSocketTraceFrame(upstreamStartedAt: number, queueTimes: readonly number[], openedAt: number): {
+    type: string;
+    wsUpstreamOpenMs: number;
+    queuedFrames: number;
+    maxQueuedDelayMs: number;
+};
+export declare function withTraceHeaders(response: Response, trace: RelayTrace): Response;
+export declare function logTrace(options: {
+    traceLog?: (event: WorkspaceRelayTraceLogEvent) => void;
+}, request: Request, workspaceId: string | undefined, trace: RelayTrace, response: Response): void;

package/dist/workerd-fixture/compatibility.d.ts

@@ -0,0 +1,2 @@
+/** The relay's deployed `compatibility_date`, so a real-workerd test boots the relay as it ships. */
+export declare function relayCompatibilityDate(config?: string): string;

package/package.json

@@ -33,26 +33,26 @@
     "access": "public"
   },
   "name": "@claxedo/workspace-relay",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "scripts": {
     "build": "tsx scripts/build.ts",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "mkdir -p .artifacts/unit && node ../../script/test-deadline.mjs bun test src scripts --path-ignore-patterns='**/relay-workerd-*' --timeout 30000 --reporter=junit --reporter-outfile=.artifacts/unit/junit.xml && node ../../script/test-deadline.mjs bun test src/relay-workerd-backpressure.test.ts src/relay-workerd-binary.test.ts src/relay-workerd-session-host.test.ts --timeout 240000 --reporter=junit --reporter-outfile=.artifacts/unit/junit-workerd.xml"
+    "test": "mkdir -p .artifacts/unit && node ../../script/test-deadline.mjs bun test src scripts --path-ignore-patterns='**/relay-workerd-*' --timeout 30000 --reporter=junit --reporter-outfile=.artifacts/unit/junit.xml && node ../../script/test-deadline.mjs bun test src/relay-workerd-backpressure.test.ts src/relay-workerd-binary.test.ts src/relay-workerd-close.test.ts src/relay-workerd-session-host.test.ts --timeout 240000 --reporter=junit --reporter-outfile=.artifacts/unit/junit-workerd.xml"
   },
   "dependencies": {
-    "@claxedo/helpers": "0.2.0",
-    "@claxedo/workspace-relay-protocol": "0.10.0",
+    "@claxedo/helpers": "0.2.1",
+    "@claxedo/workspace-relay-protocol": "0.10.1",
     "jose": "6.0.11"
   },
   "devDependencies": {
     "@tsconfig/node-lts": "22.0.4",
     "@types/bun": "1.3.13",
     "esbuild": "0.25.12",
-    "miniflare": "4.20260722.0",
+    "miniflare": "4.20260730.0",
     "tsx": "4.22.3",
     "typescript": "catalog:",
-    "wrangler": "4.114.0",
+    "wrangler": "4.116.0",
     "@cloudflare/workers-types": "catalog:"
   }
 }