@claxedo/workspace-relay 0.10.2 → 0.10.3

package/dist/relay-bytes.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Exported for `relay-base64.test.ts`, which proves byte-equality against a
+ * per-byte reference across the chunk boundaries. This sits on the path every
+ * frame pays, so its equivalence is worth asserting directly rather than
+ * inferring from a round-trip.
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(input: string): Uint8Array<ArrayBuffer>;
+export declare function concatBytes(chunks: Uint8Array[]): Uint8Array<ArrayBuffer>;
+export declare function readRequestBodyCapped(request: Request, maxBytes: number): Promise<"too_large" | Uint8Array<ArrayBuffer>>;

package/dist/relay-location.d.ts

@@ -12,7 +12,7 @@ export declare const DEFAULT_RELAY_LOCATION_HINT = "apac";
  *
  * The room sits on the path of every request to the object and asks the
  * control plane (IAD) for the token's revocation and the target on a cold
- * start and every 10 s: from apac each lookup is ~220 ms, from enam ~10 ms,
+ * start and every 30 s: from apac each lookup is ~220 ms, from enam ~10 ms,
  * while the browser's path through the room is the same ~115 ms either way
  * (docs/perf/pi-durable-latency-2026-10-18/README.md). A machine's room stays
  * beside its machine, where those lookups would cost a browser in apac
@@ -28,7 +28,6 @@ export declare const SESSION_HOST_LOCATION_HINT = "enam";
  */
 export declare const RELAY_LOCATION_HINTS: readonly ["wnam", "enam", "sam", "weur", "eeur", "apac", "oc", "afr", "me"];
 export type RelayLocationHint = typeof RELAY_LOCATION_HINTS[number];
-/** A workspace region carried on the request, if the caller supplied one. */
 export declare const RELAY_REGION_HEADER = "x-claxedo-workspace-region";
 /**
  * Chooses the location hint for a workspace's Durable Object.
@@ -40,11 +39,13 @@ export declare const RELAY_REGION_HEADER = "x-claxedo-workspace-region";
  * passed through or guessed at.
  *
  * Precedence, most authoritative first:
- *  1. the workspace's own region (header or `?region=`), which is what the
- *     control plane knows and the only signal tied to the WORKSPACE rather than
- *     to whoever happens to be connecting first;
- *  2. the requesting user's Cloudflare edge country, a decent proxy when the
- *     workspace has no region yet;
+ *  1. the workspace's own region (header or `?region=`). The caller passes it
+ *     only where the region is a fact about the runtime: see
+ *     `RelayPlacementCredential.declaresRegion`;
+ *  2. the requesting user's Cloudflare edge country. A control-plane Worker
+ *     calling on a person's behalf carries that person's country, not its own
+ *     (measured: a Worker placed in IAD, called from India, reaches the next
+ *     Worker with `cf.country` IN);
  *  3. the deployment-wide configured hint (`CLAXEDO_RELAY_LOCATION_HINT`), then
  *     `DEFAULT_RELAY_LOCATION_HINT`.
  */
@@ -53,7 +54,6 @@ export declare function relayLocationHint(input: {
     region?: string;
     country?: string;
 }): string;
