@claxedo/workspace-relay 0.6.0 → 0.8.0

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,31 @@ 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.
+     * The hibernated host-generation check rides the same alarm.
+     */
+    hibernatedRevocationCheckIntervalMs?: number;
+    /**
+     * How often an established host tunnel's serving generation is re-checked
+     * against `resolveHostGeneration` on the non-hibernating path. Defaults to
+     * 30s; 0 disables it. The lookup may answer from its cache, so a superseded
+     * tunnel closes within this interval plus the lookup's cache TTL.
+     */
+    hostGenerationCheckIntervalMs?: 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,11 +136,29 @@ 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;
     workspaceIds: string[];
     connectedAt: number;
+    /** Fence pair from the admitting Host Tunnel Token; absent on sockets attached before the fence existed. */
+    enrollmentId?: string;
+    generation?: number;
+    /** Consecutive unavailable generation lookups, persisted so hibernation cannot reset the outage grace. */
+    generationCheckFailures?: number;
 } | {
     kind: "user-hosted-client";
     channelId: string;
@@ -96,6 +178,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 +212,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. The Worker must forward `alarm()` here.
+     */
+    alarm(): Promise<void>;
     webSocketClose(socket: WorkspaceRelayDurableObjectSocket, code: number, reason: string): void;
     webSocketError(socket: WorkspaceRelayDurableObjectSocket): void;
     state(): {

package/dist/directory.d.ts

@@ -1,3 +1,8 @@
+/**
+ * One tunnel's presence, recorded once per workspace it serves. `workspaceIds`
+ * is the full set that tunnel registered, so a reader that found the entry
+ * through one workspace still sees the others.
+ */
 export type HostTunnelPresence = {
     hostId: string;
     workspaceIds: string[];
@@ -5,13 +10,21 @@ export type HostTunnelPresence = {
     lastPongAt: number;
     expiresAt: number;
 };
+/**
+ * Presence is keyed by (host, workspace): one host may hold a separate tunnel
+ * per workspace on a Bun relay, and a later registration for a workspace takes
+ * that workspace over without touching the host's other entries. `recordPong`
+ * and `disconnectHost` take the optional workspace set for the same reason —
+ * without it they act on every entry of the host, which is what a
+ * single-workspace Cloudflare room wants.
+ */
 export type WorkspaceRelayDirectory = {
     registerHostTunnel(input: {
         hostId: string;
         workspaceIds: string[];
     }): HostTunnelPresence;
-    recordPong(hostId: string): HostTunnelPresence | undefined;
-    disconnectHost(hostId: string): void;
+    recordPong(hostId: string, workspaceIds?: string[]): HostTunnelPresence | undefined;
+    disconnectHost(hostId: string, workspaceIds?: string[]): void;
     activeHost(input: {
         hostId: string;
         workspaceId: string;
@@ -29,10 +42,8 @@ export type WorkspaceRelayDirectory = {
      */
     dispose(): void;
     /**
-     * T31: count of currently-active (non-expired) host presence entries.
-     * Equivalent to running `sweep()` then returning the residual map size, but
-     * implemented as a single pass without mutating eviction state when the
-     * caller only wants a snapshot. Surfaced via the `/metrics` endpoint as
+     * Count of hosts with at least one non-expired presence entry, taken as a
+     * snapshot without evicting. Surfaced via `/metrics` as
      * `directory.activeHostCount`.
      */
     size(): number;

package/dist/http.d.ts

@@ -1,4 +1,5 @@
-export declare function bearerToken(header: string | null | undefined): string | undefined;
+import { bearerToken } from "@claxedo/helpers/string";
+export { bearerToken };
 export declare function errorBody(code: string, message: string): {
     error: {
         code: string;

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 export * from "./auth";
-export * from "./bun";
 export * from "./cloudflare";
 export * from "./cors-origins";
 export * from "./directory";