@claxedo/workspace-relay 0.8.0 → 0.10.1

package/dist/bun.d.ts

@@ -1,225 +0,0 @@
-import { type WorkspaceRelayOptions } from "./server";
-import { type RuntimeAccessTokenClaims } from "./auth";
-import { type UpstreamWebSocketConstructor } from "./upstream-websocket";
-/**
- * Bun expresses HTTP idle timeout in seconds. Runtime SSE heartbeats arrive
- * every 30 seconds, so this exceeds that interval while still bounding idle
- * unauthenticated and incomplete HTTP connections.
- */
-export declare const WORKSPACE_RELAY_IDLE_TIMEOUT_SECONDS = 45;
-type RelayClientWebSocketData = {
-    kind: "client";
-    claims: RuntimeAccessTokenClaims;
-    upstreamUrl: string;
-    headers: Record<string, string>;
-    queue: Array<{
-        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;
-    accessCheckTimer?: ReturnType<typeof setInterval>;
-    expiryTimer?: ReturnType<typeof setTimeout>;
-};
-type RelayClientWebSocketTrace = {
-    acceptedAt: number;
-    upstreamStartedAt?: number;
-    upstreamOpenMs?: number;
-    queuedFrames: number;
-    maxQueuedDelayMs: number;
-    emitted: boolean;
-};
-type RelayHostTunnelWebSocketData = {
-    kind: "host-tunnel";
-    hostId: string;
-    workspaceIds: string[];
-    /** Fence pair from the last verified Host Tunnel Token (connect or registration update); absent for tokens without one. */
-    enrollmentId?: string;
-    generation?: number;
-    pending: Map<string, PendingTunnelHttpResponse>;
-    channels: Map<string, RelayUserHostedClientWebSocket>;
-    heartbeat?: ReturnType<typeof setInterval>;
-    missedPongs: number;
-    generationCheckTimer?: ReturnType<typeof setInterval>;
-    generationCheckFailures: number;
-    messageBuffer: string;
-};
-type RelayUserHostedClientWebSocketData = {
-    kind: "user-hosted-client";
-    claims: RuntimeAccessTokenClaims;
-    hostId: string;
-    workspaceId: string;
-    channelId: string;
-    path: string;
-    relayHostToken: string;
-    accessCheckTimer?: ReturnType<typeof setInterval>;
-    expiryTimer?: ReturnType<typeof setTimeout>;
-};
-type RelayWebSocketData = RelayClientWebSocketData | RelayHostTunnelWebSocketData | RelayUserHostedClientWebSocketData;
-/** The socket type Bun hands every handler: one type carrying the data union. */
-type RelayWebSocket = Bun.ServerWebSocket<RelayWebSocketData>;
-type RelayHostTunnelWebSocket = Bun.ServerWebSocket<RelayHostTunnelWebSocketData>;
-type RelayUserHostedClientWebSocket = Bun.ServerWebSocket<RelayUserHostedClientWebSocketData>;
-type PendingTunnelHttpResponse = {
-    controller: ReadableStreamDefaultController<Uint8Array>;
-    stream: ReadableStream<Uint8Array>;
-    resolve: (response: Response) => void;
-    reject: (error: Error) => void;
-    timeout: ReturnType<typeof setTimeout>;
-    pendingChunks: Uint8Array[];
-    bytesQueued: number;
-    slowConsumerTimeout?: ReturnType<typeof setTimeout>;
-    responseStarted: boolean;
-    /**
-     * The relay's own CORS headers for this request, applied to whatever the
-     * tunnelled host answers with. The browser talks to the RELAY, so the
-     * relay's allowlist is the one that decides what it may read — the host
-     * behind the tunnel runs its own, unrelated policy, and passing its headers
-     * through made a relay's configured app origin readable only when the host
-     * happened to allow it too.
-     */
-    corsHeaders: (upstream: Headers) => Headers;
-};
-export type WorkspaceRelayHostTunnelOptions = {
-    /**
-     * Test seam replacing Host Tunnel Token verification. A boolean carries no
-     * claims, so a tunnel admitted through it has no generation and is never
-     * fenced.
-     */
-    authorizeHostTunnel?: (request: Request, input: {
-        hostId: string;
-        workspaceIds: string[];
-    }) => boolean | Promise<boolean>;
-    hostTunnelPingIntervalMs?: number;
-    hostTunnelMaxMissedPongs?: number;
-    /**
-     * How often an established host tunnel's generation is re-checked against
-     * `resolveHostGeneration`. Defaults to 30s; 0 disables the check. Because
-     * the lookup may answer from its cache, a superseded tunnel closes within
-     * this interval plus the lookup's cache TTL.
-     */
-    hostGenerationCheckIntervalMs?: number;
-    /**
-     * Consecutive unavailable lookups an established tunnel survives before it
-     * is closed 1012 for the host to reconnect. Defaults to 3.
-     */
-    hostGenerationOutageGraceAttempts?: number;
-    hostTunnelStateDebounceMs?: number;
-};
-export type WorkspaceRelayBackpressureOptions = {
-    slowConsumerHighWaterMarkBytes?: number;
-    slowConsumerTimeoutMs?: number;
-    tunnelRequestBodyMaxBytes?: number;
-    tunnelHttpResponseTimeoutMs?: number;
-    directHttpTimeoutMs?: number;
-    directHttpConcurrency?: number;
-    upstreamWebSocketOpenTimeoutMs?: number;
-    upstreamWebSocketPreOpenQueueMaxFrames?: number;
-    upstreamWebSocketPreOpenQueueMaxBytes?: number;
-    upstreamWebSocket?: UpstreamWebSocketConstructor;
-    webSocketBufferedAmountMaxBytes?: number;
-};
-export type WorkspaceRelayBunOptions = WorkspaceRelayHostTunnelOptions & WorkspaceRelayBackpressureOptions & {
-    /** How often established user WebSockets are re-checked for revocation. Defaults to 30s. */
-    runtimeAccessTokenActiveCheckIntervalMs?: number;
-    /** Clock injection used to calculate the local token-expiry deadline. */
-    now?: () => number;
-};
-/**
- * Declared as function-valued properties, not methods, because every member is
- * a closure over the adapter's counters and is routinely handed around
- * detached (`metricsSources.fragmentation ?? telemetry.getFragmentationStats`).
- * None of them reads `this`, and the same shape is used by
- * `WorkspaceRelayMetricsSources` in `./server`.
- */
-export type WorkspaceRelayBunTelemetry = {
-    getFragmentationStats: () => FragmentationStats;
-    resetFragmentationStats: () => void;
-    getSlowConsumerStats: () => SlowConsumerStats;
-    resetSlowConsumerStats: () => void;
-};
-/**
- * Drain controller exposed by `createWorkspaceRelayBun`.
- *
- * On SIGTERM the operator (see `installShutdownDrainHandler` in main.ts)
- * flips `setDraining(true)`; from that point onward the relay
- *   - returns 503 from `/health` so Fly removes the instance from routing
- *   - rejects new HTTP requests with 503 (`relay_draining`) before doing auth
- *   - rejects new host-tunnel WebSocket upgrades with 503
- *   - closes active host tunnels with 1012 so host clients reconnect promptly
- *
- * `pendingCount()` reports the total number of in-flight tunnel HTTP
- * responses across every connected host tunnel — this is what the operator
- * polls via `waitForDrain(timeoutMs)` before hard-closing remaining sockets.
- *
- * Function-valued properties rather than methods, for the same reason as
- * `WorkspaceRelayBunTelemetry`: `isDraining` and `pendingCount` are passed
- * detached into `createWorkspaceRelay`, and none of them reads `this`.
- */
-export type WorkspaceRelayBunDrainController = {
-    isDraining: () => boolean;
-    setDraining: (value: boolean) => void;
-    pendingCount: () => number;
-    waitForDrain: (timeoutMs: number) => Promise<{
-        drained: boolean;
-        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. Reading the property on a Bun socket yields
- * `undefined`, and `undefined > limit` is always false, so a guard built on it
- * never fires.
- *
- * Fails open on a socket that cannot report, deliberately: an unguarded healthy
- * connection beats a guard that kills healthy connections. This is also why the
- * guard is not portable to `cloudflare.ts` — workerd's WebSocket exposes no
- * buffer depth, so bounding that path needs a protocol-level credit/ack window.
- */
-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`: a loopback peer drains faster than a test can
- * fill it, so the decision is asserted directly.
- */
-export declare const relayOverBackpressureLimit: (socket: unknown, limitBytes: number) => boolean;
-export type FragmentationStats = {
-    fragmentsBuffered: number;
-    oversizedClosed: number;
-};
-export type SlowConsumerStats = {
-    overflowEvents: number;
-    timerFired: number;
-    droppedRequests: number;
-};
-declare function createSlowConsumerStats(): SlowConsumerStats;
-declare function enqueueChunkWithBackpressure(input: {
-    ws: RelayHostTunnelWebSocket;
-    requestId: string;
-    entry: PendingTunnelHttpResponse;
-    chunk: Uint8Array;
-    slowConsumerTimeoutMs: number;
-    slowConsumerStats: SlowConsumerStats;
-}): void;
-export declare const __slowConsumerInternalsForTest: {
-    enqueueChunkWithBackpressure: typeof enqueueChunkWithBackpressure;
-    createSlowConsumerStats: typeof createSlowConsumerStats;
-};
-export declare function createWorkspaceRelayBun(options: WorkspaceRelayOptions, bunOptions?: WorkspaceRelayBunOptions): {
-    fetch: (request: Request, server: Bun.Server<RelayWebSocketData>) => Promise<Response | undefined>;
-    websocket: {
-        maxPayloadLength: number;
-        message(ws: RelayWebSocket, message: string | Buffer<ArrayBuffer>): void;
-        open(ws: RelayWebSocket): void;
-        close(ws: RelayWebSocket, code: number, reason: string): void;
-    };
-    drain: WorkspaceRelayBunDrainController;
-    telemetry: WorkspaceRelayBunTelemetry;
-};
-export {};