@antelopejs/dms-frontend 0.6.1 → 0.6.3

package/dist/config.js

@@ -56,6 +56,7 @@ exports.TEMPLATE_FILES = [
     ["head-order.mjs", "head-order.mjs"],
     ["client-server-guard.mjs", "client-server-guard.mjs"],
     ["ui-inertia-page.mjs", "ui-inertia-page.mjs"],
+    ["ui-request-state.mjs", "ui-request-state.mjs"],
     ["icon-api.mjs", "icon-api.mjs"],
     ["icon-scan.mjs", "icon-scan.mjs"],
     ["email-renderer.ts", "email-renderer.ts"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",
@@ -15,6 +15,10 @@
     "vite",
     "vue"
   ],
+  "homepage": "https://dms.antelopejs.com/docs/frontend",
+  "bugs": {
+    "url": "https://github.com/AntelopeJS/dms-frontend/issues"
+  },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -26,7 +30,8 @@
   "files": [
     "dist/",
     "!dist/.tsbuildinfo",
-    "templates/"
+    "templates/",
+    "skills/"
   ],
   "main": "./dist/common.js",
   "types": "./dist/common.d.ts",
@@ -59,11 +64,13 @@
     "test": "node --import tsx --test tests/*.test.ts tests/*.test.mts",
     "test:real-source": "pnpm run build && node dist/verify-source-runner.js",
     "format": "oxfmt .",
-    "lint": "oxlint && oxfmt --check . && antelopejs-check-interface-ranges",
+    "lint": "oxlint && oxfmt --check . && antelopejs-check-interface-ranges && pnpm run docs:reference:check",
     "typecheck": "tsc --noEmit",
     "lint:fix": "oxlint --fix --max-warnings=1000000 && oxfmt .",
     "knip": "knip --dependencies",
-    "knip:all": "knip"
+    "knip:all": "knip",
+    "docs:reference": "tsx scripts/docs-reference.ts",
+    "docs:reference:check": "tsx scripts/docs-reference.ts --check"
   },
   "dependencies": {
     "chokidar": "^4.0.3",
@@ -73,8 +80,8 @@
     "unzipper": "^0.12.3"
   },
   "devDependencies": {
-    "@antelopejs/core": "^1.13.2",
-    "@antelopejs/tooling-configs": ">=0.0.7 <1.0.0",
+    "@antelopejs/core": "^1.16.0",
+    "@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
     "@iconify/utils": "^3.1.0",
     "@iconify/vue": "^5.0.1",
     "@inertiajs/vue3": "^3.7.1",
@@ -102,7 +109,7 @@
     "vue-i18n": "^11.2.7"
   },
   "peerDependencies": {
-    "@antelopejs/core": ">=1.13.2 <2"
+    "@antelopejs/core": ">=1.16.0 <2"
   },
   "optionalDependencies": {
     "@oxc-parser/binding-darwin-arm64": "^0.95.0",
@@ -114,5 +121,10 @@
   "engines": {
     "node": ">=20.12.0"
   },
-  "packageManager": "pnpm@10.6.5"
+  "packageManager": "pnpm@10.6.5",
+  "antelopeJs": {
+    "skills": [
+      "./skills"
+    ]
+  }
 }