-/** The workspace region a request declares, if any. */
 export declare function relayRequestRegion(request: Request): string | undefined;
 export type RelayRoomPlacement = {
     locationHint: string;
@@ -66,9 +66,18 @@ export type RelayRoomPlacement = {
  * room's workspace: the host it reaches. A `session-do:` host is the control
  * plane's signed statement that the workspace's sessions run on their own
  * Durable Objects.
+ *
+ * `declaresRegion` says whether a region on the request is a fact about the
+ * runtime. It is for a cloud runtime, whose token carries the routing id the
+ * control plane assigned with its sandbox, and for a machine's own tunnel
+ * dial. It is not for anyone else's request to a machine: a machine workspace
+ * has no home region, the control plane fills the column with the deployment
+ * default (`us-east`), and a room placed by that default sits 228 ms from a
+ * machine and owner who are both in India, for good.
  */
 export type RelayPlacementCredential = {
     hostId: string;
+    declaresRegion: boolean;
 };
 /**
  * Where a workspace's room is created, decided from what the request declares
@@ -83,11 +92,11 @@ export type RelayPlacementCredential = {
  * drag the room elsewhere, and a forged token verifies for no workspace.
  * Request-declared inputs (region, edge country) move the hint off the
  * configured floor only when the credential verifies, so anonymous first-touch
- * traffic cannot pin a workspace's room placement.
+ * traffic cannot pin a workspace's room placement. The region counts only from
+ * a credential that `declaresRegion`; the edge country counts from any.
  */
 export declare function relayRoomPlacement(request: Request, input: {
     configured?: string;
     credential: () => Promise<RelayPlacementCredential | undefined>;
 }): Promise<RelayRoomPlacement>;
-/** The Cloudflare edge country for the request, when running on Cloudflare. */
 export declare function relayRequestCountry(request: Request): string | undefined;

package/dist/relay-log.d.ts

@@ -0,0 +1,61 @@
+/**
+ * What the relay records about a machine's tunnel. A relayed request that
+ * succeeds quickly writes nothing; these are the changes and failures that
+ * explain why a machine could not be reached.
+ */
+export type RelayLogEvent = {
+    event: "tunnel_admitted";
+    hostId: string;
+    workspaceIds: string[];
+    generation: number;
+    replacedAgeMs?: number;
+} | {
+    event: "tunnel_refused";
+    hostId?: string;
+    code: string;
+} | {
+    event: "tunnel_ended";
+    hostId: string;
+    generation: number;
+    reason: string;
+    ageMs: number;
+    pendingFailed: number;
+    channelsClosed: number;
+    closeCode?: number;
+    closeReason?: string;
+    socketError?: string;
+} | {
+    event: "tunnel_timeout";
+    hostId: string;
+    traceId?: string;
+    requestId: string;
+    method: string;
+    path: string;
+    bodyBytes: number;
+    timeoutMs: number;
+    tunnelAgeMs: number;
+    pending: number;
+}
+/** The machine answered a request the relay had already timed out: it was slow, not gone. */
+ | {
+    event: "tunnel_late_response";
+    hostId: string;
+    requestId: string;
+    lateMs: number;
+} | {
+    event: "tunnel_frame_dropped";
+    hostId: string;
+    reason: string;
+    dropped: number;
+    type?: string;
+    protocol?: string;
+};
+export type RelayLog = (event: RelayLogEvent) => void;
+export declare function relayLogOf(options: {
+    relayLog?: RelayLog;
+}): RelayLog;
+/** A machine speaking another protocol drops every frame, so only the first few and then each hundredth are written. */
+export declare function frameDropWorthLogging(dropped: number): boolean;
+/** How many timed-out request ids a tunnel remembers so a late answer can be told from an unknown one. */
+export declare const TIMED_OUT_REQUESTS_REMEMBERED = 32;
+export declare function rememberTimedOut(timedOut: Map<string, number>, requestId: string, at: number): void;

package/dist/relay-trace.d.ts

@@ -19,6 +19,8 @@ export type WorkspaceRelayTraceLogEvent = {
 export type RelayTraceSampling = {
     traceSampleRate?: number;
     traceForceHeaderSecret?: string;
+    /** The data center the room runs in once it is known; asked on a sampled trace only. */
+    roomColo?: () => string | undefined;
     random?: () => number;
 };
 export type RelayTrace = {
@@ -30,6 +32,7 @@ export type RelayTrace = {
         name: string;
         ms: number;
     }>;
+    roomColo?: string;
 };
 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>;
@@ -49,6 +52,8 @@ export declare function webSocketTraceFrame(upstreamStartedAt: number, queueTime
     maxQueuedDelayMs: number;
 };
 export declare function withTraceHeaders(response: Response, trace: RelayTrace): Response;
+/** A request that fails or takes longer than this is written whether or not its trace was sampled. */
+export declare const SLOW_REQUEST_MS = 5000;
 export declare function logTrace(options: {
     traceLog?: (event: WorkspaceRelayTraceLogEvent) => void;
 }, request: Request, workspaceId: string | undefined, trace: RelayTrace, response: Response): void;

package/dist/resolver-clients.d.ts

@@ -31,9 +31,8 @@ export type RevocationLookupArgs = {
 };
 export type RevocationLookup = (args: RevocationLookupArgs) => Promise<RuntimeAccessTokenActiveResult>;
 export type CachedRevocationOptions = {
-    /** TTL in milliseconds for cached revocation responses. Defaults to 10_000. */
+    /** TTL in milliseconds for cached revocation responses. Defaults to 30_000. */
     ttlMs?: number;
-    /** Clock injection for tests. Defaults to `Date.now`. */
     now?: () => number;
 };
 /**
@@ -51,7 +50,6 @@ export type HostGenerationLookup = (args: HostGenerationLookupArgs) => Promise<H
 export type CachedHostGenerationOptions = {
     /** TTL in milliseconds for cached host-generation answers. Defaults to 10_000. */
     ttlMs?: number;
-    /** Clock injection for tests. Defaults to `Date.now`. */
     now?: () => number;
 };
 export type TargetLookupArgs = {
@@ -63,12 +61,29 @@ export type TargetLookup = (args: TargetLookupArgs) => Promise<WorkspaceRelayTar
 export declare function pruneExpiringCache<T extends {
     expiresAt: number;
 }>(cache: Map<string, T>, now: number, maxEntries: number): void;
+/** The code of an answer that says the authority could not be asked, as opposed to one that says no. */
+export declare const REVOCATION_RESOLVER_UNAVAILABLE = "relay_revocation_resolver_unavailable";
+export type RuntimeAccessTokenStanding = {
+    result: RuntimeAccessTokenActiveResult;
+    checkedAt: number;
+};
+export type CachedRevocationLookup = RevocationLookup & {
+    /**
+     * The token's standing as the authority gave it no more than `maxAgeMs`
+     * ago, asked now when the held answer is older. A request that arrives
+     * while it is being asked still gets the held answer until that expires, and
+     * an authority that cannot be reached leaves the held answer in place.
+     */
+    within(args: RevocationLookupArgs, maxAgeMs: number): Promise<RuntimeAccessTokenStanding>;
+    /** How long an answer is held, which is the bound on how late a revocation is seen. */
+    ttlMs: number;
+};
 /**
  * Wraps a revocation lookup with a small in-memory cache keyed by `jti`.
  * Both positive and negative results are cached for the full TTL; revocation
  * lag is bounded by the same TTL by design. Concurrent misses share one lookup.
  */
-export declare function createCachedRevocationClient(inner: RevocationLookup, options?: CachedRevocationOptions): RevocationLookup;
+export declare function createCachedRevocationClient(inner: RevocationLookup, options?: CachedRevocationOptions): CachedRevocationLookup;
 /**
  * The longest a revoked Runtime Access Token can keep working after the
  * authority records the revocation, derived from the configured TTLs rather

package/dist/server.d.ts

@@ -34,23 +34,15 @@ export type WorkspaceRelayAuthOptions = {
      * Cache signature/introspection-verified Runtime Access Token claims by the
      * full token string. Revocation/active checks, role enforcement, and target
      * resolution still run for every request after this cache hit. Defaults to
-     * 10s and is always capped by the token's exp claim minus skew.
+     * 30s and is always capped by the token's exp claim minus skew.
      */
     runtimeAccessTokenCacheTtlMs?: number;
     /**
-     * P-shared: optional override for runtime-access-token verification.
-     *
-     * When set, the relay calls this verifier instead of decoding the JWT
-     * with `runtimeAccessKey`. The verifier returns `{ subject, scopes,
-     * claims }`; the relay continues to use `claims` to drive
-     * `resolveTarget` and the workspace/host audit fields. `runtimeAccessKey`
-     * is then only used for legacy token paths and tests that exercise the
-     * raw JWT codepath.
-     *
-     * This is the seam downstream users plug their own auth backend
-     * through (issuer-signed tokens, OIDC introspection, custom keys, etc.).
-     * See `@claxedo/workspace-relay-protocol/token-verifier` for the
-     * `HttpTokenVerifier` and `StaticTokenVerifier` reference impls.
+     * Verifies Runtime Access Tokens in place of decoding the JWT with
+     * `runtimeAccessKey`, for a deployment with its own auth backend (issuer
+     * tokens, OIDC introspection). Its `claims` drive `resolveTarget` and the
+     * audit fields. `@claxedo/workspace-relay-protocol/token-verifier` has HTTP,
+     * OIDC and static implementations.
      */
     tokenVerifier?: TokenVerifier<RuntimeAccessVerifierClaims>;
     isRuntimeAccessTokenActive?: (claims: RuntimeAccessTokenClaims) => RuntimeAccessTokenActiveResult | Promise<RuntimeAccessTokenActiveResult>;

package/dist/socket-frames.d.ts

@@ -0,0 +1,47 @@
+import type { TunnelWsFrame } from "@claxedo/workspace-relay-protocol";
+/** What a frame awaiting the upstream socket costs the pre-open byte bound. */
+export declare function preOpenFrameBytes(input: string | ArrayBuffer | Uint8Array): number;
+/**
+ * Socket `data` → a tunnel `ws.frame` payload. Returns a promise only for
+ * `Blob` data, which a listener-path socket delivers for a binary frame at
+ * `compatibility_date >= 2026-03-17`, the relay's deployed date among them;
+ * string and ArrayBuffer frames stay synchronous and pay no extra microtask.
+ */
+export declare function socketFrame(input: unknown): Promise<{
+    binary: boolean;
+    data_base64: string;
+}> | {
+    binary: boolean;
+    data_base64: string;
+} | undefined;
+/**
+ * Wraps a per-socket frame handler so frames are delivered in ARRIVAL order
+ * even when some of them resolve asynchronously.
+ *
+ * `socketPayload` is synchronous for string/ArrayBuffer/view data and only
+ * returns a promise for `Blob`. Awaiting that promise inline inside the
+ * listener would let the next frame — resolved synchronously — overtake it,
+ * silently reordering an ordered byte stream: a terminal would render its
+ * output scrambled. So the first pending Blob installs a tail promise and every
+ * later frame chains onto it until the chain drains, at which point the
+ * synchronous fast path resumes.
+ */
+export declare function orderedFrameDelivery(deliver: (payload: string | ArrayBuffer | Uint8Array) => void): (data: unknown) => void;
+/**
+ * Runs the two frame decoders over one runtime-delivered `event.data` and
+ * reports what they produced.
+ *
+ * Exists so `relay-workerd-binary.test.ts` can assert the decoders against what
+ * REAL workerd delivers. The rest of the suite drives hand-rolled socket
+ * doubles, which by construction hand us whatever we chose to hand ourselves —
+ * so they cannot catch the hazard that binary `event.data` becomes a `Blob` at
+ * `compatibility_date >= 2026-03-17`. Test-support surface, not a relay path.
+ */
+export declare function relayFrameDiagnostics(data: unknown): Promise<{
+    frameDropped: boolean;
+    payloadDropped: boolean;
+    binary?: boolean | undefined;
+    dataBase64?: string | undefined;
+    payloadBase64: string | undefined;
+}>;
+export declare function tunnelFrame(input: TunnelWsFrame): string | Uint8Array<ArrayBuffer>;

package/dist/stream-standing.d.ts

@@ -0,0 +1,24 @@
+import type { RuntimeAccessTokenClaims } from "./auth";
+import { type RuntimeAccessTokenStanding } from "./resolver-clients";
+export type StreamStandingOptions = {
+    /** The token's standing no older than `maxAgeMs`; absent, a deployment has no revocation authority and streams are left alone. */
+    standing?: (claims: RuntimeAccessTokenClaims, maxAgeMs: number) => Promise<RuntimeAccessTokenStanding>;
+    /** The bound a request's own check keeps: no answer older than this lets bytes through. */
+    boundMs: number;
+    /** Consecutive failures to reach the authority a stream survives; `exp` still ends it. */
+    graceAttempts: number;
+    /** How long before the bound the authority is asked again; `STANDING_REFRESH_LEAD_MS` unless a test shortens the bound. */
+    leadMs?: number;
+    now?: () => number;
+};
+/**
+ * A response whose body stops when its token does.
+ *
+ * A request is authorized once, when it arrives, but an event stream stays
+ * open for hours on that one check. This keeps the answer it flows on inside
+ * the bound a new request would get, by asking the authority again shortly
+ * before the held answer ages out, and ends the body when the token is
+ * revoked or expires. Ending cancels the source, which frees a tunnel
+ * stream's slot and tells its host to stop.
+ */
+export declare function guardStreamStanding(response: Response, claims: RuntimeAccessTokenClaims, options: StreamStandingOptions): Response;

package/dist/worker.d.ts

@@ -1,6 +1,6 @@
 import { type WorkspaceRelayDurableObjectNamespace, type WorkspaceRelayDurableObjectRoomOptions, type WorkspaceRelayDurableObjectSocket } from "./cloudflare";
 import { type WorkspaceRelayTarget } from "./relay-target";
-import { type HostGenerationLookup, type RuntimeAccessTokenActiveResult } from "./resolver-clients";
+import { type CachedRevocationLookup, type HostGenerationLookup } from "./resolver-clients";
 type WorkspaceRelayWorkerBindings = {
     WORKSPACE_RELAY_ROOM?: WorkspaceRelayDurableObjectNamespace;
     CLAXEDO_RELAY_RESOLVER_URL?: string;
@@ -32,29 +32,28 @@ type WorkspaceRelayWorkerBindings = {
 export type WorkspaceRelayWorkerEnv = Record<string, unknown> & WorkspaceRelayWorkerBindings;
 type ResolverClient = {
     target(workspaceId: string, hostId: string, routingId?: string): Promise<WorkspaceRelayTarget | undefined>;
-    revocation(args: {
-        jti: string;
-        workspaceId: string;
-        hostId: string;
-    }): Promise<RuntimeAccessTokenActiveResult>;
+    revocation: CachedRevocationLookup;
     hostGeneration: HostGenerationLookup;
 };
 type ResolverFetch = (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
 export declare function workspaceRelayWorkerResolverUrl(env: WorkspaceRelayWorkerEnv): string;
 export declare function workspaceRelayWorkerResolverClient(env: WorkspaceRelayWorkerEnv, fetcher?: ResolverFetch): ResolverClient;
-export declare function workspaceRelayDurableObjectOptions(env: WorkspaceRelayWorkerEnv): Promise<WorkspaceRelayDurableObjectRoomOptions>;
+/** Everything the room needs from the environment; the Worker adds `report`, which is the object's own. */
+export declare function workspaceRelayDurableObjectOptions(env: WorkspaceRelayWorkerEnv): Promise<Omit<WorkspaceRelayDurableObjectRoomOptions, "report">>;
 /**
- * The `DurableObjectState` workerd hands a room, modelled structurally like the
- * rest of this package's Cloudflare surface (see `./cloudflare`) — this package
- * deliberately carries no `@cloudflare/workers-types` dependency.
- *
- * Everything is optional because `cloudflare.ts` treats hibernation and alarms
- * as capabilities to DETECT: an older runtime, or a harness standing in for
- * one, may provide neither, and the room degrades rather than failing.
+ * The `DurableObjectState` workerd hands a room. Everything is optional because
+ * `cloudflare.ts` detects hibernation and alarms: an older runtime, or a
+ * harness standing in for one, may provide neither, and the room degrades
+ * rather than failing.
  */
 export type WorkspaceRelayRoomState = {
+    id?: {
+        name?: string;
+    };
     acceptWebSocket?: (socket: WorkspaceRelayDurableObjectSocket) => void;
     getWebSockets?: () => WorkspaceRelayDurableObjectSocket[];
+    /** Keeps a report's POST alive past the step that made it; absent in tests that construct the room directly. */
+    waitUntil?: (promise: Promise<unknown>) => void;
     storage?: {
         getAlarm?: () => Promise<number | null>;
         setAlarm?: (scheduledTime: number) => Promise<void>;
@@ -66,7 +65,18 @@ export declare class WorkspaceRelayRoom {
     private env;
     private room?;
     private loading?;
+    private readonly telemetry;
+    private colo?;
+    private coloLookup?;
     constructor(state: WorkspaceRelayRoomState, env: WorkspaceRelayWorkerEnv);
+    /** A fault of this room's code, under `system`; the room's own name is a workspace id and is digested by the sink. */
+    private report;
+    /**
+     * A Durable Object has no API for its own location. Cloudflare's trace page
+     * names the data center a request left from, which for a subrequest is the
+     * object's. The first sampled trace starts the lookup and goes without it.
+     */
+    private roomColo;
     private hibernation;
     /**
      * The DO alarm surface, used for the hibernation-safe revocation re-check.
@@ -85,8 +95,18 @@ export declare class WorkspaceRelayRoom {
      * it, so adding another alarm user here stays safe.
      */
     alarm(): Promise<void>;
+    /**
+     * The gateway reaches a workspace's room by one name. A room under any other
+     * name keeps the sockets it accepted, and a machine whose tunnel is healthy
+     * never dials again, so the workspace reads as offline for as long as this
+     * room holds on. Closed, the machine and its browsers dial through the
+     * gateway and meet in the room it names.
+     */
+    private unreachable;
 }
 declare const _default: {
-    fetch(request: Request, env: WorkspaceRelayWorkerEnv): Promise<Response>;
+    fetch(request: Request, env: WorkspaceRelayWorkerEnv, context?: {
+        waitUntil(promise: Promise<unknown>): void;
+    }): Promise<Response>;
 };
 export default _default;

package/package.json

@@ -33,7 +33,7 @@
     "access": "public"
   },
   "name": "@claxedo/workspace-relay",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "scripts": {
     "build": "tsx scripts/build.ts",
     "prepublishOnly": "npm run build",
@@ -41,8 +41,8 @@
     "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 node scripts/test-workerd.mjs"
   },
   "dependencies": {
-    "@claxedo/helpers": "0.2.2",
-    "@claxedo/workspace-relay-protocol": "0.10.2",
+    "@claxedo/helpers": "0.2.3",
+    "@claxedo/workspace-relay-protocol": "0.10.3",
     "jose": "6.0.11"
   },
   "devDependencies": {