@floegence/flowersec-core 0.24.0 → 0.26.0

package/dist/proxy/server.js

@@ -3,41 +3,38 @@ import { DEFAULT_MAX_JSON_FRAME_BYTES, readJsonFrame, writeJsonFrame } from "../
 import { RpcRouter, RpcServer } from "../rpc/server.js";
 import { createByteReader } from "../streamio/index.js";
 import { readU32be, u32be } from "../utils/bin.js";
-import { DEFAULT_MAX_BODY_BYTES, DEFAULT_MAX_CHUNK_BYTES, DEFAULT_MAX_WS_FRAME_BYTES, PROXY_KIND_HTTP1, PROXY_KIND_WS, PROXY_PROTOCOL_VERSION, } from "./constants.js";
+import { DEFAULT_MAX_BODY_BYTES, DEFAULT_MAX_CHUNK_BYTES, DEFAULT_MAX_CONCURRENT_STREAMS, DEFAULT_MAX_WS_FRAME_BYTES, PROXY_KIND_HTTP1, PROXY_KIND_WS, PROXY_PROTOCOL_VERSION, } from "./constants.js";
 import { filterRequestHeaders, filterResponseHeaders, filterWsOpenHeaders, isSafeHeaderValue, isValidHeaderName, normalizeHeaderName } from "./headerPolicy.js";
 export async function serveProxySession(session, options, signal) {
     const compiled = compileOptions(options);
-    const active = new Set();
+    const activeProxy = new Set();
+    const activeRPC = new Set();
     try {
         while (!signal?.aborted) {
             const accepted = await session.acceptStream(signal === undefined ? {} : { signal });
             if (accepted.kind === "rpc") {
-                if (active.size >= compiled.maxConcurrentStreams) {
-                    await accepted.stream.reset(new Error("proxy stream concurrency exhausted"));
-                    continue;
-                }
                 const task = serveRPCStream(accepted.stream, options.rpcRouter ?? new RpcRouter(), options.rpcServerOptions, signal)
                     .catch(() => { })
-                    .finally(() => active.delete(task));
-                active.add(task);
+                    .finally(() => activeRPC.delete(task));
+                activeRPC.add(task);
                 continue;
             }
             if (accepted.kind !== PROXY_KIND_HTTP1 && accepted.kind !== PROXY_KIND_WS) {
                 await accepted.stream.reset(new Error(`unsupported proxy stream kind ${accepted.kind}`));
                 continue;
             }
-            if (active.size >= compiled.maxConcurrentStreams) {
+            if (activeProxy.size >= compiled.maxConcurrentStreams) {
                 await accepted.stream.reset(new Error("proxy stream concurrency exhausted"));
                 continue;
             }
             const task = serveProxyStreamCompiled(accepted.kind, accepted.stream, compiled, signal)
                 .catch(() => { })
-                .finally(() => active.delete(task));
-            active.add(task);
+                .finally(() => activeProxy.delete(task));
+            activeProxy.add(task);
         }
     }
     finally {
-        await Promise.allSettled(active);
+        await Promise.allSettled([...activeProxy, ...activeRPC]);
     }
 }
 async function serveRPCStream(stream, router, options, signal) {
@@ -50,7 +47,8 @@ async function serveRPCStream(stream, router, options, signal) {
     await server.serve(signal);
 }
 export function serveProxyStream(kind, stream, options, signal) {
-    return serveProxyStreamCompiled(kind, stream, compileOptions(options), signal);
+    const compiled = compileOptions(options);
+    return serveProxyStreamCompiled(kind, stream, compiled, signal);
 }
 async function serveProxyStreamCompiled(kind, stream, options, signal) {
     try {
@@ -67,78 +65,152 @@ async function serveProxyStreamCompiled(kind, stream, options, signal) {
     }
 }
 async function serveHTTP(stream, options, signal) {
-    const reader = createByteReader(stream, signal === undefined ? {} : { signal });
+    const reader = createByteReader(stream);
     let requestId = "unknown";
+    let responseStarted = false;
+    let streamReset = false;
+    let requestBody;
+    let responseBodyReader;
+    let controller;
+    let timer;
+    let removeAbortListener;
+    const resetStream = async (error) => {
+        if (streamReset)
+            return;
+        streamReset = true;
+        try {
+            await stream.reset(error);
+        }
+        catch { /* The peer may already have reset the stream. */ }
+    };
     try {
         const meta = assertHTTPRequestMeta(await readJsonFrame(reader, options.maxJsonFrameBytes));
         requestId = meta.request_id;
         const path = parsePath(meta.path);
-        const body = await readBody(reader, options.maxChunkBytes, options.maxBodyBytes);
+        const knownRequestLength = contentLength(meta.headers, "request");
+        if (knownRequestLength != null && knownRequestLength > options.maxBodyBytes) {
+            throw new ProxyServerError("request_body_too_large", "request body too large");
+        }
+        if (signal?.aborted)
+            throw new ProxyServerError("canceled", "proxy request canceled");
         const headers = requestHeaders(meta.headers, options);
         applyExternalOrigin(headers, meta.external_origin);
         const target = new URL(options.upstream);
         target.pathname = path.pathname;
         target.search = path.search;
         target.hash = "";
-        const timeoutMs = resolveTimeout(meta.timeout_ms, options);
-        const controller = new AbortController();
-        const onAbort = () => controller.abort(signal?.reason);
+        controller = new AbortController();
+        const abortUpstream = (error) => {
+            if (!controller.signal.aborted)
+                controller.abort(error);
+            requestBody?.abort(error);
+            if (responseStarted)
+                void resetStream(error);
+        };
+        const onAbort = () => abortUpstream(new ProxyServerError("canceled", "proxy request canceled"));
         signal?.addEventListener("abort", onAbort, { once: true });
-        const timer = timeoutMs > 0 ? setTimeout(() => controller.abort(new Error("upstream request timeout")), timeoutMs) : undefined;
-        try {
-            const method = meta.method.trim().toUpperCase();
-            const response = await options.fetch(target, {
-                method,
-                headers,
-                redirect: "manual",
-                signal: controller.signal,
-                ...((method === "GET" || method === "HEAD") ? {} : { body: body.slice().buffer }),
-            });
-            const responseHeaders = collectResponseHeaders(response.headers, options);
-            const responseMeta = {
-                v: PROXY_PROTOCOL_VERSION,
-                request_id: requestId,
-                ok: true,
-                status: response.status,
-                headers: responseHeaders,
-            };
-            await writeJsonFrame(stream, responseMeta);
-            if (response.body == null) {
-                await stream.write(u32be(0));
-                return;
-            }
-            const bodyReader = response.body.getReader();
-            let total = 0;
-            while (true) {
-                const next = await bodyReader.read();
-                if (next.done)
-                    break;
-                const bytes = next.value;
-                total += bytes.length;
-                if (total > options.maxBodyBytes)
-                    throw new ProxyServerError("response_body_too_large", "response body too large");
-                for (let offset = 0; offset < bytes.length; offset += options.maxChunkBytes) {
-                    const chunk = bytes.subarray(offset, Math.min(bytes.length, offset + options.maxChunkBytes));
-                    await stream.write(u32be(chunk.length));
-                    await stream.write(chunk);
-                }
-            }
+        removeAbortListener = () => signal?.removeEventListener("abort", onAbort);
+        if (signal?.aborted)
+            onAbort();
+        const timeoutMs = resolveTimeout(meta.timeout_ms, options);
+        timer = timeoutMs > 0
+            ? setTimeout(() => abortUpstream(new ProxyServerError("timeout", "upstream request timeout")), timeoutMs)
+            : undefined;
+        requestBody = createStreamingRequestBody(reader, options.maxChunkBytes, options.maxBodyBytes, abortUpstream);
+        const method = meta.method.trim().toUpperCase();
+        const requestInit = {
+            method,
+            headers,
+            redirect: "manual",
+            signal: controller.signal,
+        };
+        if (method === "GET" || method === "HEAD") {
+            requestBody.drain();
+        }
+        else {
+            requestInit.body = requestBody.stream;
+            requestInit.duplex = "half";
+        }
+        if (controller.signal.aborted)
+            throw controller.signal.reason;
+        const response = await options.fetch(target, requestInit);
+        if (requestBody.error != null)
+            throw requestBody.error;
+        requestBody.drain();
+        const knownResponseLength = contentLength(response.headers, "response");
+        if (knownResponseLength != null && knownResponseLength > options.maxBodyBytes) {
+            await response.body?.cancel();
+            throw new ProxyServerError("response_body_too_large", "response body too large");
+        }
+        const responseHeaders = collectResponseHeaders(response.headers, options);
+        const responseMeta = {
+            v: PROXY_PROTOCOL_VERSION,
+            request_id: requestId,
+            ok: true,
+            status: response.status,
+            headers: responseHeaders,
+        };
+        await writeJsonFrame(stream, responseMeta);
+        responseStarted = true;
+        if (response.body == null) {
             await stream.write(u32be(0));
+            const requestError = await requestBody.completion;
+            if (requestError != null)
+                throw requestError;
+            return;
         }
-        finally {
-            if (timer != null)
-                clearTimeout(timer);
-            signal?.removeEventListener("abort", onAbort);
+        responseBodyReader = response.body.getReader();
+        let total = 0;
+        while (true) {
+            const next = await Promise.race([
+                responseBodyReader.read(),
+                requestBody.failure.then((error) => { throw error; }),
+            ]);
+            if (next.done)
+                break;
+            const bytes = next.value;
+            const nextTotal = total + bytes.length;
+            if (!Number.isSafeInteger(nextTotal) || nextTotal > options.maxBodyBytes) {
+                throw new ProxyServerError("response_body_too_large", "response body too large");
+            }
+            total = nextTotal;
+            for (let offset = 0; offset < bytes.length; offset += options.maxChunkBytes) {
+                const chunk = bytes.subarray(offset, Math.min(bytes.length, offset + options.maxChunkBytes));
+                await stream.write(u32be(chunk.length));
+                await stream.write(chunk);
+            }
         }
+        await stream.write(u32be(0));
+        const requestError = await requestBody.completion;
+        if (requestError != null)
+            throw requestError;
     }
     catch (error) {
-        await writeHTTPError(stream, requestId, classifyHTTPError(error), error);
+        const effective = requestBody?.error ?? controller?.signal.reason ?? asError(error);
+        if (controller != null && !controller.signal.aborted)
+            controller.abort(effective);
+        if (responseStarted)
+            await resetStream(effective);
+        else
+            await writeHTTPError(stream, requestId, classifyHTTPError(effective));
+    }
+    finally {
+        if (timer != null)
+            clearTimeout(timer);
+        removeAbortListener?.();
+        requestBody?.stop();
+        try {
+            await responseBodyReader?.cancel();
+        }
+        catch { /* The upstream body may already be closed. */ }
     }
 }
 async function serveWebSocket(stream, options, signal) {
     const reader = createByteReader(stream, signal === undefined ? {} : { signal });
     let connId = "unknown";
     let raw;
+    let upstreamOpened = false;
+    let removePostOpenAbortListener;
     try {
         const meta = assertWSOpenMeta(await readJsonFrame(reader, options.maxJsonFrameBytes));
         connId = meta.conn_id;
@@ -164,55 +236,137 @@ async function serveWebSocket(stream, options, signal) {
             headers,
             maxPayload: options.maxWsFrameBytes,
             perMessageDeflate: false,
-            handshakeTimeout: Math.min(options.defaultTimeoutMs, options.maxTimeoutMs),
+            handshakeTimeout: resolveTimeout(undefined, options),
         });
-        await waitForUpstreamOpen(raw, signal);
-        const response = {
-            v: PROXY_PROTOCOL_VERSION,
-            conn_id: connId,
-            ok: true,
-            protocol: String(raw.protocol ?? ""),
-        };
-        await writeJsonFrame(stream, response);
         let writeChain = Promise.resolve();
+        let queuedWriteBytes = 0;
+        let terminalSettled = false;
+        let terminalError;
         let terminalResolve;
         const terminal = new Promise((resolve) => { terminalResolve = resolve; });
-        const writeFrame = (op, payload) => {
-            const write = writeChain.then(() => writeWSFrame(stream, op, payload, options.maxWsFrameBytes));
-            writeChain = write.catch(() => { });
-            void write.catch((error) => terminalResolve(asError(error)));
+        const settleTerminal = (error) => {
+            if (terminalSettled)
+                return;
+            terminalSettled = true;
+            terminalError = error;
+            terminalResolve(error);
+        };
+        const queueFrame = (op, payload, allowCloseFrame = false) => {
+            if (terminalSettled)
+                return Promise.reject(new Error("proxy WebSocket is closed"));
+            const frameBytes = payload.byteLength + 5;
+            const nextQueuedWriteBytes = queuedWriteBytes + frameBytes;
+            if (!Number.isSafeInteger(nextQueuedWriteBytes)
+                || (!allowCloseFrame && nextQueuedWriteBytes > options.maxWsQueuedBytes)) {
+                const error = new ProxyServerError("resource_exhausted", "proxy WebSocket write queue exhausted");
+                settleTerminal(error);
+                try {
+                    raw.close(1011, "proxy buffer limit exceeded");
+                }
+                catch { /* Best effort. */ }
+                return Promise.reject(error);
+            }
+            queuedWriteBytes = nextQueuedWriteBytes;
+            const write = writeChain
+                .then(() => {
+                if (terminalSettled)
+                    throw terminalError ?? new Error("proxy WebSocket is closed");
+                return writeWSFrame(stream, op, payload, options.maxWsFrameBytes);
+            })
+                .finally(() => {
+                queuedWriteBytes = Math.max(0, queuedWriteBytes - frameBytes);
+            });
+            writeChain = write;
+            void write.catch((error) => settleTerminal(asError(error)));
+            return write;
+        };
+        const queueEventFrame = (op, payload) => {
+            void queueFrame(op, payload).catch(() => { });
         };
-        raw.on("message", (data, isBinary) => writeFrame(isBinary ? 2 : 1, toBytes(data)));
-        raw.on("ping", (data) => writeFrame(9, toBytes(data)));
-        raw.on("pong", (data) => writeFrame(10, toBytes(data)));
         raw.on("close", (code, reason) => {
+            if (terminalSettled)
+                return;
+            if (!upstreamOpened) {
+                settleTerminal(new Error("upstream WebSocket closed before open"));
+                return;
+            }
             const reasonBytes = toBytes(reason);
             const payload = new Uint8Array(2 + reasonBytes.length);
             payload[0] = (code >>> 8) & 0xff;
             payload[1] = code & 0xff;
             payload.set(reasonBytes, 2);
-            writeFrame(8, payload);
-            terminalResolve();
+            void queueFrame(8, payload, true).then(() => settleTerminal(), (error) => settleTerminal(asError(error)));
         });
-        raw.on("error", (error) => terminalResolve(error));
+        raw.on("error", (error) => settleTerminal(error));
+        await waitForUpstreamOpen(raw, signal);
+        upstreamOpened = true;
+        const response = {
+            v: PROXY_PROTOCOL_VERSION,
+            conn_id: connId,
+            ok: true,
+            protocol: String(raw.protocol ?? ""),
+        };
+        const openResponseWrite = writeJsonFrame(stream, response);
+        writeChain = openResponseWrite;
+        void openResponseWrite.catch((error) => settleTerminal(asError(error)));
+        raw.on("message", (data, isBinary) => queueEventFrame(isBinary ? 2 : 1, toBytes(data)));
+        raw.on("ping", (data) => queueEventFrame(9, toBytes(data)));
+        raw.on("pong", (data) => queueEventFrame(10, toBytes(data)));
+        const onPostOpenAbort = () => {
+            const error = asError(signal?.reason ?? new Error("proxy WebSocket aborted"));
+            settleTerminal(error);
+            try {
+                if (typeof raw.terminate === "function")
+                    raw.terminate();
+                else
+                    raw.close();
+            }
+            catch {
+                // The terminal error is already authoritative.
+            }
+        };
+        if (signal != null) {
+            signal.addEventListener("abort", onPostOpenAbort, { once: true });
+            removePostOpenAbortListener = () => signal.removeEventListener("abort", onPostOpenAbort);
+            if (signal.aborted)
+                onPostOpenAbort();
+        }
+        const openResponseResult = await Promise.race([
+            openResponseWrite.then(() => undefined),
+            terminal,
+        ]);
+        if (openResponseResult != null)
+            throw openResponseResult;
+        try {
+            if (!terminalSettled && typeof raw.resume === "function")
+                raw.resume();
+        }
+        catch (error) {
+            settleTerminal(asError(error));
+            throw error;
+        }
         const inbound = (async () => {
             while (true) {
                 const frame = await readWSFrame(reader, options.maxWsFrameBytes);
                 switch (frame.op) {
                     case 1:
-                        raw.send(frame.payload, { binary: false });
+                        await sendUpstreamFrame(raw, 1, frame.payload);
                         break;
                     case 2:
-                        raw.send(frame.payload, { binary: true });
+                        await sendUpstreamFrame(raw, 2, frame.payload);
                         break;
-                    case 8:
+                    case 8: {
                         raw.close(frame.payload.length >= 2 ? (frame.payload[0] << 8) | frame.payload[1] : 1000, new TextDecoder().decode(frame.payload.subarray(2)));
+                        const closeError = await terminal;
+                        if (closeError != null)
+                            throw closeError;
                         return;
+                    }
                     case 9:
-                        raw.ping(frame.payload);
+                        await sendUpstreamFrame(raw, 9, frame.payload);
                         break;
                     case 10:
-                        raw.pong(frame.payload);
+                        await sendUpstreamFrame(raw, 10, frame.payload);
                         break;
                     default: throw new Error("invalid websocket frame operation");
                 }
@@ -224,10 +378,11 @@ async function serveWebSocket(stream, options, signal) {
         await writeChain;
     }
     catch (error) {
-        if (raw == null || raw.readyState !== 1)
-            await writeWSOpenError(stream, connId, classifyWSError(error), error);
+        if (!upstreamOpened)
+            await writeWSOpenError(stream, connId, classifyWSError(error));
     }
     finally {
+        removePostOpenAbortListener?.();
         try {
             raw?.close();
         }
@@ -247,6 +402,12 @@ function compileOptions(input) {
     const maxChunkBytes = positive(input.maxChunkBytes, DEFAULT_MAX_CHUNK_BYTES, "maxChunkBytes");
     const maxBodyBytes = positive(input.maxBodyBytes, DEFAULT_MAX_BODY_BYTES, "maxBodyBytes");
     const maxWsFrameBytes = positive(input.maxWsFrameBytes, DEFAULT_MAX_WS_FRAME_BYTES, "maxWsFrameBytes");
+    const defaultMaxWsQueuedBytes = maxWsFrameBytes <= Number.MAX_SAFE_INTEGER - 5
+        ? maxWsFrameBytes + 5
+        : maxWsFrameBytes;
+    const maxWsQueuedBytes = positive(input.maxWsQueuedBytes, defaultMaxWsQueuedBytes, "maxWsQueuedBytes");
+    if (maxWsQueuedBytes < 5)
+        throw new Error("maxWsQueuedBytes must be at least 5");
     const defaultTimeoutMs = nonNegative(input.defaultTimeoutMs, 30_000, "defaultTimeoutMs");
     const maxTimeoutMs = nonNegative(input.maxTimeoutMs, 300_000, "maxTimeoutMs");
     if (maxTimeoutMs > 0 && defaultTimeoutMs > maxTimeoutMs)
@@ -258,9 +419,10 @@ function compileOptions(input) {
         maxChunkBytes,
         maxBodyBytes,
         maxWsFrameBytes,
+        maxWsQueuedBytes,
         defaultTimeoutMs,
         maxTimeoutMs,
-        maxConcurrentStreams: positive(input.maxConcurrentStreams, 64, "maxConcurrentStreams"),
+        maxConcurrentStreams: positive(input.maxConcurrentStreams, DEFAULT_MAX_CONCURRENT_STREAMS, "maxConcurrentStreams"),
         extraRequestHeaders: input.extraRequestHeaders ?? [],
         extraResponseHeaders: input.extraResponseHeaders ?? [],
         blockedResponseHeaders: normalizeNames(input.blockedResponseHeaders),
@@ -349,30 +511,137 @@ function applyExternalOrigin(headers, input) {
     headers.set("x-forwarded-proto", new URL(external).protocol.slice(0, -1));
     headers.set("host", new URL(external).host);
 }
-async function readBody(reader, maxChunkBytes, maxBodyBytes) {
-    const chunks = [];
+function createStreamingRequestBody(reader, maxChunkBytes, maxBodyBytes, onFailure) {
     let total = 0;
-    while (true) {
-        const length = readU32be(await reader.readExactly(4), 0);
-        if (length === 0)
-            break;
-        if (length > maxChunkBytes)
-            throw new ProxyServerError("request_body_too_large", "request chunk too large");
-        total += length;
-        if (total > maxBodyBytes)
-            throw new ProxyServerError("request_body_too_large", "request body too large");
-        chunks.push(await reader.readExactly(length));
+    let finished = false;
+    let draining = false;
+    let readChain = Promise.resolve();
+    let error;
+    let streamController;
+    let resolveFailure;
+    const failure = new Promise((resolve) => { resolveFailure = resolve; });
+    let resolveCompletion;
+    const completion = new Promise((resolve) => { resolveCompletion = resolve; });
+    const fail = (cause) => {
+        if (error != null)
+            return error;
+        const raw = asError(cause);
+        error = raw instanceof ProxyServerError
+            ? raw
+            : new ProxyServerError("request_body_invalid", raw.message);
+        finished = true;
+        try {
+            streamController?.error(error);
+        }
+        catch { /* The body consumer may already be gone. */ }
+        resolveFailure(error);
+        resolveCompletion(error);
+        onFailure(error);
+        return error;
+    };
+    const readChunkUnserialized = async () => {
+        try {
+            const length = readU32be(await reader.readExactly(4), 0);
+            if (length === 0) {
+                finished = true;
+                resolveCompletion(undefined);
+                return null;
+            }
+            if (length > maxChunkBytes) {
+                throw new ProxyServerError("request_body_too_large", "request chunk too large");
+            }
+            const nextTotal = total + length;
+            if (!Number.isSafeInteger(nextTotal) || nextTotal > maxBodyBytes) {
+                throw new ProxyServerError("request_body_too_large", "request body too large");
+            }
+            const chunk = await reader.readExactly(length);
+            total = nextTotal;
+            return chunk;
+        }
+        catch (cause) {
+            throw fail(cause);
+        }
+    };
+    const readChunk = () => {
+        const next = readChain.then(readChunkUnserialized);
+        readChain = next.then(() => { }, () => { });
+        return next;
+    };
+    const drain = () => {
+        if (draining || finished)
+            return;
+        draining = true;
+        try {
+            streamController?.close();
+        }
+        catch { /* A pending pull will observe draining below. */ }
+        void (async () => {
+            while (!finished)
+                await readChunk();
+        })().catch(() => { });
+    };
+    const stream = new ReadableStream({
+        start(controller) { streamController = controller; },
+        async pull(controller) {
+            if (finished) {
+                if (error == null)
+                    controller.close();
+                return;
+            }
+            const chunk = await readChunk();
+            if (draining)
+                return;
+            if (chunk == null)
+                controller.close();
+            else
+                controller.enqueue(chunk);
+        },
+        cancel() { drain(); },
+    }, { highWaterMark: 0 });
+    return {
+        stream,
+        failure,
+        completion,
+        get error() { return error; },
+        drain,
+        abort: (cause) => { if (!finished)
+            fail(cause); },
+        stop: () => {
+            if (finished)
+                return;
+            finished = true;
+            try {
+                streamController?.close();
+            }
+            catch { /* The fetch implementation may own the stream. */ }
+            resolveCompletion(undefined);
+        },
+    };
+}
+function contentLength(headers, side) {
+    const rawValues = headers instanceof Headers
+        ? (headers.get("content-length") == null ? [] : [headers.get("content-length")])
+        : headers
+            .filter((header) => normalizeHeaderName(header.name) === "content-length")
+            .map((header) => header.value.trim());
+    if (rawValues.length === 0)
+        return undefined;
+    if (rawValues.length !== 1 || !/^(0|[1-9][0-9]*)$/.test(rawValues[0])) {
+        throw new ProxyServerError(side === "request" ? "invalid_request_meta" : "upstream_request_failed", `invalid ${side} content-length`);
     }
-    const body = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-        body.set(chunk, offset);
-        offset += chunk.length;
+    const value = Number(rawValues[0]);
+    if (!Number.isSafeInteger(value)) {
+        throw new ProxyServerError(side === "request" ? "invalid_request_meta" : "upstream_request_failed", `invalid ${side} content-length`);
     }
-    return body;
+    return value;
 }
-async function writeHTTPError(stream, requestId, code, error) {
-    const meta = { v: PROXY_PROTOCOL_VERSION, request_id: requestId.trim() || "unknown", ok: false, error: { code, message: asError(error).message } };
+async function writeHTTPError(stream, requestId, code) {
+    const meta = {
+        v: PROXY_PROTOCOL_VERSION,
+        request_id: requestId.trim() || "unknown",
+        ok: false,
+        error: { code, message: publicHTTPErrorMessage(code) },
+    };
     try {
         await writeJsonFrame(stream, meta);
         await stream.write(u32be(0));
@@ -396,8 +665,13 @@ async function writeWSFrame(stream, op, payload, maxBytes) {
     if (payload.length > 0)
         await stream.write(payload);
 }
-async function writeWSOpenError(stream, connId, code, error) {
-    const response = { v: PROXY_PROTOCOL_VERSION, conn_id: connId.trim() || "unknown", ok: false, error: { code, message: asError(error).message } };
+async function writeWSOpenError(stream, connId, code) {
+    const response = {
+        v: PROXY_PROTOCOL_VERSION,
+        conn_id: connId.trim() || "unknown",
+        ok: false,
+        error: { code, message: publicWSErrorMessage(code) },
+    };
     try {
         await writeJsonFrame(stream, response);
     }
@@ -405,13 +679,65 @@ async function writeWSOpenError(stream, connId, code, error) {
 }
 function waitForUpstreamOpen(websocket, signal) {
     return new Promise((resolve, reject) => {
-        const cleanup = () => { websocket.off("open", onOpen); websocket.off("error", onError); signal?.removeEventListener("abort", onAbort); };
-        const onOpen = () => { cleanup(); resolve(); };
+        const cleanup = () => {
+            websocket.off("open", onOpen);
+            websocket.off("error", onError);
+            websocket.off("close", onClose);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const onOpen = () => {
+            try {
+                if (typeof websocket.pause === "function")
+                    websocket.pause();
+            }
+            catch (error) {
+                cleanup();
+                reject(asError(error));
+                return;
+            }
+            cleanup();
+            resolve();
+        };
         const onError = (error) => { cleanup(); reject(error); };
+        const onClose = () => { cleanup(); reject(new Error("upstream WebSocket closed before open")); };
         const onAbort = () => { cleanup(); reject(signal?.reason ?? new Error("aborted")); };
         websocket.once("open", onOpen);
         websocket.once("error", onError);
+        websocket.once("close", onClose);
         signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
+    });
+}
+function sendUpstreamFrame(websocket, op, payload) {
+    return new Promise((resolve, reject) => {
+        const finish = (error) => {
+            if (error == null)
+                resolve();
+            else
+                reject(asError(error));
+        };
+        try {
+            switch (op) {
+                case 1:
+                    websocket.send(payload, { binary: false }, finish);
+                    return;
+                case 2:
+                    websocket.send(payload, { binary: true }, finish);
+                    return;
+                case 9:
+                    websocket.ping(payload, undefined, finish);
+                    return;
+                case 10:
+                    websocket.pong(payload, undefined, finish);
+                    return;
+                default:
+                    reject(new Error("invalid upstream WebSocket operation"));
+            }
+        }
+        catch (error) {
+            reject(asError(error));
+        }
     });
 }
 function resolveTimeout(input, options) {
@@ -458,6 +784,33 @@ function classifyWSError(error) {
         return error.code;
     return "upstream_ws_dial_failed";
 }
+function publicHTTPErrorMessage(code) {
+    switch (code) {
+        case "invalid_request_meta":
+            return "invalid proxy request";
+        case "request_body_too_large":
+        case "response_body_too_large":
+            return "proxy body limit exceeded";
+        case "resource_exhausted":
+            return "proxy resource limit exceeded";
+        case "timeout":
+            return "upstream request timed out";
+        case "canceled":
+            return "proxy request canceled";
+        default:
+            return "upstream request failed";
+    }
+}
+function publicWSErrorMessage(code) {
+    switch (code) {
+        case "invalid_ws_open_meta":
+            return "invalid proxy WebSocket request";
+        case "resource_exhausted":
+            return "proxy WebSocket resource limit exceeded";
+        default:
+            return "upstream WebSocket connection failed";
+    }
+}
 function toBytes(input) {
     if (input instanceof Uint8Array)
         return input;