@claxedo/workspace-relay 0.7.0 → 0.10.0

package/dist/cloudflare.d.ts

@@ -1,54 +1,17 @@
 import { type AuthorizedWorkspaceRelayRequest, type WorkspaceRelayOptions } from "./server";
+import { type SessionHostNamespace } from "./session-host-forwarding";
 export type WorkspaceRelayDurableObjectId = unknown;
 export type WorkspaceRelayDurableObjectStub = {
     fetch: (request: Request) => Promise<Response>;
 };
 export type WorkspaceRelayDurableObjectGetOptions = {
+    /** Cloudflare's placement hint, honoured on the room's first creation only: beside the workspace's runtime (`workspaceRelayRoomPlacement`). */
     locationHint?: string;
 };
 export type WorkspaceRelayDurableObjectNamespace = {
     idFromName: (name: string) => WorkspaceRelayDurableObjectId;
     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;
@@ -77,6 +40,7 @@ export type WorkspaceRelayDurableObjectConnectWebSocket = (url: string, init: {
     headers: Record<string, string>;
 }) => WorkspaceRelayDurableObjectSocket | Promise<WorkspaceRelayDurableObjectSocket>;
 export type WorkspaceRelayDurableObjectRoomOptions = WorkspaceRelayOptions & {
+    sessionHost?: SessionHostNamespace;
     createWebSocketPair?: () => WorkspaceRelayDurableObjectSocketPair;
     connectWebSocket?: WorkspaceRelayDurableObjectConnectWebSocket;
     hibernation?: WorkspaceRelayDurableObjectHibernation;
@@ -89,6 +53,15 @@ export type WorkspaceRelayDurableObjectRoomOptions = WorkspaceRelayOptions & {
     tunnelResponseBodyMaxBytes?: number;
     slowConsumerHighWaterMarkBytes?: number;
     slowConsumerTimeoutMs?: number;
+    /**
+     * How often established client WebSockets are re-checked for revocation.
+     * Defaults to 30s; 0 disables the re-check. Because the check may answer
+     * from the revocation lookup's cache, a revoked token closes the socket
+     * within this interval plus the lookup's cache TTL — see
+     * `runtimeAccessTokenRevocationDelayMs` in `./server`. A resolver outage
+     * gets `resolverOutageGraceAttempts` and never extends the socket past the
+     * token's `exp`, which the watcher enforces locally.
+     */
     runtimeAccessTokenActiveCheckIntervalMs?: number;
     workspaceTargetActiveCheckIntervalMs?: number;
     /**
@@ -100,8 +73,16 @@ export type WorkspaceRelayDurableObjectRoomOptions = WorkspaceRelayOptions & {
     /**
      * 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
@@ -146,8 +127,12 @@ export type WorkspaceRelaySocketAttachment = {
     hostId: string;
     workspaceIds: string[];
     connectedAt: number;
+    enrollmentId: string;
+    generation: number;
+    /** Consecutive unavailable generation lookups, persisted so hibernation cannot reset the outage grace. */
+    generationCheckFailures?: number;
 } | {
-    kind: "user-hosted-client";
+    kind: "host-tunnel-client";
     channelId: string;
     claims: RuntimeAccessAttachmentClaims;
     target: WorkspaceRelayTargetAttachment;
@@ -191,8 +176,6 @@ export declare function relayFrameDiagnostics(data: unknown): Promise<{
 }>;
 export declare function workspaceRelayDurableObjectRoomName(workspaceId: string): string;
 export declare function workspaceRelayDurableObjectWorkspaceId(request: Request): string | undefined;
-export declare function setWorkspaceRelayAppOrigins(raw: string | undefined): void;
-export declare function setWorkspaceRelayAllowedOrigins(raw: string | undefined): void;
 export declare function createWorkspaceRelayDurableObjectGateway(options?: WorkspaceRelayDurableObjectGatewayOptions): {
     fetch(request: Request, env?: WorkspaceRelayDurableObjectEnv): Promise<Response>;
 };
@@ -201,7 +184,7 @@ export declare function createWorkspaceRelayDurableObjectRoom(options: Workspace
     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.
+     * sweep. The Worker must forward `alarm()` here.
      */
     alarm(): Promise<void>;
     webSocketClose(socket: WorkspaceRelayDurableObjectSocket, code: number, reason: string): void;

package/dist/cors-origins.d.ts

@@ -1,3 +1,5 @@
 export declare const DEFAULT_RELAY_APP_ORIGINS: string[];
+/** Request headers a browser may send on relayed workspace requests, as the `access-control-allow-headers` value. */
+export declare const RELAY_ALLOWED_REQUEST_HEADERS: string;
 export declare function parseAllowedOrigins(raw: string | undefined): string[] | undefined;
 export declare function createOriginMatcher(patterns: string[]): (origin: string) => boolean;

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,6 +10,11 @@ export type HostTunnelPresence = {
     lastPongAt: number;
     expiresAt: number;
 };
+/**
+ * Presence is keyed by (host, workspace), so a later registration for a
+ * workspace takes that workspace over without touching the host's other
+ * entries. `recordPong` and `disconnectHost` act on every entry of the host.
+ */
 export type WorkspaceRelayDirectory = {
     registerHostTunnel(input: {
         hostId: string;
@@ -16,40 +26,8 @@ export type WorkspaceRelayDirectory = {
         hostId: string;
         workspaceId: string;
     }): HostTunnelPresence | undefined;
-    /**
-     * Manually run an expiry sweep over the presence map. Removes any entry
-     * whose `expiresAt <= now()`. Safe to call on a fresh/empty directory.
-     * Useful in tests; the production path runs this on a timer (see
-     * `sweepIntervalMs`).
-     */
-    sweep(): void;
-    /**
-     * Stop the active sweep timer (if one was started). Safe to call multiple
-     * times and on directories that were created with `sweepIntervalMs: 0`.
-     */
-    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
-     * `directory.activeHostCount`.
-     */
-    size(): number;
 };
 export declare function createWorkspaceRelayDirectory(options?: {
     ttlMs?: number;
     now?: () => number;
-    /**
-     * Interval in milliseconds at which a background sweep runs to evict
-     * expired host presence entries. Defaults to 30_000. Set to `0` to disable
-     * the timer entirely (useful for tests; callers can still drive cleanup
-     * manually via `sweep()`).
-     */
-    sweepIntervalMs?: number;
 }): WorkspaceRelayDirectory;
-/**
- * Convenience companion to `createWorkspaceRelayDirectory` for callers that
- * prefer a free function over a method. Equivalent to `directory.dispose()`.
- */
-export declare function disposeWorkspaceRelayDirectory(directory: WorkspaceRelayDirectory): void;

package/dist/gateway-placement.d.ts

@@ -0,0 +1,7 @@
+import type { WorkspaceRelayDurableObjectEnv } from "./cloudflare";
+/**
+ * Where the gateway creates the room of the request's workspace. The room's
+ * location is fixed at its first creation and never migrates, so this
+ * decision is permanent for the workspace.
+ */
+export declare function workspaceRelayRoomPlacement(request: Request, env: WorkspaceRelayDurableObjectEnv, workspaceId: string): Promise<import("./relay-location").RelayRoomPlacement>;

package/dist/host-tunnel-failure.d.ts

@@ -0,0 +1,7 @@
+export type HostTunnelFailureCode = "host_tunnel_timeout" | "host_tunnel_response_body_too_large" | "host_tunnel_unavailable";
+export declare function hostTunnelFailure(code: HostTunnelFailureCode): Error & {
+    code: HostTunnelFailureCode;
+    status: number;
+    retryable: boolean;
+};
+export declare function hostTunnelFailureResponse(error: unknown): Response;

package/dist/host-tunnel-forwarding.d.ts

@@ -0,0 +1,29 @@
+import type { RelayBacking } from "./auth";
+/**
+ * Whether a relay target is reached through a host tunnel.
+ *
+ * A `local-worktree` placement runs on an enrolled machine that dials the
+ * relay and multiplexes its traffic over that one socket; a `cloud-vm`
+ * placement runs on the provisioner's machine, which the relay reaches by a
+ * direct upstream connection.
+ */
+export declare function isHostTunnelTarget(target: {
+    backing: RelayBacking;
+}): boolean;
+export type WorkspaceRelaySocketKind = "host-tunnel-client" | "client";
+export declare function socketKindFor(target: {
+    backing: RelayBacking;
+}): WorkspaceRelaySocketKind;
+/**
+ * Privacy rule: never forward the browser's `Cookie` header through a host
+ * tunnel. The host process runs on a machine somebody uses, whose cookie jar
+ * the browser may share (localhost dev tooling), so passing cookies verbatim
+ * risks leaking session data to it. A cloud-vm sits behind a dedicated network
+ * boundary where a session cookie may legitimately be needed, so it passes
+ * `Cookie` through unchanged.
+ *
+ * Returns a new `Headers` instance; `headers` is not mutated.
+ */
+export declare function forwardHeadersFor(target: {
+    backing: RelayBacking;
+}, headers: Headers): Headers;

package/dist/http.d.ts

@@ -1,7 +1,12 @@
-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;
         message: string;
     };
 };
+/** The host a tunnel request names, `/host-tunnels/<hostId>`. */
+export declare function hostIdFromTunnelPath(pathname: string): string | undefined;
+/** The workspaces a tunnel request registers for, under either spelling of the query name. */
+export declare function workspaceIdsFromSearch(url: URL): string[];

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 export * from "./auth";
-export * from "./bun";
 export * from "./cloudflare";
+export * from "./relay-cors";
 export * from "./cors-origins";
 export * from "./directory";
+export * from "./gateway-placement";
+export * from "./relay-location";
+export * from "./relay-target";
 export * from "./server";
+export * from "./resolver-clients";