@undefineds.co/xpod 0.4.11 → 0.4.12

package/dist/runtime/bootstrap.js

@@ -13,6 +13,7 @@ const global_logger_factory_1 = require("global-logger-factory");
 const node_path_1 = __importDefault(require("node:path"));
 const node_url_1 = require("node:url");
 const ConfigurableLoggerFactory_1 = require("../logging/ConfigurableLoggerFactory");
+const log_file_1 = require("../logging/log-file");
 const package_root_1 = require("./package-root");
 const oidc_issuer_1 = require("./oidc-issuer");
 const NodeRuntimePlatform_1 = require("./platform/node/NodeRuntimePlatform");
@@ -402,7 +403,7 @@ function rewriteConfigImport(sourceConfigPath, importValue, outputDir, platform,
 }
 function initRuntimeLogger(level, platform = NodeRuntimePlatform_1.nodeRuntimePlatform) {
     const loggerFactory = new ConfigurableLoggerFactory_1.ConfigurableLoggerFactory(level, {
-        fileName: platform.joinPath(platform.cwd(), 'logs/xpod-%DATE%.log'),
+        fileName: platform.joinPath(platform.cwd(), log_file_1.LOG_FILE_PATTERN),
         showLocation: true,
     });
     (0, global_logger_factory_1.setGlobalLoggerFactory)(loggerFactory);

package/dist/runtime/upgrade/BunNativeUpgradeRelay.d.ts

@@ -0,0 +1,116 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+/**
+ * WebSocket upgrade relay for runtimes whose HTTP server cannot hand the raw
+ * upgraded socket back to JavaScript.
+ *
+ * Bun's `node:http` server is one of them: the socket passed to the `'upgrade'`
+ * event never delivers client bytes (`'data'` does not fire) and its
+ * `socket.write()` never reaches the peer, so `http-proxy`'s WebSocket pass
+ * drops the `101` response and then the whole frame stream
+ * (oven-sh/bun#9882, oven-sh/bun#18945, oven-sh/bun#28396). The internal
+ * services keep working because they use `ws`, which Bun implements natively.
+ *
+ * The relay therefore terminates the client side with that same native
+ * WebSocket support and speaks the upstream hop itself over a raw TCP/Unix
+ * socket. The upstream side stays byte-accurate — including non-101 rejections
+ * and Unix socket targets — while `WebSocketFrames` bridges messages to frames.
+ */
+export interface NativeUpgradeTarget {
+    url?: string;
+    socketPath?: string;
+}
+/** Logging surface of the relay (satisfied by `getLoggerFor`). */
+export interface RelayLogger {
+    debug(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+/** Subset of the `ws` module surface used by the relay. */
+export interface RelayWebSocket {
+    send(data: Buffer, options?: {
+        binary?: boolean;
+    }): void;
+    close(code?: number, reason?: string): void;
+    on(event: 'message', listener: (data: Buffer | ArrayBuffer | Buffer[] | string, isBinary: boolean) => void): void;
+    on(event: 'close', listener: (code: number, reason: Buffer) => void): void;
+    on(event: 'error', listener: (error: Error) => void): void;
+}
+export interface RelayWebSocketServer {
+    handleUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, callback: (client: RelayWebSocket) => void): void;
+}
+export interface RelayWebSocketModule {
+    WebSocketServer: new (options: Record<string, unknown>) => RelayWebSocketServer;
+}
+/** Loads the runtime's `ws` implementation; `undefined` when it is unavailable. */
+export type WebSocketModuleLoader = () => Promise<RelayWebSocketModule | undefined>;
+export interface BunNativeUpgradeRelayOptions {
+    logger: RelayLogger;
+    /** Relays the upgrade the classic way when native WebSocket support is unavailable. */
+    fallback(req: IncomingMessage, socket: Duplex, head: Buffer, target: NativeUpgradeTarget): void;
+    /** Test seam: replaces the runtime `ws` import. */
+    loadWebSocketModule?: WebSocketModuleLoader;
+    handshakeTimeoutMs?: number;
+    closeGraceMs?: number;
+    maxHandshakeBytes?: number;
+}
+export interface RelayConnectionDependencies {
+    logger: RelayLogger;
+    onClosed(connection: NativeUpgradeConnection): void;
+    handshakeTimeoutMs: number;
+    closeGraceMs: number;
+    maxHandshakeBytes: number;
+}
+export declare class BunNativeUpgradeRelay {
+    private readonly options;
+    private readonly connections;
+    private readonly loadWebSocketModule;
+    private readonly handshakeTimeoutMs;
+    private readonly closeGraceMs;
+    private readonly maxHandshakeBytes;
+    private modulePromise?;
+    private moduleReported;
+    constructor(options: BunNativeUpgradeRelayOptions);
+    handle(req: IncomingMessage, socket: Duplex, head: Buffer, target: NativeUpgradeTarget): void;
+    /** Terminates every relayed connection (gateway shutdown/restart). */
+    close(): void;
+    private start;
+    private webSocketModule;
+}
+export declare class NativeUpgradeConnection {
+    private readonly module;
+    private readonly deps;
+    private upstream?;
+    private clientSocket?;
+    private client?;
+    private parser?;
+    private protocol;
+    private handshakeBuffer;
+    private handshakeTimer?;
+    private handshakeListener?;
+    private closeTimer?;
+    private errorTimer?;
+    private state;
+    constructor(module: RelayWebSocketModule, deps: RelayConnectionDependencies);
+    start(req: IncomingMessage, socket: Duplex, head: Buffer, target: NativeUpgradeTarget): void;
+    /** Closes the relayed connection as part of gateway shutdown. */
+    shutdown(): void;
+    private connectUpstream;
+    private onUpstreamHandshakeData;
+    /**
+     * Relays a non-101 upstream answer verbatim so clients observe the real
+     * status (401 for an expired ticket, 404 for an unknown channel, ...).
+     */
+    private relayRejection;
+    private closeRejectedClient;
+    private createFrameParser;
+    private upgradeClient;
+    private forwardClientMessage;
+    private onClientClose;
+    /** Waits briefly for the upstream close handshake before dropping the socket. */
+    private scheduleUpstreamClose;
+    private fail;
+    private destroy;
+    private clearHandshakeTimer;
+    private finish;
+}

package/dist/runtime/upgrade/BunNativeUpgradeRelay.js

@@ -0,0 +1,423 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeUpgradeConnection = exports.BunNativeUpgradeRelay = void 0;
+const node_net_1 = __importDefault(require("node:net"));
+const node_tls_1 = __importDefault(require("node:tls"));
+const WebSocketFrames_1 = require("./WebSocketFrames");
+const UpgradeHandshake_1 = require("./UpgradeHandshake");
+const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10_000;
+const DEFAULT_CLOSE_GRACE_MS = 5_000;
+const DEFAULT_MAX_HANDSHAKE_BYTES = 64 * 1024;
+const ERROR_SOCKET_LINGER_MS = 1_000;
+const SHUTDOWN_FLUSH_MS = 50;
+/**
+ * Loads `ws` from the runtime. Bun resolves this to its built-in, native
+ * implementation — the only one that can complete an upgrade on Bun's
+ * `node:http` server.
+ */
+async function loadRuntimeWebSocketModule() {
+    try {
+        return await Promise.resolve().then(() => __importStar(require('ws')));
+    }
+    catch {
+        return undefined;
+    }
+}
+function describeImplementation(module) {
+    const source = module.WebSocketServer?.prototype?.handleUpgrade?.toString?.() ?? '';
+    return source.includes('kBunInternals') || source.includes('server.upgrade')
+        ? 'runtime-native'
+        : 'javascript';
+}
+/** Close codes that must never be sent on the wire (RFC 6455 §7.4.1). */
+function wireCloseCode(code) {
+    return code >= 1000 && code <= 4999 && code !== 1005 && code !== 1006 && code !== 1015 ? code : 1000;
+}
+function resolveUpstreamAddress(target) {
+    if (target.socketPath) {
+        return { kind: 'socket', path: target.socketPath };
+    }
+    if (!target.url) {
+        return undefined;
+    }
+    try {
+        const url = new URL(target.url);
+        if (!['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol)) {
+            return undefined;
+        }
+        const secure = url.protocol === 'https:' || url.protocol === 'wss:';
+        return {
+            kind: 'tcp',
+            host: url.hostname,
+            port: url.port ? Number(url.port) : secure ? 443 : 80,
+            secure,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function toBuffer(data) {
+    if (Buffer.isBuffer(data)) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return Buffer.concat(data);
+    }
+    if (typeof data === 'string') {
+        return Buffer.from(data, 'utf8');
+    }
+    return Buffer.from(data);
+}
+class BunNativeUpgradeRelay {
+    constructor(options) {
+        this.options = options;
+        this.connections = new Set();
+        this.moduleReported = false;
+        this.loadWebSocketModule = options.loadWebSocketModule ?? loadRuntimeWebSocketModule;
+        this.handshakeTimeoutMs = options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS;
+        this.closeGraceMs = options.closeGraceMs ?? DEFAULT_CLOSE_GRACE_MS;
+        this.maxHandshakeBytes = options.maxHandshakeBytes ?? DEFAULT_MAX_HANDSHAKE_BYTES;
+        // Warm the module up so the first upgrade does not wait on the import.
+        void this.webSocketModule();
+    }
+    handle(req, socket, head, target) {
+        const upgradeHeader = req.headers.upgrade;
+        if (req.method !== 'GET' || typeof upgradeHeader !== 'string' || upgradeHeader.toLowerCase() !== 'websocket') {
+            this.options.logger.debug(`Rejecting unsupported upgrade request: ${req.method} ${req.url}`);
+            socket.destroy();
+            return;
+        }
+        void this.start(req, socket, head, target);
+    }
+    /** Terminates every relayed connection (gateway shutdown/restart). */
+    close() {
+        for (const connection of [...this.connections]) {
+            connection.shutdown();
+        }
+    }
+    async start(req, socket, head, target) {
+        const module = await this.webSocketModule();
+        if (!module) {
+            this.options.logger.warn('Native WebSocket support is unavailable; falling back to the http-proxy upgrade relay');
+            this.options.fallback(req, socket, head, target);
+            return;
+        }
+        const connection = new NativeUpgradeConnection(module, {
+            logger: this.options.logger,
+            onClosed: (closed) => this.connections.delete(closed),
+            handshakeTimeoutMs: this.handshakeTimeoutMs,
+            closeGraceMs: this.closeGraceMs,
+            maxHandshakeBytes: this.maxHandshakeBytes,
+        });
+        this.connections.add(connection);
+        connection.start(req, socket, head, target);
+    }
+    async webSocketModule() {
+        this.modulePromise ??= this.loadWebSocketModule();
+        const module = await this.modulePromise;
+        if (module && !this.moduleReported) {
+            this.moduleReported = true;
+            this.options.logger.debug(`Upgrade relay using a ${describeImplementation(module)} WebSocket implementation`);
+        }
+        return module;
+    }
+}
+exports.BunNativeUpgradeRelay = BunNativeUpgradeRelay;
+class NativeUpgradeConnection {
+    constructor(module, deps) {
+        this.module = module;
+        this.deps = deps;
+        this.protocol = '';
+        this.handshakeBuffer = Buffer.alloc(0);
+        this.state = 'connecting';
+    }
+    start(req, socket, head, target) {
+        this.clientSocket = socket;
+        socket.once('error', () => this.destroy());
+        socket.once('close', () => this.destroy());
+        // The client may disconnect while the module or upstream handshake is
+        // pending. Its native Request is no longer valid for handleUpgrade then.
+        if (socket.destroyed || req.aborted) {
+            this.destroy();
+            return;
+        }
+        const address = resolveUpstreamAddress(target);
+        if (!address) {
+            this.fail(503, 'Service Unavailable', 'No WebSocket upstream is configured for this path.');
+            this.finish();
+            return;
+        }
+        // Upgraded connections are long lived and may stay idle for a long time
+        // (a Solid notification channel can live for days), so no idle timeout may
+        // tear them down.
+        socket.setTimeout?.(0);
+        const upstream = this.connectUpstream(address);
+        this.upstream = upstream;
+        upstream.setNoDelay(true);
+        upstream.setKeepAlive(true, 0);
+        upstream.setTimeout(0);
+        const onHandshakeData = (chunk) => this.onUpstreamHandshakeData(req, socket, head, chunk);
+        this.handshakeListener = onHandshakeData;
+        upstream.on(address.kind === 'tcp' && address.secure ? 'secureConnect' : 'connect', () => {
+            this.state = 'handshaking';
+            upstream.write((0, UpgradeHandshake_1.buildUpstreamUpgradeRequest)({
+                path: req.url ?? '/',
+                headers: req.headers,
+                protocols: (0, UpgradeHandshake_1.parseRequestedProtocols)(req.headers['sec-websocket-protocol']),
+                ...(0, UpgradeHandshake_1.forwardedHeaderValues)(req),
+            }));
+            this.handshakeTimer = setTimeout(() => {
+                this.deps.logger.warn(`WebSocket upstream handshake timed out for ${req.url}`);
+                this.fail(504, 'Gateway Timeout', 'The internal service did not answer the WebSocket handshake.');
+                upstream.destroy();
+                this.finish();
+            }, this.deps.handshakeTimeoutMs);
+        });
+        upstream.on('data', onHandshakeData);
+        upstream.on('error', (error) => {
+            this.deps.logger.warn(`WebSocket upstream error for ${req.url}: ${String(error)}`);
+            if (this.state === 'connecting' || this.state === 'handshaking') {
+                this.fail(502, 'Bad Gateway', 'The internal service is unavailable.');
+            }
+            this.finish();
+        });
+        upstream.on('close', () => {
+            if (this.state === 'closed') {
+                return;
+            }
+            if (this.state === 'rejected') {
+                // The rejection response may end without a graceful `end` (reset).
+                this.closeRejectedClient();
+                return;
+            }
+            this.clientSocket?.destroy();
+            this.finish();
+        });
+    }
+    /** Closes the relayed connection as part of gateway shutdown. */
+    shutdown() {
+        try {
+            this.client?.close(1001, 'gateway shutting down');
+        }
+        catch {
+            // The client WebSocket may already be closed.
+        }
+        // Shutdown must not wait for the peer's close handshake — a notification
+        // channel can stay idle for days. The short delay lets the close frame
+        // reach the client before the sockets go away.
+        const timer = setTimeout(() => this.destroy(), SHUTDOWN_FLUSH_MS);
+        timer.unref?.();
+    }
+    connectUpstream(address) {
+        if (address.kind === 'socket') {
+            return node_net_1.default.connect({ path: address.path });
+        }
+        return address.secure
+            ? node_tls_1.default.connect({ host: address.host, port: address.port, servername: address.host })
+            : node_net_1.default.connect({ host: address.host, port: address.port });
+    }
+    onUpstreamHandshakeData(req, socket, head, chunk) {
+        if (this.state !== 'handshaking') {
+            return;
+        }
+        this.handshakeBuffer = Buffer.concat([this.handshakeBuffer, chunk]);
+        if (this.handshakeBuffer.length > this.deps.maxHandshakeBytes) {
+            this.deps.logger.warn(`WebSocket upstream sent an oversized handshake for ${req.url}`);
+            this.fail(502, 'Bad Gateway', 'The internal service sent an invalid WebSocket handshake.');
+            this.upstream?.destroy();
+            this.finish();
+            return;
+        }
+        const response = (0, UpgradeHandshake_1.parseUpgradeHandshakeResponse)(this.handshakeBuffer);
+        if (!response) {
+            return;
+        }
+        this.clearHandshakeTimer();
+        const upstream = this.upstream;
+        if (!upstream) {
+            return;
+        }
+        if (this.handshakeListener) {
+            upstream.removeListener('data', this.handshakeListener);
+            this.handshakeListener = undefined;
+        }
+        if (!(0, UpgradeHandshake_1.isWebSocketUpgrade)(response)) {
+            this.relayRejection(response);
+            return;
+        }
+        this.protocol = (0, UpgradeHandshake_1.selectedProtocol)(response);
+        this.parser = this.createFrameParser(req.url ?? '/');
+        upstream.on('data', (frameChunk) => this.parser?.push(frameChunk));
+        this.upgradeClient(req, socket, head, response.rest);
+    }
+    /**
+     * Relays a non-101 upstream answer verbatim so clients observe the real
+     * status (401 for an expired ticket, 404 for an unknown channel, ...).
+     */
+    relayRejection(response) {
+        const upstream = this.upstream;
+        const socket = this.clientSocket;
+        if (!upstream || !socket) {
+            return;
+        }
+        this.state = 'rejected';
+        (0, UpgradeHandshake_1.writeUpgradeSocketBytes)(socket, response.head);
+        if (response.rest.length > 0) {
+            (0, UpgradeHandshake_1.writeUpgradeSocketBytes)(socket, response.rest);
+        }
+        upstream.on('data', (rest) => (0, UpgradeHandshake_1.writeUpgradeSocketBytes)(socket, rest));
+        upstream.on('end', () => this.closeRejectedClient());
+    }
+    closeRejectedClient() {
+        if (this.state === 'closed') {
+            return;
+        }
+        if (this.clientSocket) {
+            (0, UpgradeHandshake_1.endUpgradeSocket)(this.clientSocket);
+        }
+        this.finish();
+    }
+    createFrameParser(url) {
+        return new WebSocketFrames_1.WebSocketFrameParser({
+            onMessage: (payload, isBinary) => this.client?.send(payload, { binary: isBinary }),
+            onPing: (payload) => {
+                this.upstream?.write((0, WebSocketFrames_1.encodeWebSocketFrame)(payload, { opcode: WebSocketFrames_1.WS_OPCODE.pong, mask: true }));
+            },
+            onPong: () => undefined,
+            onClose: (code, reason) => {
+                try {
+                    this.client?.close(wireCloseCode(code), reason);
+                }
+                catch {
+                    // The client WebSocket may already be closed.
+                }
+                this.scheduleUpstreamClose();
+            },
+            onProtocolError: (reason) => {
+                this.deps.logger.warn(`WebSocket upstream protocol error for ${url}: ${reason}`);
+                try {
+                    this.client?.close(WebSocketFrames_1.WS_CLOSE_PROTOCOL_ERROR, 'protocol error');
+                }
+                catch {
+                    // The client WebSocket may already be closed.
+                }
+                this.destroy();
+            },
+        });
+    }
+    upgradeClient(req, socket, head, bufferedFrames) {
+        const protocol = this.protocol;
+        try {
+            const server = new this.module.WebSocketServer({
+                noServer: true,
+                perMessageDeflate: false,
+                // The upstream handshake already picked a subprotocol; echo exactly that
+                // one so the client observes the same negotiation as a direct connection.
+                handleProtocols: () => protocol || false,
+            });
+            server.handleUpgrade(req, socket, head, (client) => {
+                this.client = client;
+                this.state = 'open';
+                client.on('message', (data, isBinary) => this.forwardClientMessage(data, isBinary));
+                client.on('close', (code, reason) => this.onClientClose(code, reason));
+                client.on('error', () => this.destroy());
+                if (bufferedFrames.length > 0) {
+                    this.parser?.push(bufferedFrames);
+                }
+            });
+        }
+        catch (error) {
+            this.deps.logger.warn(`Failed to complete the client WebSocket handshake for ${req.url}: ${String(error)}`);
+            this.fail(400, 'Bad Request', 'Invalid WebSocket handshake.');
+            this.destroy();
+        }
+    }
+    forwardClientMessage(data, isBinary) {
+        if (!this.upstream || this.upstream.destroyed) {
+            return;
+        }
+        this.upstream.write((0, WebSocketFrames_1.encodeWebSocketFrame)(toBuffer(data), {
+            opcode: isBinary ? WebSocketFrames_1.WS_OPCODE.binary : WebSocketFrames_1.WS_OPCODE.text,
+            mask: true,
+        }));
+    }
+    onClientClose(code, reason) {
+        if (this.state === 'open' && this.upstream && !this.upstream.destroyed) {
+            this.upstream.write((0, WebSocketFrames_1.encodeWebSocketFrame)((0, WebSocketFrames_1.encodeWebSocketClosePayload)(wireCloseCode(code), reason.toString('utf8')), { opcode: WebSocketFrames_1.WS_OPCODE.close, mask: true }));
+        }
+        this.scheduleUpstreamClose();
+    }
+    /** Waits briefly for the upstream close handshake before dropping the socket. */
+    scheduleUpstreamClose() {
+        this.closeTimer ??= setTimeout(() => this.destroy(), this.deps.closeGraceMs);
+    }
+    fail(statusCode, statusMessage, message) {
+        const socket = this.clientSocket;
+        if (!socket || socket.destroyed) {
+            return;
+        }
+        (0, UpgradeHandshake_1.writeUpgradeErrorResponse)(socket, statusCode, statusMessage, {
+            'Content-Type': 'application/json',
+        }, JSON.stringify({ error: statusMessage, message }));
+        this.errorTimer ??= setTimeout(() => socket.destroy(), ERROR_SOCKET_LINGER_MS);
+    }
+    destroy() {
+        if (this.state === 'closed') {
+            return;
+        }
+        this.upstream?.destroy();
+        this.clientSocket?.destroy();
+        this.finish();
+    }
+    clearHandshakeTimer() {
+        if (this.handshakeTimer) {
+            clearTimeout(this.handshakeTimer);
+            this.handshakeTimer = undefined;
+        }
+    }
+    finish() {
+        if (this.state === 'closed') {
+            return;
+        }
+        this.state = 'closed';
+        this.clearHandshakeTimer();
+        if (this.closeTimer) {
+            clearTimeout(this.closeTimer);
+            this.closeTimer = undefined;
+        }
+        if (this.errorTimer) {
+            clearTimeout(this.errorTimer);
+            this.errorTimer = undefined;
+        }
+        this.deps.onClosed(this);
+    }
+}
+exports.NativeUpgradeConnection = NativeUpgradeConnection;
+//# sourceMappingURL=BunNativeUpgradeRelay.js.map

package/dist/runtime/upgrade/UpgradeHandshake.d.ts

@@ -0,0 +1,63 @@
+import type { IncomingHttpHeaders, IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+export interface BuildUpstreamUpgradeOptions {
+    /** Request path (including query string) to request from the upstream. */
+    path: string;
+    /** Client request headers. */
+    headers: IncomingHttpHeaders;
+    /** Subprotocols requested by the client, in client preference order. */
+    protocols: string[];
+    /** Freshly generated `Sec-WebSocket-Key`. Defaults to a random key. */
+    key?: string;
+    /** `X-Forwarded-*` values; parity with `http-proxy`'s `xfwd: true`. */
+    forwardedFor?: string;
+    forwardedPort?: string;
+    forwardedProto?: string;
+}
+export declare function createWebSocketKey(): string;
+/**
+ * Builds the raw HTTP upgrade request that is sent to the internal service.
+ * The client's `Host` and its application headers (authorization, cookies,
+ * origin, DPoP, custom `X-*`, ...) are forwarded unchanged so the internal
+ * server answers exactly as it would for a direct connection.
+ */
+export declare function buildUpstreamUpgradeRequest(options: BuildUpstreamUpgradeOptions): Buffer;
+export interface UpgradeHandshakeResponse {
+    statusCode: number;
+    statusMessage: string;
+    headers: Record<string, string>;
+    /** Raw response bytes (status line + headers), without the body that follows. */
+    head: Buffer;
+    /** Bytes received after the header block (already-upgraded frames or a body). */
+    rest: Buffer;
+}
+/**
+ * Parses the beginning of the upstream upgrade response.
+ * @returns the parsed response, or `undefined` while the header block is incomplete.
+ */
+export declare function parseUpgradeHandshakeResponse(buffer: Buffer): UpgradeHandshakeResponse | undefined;
+/** Subprotocol selected by the upstream server, if any. */
+export declare function selectedProtocol(response: UpgradeHandshakeResponse): string;
+/** True when the upstream actually switched protocols to WebSocket. */
+export declare function isWebSocketUpgrade(response: UpgradeHandshakeResponse): boolean;
+export declare function parseRequestedProtocols(header: string | string[] | undefined): string[];
+/**
+ * Writes raw bytes to a socket handed over by the HTTP server's `upgrade` event.
+ *
+ * Bun's `node:http` server hands the upgrade listener a socket shim whose
+ * `write()` never reaches the peer (`socket.write()` returns `true` and the
+ * bytes are dropped), which is why the gateway cannot use `http-proxy`'s
+ * WebSocket pass there. The underlying Bun socket handle still writes
+ * correctly, so error responses are written through it; on every other runtime
+ * the regular socket write is used.
+ */
+export declare function writeUpgradeSocketBytes(socket: Duplex, chunk: Buffer): void;
+export declare function endUpgradeSocket(socket: Duplex): void;
+/** Writes a complete HTTP response to an upgrade request that could not be relayed. */
+export declare function writeUpgradeErrorResponse(socket: Duplex, statusCode: number, statusMessage: string, headers: Record<string, string>, body: string): void;
+/** Best-effort `X-Forwarded-*` values matching `http-proxy`'s `xfwd: true`. */
+export declare function forwardedHeaderValues(req: IncomingMessage): {
+    forwardedFor?: string;
+    forwardedPort?: string;
+    forwardedProto: string;
+};