@claxedo/workspace-relay 0.6.0 → 0.7.0

package/dist/bun.d.ts

@@ -7,6 +7,8 @@ type RelayClientWebSocketData = {
         payload: string | Buffer<ArrayBuffer>;
         queuedAt: number;
     }>;
+    /** Running byte size of `queue`; reset when the queue is flushed upstream. */
+    queuedBytes?: number;
     upstream?: WebSocket;
     upstreamOpenTimer?: ReturnType<typeof setTimeout>;
     trace?: RelayClientWebSocketTrace;
@@ -70,6 +72,7 @@ export type WorkspaceRelayBackpressureOptions = {
     directHttpConcurrency?: number;
     upstreamWebSocketOpenTimeoutMs?: number;
     upstreamWebSocketPreOpenQueueMaxFrames?: number;
+    upstreamWebSocketPreOpenQueueMaxBytes?: number;
     upstreamWebSocket?: UpstreamWebSocketConstructor;
     webSocketBufferedAmountMaxBytes?: number;
 };
@@ -103,6 +106,34 @@ export type WorkspaceRelayBunDrainController = {
         remaining: number;
     }>;
 };
+/**
+ * Bytes queued in a socket's send buffer, or `undefined` if it cannot report.
+ *
+ * Bun spells this `getBufferedAmount()` — a method, not the browser's
+ * `bufferedAmount` property. The two guards below used to read the property
+ * behind a non-null assertion, which typechecked and then evaluated
+ * `undefined > 8388608` forever: neither had ever closed a connection. Measured
+ * in `relay-workerd-backpressure.test.ts` at 16.8 MB queued, twice the limit,
+ * guard silent.
+ *
+ * FAILS OPEN on a socket that cannot report, deliberately. Test doubles and any
+ * exotic socket must not be closed for lacking the accessor — an unguarded
+ * healthy connection beats a guard that kills healthy connections. Note this is
+ * also why the same guard is NOT portable to `cloudflare.ts`: workerd's
+ * WebSocket exposes no buffer depth in any form, so there it would fail open
+ * unconditionally. Bounding the Cloudflare path needs a protocol-level
+ * credit/ack window instead.
+ */
+export declare const relayBufferedBytes: (socket: unknown) => number | undefined;
+/**
+ * True only when the socket reports a depth over the limit. Unknown ⇒ false.
+ *
+ * Exported for `bun.test.ts`. Forcing a real over-limit buffer through the
+ * server's own sockets is not achievable locally — a loopback peer drains far
+ * faster than a test can outrun it, which is precisely why the dead guard went
+ * unnoticed for so long — so the decision itself is asserted directly.
+ */
+export declare const relayOverBackpressureLimit: (socket: unknown, limitBytes: number) => boolean;
 export type FragmentationStats = {
     fragmentsBuffered: number;
     oversizedClosed: number;

package/dist/cloudflare.d.ts

@@ -11,6 +11,44 @@ export type WorkspaceRelayDurableObjectNamespace = {
     get: (id: WorkspaceRelayDurableObjectId, options?: WorkspaceRelayDurableObjectGetOptions) => WorkspaceRelayDurableObjectStub;
 };
 export declare const DEFAULT_RELAY_LOCATION_HINT = "apac";
+/**
+ * The complete set of Cloudflare Durable Object location hints.
+ *
+ * Cloudflare rejects an unknown hint, and a rejected `get()` fails the request —
+ * so an unrecognised region must fall back rather than be passed through. This
+ * list is the validator for that.
+ */
+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.
+ *
+ * This decision is PERMANENT: a DO's location is fixed at first creation and
+ * never migrates, so a workspace created with the wrong hint pays the extra
+ * ocean crossing on every frame for its entire life. That is why an
+ * unrecognised value falls back to the configured default instead of being
+ * 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;
+ *  3. the deployment-wide configured hint (`CLAXEDO_RELAY_LOCATION_HINT`), then
+ *     `DEFAULT_RELAY_LOCATION_HINT`.
+ */
+export declare function relayLocationHint(input: {
+    configured?: string;
+    region?: string;
+    country?: string;
+}): string;
+/** The workspace region a request declares, if any. */
+export declare function relayRequestRegion(request: Request): string | undefined;
+/** The Cloudflare edge country for the request, when running on Cloudflare. */
+export declare function relayRequestCountry(request: Request): string | undefined;
 export type WorkspaceRelayDurableObjectEnv = Record<string, unknown>;
 export type WorkspaceRelayDurableObjectGatewayOptions = {
     bindingName?: string;
@@ -43,6 +81,7 @@ export type WorkspaceRelayDurableObjectRoomOptions = WorkspaceRelayOptions & {
     connectWebSocket?: WorkspaceRelayDurableObjectConnectWebSocket;
     hibernation?: WorkspaceRelayDurableObjectHibernation;
     upstreamWebSocketPreOpenQueueMaxFrames?: number;
+    upstreamWebSocketPreOpenQueueMaxBytes?: number;
     tunnelPendingHttpCap?: number;
     tunnelStartedStreamCap?: number;
     tunnelChannelCap?: number;
@@ -52,6 +91,23 @@ export type WorkspaceRelayDurableObjectRoomOptions = WorkspaceRelayOptions & {
     slowConsumerTimeoutMs?: number;
     runtimeAccessTokenActiveCheckIntervalMs?: number;
     workspaceTargetActiveCheckIntervalMs?: number;
+    /**
+     * Consecutive resolver-unreachable answers tolerated on an established
+     * connection before closing it. Applies ONLY to "could not reach the
+     * resolver"; an explicit revoked/inactive answer still closes immediately.
+     */
+    resolverOutageGraceAttempts?: number;
+    /**
+     * Interval for the alarm-based revocation re-check that covers hibernated
+     * connections, where `setInterval` watchers cannot survive. 0 disables it.
+     */
+    hibernatedRevocationCheckIntervalMs?: number;
+    /**
+     * Durable Object alarm surface, supplied by the Worker (`state.storage`) so the
+     * room can schedule the hibernation-safe revocation re-check. Absent on the
+     * non-hibernating path and in tests that do not exercise it.
+     */
+    alarms?: WorkspaceRelayDurableObjectAlarms;
     traceSampleRate?: number;
     traceForceHeaderSecret?: string;
     traceLog?: (event: WorkspaceRelayTraceLogEvent) => void;
@@ -72,6 +128,19 @@ export type WorkspaceRelayDurableObjectHibernation = {
     acceptWebSocket: (socket: WorkspaceRelayDurableObjectSocket) => void;
     getWebSockets: () => WorkspaceRelayDurableObjectSocket[];
 };
+/**
+ * The Durable Object alarm surface, narrowed to what the room needs.
+ *
+ * Alarms are the only periodic mechanism that survives hibernation — a
+ * `setInterval` dies when the DO is evicted, which is exactly why the token and
+ * target watchers are not installed on the hibernating path. Backed by
+ * `state.storage` in the Worker.
+ */
+export type WorkspaceRelayDurableObjectAlarms = {
+    getAlarm: () => Promise<number | null> | number | null;
+    setAlarm: (scheduledTime: number) => Promise<void> | void;
+    deleteAlarm?: () => Promise<void> | void;
+};
 export type WorkspaceRelaySocketAttachment = {
     kind: "host-tunnel";
     hostId: string;
@@ -96,6 +165,30 @@ export type WorkspaceRelayDurableObjectDrainController = {
         remaining: number;
     }>;
 };
+/**
+ * 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;
+/**
+ * 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 workspaceRelayDurableObjectRoomName(workspaceId: string): string;
 export declare function workspaceRelayDurableObjectWorkspaceId(request: Request): string | undefined;
 export declare function setWorkspaceRelayAppOrigins(raw: string | undefined): void;
@@ -106,6 +199,11 @@ export declare function createWorkspaceRelayDurableObjectGateway(options?: Works
 export declare function createWorkspaceRelayDurableObjectRoom(options: WorkspaceRelayDurableObjectRoomOptions): {
     fetch(request: Request): Promise<Response>;
     webSocketMessage(socket: WorkspaceRelayDurableObjectSocket, message: string | ArrayBuffer): Promise<void>;
+    /**
+     * Durable Object alarm entry point. Runs the hibernation-safe revocation
+     * sweep (W6b.2). The Worker must forward `alarm()` here.
+     */
+    alarm(): Promise<void>;
     webSocketClose(socket: WorkspaceRelayDurableObjectSocket, code: number, reason: string): void;
     webSocketError(socket: WorkspaceRelayDurableObjectSocket): void;
     state(): {