codex-copilot-dx 0.4.25 → 0.4.26

package/src/atomic-file.mjs

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+function existingMode(filePath, fallback) {
+  try {
+    return fs.statSync(filePath).mode & 0o777;
+  } catch (e) {
+    if (e?.code === "ENOENT") return fallback;
+    throw e;
+  }
+}
+
+function syncDirectory(directory) {
+  if (process.platform === "win32") return;
+  let fd;
+  try {
+    fd = fs.openSync(directory, "r");
+    fs.fsyncSync(fd);
+  } catch (e) {
+    if (!["EINVAL", "ENOTSUP", "EBADF"].includes(e?.code)) throw e;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+export function atomicWriteFileSync(filePath, data, { mode = 0o600 } = {}) {
+  const directory = path.dirname(filePath);
+  const finalMode = existingMode(filePath, mode);
+  const tempPath = path.join(directory, `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+
+  let fd;
+  try {
+    fd = fs.openSync(tempPath, "wx", finalMode);
+    fs.writeFileSync(fd, data);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.renameSync(tempPath, filePath);
+    fs.chmodSync(filePath, finalMode);
+    syncDirectory(directory);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    try {
+      fs.unlinkSync(tempPath);
+    } catch (e) {
+      if (e?.code !== "ENOENT") throw e;
+    }
+  }
+}
+
+export function atomicWriteFileIfChangedSync(filePath, data, options = {}) {
+  try {
+    const current = fs.readFileSync(filePath);
+    const next = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    if (current.equals(next)) return false;
+  } catch (e) {
+    if (e?.code !== "ENOENT") throw e;
+  }
+  atomicWriteFileSync(filePath, data, options);
+  return true;
+}

package/src/claude-config.mjs

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { status } from "./status.mjs";
+import { atomicWriteFileIfChangedSync } from "./atomic-file.mjs";
 
 const SETTINGS_PATH = path.join(os.homedir(), ".claude", "settings.json");
 
@@ -23,20 +24,19 @@ export function computeUpdatedSettings(settings, port) {
 }
 
 // Point Claude Code at the adapter by updating ~/.claude/settings.json.
-export function ensureClaudeConfig(port = 2026) {
+export function ensureClaudeConfig(port = 2026, { filePath = SETTINGS_PATH } = {}) {
   const target = `http://127.0.0.1:${port}`;
 
-  if (!fs.existsSync(SETTINGS_PATH)) {
-    fs.mkdirSync(path.dirname(SETTINGS_PATH), { recursive: true });
+  if (!fs.existsSync(filePath)) {
     const { json } = computeUpdatedSettings({}, port);
-    fs.writeFileSync(SETTINGS_PATH, JSON.stringify(json, null, 2) + "\n");
+    atomicWriteFileIfChangedSync(filePath, JSON.stringify(json, null, 2) + "\n");
     console.log(status("ok", `Created ~/.claude/settings.json for Claude Code at ${target}`));
     return;
   }
 
   let raw, settings;
   try {
-    raw = fs.readFileSync(SETTINGS_PATH, "utf-8");
+    raw = fs.readFileSync(filePath, "utf-8");
     settings = JSON.parse(raw);
   } catch (e) {
     console.log(status("warn", `Could not parse ~/.claude/settings.json: ${e.message}`));
@@ -50,7 +50,7 @@ export function ensureClaudeConfig(port = 2026) {
     return;
   }
 
-  fs.writeFileSync(`${SETTINGS_PATH}.bak`, raw);
-  fs.writeFileSync(SETTINGS_PATH, JSON.stringify(json, null, 2) + "\n");
+  atomicWriteFileIfChangedSync(`${filePath}.bak`, raw);
+  atomicWriteFileIfChangedSync(filePath, JSON.stringify(json, null, 2) + "\n");
   console.log(status("ok", `Configured Claude Code ANTHROPIC_BASE_URL="${target}" and backed up settings.json.bak`));
 }

package/src/claude-desktop-config.mjs

@@ -4,6 +4,7 @@ import os from "node:os";
 import { randomUUID } from "node:crypto";
 import { claudeDesktopModelIds } from "./models.mjs";
 import { status } from "./status.mjs";
+import { atomicWriteFileIfChangedSync, atomicWriteFileSync } from "./atomic-file.mjs";
 
 const CONFIG_FILE = "claude_desktop_config.json";
 const CONFIG_LIBRARY_DIR = "configLibrary";
@@ -127,8 +128,7 @@ function readJsonFile(filePath, fallback = {}) {
 }
 
 function writeJsonFile(filePath, data) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+  return atomicWriteFileIfChangedSync(filePath, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
 }
 
 function snapshotFiles(files) {
@@ -148,8 +148,7 @@ function restoreSnapshots(snapshots) {
       fs.rmSync(snapshot.filePath, { force: true });
       continue;
     }
-    fs.mkdirSync(path.dirname(snapshot.filePath), { recursive: true });
-    fs.writeFileSync(snapshot.filePath, snapshot.data, { mode: 0o600 });
+    atomicWriteFileSync(snapshot.filePath, snapshot.data, { mode: 0o600 });
   }
 }
 

package/src/cli-options.mjs

@@ -0,0 +1,69 @@
+const HELP_COMMANDS = new Set(["help", "--help", "-h"]);
+const VERSION_COMMANDS = new Set(["version", "--version", "-v"]);
+
+function unexpectedArgs(args) {
+  throw new Error(`Unexpected argument${args.length === 1 ? "" : "s"}: ${args.join(" ")}`);
+}
+
+export function parseCliArgs(args = []) {
+  const [command, ...rest] = args;
+  if (!command) return { command: "start", configureClaudeDesktop: false, online: false };
+  if (HELP_COMMANDS.has(command)) {
+    if (rest.length) unexpectedArgs(rest);
+    return { command: "help", configureClaudeDesktop: false, online: false };
+  }
+  if (VERSION_COMMANDS.has(command)) {
+    if (rest.length) unexpectedArgs(rest);
+    return { command: "version", configureClaudeDesktop: false, online: false };
+  }
+  if (command === "usage") {
+    if (rest.length) unexpectedArgs(rest);
+    return { command: "usage", configureClaudeDesktop: false, online: false };
+  }
+  if (command === "doctor" || command === "--doctor") {
+    const invalid = rest.filter((arg) => arg !== "--online");
+    if (invalid.length) unexpectedArgs(invalid);
+    if (rest.filter((arg) => arg === "--online").length > 1) unexpectedArgs(["--online"]);
+    return { command: "doctor", configureClaudeDesktop: false, online: rest.includes("--online") };
+  }
+  if (command === "--configure-claude-desktop") {
+    if (rest.length) unexpectedArgs(rest);
+    return { command: "start", configureClaudeDesktop: true, online: false };
+  }
+  throw new Error(`Unknown command or option: ${command}`);
+}
+
+function integerEnv(env, name, fallback, { min, max = Number.MAX_SAFE_INTEGER }) {
+  const raw = env[name];
+  if (raw === undefined || raw === null || String(raw).trim() === "") return fallback;
+  const text = String(raw).trim();
+  if (!/^\d+$/.test(text)) throw new Error(`${name} must be an integer between ${min} and ${max}`);
+  const value = Number(text);
+  if (!Number.isSafeInteger(value) || value < min || value > max) {
+    throw new Error(`${name} must be an integer between ${min} and ${max}`);
+  }
+  return value;
+}
+
+export function parseRuntimeOptions(env = process.env) {
+  return {
+    adapterPort: integerEnv(env, "ADAPTER_PORT", 2026, { min: 1, max: 65535 }),
+    adapterHost: String(env.ADAPTER_HOST || "127.0.0.1").trim() || "127.0.0.1",
+    modelRefreshTimeoutMs: integerEnv(env, "CCDX_MODEL_REFRESH_TIMEOUT_MS", 5000, { min: 1 }),
+    existingAdapterTimeoutMs: integerEnv(env, "CCDX_EXISTING_ADAPTER_TIMEOUT_MS", 500, { min: 1 }),
+    modelRefreshIntervalMs: integerEnv(env, "CCDX_MODEL_REFRESH_INTERVAL_MS", 30 * 60 * 1000, { min: 0 }),
+    upstreamTimeoutMs: integerEnv(env, "CCDX_UPSTREAM_TIMEOUT_MS", 120000, { min: 1 }),
+    streamHandshakeTimeoutMs: integerEnv(env, "CCDX_STREAM_HANDSHAKE_TIMEOUT_MS", 120000, { min: 1 }),
+    streamIdleTimeoutMs: integerEnv(env, "CCDX_STREAM_IDLE_TIMEOUT_MS", 120000, { min: 1 }),
+    shutdownTimeoutMs: integerEnv(env, "CCDX_SHUTDOWN_TIMEOUT_MS", 5000, { min: 1 }),
+  };
+}
+
+export function cliHelp() {
+  return `Usage:
+  codex-copilot-dx [--configure-claude-desktop]
+  codex-copilot-dx doctor [--online]
+  codex-copilot-dx usage
+  codex-copilot-dx --version
+  codex-copilot-dx --help`;
+}

package/src/config.mjs

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { status } from "./status.mjs";
+import { atomicWriteFileIfChangedSync } from "./atomic-file.mjs";
 
 const CONFIG_PATH = path.join(os.homedir(), ".codex", "config.toml");
 
@@ -74,20 +75,23 @@ OPENAI_API_KEY = "dummy"
 `;
 }
 
-export function ensureCodexConfig(adapterPort = 2026) {
+export function ensureCodexConfig(adapterPort = 2026, { filePath = CONFIG_PATH } = {}) {
   const baseUrl = `http://127.0.0.1:${adapterPort}/v1`;
 
-  if (!fs.existsSync(CONFIG_PATH)) {
+  if (!fs.existsSync(filePath)) {
     // Codex config does not exist yet; create the local proxy defaults.
-    fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
-    fs.writeFileSync(CONFIG_PATH, initialCodexConfig(adapterPort));
+    atomicWriteFileIfChangedSync(filePath, initialCodexConfig(adapterPort));
     console.log(status("ok", "Created ~/.codex/config.toml"));
     return;
   }
 
-  let content = fs.readFileSync(CONFIG_PATH, "utf-8");
+  const content = fs.readFileSync(filePath, "utf-8");
   const updated = computeUpdatedCodexConfig(content, adapterPort);
 
-  fs.writeFileSync(CONFIG_PATH, updated.content);
+  if (!updated.changed) {
+    console.log(status("ok", `Codex already points to ${baseUrl}`));
+    return;
+  }
+  atomicWriteFileIfChangedSync(filePath, updated.content);
   console.log(status("ok", `Configured Codex base URL: ${baseUrl}`));
 }

package/src/copilot.mjs

@@ -4,6 +4,21 @@ import { randomUUID } from "node:crypto";
 import { status } from "./status.mjs";
 import { debugLog } from "./log.mjs";
 import { ensureGithubTokenMetadata, githubReauthMessage, githubTokenPath, importDiscoveredGithubToken } from "./auth.mjs";
+import {
+  optimizeImageDataUrl,
+  optimizeImagesInBody,
+  parseImageConcurrency,
+  runWithConcurrency,
+  summarizeReqBody,
+} from "./image-optimization.mjs";
+
+export {
+  optimizeImageDataUrl,
+  optimizeImagesInBody,
+  parseImageConcurrency,
+  runWithConcurrency,
+  summarizeReqBody,
+} from "./image-optimization.mjs";
 
 export const DEFAULT_API_BASE = "https://api.githubcopilot.com";
 let apiBase = DEFAULT_API_BASE;
@@ -35,25 +50,12 @@ export function getCachedModelEndpoints(modelId) {
 export function resetModelEndpointCacheForTests() {
   modelEndpointCache.clear();
 }
-const IMG_MAX_DIM = parseInt(process.env.CCDX_IMG_MAX_DIM || "2048", 10);
-const IMG_QUALITY = parseInt(process.env.CCDX_IMG_QUALITY || "85", 10);
-const IMG_MIN_BYTES = parseInt(process.env.CCDX_IMG_MIN_BYTES || "100000", 10);
-const DEFAULT_IMG_CONCURRENCY = 4;
-const IMG_MAX_CONCURRENCY = 12;
 const DEFAULT_UPSTREAM_RETRIES = 2;
 const MAX_UPSTREAM_RETRIES = 5;
 const DEFAULT_UPSTREAM_RETRY_DELAY_MS = 300;
 const MAX_UPSTREAM_RETRY_DELAY_MS = 5000;
-const IMG_OPT_DISABLED = process.env.CCDX_DISABLE_IMG_OPT === "1";
-const IMG_CONCURRENCY = parseImageConcurrency(process.env.CCDX_IMG_CONCURRENCY);
 const UPSTREAM_RETRIES = parseUpstreamRetries(process.env.CCDX_UPSTREAM_RETRIES);
 const UPSTREAM_RETRY_DELAY_MS = parseUpstreamRetryDelayMs(process.env.CCDX_UPSTREAM_RETRY_DELAY_MS);
-let sharpImport = null;
-
-export function parseImageConcurrency(value) {
-  const n = Number.parseInt(value, 10);
-  return Number.isFinite(n) && n > 0 ? Math.min(n, IMG_MAX_CONCURRENCY) : DEFAULT_IMG_CONCURRENCY;
-}
 
 export function parseUpstreamRetries(value) {
   const n = Number.parseInt(value, 10);
@@ -200,149 +202,6 @@ export async function fetchCopilotUpstream(
   }
 }
 
-async function sharp() {
-  sharpImport ||= import("sharp");
-  const mod = await sharpImport;
-  return mod.default || mod;
-}
-
-export async function optimizeImageDataUrl(dataUrl) {
-  if (IMG_OPT_DISABLED) return dataUrl;
-  if (typeof dataUrl !== "string" || !dataUrl.startsWith("data:")) return dataUrl;
-  const match = /^data:(image\/[a-z+.-]+);base64,(.+)$/i.exec(dataUrl);
-  if (!match) return dataUrl;
-  const mime = match[1].toLowerCase();
-  const raw = Buffer.from(match[2], "base64");
-  if (raw.length < IMG_MIN_BYTES || mime.includes("gif")) return dataUrl;
-
-  try {
-    const resize = await sharp();
-    const out = await resize(raw, { failOn: "none" })
-      .rotate()
-      .resize(IMG_MAX_DIM, IMG_MAX_DIM, { fit: "inside", withoutEnlargement: true })
-      .webp({ quality: IMG_QUALITY, effort: 4 })
-      .toBuffer();
-    const ratio = ((out.length / raw.length) * 100).toFixed(1);
-    console.log(status("info", `image ${(raw.length / 1024).toFixed(0)}KB ${mime} -> ${(out.length / 1024).toFixed(0)}KB webp (${ratio}%)`));
-    return `data:image/webp;base64,${out.toString("base64")}`;
-  } catch (e) {
-    console.warn(status("warn", `image optimize failed (${mime}, ${raw.length}b): ${e.message}`));
-    return dataUrl;
-  }
-}
-
-export async function runWithConcurrency(taskFns, concurrency) {
-  if (!Array.isArray(taskFns) || taskFns.length === 0) return;
-  const limit = Math.min(parseImageConcurrency(concurrency), taskFns.length);
-  let next = 0;
-  await Promise.all(Array.from({ length: limit }, async () => {
-    while (next < taskFns.length) {
-      const task = taskFns[next++];
-      await task();
-    }
-  }));
-}
-
-function visitImageParts(parts, tasks) {
-  if (!Array.isArray(parts)) return;
-  for (const part of parts) {
-    if (!part) continue;
-    if (part.type === "input_image" && typeof part.image_url === "string") {
-      tasks.push(async () => { part.image_url = await optimizeImageDataUrl(part.image_url); });
-    } else if (part.type === "image" && part.source?.type === "base64" && part.source?.data) {
-      tasks.push(async () => {
-        const dataUrl = `data:${part.source.media_type || "image/png"};base64,${part.source.data}`;
-        const opt = await optimizeImageDataUrl(dataUrl);
-        const match = /^data:([^;]+);base64,(.+)$/.exec(opt);
-        if (match) {
-          part.source.media_type = match[1];
-          part.source.data = match[2];
-        }
-      });
-    }
-  }
-}
-
-export async function optimizeImagesInBody(reqBody) {
-  if (IMG_OPT_DISABLED || !Array.isArray(reqBody.input)) return reqBody;
-  const tasks = [];
-
-  for (const item of reqBody.input) {
-    if (!item) continue;
-    if (item.type === "message" && Array.isArray(item.content)) {
-      visitImageParts(item.content, tasks);
-    }
-    if (item.type === "function_call_output") {
-      if (Array.isArray(item.output)) {
-        visitImageParts(item.output, tasks);
-      } else if (typeof item.output === "string") {
-        const trimmed = item.output.trim();
-        if (trimmed.startsWith("[")) {
-          try {
-            const parsed = JSON.parse(trimmed);
-            if (Array.isArray(parsed)) {
-              const localTasks = [];
-              visitImageParts(parsed, localTasks);
-              if (localTasks.length) {
-                tasks.push(async () => {
-                  await runWithConcurrency(localTasks, IMG_CONCURRENCY);
-                  item.output = JSON.stringify(parsed);
-                });
-              }
-            }
-          } catch {
-            // Leave non-JSON tool output untouched.
-          }
-        }
-      }
-    }
-  }
-
-  if (tasks.length) await runWithConcurrency(tasks, IMG_CONCURRENCY);
-  return reqBody;
-}
-
-export function summarizeReqBody(reqBody) {
-  try {
-    const input = reqBody.input;
-    if (!Array.isArray(input)) return { items: 0, images: 0, biggest: 0, biggestKind: "n/a" };
-    let biggest = 0;
-    let biggestKind = "";
-    let images = 0;
-    const countImages = (parts) => {
-      if (!Array.isArray(parts)) return;
-      for (const part of parts) {
-        if (part?.type === "input_image" || part?.type === "image") images++;
-      }
-    };
-
-    for (const item of input) {
-      const size = JSON.stringify(item).length;
-      if (size > biggest) {
-        biggest = size;
-        biggestKind = item?.type || "?";
-      }
-      if (item?.type === "message") countImages(item.content);
-      if (item?.type === "function_call_output") {
-        if (Array.isArray(item.output)) {
-          countImages(item.output);
-        } else if (typeof item.output === "string" && item.output.trim().startsWith("[")) {
-          try {
-            const parsed = JSON.parse(item.output);
-            if (Array.isArray(parsed)) countImages(parsed);
-          } catch {
-            // Ignore non-JSON tool output.
-          }
-        }
-      }
-    }
-
-    return { items: input.length, images, biggest, biggestKind };
-  } catch {
-    return { items: -1, images: -1, biggest: -1, biggestKind: "err" };
-  }
-}
-
 export function computeInitiator(messages) {
   const isAgent = Array.isArray(messages)
     && messages.some((m) => m && ["assistant", "tool"].includes(m.role));
@@ -525,11 +384,11 @@ export async function listModels({ signal, fetchImpl, retryOptions } = {}) {
 // Responses-only models go directly to Copilot's /responses endpoint.
 export async function responses(reqBody, { signal, fetchImpl, retryOptions } = {}) {
   const token = await getCopilotToken({ signal });
-  const beforeBytes = Buffer.byteLength(JSON.stringify(reqBody));
   await optimizeImagesInBody(reqBody);
-  const bodyBuf = Buffer.from(JSON.stringify(reqBody), "utf8");
+  const bodyText = JSON.stringify(reqBody);
+  const bodyBytes = Buffer.byteLength(bodyText);
   const summary = summarizeReqBody(reqBody);
-  console.log(status("info", `responses payload bytes=${bodyBuf.length} was=${beforeBytes} input_items=${summary.items} images=${summary.images} biggest_item=${summary.biggest}b (${summary.biggestKind})`));
+  console.log(status("info", `responses payload bytes=${bodyBytes} input_items=${summary.items} images=${summary.images}`));
   const headers = buildHeaders({
     token,
     version: getVSCodeVersion(),
@@ -537,14 +396,14 @@ export async function responses(reqBody, { signal, fetchImpl, retryOptions } = {
     vision: false,
   });
   headers["Content-Type"] = "application/json; charset=utf-8";
-  headers["Content-Length"] = String(bodyBuf.length);
+  headers["Content-Length"] = String(bodyBytes);
   headers["Accept"] = reqBody.stream ? "text/event-stream" : "application/json";
 
   try {
     return await fetchCopilotUpstream(`${getApiBase()}${responsesEndpointPath()}`, {
       method: "POST",
       headers,
-      body: bodyBuf,
+      body: bodyText,
       signal,
     }, { fetchImpl, ...retryOptions });
   } catch (e) {

package/src/file-rotation.mjs

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+
+export function parseByteLimit(value, fallback) {
+  if (value === undefined || value === null || String(value).trim() === "") return fallback;
+  const text = String(value).trim();
+  if (!/^\d+$/.test(text)) return fallback;
+  const parsed = Number(text);
+  return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+export function rotatedFilePath(filePath) {
+  return `${filePath}.1`;
+}
+
+export function rotateFileIfNeededSync(filePath, incomingBytes, maxBytes) {
+  if (!Number.isFinite(maxBytes) || maxBytes <= 0) return false;
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch (e) {
+    if (e?.code === "ENOENT") return false;
+    throw e;
+  }
+  if (!stat.isFile() || stat.size === 0 || stat.size + incomingBytes <= maxBytes) return false;
+
+  const backupPath = rotatedFilePath(filePath);
+  fs.rmSync(backupPath, { force: true });
+  fs.renameSync(filePath, backupPath);
+  return true;
+}

package/src/http-transport.mjs

@@ -0,0 +1,182 @@
+import { promisify } from "node:util";
+import * as zlib from "node:zlib";
+import { status } from "./status.mjs";
+
+const DEFAULT_MAX_BODY_BYTES = 128 * 1024 * 1024;
+const DEFAULT_MAX_DECODED_BODY_BYTES = 256 * 1024 * 1024;
+const gunzipAsync = promisify(zlib.gunzip);
+const inflateAsync = promisify(zlib.inflate);
+const brotliDecompressAsync = promisify(zlib.brotliDecompress);
+const zstdDecompressAsync = zlib.zstdDecompress ? promisify(zlib.zstdDecompress) : null;
+
+function positiveInt(value, fallback) {
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+const MAX_BODY_BYTES = positiveInt(process.env.CCDX_MAX_BODY_BYTES, DEFAULT_MAX_BODY_BYTES);
+const MAX_DECODED_BODY_BYTES = positiveInt(process.env.CCDX_MAX_DECODED_BODY_BYTES, DEFAULT_MAX_DECODED_BODY_BYTES);
+
+export function httpError(message, statusCode) {
+  const err = new Error(message);
+  err.statusCode = statusCode;
+  return err;
+}
+
+function payloadTooLarge(kind, maxBytes) {
+  return httpError(`${kind} request body exceeds ${maxBytes} bytes`, 413);
+}
+
+async function readRequestBuffer(req, maxBytes) {
+  const contentLength = Number.parseInt(req.headers?.["content-length"] || "", 10);
+  if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+    throw payloadTooLarge("Raw", maxBytes);
+  }
+
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of req) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    total += buffer.length;
+    if (total > maxBytes) throw payloadTooLarge("Raw", maxBytes);
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks);
+}
+
+async function decompressBody(decompress, buffer, maxBytes) {
+  try {
+    return await decompress(buffer, { maxOutputLength: maxBytes });
+  } catch (e) {
+    if (e?.code === "ERR_BUFFER_TOO_LARGE" || /maxOutputLength/i.test(e?.message || "")) {
+      throw payloadTooLarge("Decoded", maxBytes);
+    }
+    throw e;
+  }
+}
+
+async function decodeRequestBuffer(buffer, contentEncoding, maxBytes) {
+  const encodings = String(contentEncoding || "identity")
+    .split(",")
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean);
+
+  let decoded = buffer;
+  for (const encoding of encodings.reverse()) {
+    if (encoding === "identity") continue;
+    if (encoding === "gzip" || encoding === "x-gzip") {
+      decoded = await decompressBody(gunzipAsync, decoded, maxBytes);
+    } else if (encoding === "deflate") {
+      decoded = await decompressBody(inflateAsync, decoded, maxBytes);
+    } else if (encoding === "br") {
+      decoded = await decompressBody(brotliDecompressAsync, decoded, maxBytes);
+    } else if (encoding === "zstd") {
+      if (!zstdDecompressAsync) throw new Error("Unsupported Content-Encoding: zstd");
+      decoded = await decompressBody(zstdDecompressAsync, decoded, maxBytes);
+    } else {
+      throw new Error(`Unsupported Content-Encoding: ${encoding}`);
+    }
+    if (decoded.length > maxBytes) throw payloadTooLarge("Decoded", maxBytes);
+  }
+  if (decoded.length > maxBytes) throw payloadTooLarge("Decoded", maxBytes);
+  return decoded;
+}
+
+export async function readJsonBody(req, {
+  maxBodyBytes = MAX_BODY_BYTES,
+  maxDecodedBodyBytes = MAX_DECODED_BODY_BYTES,
+} = {}) {
+  const buffer = await readRequestBuffer(req, maxBodyBytes);
+  const decoded = await decodeRequestBuffer(buffer, req.headers?.["content-encoding"], maxDecodedBodyBytes);
+  return JSON.parse(decoded.toString("utf8"));
+}
+
+export function sendJsonError(res, err, fallbackStatus = 400) {
+  if (res.destroyed || res.writableEnded) return;
+  if (!res.headersSent) res.writeHead(err?.statusCode || fallbackStatus, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ error: err?.message || "Request failed" }));
+}
+
+export function sendUpstreamError(res, response, text) {
+  if (!res.headersSent) {
+    res.writeHead(response.status || 502, { "Content-Type": response.headers?.get("content-type") || "application/json" });
+  }
+  res.end(text || JSON.stringify({ error: "Upstream request failed" }));
+}
+
+export function writeOrDrain(res, chunk) {
+  if (res.destroyed || res.writableEnded) return Promise.resolve(false);
+  if (res.write(chunk)) return Promise.resolve(true);
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      res.off("drain", onDrain);
+      res.off("error", onError);
+      res.off("close", onClose);
+    };
+    const onDrain = () => { cleanup(); resolve(true); };
+    const onClose = () => { cleanup(); resolve(false); };
+    const onError = (err) => { cleanup(); reject(err); };
+    res.once("drain", onDrain);
+    res.once("close", onClose);
+    res.once("error", onError);
+  });
+}
+
+export function isAbortLikeError(err) {
+  return err?.name === "AbortError" || /operation was aborted/i.test(String(err?.message || ""));
+}
+
+export function abortErrorStatusCode(reason) {
+  if (["upstream_timeout", "stream_handshake_timeout", "stream_idle_timeout"].includes(reason)) return 504;
+  if (reason === "client_aborted" || reason === "client_closed") return 499;
+  return 400;
+}
+
+export function createRequestAbort(req, res) {
+  const controller = new AbortController();
+  let timer = null;
+  let cleaned = false;
+  let reason = null;
+  const abort = (nextReason = "aborted") => {
+    if (!cleaned && !controller.signal.aborted) {
+      reason = nextReason;
+      controller.abort();
+    }
+  };
+  const onReqAborted = () => abort("client_aborted");
+  const onResClose = () => {
+    if (!res.writableEnded) abort("client_closed");
+  };
+  req.on("aborted", onReqAborted);
+  res.on("close", onResClose);
+  return {
+    signal: controller.signal,
+    get reason() { return reason; },
+    setTimeout(ms, nextReason = "upstream_timeout") {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      if (ms > 0) timer = setTimeout(() => abort(nextReason), ms);
+    },
+    clearTimeout() {
+      if (timer) clearTimeout(timer);
+      timer = null;
+    },
+    cleanup() {
+      cleaned = true;
+      if (timer) clearTimeout(timer);
+      req.off("aborted", onReqAborted);
+      res.off("close", onResClose);
+    },
+  };
+}
+
+export function logRequestFailure(label, err, abort) {
+  if (!isAbortLikeError(err)) {
+    console.error(status("err", `${label} request failed: ${err.message}`));
+    return;
+  }
+
+  const reason = abort?.reason || "aborted";
+  err.statusCode ||= abortErrorStatusCode(reason);
+  console.warn(status("warn", `${label} request aborted: ${reason}`));
+}