velocious 1.0.570 → 1.0.571

package/README.md

@@ -26,6 +26,7 @@
 * Translated model attributes with current-locale relationship sorting (see [docs/translations.md](docs/translations.md))
 * Cross-process broadcast bus for `broadcastToChannel` via `velocious beacon`, including background job runner processes (see [docs/beacon.md](docs/beacon.md))
 * Configurable HTTP server worker handlers plus backpressured, descriptor-only file responses with completion callbacks (see [docs/http-server.md](docs/http-server.md))
+* Default-on buffered HTTP response compression with Brotli/gzip content negotiation, global and per-response opt-outs, and HEAD-correct representation headers (see [docs/http-server.md](docs/http-server.md#response-compression))
 * Background jobs with failure events for production reporting and authorized database-scoped dashboard count snapshots/deltas (see [docs/background-jobs.md](docs/background-jobs.md) and [docs/background-jobs-dashboard.md](docs/background-jobs-dashboard.md))
 * Durable one-off background-job scheduling with exact epoch timestamps (see [docs/scheduled-background-job-enqueue.md](docs/scheduled-background-job-enqueue.md))
 * Rails-style request and database query logging (see [docs/logging.md](docs/logging.md))
@@ -93,6 +94,45 @@ npm run test:expo
 
 Maintainers cutting a package release must follow the [Velocious release runbook](docs/releasing.md); `npm run release:patch` commits, pushes, and publishes rather than acting as a local-only version command.
 
+# Docker development environment
+
+The checked-in root `Dockerfile` and `compose.yml` define one canonical `dev` service used by humans, CI, and agent systems alike (see [docs/docker-development-environment.md](docs/docker-development-environment.md)). The image is Ubuntu 26.04 LTS (pinned by digest) with Node.js 24.x from signed NodeSource, the universal apt coding/debugging baseline, and the newest published provider CLIs; it is source-independent — no project source is copied and no project dependencies are installed at image build time.
+
+Prerequisites: Docker with the Compose v2 plugin, and this repository checked out at `$DEV_HOME_PATH/velocious` (default `DEV_HOME_PATH`: `/home/dev`).
+
+First-use setup: copy `.env.example` to the git-ignored `.env` and set `GH_CONFIG_SOURCE_PATH` to an existing host GitHub CLI config directory:
+
+```bash
+cp .env.example .env
+```
+
+`$DEV_HOME_PATH` must be a dedicated development home that already exists, holds no credentials or secrets, and is owned by (or at least writable by) UID/GID 1000 — the in-container `dev` user. Do not point it at a general host home directory, and do not recursively chown an existing home; the external environment owns safe initial provisioning.
+
+Normal usage:
+
+```bash
+docker compose up --build --detach dev
+docker compose exec dev bash
+scripts/docker-run.sh npm ci   # one-off command in a disposable container
+```
+
+The dev service preserves the complete `$DEV_HOME_PATH` bind at `/home/dev`, so dependencies, caches, settings, and `node_modules` persist naturally across runs. Install dependencies with the normal package commands inside the service (for example `docker compose exec dev npm ci`), never at image build time.
+
+Concurrent isolated instances use the standard Compose project-name contract plus a distinct development home per instance:
+
+```bash
+COMPOSE_PROJECT_NAME=velocious-review DEV_HOME_PATH=/srv/dev-homes/review \
+  docker compose up --build --detach dev
+```
+
+GitHub CLI authentication is the sole authorized credential boundary: the host config directory named by `GH_CONFIG_SOURCE_PATH` is mounted read-only at `/home/dev/.config/gh`, with container-side `GH_CONFIG_DIR` pointing there. Do not add SSH keys or other credential mounts. Kimi (and other provider) credentials are intentionally kept out of the tracked Compose files — they are an external operational override layered on by the calling environment. Threadwire is not installed in the image or the project; it remains parent orchestration resolved through unversioned `npx` outside the container.
+
+After changing the Docker artifacts, run the checked-in static contract verifier:
+
+```bash
+npm run verify:docker-dev-environment
+```
+
 # Code quality (fallow)
 
 [fallow](https://github.com/fallow-rs/fallow) analyzes the codebase for unused/dead code, duplication, and complexity. CI runs it as a **regression gate**: it fails only on findings beyond the committed baseline in `fallow-baselines/`, so existing backlog never blocks a PR but new issues do.
@@ -1831,6 +1871,8 @@ this.getConfiguration().getWebsocketEvents().publish(channel, payload)
 this.renderJsonArg({status: "published"})
 ```
 
+Publishes are queued per channel: events on the same channel are persisted and dispatched in FIFO order, while a slow or failing channel never delays unrelated channels. `configuration.awaitPendingBroadcasts()` settles once every broadcast accepted before the call has settled. See [docs/websocket-channels.md](docs/websocket-channels.md#publish-ordering-and-failure-semantics) for the full ordering and failure contract.
+
 ## Websocket channels
 
 You can resolve websocket channel classes from subscribe messages and let them decide which streams to allow:
@@ -2365,6 +2407,8 @@ When the server runs in the `development` environment, Velocious watches applica
 
 Starting the HTTP server creates `tmp/server.lock` under the configured application directory before Beacon, workers, or the TCP listener start. A second server for the same app fails fast with the lock owner details instead of partially starting. Normal shutdown removes the lock; stale locks with a dead local PID are reclaimed automatically, while locks from another host or unreadable metadata should be removed manually only after confirming no server is running. See [docs/http-server.md](docs/http-server.md#server-lock).
 
+Buffered string and `Uint8Array` responses are compressed with Brotli (`br`) or gzip by default whenever request negotiation and response eligibility allow — no opt-in is required. Disable compression globally with `httpServer.compression: false` or `httpServer.compression: {enabled: false}`, and tune it with `threshold`/`brotliQuality`/`gzipLevel` overrides. Negotiation honors `Accept-Encoding` q-values, wildcards, and identity semantics (empty `406` when no acceptable representation exists), merges `Accept-Encoding` into `Vary`, and skips streamed `sendFile` responses, already-encoded or `no-transform` responses, server-sent events, partial/range responses, bodyless statuses, and non-allowlisted content types. Transformation is additionally excluded automatically for credentialed traffic and validator-carrying responses — requests with `Authorization`/`Cookie` and responses with `Set-Cookie`, `ETag`, `Digest`, or `Content-Digest` are never compressed (compression-oracle protection, and validators stay application-owned). Controllers opt out per response with `response.disableCompression()`, and HEAD requests compute GET-equivalent representation headers without emitting a body. See [docs/http-server.md](docs/http-server.md#response-compression).
+
 # Authorization (CanCan-style)
 
 Define resource classes with an `abilities()` method and use `can` / `cannot` rules to constrain model access.

package/build/configuration-types.js

@@ -249,8 +249,25 @@
  * @property {number} [unreachableReportMs] - Grace window (ms) a beacon connect/disconnect blip must persist before it is reported as a framework-error. Transient outages that recover within this window (e.g. a deploy restarting the broker) are not reported. Defaults to 30000.
  */
 
+/**
+ * @typedef {object} HttpCompressionConfiguration
+ * @property {boolean} [enabled] - Whether buffered response compression is enabled. Defaults to true; set false to disable globally.
+ * @property {number} [threshold] - Minimum buffered body size in bytes before compression is applied. Defaults to 1024.
+ * @property {number} [brotliQuality] - Brotli encoder quality (0-11). Defaults to 4.
+ * @property {number} [gzipLevel] - Gzip compression level (0-9). Defaults to 6.
+ */
+
+/**
+ * @typedef {object} NormalizedHttpCompressionConfiguration
+ * @property {boolean} enabled - Whether buffered HTTP response compression is enabled.
+ * @property {number} threshold - Minimum buffered body size in bytes before compression is applied.
+ * @property {number} brotliQuality - Brotli encoder quality (0-11).
+ * @property {number} gzipLevel - Gzip compression level (0-9).
+ */
+
 /**
  * @typedef {object} HttpServerConfiguration
+ * @property {boolean | HttpCompressionConfiguration} [compression] - Buffered response compression. Enabled with documented defaults when absent; false or {enabled: false} disables it globally.
  * @property {string} [host] - Hostname to bind the HTTP server to.
  * @property {boolean} [inProcess] - Run HTTP handlers in the main thread instead of worker threads.
  * @property {number} [maxWorkers] - Backward-compatible alias for workers.

package/build/configuration.js

@@ -120,6 +120,10 @@ const DEFAULT_WEBSOCKET_INBOUND_MAX_PENDING_MESSAGES = 256
 const DEFAULT_WEBSOCKET_OUTBOUND_MAX_PENDING_BYTES = 16 * 1024 * 1024
 const DEFAULT_WEBSOCKET_OUTBOUND_MAX_PENDING_FRAMES = 256
 
+const DEFAULT_COMPRESSION_THRESHOLD = 1024
+const DEFAULT_COMPRESSION_BROTLI_QUALITY = 4
+const DEFAULT_COMPRESSION_GZIP_LEVEL = 6
+
 /**
  * Validates a positive safe integer configuration value.
  * @param {?} value - Configured positive safe integer.
@@ -136,6 +140,63 @@ function positiveSafeInteger(value, name, defaultValue) {
   return value
 }
 
+/**
+ * Validates an integer configuration value inside an inclusive range.
+ * @param {?} value - Configured integer.
+ * @param {string} name - Configuration key.
+ * @param {number} min - Minimum accepted value (inclusive).
+ * @param {number} max - Maximum accepted value (inclusive).
+ * @param {number} defaultValue - Default value.
+ * @returns {number} - Validated configured or default value.
+ */
+function integerInRange(value, name, min, max, defaultValue) {
+  if (value === undefined) return defaultValue
+  if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) {
+    throw new TypeError(`${name} must be an integer between ${min} and ${max}`)
+  }
+
+  return value
+}
+
+/**
+ * Normalizes the buffered HTTP response compression configuration. Compression is
+ * enabled by default when the setting is absent; `false` or `{enabled: false}`
+ * disables it globally.
+ * @param {boolean | import("./configuration-types.js").HttpCompressionConfiguration | undefined} value - Configured compression value.
+ * @returns {import("./configuration-types.js").NormalizedHttpCompressionConfiguration} - Normalized compression configuration.
+ */
+function normalizeHttpCompression(value) {
+  if (value === undefined || value === true) {
+    return {enabled: true, threshold: DEFAULT_COMPRESSION_THRESHOLD, brotliQuality: DEFAULT_COMPRESSION_BROTLI_QUALITY, gzipLevel: DEFAULT_COMPRESSION_GZIP_LEVEL}
+  }
+
+  if (value === false) {
+    return {enabled: false, threshold: DEFAULT_COMPRESSION_THRESHOLD, brotliQuality: DEFAULT_COMPRESSION_BROTLI_QUALITY, gzipLevel: DEFAULT_COMPRESSION_GZIP_LEVEL}
+  }
+
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new TypeError(`httpServer.compression must be a boolean or an object, got: ${String(value)}`)
+  }
+
+  const {brotliQuality, enabled, gzipLevel, threshold, ...restCompression} = value
+  const restCompressionKeys = Object.keys(restCompression)
+
+  if (restCompressionKeys.length > 0) {
+    throw new TypeError(`httpServer.compression received unknown keys: ${restCompressionKeys.join(", ")} (supported: brotliQuality, enabled, gzipLevel, threshold)`)
+  }
+
+  if (enabled !== undefined && typeof enabled !== "boolean") {
+    throw new TypeError(`httpServer.compression.enabled must be a boolean, got: ${String(enabled)}`)
+  }
+
+  return {
+    enabled: enabled ?? true,
+    threshold: positiveSafeInteger(threshold, "httpServer.compression.threshold", DEFAULT_COMPRESSION_THRESHOLD),
+    brotliQuality: integerInRange(brotliQuality, "httpServer.compression.brotliQuality", 0, 11, DEFAULT_COMPRESSION_BROTLI_QUALITY),
+    gzipLevel: integerInRange(gzipLevel, "httpServer.compression.gzipLevel", 0, 9, DEFAULT_COMPRESSION_GZIP_LEVEL)
+  }
+}
+
 export default class VelociousConfiguration {
   /**
    * Close database connections promise.
@@ -236,6 +297,7 @@ export default class VelociousConfiguration {
 
     this.httpServer = {
       ...(httpServer || {}),
+      compression: normalizeHttpCompression(httpServer?.compression),
       websocketInboundQueue: {
         maxPendingBytes: positiveSafeInteger(websocketInboundQueue?.maxPendingBytes, "httpServer.websocketInboundQueue.maxPendingBytes", DEFAULT_WEBSOCKET_INBOUND_MAX_PENDING_BYTES),
         maxPendingMessages: positiveSafeInteger(websocketInboundQueue?.maxPendingMessages, "httpServer.websocketInboundQueue.maxPendingMessages", DEFAULT_WEBSOCKET_INBOUND_MAX_PENDING_MESSAGES)
@@ -500,6 +562,14 @@ export default class VelociousConfiguration {
     return this.cors
   }
 
+  /**
+   * Runs get http server compression.
+   * @returns {import("./configuration-types.js").NormalizedHttpCompressionConfiguration} - Normalized buffered response compression configuration.
+   */
+  getHttpServerCompression() {
+    return this.httpServer.compression
+  }
+
   /**
    * Runs get cookie secret.
    * @returns {string | undefined} - Cookie secret.

package/build/http-server/client/index.js

@@ -8,6 +8,7 @@ import EventEmitter from "../../utils/event-emitter.js"
 import Logger from "../../logger.js"
 import Request from "./request.js"
 import RequestRunner from "./request-runner.js"
+import {applyResponseCompression} from "./response-compression.js"
 import WebsocketSession from "./websocket-session.js"
 
 /**
@@ -38,6 +39,16 @@ export default class VeoliciousHttpServerClient {
   events = new EventEmitter()
   state = "initial"
 
+  /**
+   * Whether a done-requests drain is currently sending responses for this client.
+   * @type {boolean} */
+  _doneRequestsDrainActive = false
+
+  /**
+   * Whether another drain was requested while one was already active.
+   * @type {boolean} */
+  _doneRequestsDrainPending = false
+
   /**
    * Runs constructor.
    * @param {object} args - Options object.
@@ -311,12 +322,38 @@ export default class VeoliciousHttpServerClient {
 
   requestDone = () => {
     this.logger.debug(() => ["requestDone", {clientCount: this.clientCount, queueLength: this.requestRunners.length}])
-    void this.sendDoneRequests().catch((error) => {
+
+    return this._drainDoneRequests().catch((error) => {
       this.logger.warn("Failed while sending done requests", error)
       this.events.emit("close")
     })
   }
 
+  /**
+   * Drains done requests one at a time. A runner is shifted out of the queue before
+   * its response finishes sending (async compression, file transfer), so an
+   * overlapping drain would otherwise pick up the next runner and reorder pipelined
+   * socket writes. Calls that arrive while a drain is active are folded into it.
+   * @returns {Promise<void>} - Resolves when every done response has been sent.
+   */
+  async _drainDoneRequests() {
+    if (this._doneRequestsDrainActive) {
+      this._doneRequestsDrainPending = true
+      return
+    }
+
+    this._doneRequestsDrainActive = true
+
+    try {
+      do {
+        this._doneRequestsDrainPending = false
+        await this.sendDoneRequests()
+      } while (this._doneRequestsDrainPending)
+    } finally {
+      this._doneRequestsDrainActive = false
+    }
+  }
+
   async sendDoneRequests() {
     while (true) {
       const requestRunner = this.requestRunners[0]
@@ -393,6 +430,14 @@ export default class VeoliciousHttpServerClient {
     // arrive — drop the body entirely for those codes.
     const isBodylessStatus = isNoBodyStatusCode(response.getStatusCode())
 
+    // HEAD responses select and compute the exact same representation headers as the
+    // equivalent GET (including Content-Length and any negotiated Content-Encoding),
+    // but no buffered or file body is emitted below.
+    const isHeadRequest = request.httpMethod() == "HEAD"
+
+    /** @type {string | Uint8Array | null} */
+    let bodyToEmit = body
+
     if (!isBodylessStatus) {
       let contentLength
 
@@ -400,9 +445,34 @@ export default class VeoliciousHttpServerClient {
         const stats = await fs.stat(filePath)
         contentLength = stats.size
       } else {
-        contentLength = bodyIsString ? Buffer.byteLength(body, "utf8") : body.byteLength
+        // String bodies are UTF-8 framed, so the buffered bytes are the UTF-8 encoding;
+        // Uint8Array bodies are already the exact wire bytes.
+        const bodyBuffer = bodyIsString ? Buffer.from(body, "utf8") : Buffer.from(body)
+        const compressionResult = await applyResponseCompression({
+          bodyBuffer,
+          compression: this.configuration.getHttpServerCompression(),
+          request,
+          response
+        })
+
+        if (compressionResult.outcome == "not-acceptable") {
+          // The client forbids identity and no supported coding is acceptable: answer
+          // with an empty 406 instead of an unacceptable representation.
+          response.setStatus(406)
+          response.setBody("")
+          bodyToEmit = ""
+          contentLength = 0
+        } else if (compressionResult.outcome == "compressed") {
+          bodyToEmit = compressionResult.body
+          contentLength = compressionResult.body.length
+        } else {
+          contentLength = bodyBuffer.length
+        }
       }
 
+      // Remove any application pre-set Content-Length (any casing) so exactly one
+      // recomputed value goes on the wire.
+      response.removeHeader("Content-Length")
       response.setHeader("Content-Length", contentLength)
     }
 
@@ -427,11 +497,14 @@ export default class VeoliciousHttpServerClient {
     if (isBodylessStatus) {
       this.logger.debug(() => ["sendResponse body suppressed for no-body status", {clientCount: this.clientCount, statusCode: response.getStatusCode()}])
       if (hasFilePath) await this.sendFileOutput(filePath, false, fileOnFinished)
+    } else if (isHeadRequest) {
+      this.logger.debug(() => ["sendResponse body suppressed for HEAD request", {clientCount: this.clientCount}])
+      if (hasFilePath) await this.sendFileOutput(filePath, false, fileOnFinished)
     } else if (hasFilePath) {
       await this.sendFileOutput(filePath, true, fileOnFinished)
     } else {
-      this.events.emit("output", body)
-      this.logger.debug(() => ["sendResponse body emitted", {clientCount: this.clientCount, bodyLength: bodyIsString ? body.length : body.byteLength}])
+      this.events.emit("output", bodyToEmit)
+      this.logger.debug(() => ["sendResponse body emitted", {clientCount: this.clientCount, bodyLength: bodyToEmit ? bodyToEmit.length : 0}])
     }
 
     await requestRunner.logCompletedRequest()

package/build/http-server/client/response-compression.js

@@ -0,0 +1,224 @@
+// @ts-check
+
+import zlib from "node:zlib"
+import {promisify} from "node:util"
+
+const brotliCompressAsync = promisify(zlib.brotliCompress)
+const gzipAsync = promisify(zlib.gzip)
+
+/**
+ * Exact media types (beyond the text/*, *+json, and *+xml families) that are worth compressing.
+ * Everything else — unknown binary types and commonly pre-compressed media such as images,
+ * video, and archives — is left untouched by the conservative allowlist.
+ * @type {Set<string>} */
+const COMPRESSIBLE_EXACT_MEDIA_TYPES = new Set([
+  "application/ecmascript",
+  "application/javascript",
+  "application/json",
+  "application/x-javascript",
+  "application/xml",
+  "image/svg+xml"
+])
+
+/**
+ * RFC 9110 §12.4.2 qvalue grammar: `0` or `1` with at most three fractional
+ * digits, and only zeros after `1`.
+ * @type {RegExp} */
+const QVALUE_PATTERN = /^(?:0(?:\.\d{1,3})?|1(?:\.0{1,3})?)$/u
+
+/**
+ * Runs parse accept encoding.
+ * @param {string} headerValue - Accept-Encoding header value.
+ * @returns {Map<string, number>} - Lowercased coding to q-value (0-1).
+ */
+export function parseAcceptEncoding(headerValue) {
+  /** @type {Map<string, number>} */
+  const codings = new Map()
+
+  for (const part of headerValue.split(",")) {
+    const [codingToken, ...parameters] = part.split(";")
+    const coding = codingToken?.trim().toLowerCase()
+
+    if (!coding) continue
+
+    let q = 1
+
+    for (const parameter of parameters) {
+      const [name, value] = parameter.split("=")
+
+      if (name?.trim().toLowerCase() != "q") continue
+
+      const qvalue = value?.trim() || ""
+
+      // A malformed q-value (e.g. `.5`, `01`, `1.001`, more than three fractional
+      // digits, or empty) is treated as "not acceptable" (q=0), per RFC 9110 §12.4.2.
+      q = QVALUE_PATTERN.test(qvalue) ? Number(qvalue) : 0
+    }
+
+    codings.set(coding, q)
+  }
+
+  return codings
+}
+
+/**
+ * Negotiates the content coding for a response from the Accept-Encoding header.
+ * Identity participates in the same quality comparison as the supported codings:
+ * a higher-q identity selects identity, and equal-q ties break in server order
+ * br, gzip, identity. Identity defaults to acceptable unless explicitly refused
+ * with `identity;q=0` or a `*;q=0` wildcard without a more specific identity
+ * entry, and an explicit coding entry beats the wildcard.
+ * @param {string | null | undefined} acceptEncoding - Accept-Encoding header value.
+ * @returns {{encoding: "br" | "gzip" | "identity", identityAcceptable: boolean} | {notAcceptable: true}} - Negotiated coding, or that no acceptable representation exists.
+ */
+export function negotiateContentEncoding(acceptEncoding) {
+  if (acceptEncoding === undefined || acceptEncoding === null || acceptEncoding.trim() === "") {
+    return {encoding: "identity", identityAcceptable: true}
+  }
+
+  const codings = parseAcceptEncoding(acceptEncoding)
+  const wildcardQ = codings.get("*")
+  const identityQ = codings.get("identity") ?? wildcardQ ?? 1
+
+  // Declared in server preference order; the stable sort keeps this order for ties.
+  /** @type {Array<{coding: "br" | "gzip" | "identity", q: number}>} */
+  const candidates = [
+    {coding: "br", q: codings.get("br") ?? wildcardQ ?? 0},
+    {coding: "gzip", q: codings.get("gzip") ?? wildcardQ ?? 0},
+    {coding: "identity", q: identityQ}
+  ]
+  const selected = candidates
+    .filter((candidate) => candidate.q > 0)
+    .sort((a, b) => b.q - a.q)[0]
+
+  if (!selected) return {notAcceptable: true}
+
+  return {encoding: selected.coding, identityAcceptable: identityQ > 0}
+}
+
+/**
+ * Runs is compressible content type.
+ * @param {string} contentType - Content-Type header value.
+ * @returns {boolean} - Whether the media type is on the compressible allowlist.
+ */
+export function isCompressibleContentType(contentType) {
+  const mediaType = contentType.split(";")[0]?.trim().toLowerCase()
+
+  if (!mediaType) return false
+
+  // Server-sent events are long-lived streams; buffering them for compression
+  // would break delivery, so they are excluded before the textual allowlist.
+  if (mediaType == "text/event-stream") return false
+  if (mediaType.startsWith("text/")) return true
+  if (mediaType.endsWith("+json") || mediaType.endsWith("+xml")) return true
+
+  return COMPRESSIBLE_EXACT_MEDIA_TYPES.has(mediaType)
+}
+
+/**
+ * Merges Accept-Encoding into the response Vary header case-insensitively and
+ * without duplicates. An existing `Vary: *` already covers every request header
+ * and is preserved as-is.
+ * @param {import("./response.js").default} response - Response instance.
+ * @returns {void} - No return value.
+ */
+export function addAcceptEncodingToVary(response) {
+  for (const headerKey in response.headers) {
+    if (headerKey.toLowerCase() != "vary") continue
+
+    const values = response.headers[headerKey]
+    const tokens = values.flatMap((value) => value.split(",").map((token) => token.trim().toLowerCase()))
+
+    if (tokens.includes("*") || tokens.includes("accept-encoding")) return
+
+    if (values.length > 0) {
+      values[0] = `${values[0]}, Accept-Encoding`
+    }
+
+    return
+  }
+
+  response.setHeader("Vary", "Accept-Encoding")
+}
+
+/**
+ * Negotiates and applies compression to a buffered response body immediately before
+ * framing. Only string/Uint8Array responses reach this point; sendFile responses and
+ * bodyless statuses are excluded by the caller. Transformation is skipped for
+ * Cache-Control no-transform, non-allowlisted or pre-compressed media types,
+ * server-sent events, partial (206) responses, requests with a Range header,
+ * credentialed requests (Authorization/Cookie headers), responses carrying
+ * credentials or validators (Set-Cookie/ETag/Digest/Content-Digest/Content-Range
+ * headers), and per-response opt-outs; a skipped
+ * transformation is still sent as identity when the client accepts identity, and
+ * answered "not-acceptable" when it does not. Responses that already carry an
+ * application-supplied Content-Encoding are passed through unchanged and never
+ * negotiate. When the client forbids every representation (identity and all
+ * supported codings), the outcome is "not-acceptable".
+ * @param {object} args - Options object.
+ * @param {Buffer} args.bodyBuffer - Buffered response body bytes (UTF-8 encoded for string bodies).
+ * @param {import("../../configuration-types.js").NormalizedHttpCompressionConfiguration} args.compression - Normalized compression configuration.
+ * @param {import("./request.js").default | import("./websocket-request.js").default} args.request - Request object.
+ * @param {import("./response.js").default} args.response - Response instance.
+ * @returns {Promise<{outcome: "identity"} | {outcome: "compressed", body: Buffer} | {outcome: "not-acceptable"}>} - Compression outcome.
+ */
+export async function applyResponseCompression({bodyBuffer, compression, request, response}) {
+  if (!compression.enabled) return {outcome: "identity"}
+
+  // Application-supplied encodings stay application-owned: they are passed through
+  // unchanged and never take part in negotiation failure handling.
+  if (response.getHeader("Content-Encoding").length > 0) return {outcome: "identity"}
+
+  const negotiated = negotiateContentEncoding(request.header("accept-encoding"))
+
+  if ("notAcceptable" in negotiated) return {outcome: "not-acceptable"}
+
+  const cacheControlTokens = response.getHeader("Cache-Control")
+    .flatMap((value) => value.split(","))
+    .map((token) => token.trim().toLowerCase())
+  const contentType = response.getHeader("Content-Type")[0]
+
+  // Automatic security exclusions: credentialed requests (Authorization/Cookie) and
+  // responses carrying credentials (Set-Cookie) or representation validators
+  // (ETag/Digest/Content-Digest) are never transformed — compression could leak
+  // secret-bearing content through a compression oracle, and validators stay
+  // application-owned rather than being recomputed for encoded variants.
+  const transformable = !response.isCompressionDisabled() &&
+    response.getStatusCode() !== 206 &&
+    !request.header("range") &&
+    !request.header("authorization") &&
+    !request.header("cookie") &&
+    response.getHeader("Content-Range").length === 0 &&
+    response.getHeader("Set-Cookie").length === 0 &&
+    response.getHeader("ETag").length === 0 &&
+    response.getHeader("Digest").length === 0 &&
+    response.getHeader("Content-Digest").length === 0 &&
+    !cacheControlTokens.includes("no-transform") &&
+    contentType !== undefined &&
+    isCompressibleContentType(contentType)
+
+  if (!transformable) {
+    // A skipped transformation may still go out as identity when the client accepts
+    // identity; when identity is forbidden, no acceptable representation can be sent.
+    return negotiated.identityAcceptable ? {outcome: "identity"} : {outcome: "not-acceptable"}
+  }
+
+  // The representation now depends on the request's Accept-Encoding, even when this
+  // particular response ends up identity (missing header, higher-q identity, below threshold).
+  addAcceptEncodingToVary(response)
+
+  if (negotiated.encoding == "identity") return {outcome: "identity"}
+
+  // Below the threshold the smaller identity representation is sent instead — but only
+  // when identity is acceptable; a client that forbids identity must never be forced
+  // onto an unacceptable representation by the size check.
+  if (bodyBuffer.length < compression.threshold && negotiated.identityAcceptable) return {outcome: "identity"}
+
+  const body = negotiated.encoding == "br"
+    ? await brotliCompressAsync(bodyBuffer, {params: {[zlib.constants.BROTLI_PARAM_QUALITY]: compression.brotliQuality}})
+    : await gzipAsync(bodyBuffer, {level: compression.gzipLevel})
+
+  response.setHeader("Content-Encoding", negotiated.encoding)
+
+  return {body, outcome: "compressed"}
+}

package/build/http-server/client/response.js

@@ -98,6 +98,11 @@ export default class VelociousHttpServerClientResponse {
    * @type {Record<string, string[]>} */
   headers = {}
 
+  /**
+   * Whether compression has been disabled for this specific response.
+   * @type {boolean} */
+  compressionDisabled = false
+
   /**
    * Runs constructor.
    * @param {object} args - Options object.
@@ -133,6 +138,58 @@ export default class VelociousHttpServerClientResponse {
     this.headers[key] = [value]
   }
 
+  /**
+   * Returns every value set for a header, matched case-insensitively.
+   * @param {string} key - Header name.
+   * @returns {string[]} - Header values in insertion order.
+   */
+  getHeader(key) {
+    const lowerCaseKey = key.toLowerCase()
+
+    /** @type {string[]} */
+    const values = []
+
+    for (const headerKey in this.headers) {
+      if (headerKey.toLowerCase() == lowerCaseKey) {
+        values.push(...this.headers[headerKey])
+      }
+    }
+
+    return values
+  }
+
+  /**
+   * Removes every value set for a header, matched case-insensitively.
+   * @param {string} key - Header name.
+   * @returns {void} - No return value.
+   */
+  removeHeader(key) {
+    const lowerCaseKey = key.toLowerCase()
+
+    for (const headerKey in this.headers) {
+      if (headerKey.toLowerCase() == lowerCaseKey) {
+        delete this.headers[headerKey]
+      }
+    }
+  }
+
+  /**
+   * Disables HTTP response compression for this specific response, even when the
+   * server is configured to compress buffered responses.
+   * @returns {void} - No return value.
+   */
+  disableCompression() {
+    this.compressionDisabled = true
+  }
+
+  /**
+   * Runs is compression disabled.
+   * @returns {boolean} - Whether compression has been disabled for this response.
+   */
+  isCompressionDisabled() {
+    return this.compressionDisabled
+  }
+
   /**
    * Runs get body.
    * @returns {string | Uint8Array | null} - The body.