import { ServerWebSocket, type ServerWebSocketOptions } from "./server.js";
/**
 * The upgrade, as an HTTP exchange: a `GET` with `Upgrade: websocket` goes to
 * an ordinary `(Request) => Response` handler, and a `101` answer carrying a
 * server socket means accepted. Anything else is a refusal, with its status.
 *
 * FORBIDDEN HEADERS. A browser drops `Upgrade`, `Connection` and every
 * `Sec-*` header from a `new Request()`. The upgrade request therefore carries
 * its headers as an own `headers` property, a standalone `Headers` that keeps
 * them, so handler code reads `request.headers.get("upgrade")` as usual.
 *
 * NO 101 IN A `Response`. The constructor refuses statuses below 200, so the
 * response `upgradeWebSocket` returns reports 101 through an own `status`
 * property; the port that goes back to the caller is found with `takePort`.
 */
/** The request header carrying the client's version of the frame protocol. */
export declare const WS_VERSION_HEADER = "x-webrun-ws-version";
export interface WebSocketUpgradeInit {
    /** Requested subprotocols, in order of preference. */
    protocols?: string[];
    /** More headers for the handler to see (cookies, origin, authorization...). */
    headers?: HeadersInit;
}
/**
 * The `GET` a handler sees for `new WebSocket(url, protocols)`. A `ws:` or
 * `wss:` url is given as `http:` or `https:`, as a server sees it.
 */
export declare function newWebSocketUpgradeRequest(url: string | URL, { protocols, headers }?: WebSocketUpgradeInit): Request;
/**
 * Re-attaches `headers` to `request` as its own `headers` property, keeping
 * the forbidden ones a browser dropped. Returns `request`.
 */
export declare function withHeaders(request: Request, headers: Headers): Request;
/** Whether `request` asks for a WebSocket. */
export declare function isWebSocketUpgrade(request: Request): boolean;
/** The subprotocols `request` asks for, in order of preference. */
export declare function requestedProtocols(request: Request): string[];
export interface UpgradeWebSocketOptions extends Omit<ServerWebSocketOptions, "url"> {
}
export interface WebSocketUpgrade {
    /** The server end. Call `accept()`, then listen and send. */
    socket: ServerWebSocket;
    /** Return it from the handler: status 101. */
    response: Response;
}
interface PendingUpgrade {
    port: MessagePort;
    protocol: string;
}
/**
 * Accepts a WebSocket upgrade in a handler:
 *
 * ```ts
 * if (isWebSocketUpgrade(request)) {
 *   const { socket, response } = upgradeWebSocket(request, { protocol: "v1" });
 *   socket.accept();
 *   socket.addEventListener("message", (event) => socket.send(event.data));
 *   return response;
 * }
 * ```
 *
 * The host takes the client's port from the response with `takePort` and
 * hands it to the caller.
 */
export declare function upgradeWebSocket(request: Request, options?: UpgradeWebSocketOptions): WebSocketUpgrade;
/**
 * The port to hand to the caller, for a response from `upgradeWebSocket`.
 * Taken once: a second call returns `undefined`.
 */
export declare function takePort(response: Response): MessagePort | undefined;
/** `takePort`, with the subprotocol the server picked. */
export declare function takeUpgrade(response: Response): PendingUpgrade | undefined;
export type WebSocketUpgradeResult = {
    ok: true;
    port: MessagePort;
    protocol: string;
} | {
    ok: false;
    status: number;
    message: string;
};
export interface ServeWebSocketUpgradeInit extends WebSocketUpgradeInit {
    url: string;
}
/**
 * Runs an upgrade through `handler`, as a host does when a caller asks for a
 * socket: builds the upgrade request, calls the handler, and either takes the
 * port of a `101` or reports the refusal. A subprotocol the caller did not ask
 * for is a refusal, as in the standard.
 */
export declare function serveWebSocketUpgrade(handler: (request: Request) => Response | Promise<Response>, { url, protocols, headers }: ServeWebSocketUpgradeInit): Promise<WebSocketUpgradeResult>;
export {};
//# sourceMappingURL=upgrade.d.ts.map