package/skills/dms-frontend/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: dms-frontend
+description: Runs, builds, deploys and extends the AntelopeJS DMS frontend with @antelopejs/dms-frontend (the ajs dms CLI, the Vue renderer, the frontend-module SDK). Use when running ajs dms dev, build, start, prepare, workspaces, clean or verify-source; configuring DMS_* environment variables, the session or bootstrap secret; writing a frontend module's dms.frontend.ts, dms.server.ts (server routes, auth hooks, route rules, backend proxies) or dms.frontend.build.ts; declaring engines["@antelopejs/dms-frontend"]; deploying the frontend server behind a reverse proxy; or debugging a refused range, a missing secret, a 404 from the proxy or a stale workspace.
+icon: i-lucide-app-window
+category: tooling
+tags: [frontend, cli, renderer, vue, inertia, ssr, deployment, dms-module]
+---
+
+# dms-frontend
+
+`@antelopejs/dms-frontend` is the DMS frontend: the `ajs dms` CLI, the Vue renderer it generates, and the SDK frontend modules register through. The full guide is at <https://dms.antelopejs.com/docs/frontend>; this skill holds what the `--help` output does not say. For starting and stopping the backend and frontend of a project, use the **dms-dev** skill; for the dashboard pages and blocks, **dms-pages**.
+
+## Look things up first
+
+- `ajs dms <command> --help` gives every option, its variable and examples.
+- `ajs dms help environment` lists every variable the CLI and the server read.
+- `ajs dms workspaces` shows which workspaces exist, keyed on what, and how big.
+
+## Rules that bite
+
+- **One workspace per backend URL**, under `~/.antelopejs/dms-frontend/<sha256>/`. `dev` without `-b` keys its own on the project directory instead, so `dev` then `build -b` builds a second workspace. `start` serves the workspace `build` made for the same URL, user and home directory.
+- **Secrets.** `build` and `start` need the same `DMS_SESSION_SECRET` (32+ characters); `dev` generates one only when it is unset. `build` takes `DMS_BOOTSTRAP_SECRET` explicitly, never from `.antelope/dms-dev.json`. A build without it still succeeds, but loses the modules' private options, the manifest's backend proxies and the e-mail and OAuth secrets: `start` then warns that e-mail renders and OAuth sign-in will be refused.
+- **`.env`** is read from the current directory only (shell, then `.env.local`, then `.env`). A `DMS_API_BASE_URL` in `.env` turns off backend discovery for `dev`. `clean` never reads it.
+- **`prepare` never fails** without `--strict`: it warns and exits 0. Use `--strict` where the types are required.
+- **Exit codes:** 0 success, 1 failure, 2 usage error, 130 Ctrl+C.
+
+## Writing a frontend module
+
+- The entry is `dms.frontend.ts`, default-exporting `{ componentPrefix?, setup(sdk) }`. `setup` only registers: under `dev` it runs again on every layer change.
+- Set a `componentPrefix`; the backend names a component by its full name (`CustomComponent("AcmeBanner")`). Replace another module's component with `registerComponent(fullName, c, { prefix: false })`.
+- Nothing is auto-imported unless `dms.frontend.build.ts` declares it; `app/build/` never is.
+- Server routes, auth hooks, route rules and backend proxies go in `dms.server.ts` (`defineDmsServer` from `#dms/server`). It is trusted Node.js code: import what it uses, never `.vue` files or `dms.frontend.ts`.
+- The browser reaches the backend only through declared prefixes (`registerBackendProxy`, `backendProxies`, `DMS_BACKEND_PROXIES`). An undeclared backend route answers `404`; in development, the `x-dms-route-owner` header names who answered.
+- Declare `engines["@antelopejs/dms-frontend"]`, capped below the next minor (`">=0.6.0 <0.7.0"`); a range that excludes the installed loader stops `dev`, `build` and `verify-source`.
+- Give every server-rendered `useDmsAsyncData` / `useDmsFetch` call a key, and replace `data` instead of mutating it (shallow by default).
+- Check a module with `ajs dms verify-source` from the project: no backend needed.
+
+## Where the details are
+
+| Task | Page |
+| --- | --- |
+| Compatibility with DMS releases | `/docs/frontend/introduction#compatibility` |
+| One command in depth | `/docs/frontend/cli/<command>` |
+| Variables and secrets | `/docs/frontend/configuration` |
+| Module files and SDK | `/docs/frontend/frontend-modules/anatomy`, then `server-routes`, `sessions-and-sign-in`, `route-rules`, `emails` |
+| SSR, navigation, data, icons | `/docs/frontend/rendering/model`, `navigation`, `data-loading`, `icons` |
+| Production, proxy, security | `/docs/frontend/deployment/production`, `routing-and-proxy`, `public-endpoints`, `security` |
+| An error message | `/docs/frontend/troubleshooting` |
+
+The same pages ship in this package's repository under `docs/`.

package/templates/vue/frontend-module.ts

@@ -384,6 +384,14 @@ export interface DmsMiddlewareRegistrationOptions {
 }
 export interface DmsPluginRegistrationOptions {
   clientOnly?: boolean;
+  /**
+   * When the plugin runs, as Nuxt's `enforce`: every module's `"pre"`
+   * plugins first, then the `"default"` ones, then the `"post"` ones, each
+   * group in the modules' priority order. A plugin that the others depend on
+   * whatever their module's priority, such as the one setting the async data
+   * scope (`setDmsAsyncDataScope`), is `"pre"`.
+   */
+  enforce?: "pre" | "default" | "post";
 }
 export type DmsComponentPreloader = () => Promise<unknown>;
 export interface DmsComponentRegistrationOptions {
@@ -494,8 +502,11 @@ interface DmsAsyncComponent {
 interface DmsPluginRegistration {
   setup: DmsPluginSetup;
   clientOnly: boolean;
+  enforce: NonNullable<DmsPluginRegistrationOptions["enforce"]>;
 }
 
+const PLUGIN_ORDER = { pre: 0, default: 1, post: 2 } as const;
+
 /**
  * What the frontend modules registered through their SDK. Modules are set up
  * by descending priority, so the first one to claim a name keeps it.
@@ -2263,7 +2274,9 @@ export async function refreshDmsPageData(): Promise<void> {
  * show their default until they load again. Call it on both sides before
  * the page renders, with the same value, so the browser finds the data the
  * server transferred; the scope is written in the page with each key, so a
- * digest rather than an identifier.
+ * digest rather than an identifier. Call it from a plugin registered with
+ * `{ enforce: "pre" }`: a plugin of another module that reads data at setup
+ * would otherwise run first, and the new scope abort its read.
  *
  * @param scope The scope, or `undefined` for none
  */
@@ -3220,6 +3233,7 @@ function createSdk(
       target.pluginSetups.push({
         setup,
         clientOnly: options.clientOnly ?? false,
+        enforce: options.enforce ?? "default",
       }),
     registerMiddleware: (name, handler, options = {}) => {
       if (!target.namedMiddleware.has(name))
@@ -3361,7 +3375,11 @@ export async function installDmsPlugins(
   registry.plugins.forEach((plugin) => {
     app.use(plugin);
   });
-  for (const registration of registry.pluginSetups) {
+  // Stable: within a group, the modules' priority order stays.
+  const pluginSetups = [...registry.pluginSetups].sort(
+    (left, right) => PLUGIN_ORDER[left.enforce] - PLUGIN_ORDER[right.enforce],
+  );
+  for (const registration of pluginSetups) {
     if (registration.clientOnly && typeof window === "undefined") continue;
     await runtime.scope.run(() =>
       app.runWithContext(() => registration.setup(appContext)),

package/templates/vue/main.ts

@@ -57,27 +57,40 @@ if (import.meta.env.DEV) adoptViteDevStyles();
 // the generated server answers those queries from the installed collections.
 addAPIProvider("", sameOriginIconProvider(location.origin));
 
-await setupFrontendModules(frontendModules, appConfigs);
-// A layer's app config edited during development reaches the page without a
-// reload. A server render imports the new configs instead.
-syncAppConfigs(applyLayerAppConfigs);
+/**
+ * Sets the modules up, then starts the app.
+ *
+ * A function rather than top-level statements: Rollup keeps apart every module
+ * the entry shares with a dynamic import when the entry awaits at its top level
+ * (merging them could deadlock that await). Every page and component is such
+ * an import, so the bundle split the entry into a hundred one-module chunks the
+ * browser requested one by one.
+ */
+async function startDmsApp(): Promise<void> {
+  await setupFrontendModules(frontendModules, appConfigs);
+  // A layer's app config edited during development reaches the page without a
+  // reload. A server render imports the new configs instead.
+  syncAppConfigs(applyLayerAppConfigs);
+
+  createInertiaApp({
+    resolve: resolveDmsInertiaPage,
+    async setup({ App, el, props, plugin }) {
+      const root = { render: () => h(App, props) };
+      const app = el.hasAttribute("data-server-rendered")
+        ? createSSRApp(root)
+        : createApp(root);
+      const configured = await configureDmsApp({
+        app,
+        head: createHead(),
+        initialPageProps: props.initialPage.props,
+        initialPageUrl: props.initialPage.url,
+        inertiaPlugin: plugin,
+      });
+      app.mount(el);
+      markDmsReady();
+      await configured.mounted();
+    },
+  });
+}
 
-createInertiaApp({
-  resolve: resolveDmsInertiaPage,
-  async setup({ App, el, props, plugin }) {
-    const root = { render: () => h(App, props) };
-    const app = el.hasAttribute("data-server-rendered")
-      ? createSSRApp(root)
-      : createApp(root);
-    const configured = await configureDmsApp({
-      app,
-      head: createHead(),
-      initialPageProps: props.initialPage.props,
-      initialPageUrl: props.initialPage.url,
-      inertiaPlugin: plugin,
-    });
-    app.mount(el);
-    markDmsReady();
-    await configured.mounted();
-  },
-});
+void startDmsApp();

package/templates/vue/server/built-files.mjs

@@ -0,0 +1,48 @@
+// The built files the production server hands to a browser: what the client
+// build wrote to `dist/client`, except a file or directory whose name starts
+// with a dot. Vite keeps its build metadata there (`.vite/manifest.json`, the
+// source path of every module file), and a module's `public/` may hold dot
+// files too. `/.well-known/`, which RFC 8615 reserves for files meant to be
+// public, stays served.
+
+import { existsSync, statSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+
+const PUBLIC_DOT_DIRECTORY = ".well-known";
+
+/**
+ * Whether a path relative to the build root may be served: no segment starts
+ * with a dot, but a leading `.well-known`. Split on both separators: on
+ * Windows, `relative` answers with backslashes, and a decoded `%5C` is one.
+ */
+export function isPublicBuildPath(relativePath) {
+  return relativePath
+    .split(/[\\/]/)
+    .every(
+      (segment, index) =>
+        !segment.startsWith(".") ||
+        (index === 0 && segment === PUBLIC_DOT_DIRECTORY),
+    );
+}
+
+/**
+ * The file under `root` a request path names, or `undefined` when the server
+ * serves none there: the path is malformed, leaves `root`, names a dot file or
+ * directory, or is not a regular file. Decoded first, as the browser encoded
+ * it, so the file checked is the file served.
+ */
+export function publicBuildFile(root, pathname) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return undefined;
+  }
+  const base = resolve(root);
+  const file = resolve(base, `.${decoded}`);
+  // Native separator: `resolve` answers with backslashes on Windows.
+  if (!file.startsWith(`${base}${sep}`)) return undefined;
+  if (!isPublicBuildPath(relative(base, file))) return undefined;
+  if (!existsSync(file) || !statSync(file).isFile()) return undefined;
+  return file;
+}

package/templates/vue/server/content.mjs

@@ -6,23 +6,63 @@ import {
   constants as zlibConstants,
 } from "node:zlib";
 
-const MINIMUM_COMPRESSION_BYTES = 1_024;
+/** Below this size, compressing saves less than it costs. */
+export const MINIMUM_COMPRESSION_BYTES = 1_024;
 const DYNAMIC_BROTLI_QUALITY = 4;
 
-function responseEncoder(request, content) {
-  if (Buffer.byteLength(content) < MINIMUM_COMPRESSION_BYTES) return undefined;
+/**
+ * A compressor for a body generated or relayed now, in the encoding the client
+ * accepts (Brotli first), or `undefined` when it accepts neither. `streaming`
+ * flushes what each write gives at once, for a body written over time: the
+ * client gets each part when it is written, not when a block fills.
+ */
+export function acceptedEncoder(request, { streaming = false } = {}) {
   const accepted = request.headers["accept-encoding"] ?? "";
-  if (accepted.includes("br"))
+  const qualities = new Map();
+  for (const entry of accepted.split(",")) {
+    const [token, ...parameters] = entry.trim().toLowerCase().split(";");
+    if (!token) continue;
+    const parameter = parameters.find((value) => /^\s*q\s*=/.test(value));
+    const value = parameter?.split("=")[1].trim();
+    const quality =
+      value === undefined
+        ? 1
+        : /^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/.test(value)
+          ? Number(value)
+          : 0;
+    qualities.set(
+      token.trim(),
+      Math.min(qualities.get(token.trim()) ?? 1, quality),
+    );
+  }
+  const quality = (token) => qualities.get(token) ?? qualities.get("*") ?? 0;
+  const br = quality("br");
+  const gzip = quality("gzip");
+  // Implicit identity is a fallback, not a preference over compression.
+  const identity = qualities.get("identity") ?? 0;
+  if (identity > Math.max(br, gzip)) return undefined;
+  if (br > 0 && br >= gzip)
     return {
       encoding: "br",
       stream: createBrotliCompress({
+        ...(streaming && { flush: zlibConstants.BROTLI_OPERATION_FLUSH }),
         params: {
           [zlibConstants.BROTLI_PARAM_QUALITY]: DYNAMIC_BROTLI_QUALITY,
         },
       }),
     };
-  if (accepted.includes("gzip"))
-    return { encoding: "gzip", stream: createGzip() };
+  if (gzip > 0)
+    return {
+      encoding: "gzip",
+      stream: createGzip(
+        streaming ? { flush: zlibConstants.Z_SYNC_FLUSH } : {},
+      ),
+    };
+}
+
+function responseEncoder(request, content) {
+  if (Buffer.byteLength(content) < MINIMUM_COMPRESSION_BYTES) return undefined;
+  return acceptedEncoder(request);
 }
 
 /** Send a generated body, compressed when the client accepts it. */

package/templates/vue/server/email-bundle-watch.mjs

@@ -4,7 +4,9 @@
 // dev server does and follows every template edit the layer watchers mirror
 // into the workspace. It lives in its own process so its builds never hold the
 // dev server's event loop, and it reports each build over IPC so the server
-// renders from a finished bundle only.
+// renders from a finished bundle only. A build empties `dist/server` first, so
+// it asks the server before it starts and waits for the go-ahead, which the
+// server gives once no render reads the previous bundle any more.
 
 import { fileURLToPath } from "node:url";
 import { build } from "vite";
@@ -15,17 +17,36 @@ const PROJECT_ROOT = fileURLToPath(new URL("..", import.meta.url));
 // server ended, there is nobody left to build for.
 process.on("disconnect", () => process.exit(0));
 
+let startBuild;
+process.on("message", (message) => {
+  if (message?.state !== "build") return;
+  startBuild?.();
+  startBuild = undefined;
+});
+
+/** Holds each build until the server lets it replace the bundle. */
+const serverHandoff = {
+  name: "dms-email-bundle-handoff",
+  buildStart() {
+    if (!process.send) return;
+    return new Promise((start) => {
+      startBuild = start;
+      process.send({ state: "building" });
+    });
+  },
+};
+
 const watcher = await build({
   root: PROJECT_ROOT,
   configFile: fileURLToPath(
     new URL("../vite.email.config.ts", import.meta.url),
   ),
   logLevel: "warn",
+  plugins: [serverHandoff],
   build: { watch: {} },
 });
 
 watcher.on("event", (event) => {
-  if (event.code === "START") process.send?.({ state: "building" });
-  else if (event.code === "END") process.send?.({ state: "ready" });
+  if (event.code === "END") process.send?.({ state: "ready" });
   else if (event.code === "ERROR") process.send?.({ state: "failed" });
 });

package/templates/vue/server/email.mjs

@@ -10,8 +10,7 @@ const EMAIL_BUNDLE_WATCH_URL = new URL(
   "./email-bundle-watch.mjs",
   import.meta.url,
 );
-// A render waits this long for a build in progress, then tries the bundle
-// already on disk rather than holding the backend's request indefinitely.
+// Bound the request's wait, but never read a bundle being replaced.
 const EMAIL_BUILD_WAIT_MS = 60_000;
 
 // Settled whenever no email build is running. The version changes with each
@@ -20,6 +19,11 @@ const EMAIL_BUILD_WAIT_MS = 60_000;
 let emailBuild = Promise.resolve();
 let settleEmailBuild;
 let emailBundleVersion = 0;
+// A build empties dist/server before it writes the new bundle, so it never
+// starts while a render still imports from the previous one: the builder asks
+// first, and gets the go-ahead once the renders in progress have finished.
+let rendersInProgress = 0;
+let startPendingBuild;
 
 function emailBuildStarted() {
   if (settleEmailBuild) return;
@@ -30,10 +34,24 @@ function emailBuildStarted() {
 
 function emailBuildSettled() {
   emailBundleVersion += 1;
+  startPendingBuild = undefined;
   settleEmailBuild?.();
   settleEmailBuild = undefined;
 }
 
+function startBuildOnceRendersFinish(start) {
+  if (rendersInProgress) startPendingBuild = start;
+  else start();
+}
+
+function renderFinished() {
+  rendersInProgress -= 1;
+  if (rendersInProgress || !startPendingBuild) return;
+  const start = startPendingBuild;
+  startPendingBuild = undefined;
+  start();
+}
+
 /**
  * Build the email bundle now and again on every template change, for
  * development: only the production build otherwise produces it. The builder
@@ -51,8 +69,14 @@ export function watchEmailBundle() {
     // Not permitted on this platform; the build only runs at normal priority.
   }
   builder.on("message", (message) => {
-    if (message?.state === "building") emailBuildStarted();
-    else emailBuildSettled();
+    if (message?.state !== "building") {
+      emailBuildSettled();
+      return;
+    }
+    emailBuildStarted();
+    startBuildOnceRendersFinish(() => {
+      if (builder.connected) builder.send({ state: "build" });
+    });
   });
   builder.on("exit", (code) => {
     emailBuildSettled();
@@ -61,15 +85,25 @@ export function watchEmailBundle() {
   return builder;
 }
 
-async function loadEmailRenderer() {
-  let timer;
-  await Promise.race([
-    emailBuild,
-    new Promise((settle) => {
-      timer = setTimeout(settle, EMAIL_BUILD_WAIT_MS);
-    }),
-  ]);
-  clearTimeout(timer);
+async function waitForEmailBuild() {
+  const deadline = Date.now() + EMAIL_BUILD_WAIT_MS;
+  // Another build may start while a render waits for the previous one.
+  while (settleEmailBuild && Date.now() < deadline) {
+    let timer;
+    await Promise.race([
+      emailBuild,
+      new Promise((settle) => {
+        timer = setTimeout(settle, deadline - Date.now());
+      }),
+    ]);
+    clearTimeout(timer);
+  }
+  if (settleEmailBuild) {
+    throw new Error("Timed out waiting for the email bundle build");
+  }
+}
+
+function loadEmailRenderer() {
   const url = new URL(EMAIL_RENDERER_URL);
   if (emailBundleVersion) url.searchParams.set("v", emailBundleVersion);
   return import(url.href);
@@ -84,6 +118,15 @@ async function loadEmailRenderer() {
  * @param options `locale`, the language to render in
  */
 export async function renderEmailTemplate(template, props, options = {}) {
-  const { renderEmail } = await loadEmailRenderer();
-  return renderEmail(template, props, options);
+  await waitForEmailBuild();
+  // Counted from here, with no await in between, so a build the builder asks
+  // for now waits for this render, which imports templates and reads catalogs
+  // from the bundle until it ends.
+  rendersInProgress += 1;
+  try {
+    const { renderEmail } = await loadEmailRenderer();
+    return await renderEmail(template, props, options);
+  } finally {
+    renderFinished();
+  }
 }

package/templates/vue/server/proxy-compression.mjs

@@ -0,0 +1,101 @@
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { acceptedEncoder, MINIMUM_COMPRESSION_BYTES } from "./content.mjs";
+import { writeProxyHeaders } from "./proxy-headers.mjs";
+
+/**
+ * Asks the backend for its answer uncompressed. fetch decodes a compressed
+ * answer but keeps its Content-Encoding and Content-Length, which then
+ * described bytes the client never got: the proxy compresses for the client
+ * itself (see proxyEncoder).
+ */
+export const PLAIN_ANSWER_HEADERS = { "accept-encoding": "identity" };
+
+// Text the backend sends uncompressed: JSON above all, which the antelope API
+// module never compresses. An event stream is left as it is: its events are
+// small and many, and proxies between here and the browser expect it plain.
+const COMPRESSIBLE_TYPE =
+  /^(?:text\/(?!event-stream)[\w.+-]+|application\/(?:[\w.-]+\+)?(?:json|xml|javascript|ecmascript)|image\/svg\+xml)\s*(?:;|$)/i;
+// Statuses that carry no body to compress.
+const BODILESS_STATUSES = new Set([204, 205, 304]);
+
+/** Whether the backend answer is one to compress on its way to the client. */
+function isCompressible(request, upstream) {
+  if (request.method === "HEAD" || !upstream.body) return false;
+  if (BODILESS_STATUSES.has(upstream.status)) return false;
+  const headers = upstream.headers;
+  // Already encoded, or a range of the bytes: compressing would change what
+  // the encoding or the range describes.
+  const encoding = headers.get("content-encoding");
+  if (encoding && encoding.toLowerCase() !== "identity") return false;
+  if (upstream.status === 206 || headers.has("content-range")) return false;
+  if (
+    /(?:^|,)\s*no-transform\s*(?:,|$)/i.test(headers.get("cache-control") ?? "")
+  )
+    return false;
+  if (!COMPRESSIBLE_TYPE.test(headers.get("content-type") ?? "")) return false;
+  const length = headers.get("content-length");
+  return length === null || Number(length) >= MINIMUM_COMPRESSION_BYTES;
+}
+
+/**
+ * The compressor for a backend answer the proxy relays, in the encoding the
+ * client accepts, or `undefined` to relay it as it came.
+ */
+function proxyEncoder(request, upstream) {
+  // Streaming: an answer of unknown length (chunked JSON, streamed text)
+  // reaches the client part by part, as the backend writes it.
+  return isCompressible(request, upstream)
+    ? acceptedEncoder(request, { streaming: true })
+    : undefined;
+}
+
+/** Relays a backend answer to the client, compressed when it should be. */
+export async function relayAnswer(
+  request,
+  response,
+  upstream,
+  { fetched = false } = {},
+) {
+  // Only native fetch bodies are decoded. Synthetic/opaque responses may
+  // still contain the encoded bytes, and unknown coding chains stay opaque.
+  const codings = (upstream.headers.get("content-encoding") ?? "")
+    .toLowerCase()
+    .split(",")
+    .map((coding) => coding.trim());
+  if (
+    fetched &&
+    request.method !== "HEAD" &&
+    upstream.body &&
+    !BODILESS_STATUSES.has(upstream.status) &&
+    codings.every((coding) =>
+      ["gzip", "x-gzip", "deflate", "br"].includes(coding),
+    )
+  ) {
+    // A decoded partial representation cannot retain the encoded byte offsets.
+    // Do not manufacture a complete 200 response from a partial 206 either.
+    if (upstream.status === 206 || upstream.headers.has("content-range")) {
+      await upstream.body.cancel();
+      response.writeHead(502);
+      response.end();
+      return;
+    }
+    const headers = new Headers(upstream.headers);
+    headers.delete("content-encoding");
+    headers.delete("content-length");
+    const etag = headers.get("etag");
+    if (etag && !etag.startsWith("W/")) headers.set("etag", `W/${etag}`);
+    upstream = { status: upstream.status, headers, body: upstream.body };
+  }
+  const encoder = proxyEncoder(request, upstream);
+  writeProxyHeaders(
+    response,
+    upstream,
+    encoder?.encoding,
+    isCompressible(request, upstream),
+  );
+  if (!upstream.body || request.method === "HEAD") return response.end();
+  const body = Readable.fromWeb(upstream.body);
+  if (encoder) await pipeline(body, encoder.stream, response);
+  else await pipeline(body, response);
+}