@antelopejs/dms-frontend 0.9.1 → 0.9.3

package/templates/vue/server/favicon.mjs

@@ -1,18 +1,19 @@
-// The favicon placeholder of a page whose render declares no icon.
-//
-// A document without any `<link rel="icon">` makes the browser ask for
-// `/favicon.ico`, a request the frontend server would pass on to the backend
-// on every page load. An empty data URL stops it. The template used to carry
-// that placeholder itself, but a module declaring real icons through `useHead`
-// (light and dark, one per `prefers-color-scheme`) then competed with it, and
-// the browser could keep the empty one: it only goes in when the rendered head
-// has no icon of its own.
-
 const FAVICON_PLACEHOLDER = '<link rel="icon" href="data:," />';
 /** A `<link>` whose `rel` holds the `icon` token, `shortcut icon` included. */
 const ICON_LINK = /<link\b[^>]*\srel=(["'])(?:[^"']*\s)?icon(?:\s[^"']*)?\1/i;
 
-/** The rendered head tags, behind the placeholder when they hold no icon. */
+/**
+ * The rendered head tags, behind the placeholder when they hold no icon.
+ *
+ * The favicon placeholder of a page whose render declares no icon. A
+ * document without any `<link rel="icon">` makes the browser ask for
+ * `/favicon.ico`, a request the frontend server would pass on to the backend
+ * on every page load; an empty data URL stops it. It only goes in when the
+ * rendered head has no icon of its own: a module declaring real icons
+ * through `useHead` (light and dark, one per `prefers-color-scheme`)
+ * competed with a placeholder carried by the template, and the browser could
+ * keep the empty one.
+ */
 export function withFaviconPlaceholder(headTags) {
   return ICON_LINK.test(headTags)
     ? headTags

package/templates/vue/server/homepage.mjs

@@ -1,13 +1,3 @@
-// Working out which page a visit to `/` means.
-//
-// The answer lives in the module registry the workspace was materialized with:
-// a module declares `homepage` somewhere in its options, at whatever depth its
-// own configuration shape puts it, and the highest-priority declaration wins —
-// the registry is already sorted. Read once at boot, because the registry is a
-// build artifact and cannot change while the server is up.
-//
-// Split out of server.mjs, whose size the linter caps.
-
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -29,6 +19,14 @@ function findHomepage(options) {
 
 const OPTIONS = publicOptionsOf(REGISTRY);
 
+/**
+ * Works out which page a visit to `/` means. The answer lives in the module
+ * registry the workspace was materialized with: a module declares `homepage`
+ * somewhere in its options, at whatever depth its own configuration shape
+ * puts it, and the highest-priority declaration wins, since the registry is
+ * already sorted. Read once at boot, because the registry is a build
+ * artifact and cannot change while the server is up.
+ */
 export const HOMEPAGE =
   REGISTRY.modules
     .map((module) => findHomepage(OPTIONS[module.id]))

package/templates/vue/server/icons.mjs

@@ -9,20 +9,27 @@ import { writeContent } from "./content.mjs";
 const WORKSPACE_ROOT = fileURLToPath(new URL("..", import.meta.url));
 const JSON_TYPE = "application/json";
 const READ_METHODS = new Set(["GET", "HEAD"]);
-// Iconify's own naming rule, for prefixes and icon names alike. It is also
-// what keeps a request from naming anything but a collection file.
+/**
+ * Iconify's own naming rule, for prefixes and icon names alike. It is also
+ * what keeps a request from naming anything but a collection file.
+ */
 const ICON_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const COLLECTION_FILE = /^([^/]+)\.json$/;
 const ICON_NAME_SEPARATOR = ",";
 const COLLECTION_PACKAGES = join("node_modules", "@iconify-json");
-// An icon's data only changes with the installed collection, which a
-// deployment replaces; a week bounds how long an upgraded icon can lag.
+/**
+ * An icon's data only changes with the installed collection, which a
+ * deployment replaces; a week bounds how long an upgraded icon can lag.
+ */
 const ICON_CACHE_CONTROL =
   "public, max-age=604800, stale-while-revalidate=86400";
 const ERROR_CACHE_CONTROL = "no-store";
 const collections = new Map();
-// By renderer module: a development server evaluates a new one after a layer
-// changes, and each must find the collections loaded before it renders.
+/**
+ * Kept by renderer module: a development server evaluates a new one after a
+ * layer changes, and each must find the collections loaded before it
+ * renders.
+ */
 const rendererCollections = new WeakMap();
 
 function collectionSpecifiers(prefix) {
@@ -32,14 +39,16 @@ function collectionSpecifiers(prefix) {
   ];
 }
 
+/**
+ * The file of an icon collection from the first source installed under its
+ * name; a source not installed is skipped and the next one tried.
+ */
 function resolveCollectionFile(root, prefix) {
   const require = createRequire(join(root, "package.json"));
   for (const specifier of collectionSpecifiers(prefix)) {
     try {
       return require.resolve(specifier);
-    } catch {
-      // Not installed under this name: try the next source.
-    }
+    } catch {}
   }
   return undefined;
 }

package/templates/vue/server/in-place-render.mjs

@@ -1,9 +1,3 @@
-// A page that completes its query as it renders, rendered at that query in
-// the same request rather than answered with a redirect.
-//
-// Lives apart from server.mjs so the file stays under the size the linter
-// allows.
-
 import { ofetch } from "ofetch";
 
 /**
@@ -34,6 +28,9 @@ function reusableReadKey(path, options, headers) {
  * `backendHeaders()` and the read's own. After `reuseCompletedReads()`, a later
  * render of the same request is given a copy of each read a previous render
  * completed instead of reading the backend again.
+ *
+ * A read returns a copy: the render that read it may still change the object it
+ * got. A body that cannot be copied is read again.
  */
 export function serverReads(backendHeaders) {
   const completed = new Map();
@@ -52,8 +49,6 @@ export function serverReads(backendHeaders) {
       headers,
     });
     if (!key) return reading;
-    // A copy: the render that read it may still change the object it got. A
-    // body that cannot be copied is read again.
     return reading.then((data) => {
       try {
         completed.set(key, structuredClone(data));
@@ -89,6 +84,9 @@ function rendersInPlace(request, from, location) {
  * the first render made (`fetch`), instead of being answered with a redirect
  * the browser would follow with a whole new request. The page served then
  * names the URL the document shows, which the browser puts in the address bar.
+ *
+ * A page that completes its query as it renders is rendered at that query in
+ * the same request, rather than answered with a redirect.
  */
 export async function renderInPlace(request, page, fetch, render, propsAt) {
   let rendered = await render(page);

package/templates/vue/server/listen-host.mjs

@@ -1,5 +1,3 @@
-// The address the frontend server listens on.
-
 const LOOPBACK = "127.0.0.1";
 const EVERY_INTERFACE = "0.0.0.0";
 
@@ -10,6 +8,8 @@ const EVERY_INTERFACE = "0.0.0.0";
  * reach. `HOST=0.0.0.0` opens it to them. A production server listens on
  * every interface, as a container expects.
  *
+ * The address the frontend server listens on.
+ *
  * @param env The server's environment
  */
 export function listenHost(env = process.env) {

package/templates/vue/server/module-event.mjs

@@ -1,8 +1,3 @@
-// What a module route handler receives and how its answer is written: the
-// Web-standard request, the session, the module's sealed cookies, the backend,
-// and the defaults every route gets once (same-origin on unsafe methods, a body
-// limit, `no-store`). See `server-module.ts` for the types a module reads.
-
 import { Readable } from "node:stream";
 import { backend, json, RequestBodyError } from "./auth/backend.mjs";
 import {
@@ -165,6 +160,11 @@ function frozenCopy(value) {
 /**
  * The event a handler receives.
  *
+ * What a module route handler receives and how its answer is written: the Web-
+ * standard request, the session, the module's sealed cookies, the backend, and
+ * the defaults every route gets once (same-origin on unsafe methods, a body
+ * limit, `no-store`). See `server-module.ts` for the types a module reads.
+ *
  * @param context `{ request, response, route, params, module, app, view,
  *   authOwner }`, where `module` is `{ id, options, privateOptions }`, `app`
  *   the deployment's read-only data, `view` what a session shows a page and

package/templates/vue/server/module-routes.mjs

@@ -1,8 +1,3 @@
-// The routes frontend modules declare in their `dms.server.ts`: what each
-// declaration is checked against, how conflicts are settled, and which route a
-// request reaches. Pure: the server hands it the declarations it loaded, and
-// `module-event.mjs` runs the handler a request reaches.
-
 import { resolveBackendProxies } from "./backend-proxies.mjs";
 import { compilePathPattern } from "./path-patterns.mjs";
 import { matchPublicEndpoint } from "./public-endpoints.mjs";
@@ -93,6 +88,10 @@ function optionsRejection(options) {
   return undefined;
 }
 
+/**
+ * Two declarations of one path whatever their parameters are named share a
+ * shape.
+ */
 function compilePath(path) {
   const normalized = normalizedPath(path);
   const segments = normalized === "/" ? [] : normalized.slice(1).split("/");
@@ -107,7 +106,6 @@ function compilePath(path) {
     .join("");
   return {
     path: normalized,
-    // Two declarations of one path whatever their parameters are named.
     shape: segments
       .map((segment) => (PARAM_SEGMENT.test(segment) ? ":" : segment))
       .join("/"),
@@ -432,6 +430,11 @@ function resolveRules(modules, warn) {
  * `proxies`: the backend prefixes the modules and the manifest declare, the
  * most specific first (see `backend-proxies.mjs`).
  *
+ * The routes frontend modules declare in their `dms.server.ts`: what each
+ * declaration is checked against, how conflicts are settled, and which route a
+ * request reaches. Pure: the server hands it the declarations it loaded, and
+ * `module-event.mjs` runs the handler a request reaches.
+ *
  * @param declarations `{ id, priority, setup }` per module with a dms.server.ts
  * @param warn Reports a declaration problem
  * @param publicEndpoints The deployment's public endpoints (#108), to report a
@@ -478,13 +481,14 @@ function decodedParams(route, match) {
 /**
  * The route a request reaches, with its parameters, or `undefined`.
  *
+ * A `HEAD` no route declares is the `GET`'s, without its body.
+ *
  * @param routes What `resolveServerDeclarations` returned
  * @param method The request's method
  * @param pathname The request's normalized path, without its query string
  */
 export function matchModuleRoute(routes, method, pathname) {
   const reached = matchMethod(routes, method, pathname);
-  // A `HEAD` no route declares is the `GET`'s, without its body.
   if (reached || method !== "HEAD") return reached;
   return matchMethod(routes, "GET", pathname);
 }

package/templates/vue/server/module-server.mjs

@@ -1,9 +1,3 @@
-// Loads what the frontend modules declare in their `dms.server.ts` and hands
-// a request to the module route it reaches. In development the declarations
-// come from Vite (`ssrLoadModule`), so an edited entry or handler answers on
-// the next request; in production from the bundle `ajs dms build` makes
-// (`dist/server-modules`). A workspace built before the feature has none.
-
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { allowedEstablishEndpoints } from "./auth/establish-endpoints.mjs";
@@ -185,6 +179,8 @@ async function currentDeclarations(devServer) {
 /**
  * A set of server modules, resolved for a deployment.
  *
+ * `authOwner` is the module whose sealed cookies are the `dms_*` ones.
+ *
  * @param declarations `{ id, priority, setup }` per module with a dms.server.ts
  * @param deployment `{ publicOptions, privateOptions, authEstablishEndpoints,
  *   publicEndpoints, backendProxies, warn }`: each module's options by id,
@@ -211,7 +207,6 @@ export function createServerModules(declarations, deployment) {
     app: {
       authEstablishEndpoints: deployment.authEstablishEndpoints?.() ?? [],
     },
-    // The module whose sealed cookies are the `dms_*` ones.
     authOwner: resolution.auth?.id,
   });
   return {
@@ -244,6 +239,12 @@ function serverModules(declarations) {
 /**
  * The server modules of this deployment, resolved.
  *
+ * Loads what the frontend modules declare in their `dms.server.ts` and hands a
+ * request to the module route it reaches. In development the declarations come
+ * from Vite (`ssrLoadModule`), so an edited entry or handler answers on the
+ * next request; in production from the bundle `ajs dms build` makes
+ * (`dist/server-modules`). A workspace built before the feature has none.
+ *
  * @param devServer Vite in development, `undefined` in production
  */
 export async function loadServerModules(devServer) {

package/templates/vue/server/module-testing.mjs

@@ -1,10 +1,3 @@
-// Serves a frontend module's `dms.server.ts` routes the way the frontend
-// server does, for the module's own tests: same router, same event, same
-// cookie jar and the same defaults. Imported from
-// `@antelopejs/dms-frontend/templates/vue/server/module-testing.mjs`; the
-// server reads `DMS_API_BASE_URL` and `DMS_SESSION_SECRET` from the
-// environment, as in production.
-
 import { createServer } from "node:http";
 import { RequestBodyError, UpstreamError } from "./auth/backend.mjs";
 import { UNEXPECTED_ERROR_BODY } from "./backend-response.mjs";
@@ -26,6 +19,13 @@ function writeFailure(error, response) {
  * Starts an HTTP server on a free local port answering the modules' routes,
  * and `404` to anything else.
  *
+ * Serves a frontend module's `dms.server.ts` routes the way the frontend server
+ * does, for the module's own tests: same router, same event, same cookie jar
+ * and the same defaults. Imported from
+ * `@antelopejs/dms-frontend/templates/vue/server/module-testing.mjs`; the server reads
+ * `DMS_API_BASE_URL` and `DMS_SESSION_SECRET` from the environment, as in
+ * production.
+ *
  * @param declarations `{ id, priority?, setup }` per module, `setup` being
  *   the default export of its `dms.server.ts`
  * @param deployment `{ publicOptions?, privateOptions?, authEstablishEndpoints?,

package/templates/vue/server/page-props.mjs

@@ -1,8 +1,3 @@
-// The props of a DMS page visit, and which of them the browser already has.
-//
-// Lives apart from server.mjs so the file stays under the size the linter
-// allows.
-
 import { createHash } from "node:crypto";
 import { readSession } from "./auth/session.mjs";
 import { BackendResponseError } from "./backend-response.mjs";
@@ -43,8 +38,10 @@ function holdsOnlyThisLayout(held, sharedKey) {
   );
 }
 
-// The parameters of the page request itself, which a page query of the same
-// name cannot override.
+/**
+ * The parameters of the page request itself, which a page query of the same
+ * name cannot override.
+ */
 const PAGE_REQUEST_PARAMETERS = new Set(["path", SHARED_PROP]);
 
 /**
@@ -118,6 +115,16 @@ export async function propsForQuery(props, url, backend, auth) {
  * asks for it, and otherwise asks the backend for the page alone. A partial
  * reload gets the props it names, and the layout too when the browser's copy
  * is not this session's.
+ *
+ * The sealed session names the account and workspace, whatever the module
+ * owning sign-in shows a page of it.
+ *
+ * A partial reload merges what it gets into the page on screen: a session that
+ * ended has to be sent as one, not left out.
+ *
+ * The shared layout is declared only when the browser ends up with this
+ * session's layout, sent now or already held: declaring it otherwise would let
+ * a layout of another session pass for this one.
  */
 export async function loadPageProps(request, backend, auth) {
   const url = new URL(request.url, "http://frontend.local");
@@ -125,15 +132,11 @@ export async function loadPageProps(request, backend, auth) {
   const sealed = readSession(request);
   const { user, session } = auth.view(sealed);
   const { partial, wants } = requestedProps(request);
-  // The sealed session names the account and workspace, whatever the module
-  // owning sign-in shows a page of it.
   const sharedKey = sharedOnceKey(sealed);
   const holdsShared = holdsOnlyThisLayout(heldOnceProps(request), sharedKey);
   const withShared = (partial && wants(SHARED_PROP)) || !holdsShared;
   const props = {};
   if (wants("path")) props.path = pathname;
-  // A partial reload merges what it gets into the page on screen: a session
-  // that ended has to be sent as one, not left out.
   if (wants("user") && (user || partial)) props.user = user ?? null;
   if (wants("session") && (session || partial)) props.session = session ?? null;
   let shared;
@@ -145,9 +148,6 @@ export async function loadPageProps(request, backend, auth) {
     shared = await backend.fetchJson(SITE_LAYOUT_PATH);
   }
   if (shared) props[SHARED_PROP] = shared;
-  // Declared only when the browser ends up with this session's layout: sent
-  // now, or already held. Declaring it otherwise would let a layout of
-  // another session pass for this one.
   const onceProps =
     shared || holdsShared
       ? {

package/templates/vue/server/path-patterns.mjs

@@ -1,7 +1,3 @@
-// Page path patterns, as the modules' `dms.server.ts` name them: `/x` is the
-// page itself, `/x/*` one segment below it, `/x/**` the page and everything
-// below it. Nothing else: no prefix match inside a segment, no query string.
-
 const SEGMENT = /^[A-Za-z0-9._~-]+$/;
 
 /**
@@ -9,6 +5,10 @@ const SEGMENT = /^[A-Za-z0-9._~-]+$/;
  *
  * `specificity` orders matching patterns from the least to the most specific:
  * more literal segments first, then a single-segment `*` over `**`.
+ *
+ * Page path patterns, as the modules' `dms.server.ts` name them: `/x` is the
+ * page itself, `/x/*` one segment below it, `/x/**` the page and everything
+ * below it. Nothing else: no prefix match inside a segment, no query string.
  */
 export function compilePathPattern(pattern) {
   if (typeof pattern !== "string" || !pattern.startsWith("/")) return undefined;

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

@@ -10,21 +10,26 @@ import { pipeWebBody } from "./web-body.mjs";
  */
 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.
+/**
+ * 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. */
+/**
+ * Whether the backend answer is one to compress on its way to the client.
+ *
+ * A response already encoded, or a range of the bytes, is not compressed:
+ * compressing would change what the encoding or the range describes.
+ */
 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;
@@ -40,10 +45,11 @@ function isCompressible(request, upstream) {
 /**
  * The compressor for a backend answer the proxy relays, in the encoding the
  * client accepts, or `undefined` to relay it as it came.
+ *
+ * Streaming: an answer of unknown length (chunked JSON, streamed text) reaches
+ * the client part by part, as the backend writes it.
  */
 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;
@@ -52,6 +58,12 @@ function proxyEncoder(request, upstream) {
 /**
  * Relays a backend answer to the client, compressed when it should be.
  * `isProxiedPath` decides which backend `Location` becomes a frontend path.
+ *
+ * Only native fetch bodies are decoded. Synthetic or opaque responses may still
+ * contain the encoded bytes, and unknown coding chains stay opaque.
+ *
+ * A decoded partial representation cannot retain the encoded byte offsets, and
+ * a complete 200 response is not manufactured from a partial 206 either.
  */
 export async function relayAnswer(
   request,
@@ -59,8 +71,6 @@ export async function relayAnswer(
   upstream,
   { fetched = false, isProxiedPath } = {},
 ) {
-  // 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(",")
@@ -74,8 +84,6 @@ export async function relayAnswer(
       ["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);

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

@@ -1,8 +1,10 @@
 import { relayedLocation } from "./proxy-redirects.mjs";
 
-// Hop-by-hop headers describe the backend connection, not the client's one.
-// Forwarded, an explicit `connection: keep-alive` overrode the client's own
-// `Connection: close`, so Node kept the socket open until its idle timeout.
+/**
+ * Hop-by-hop headers describe the backend connection, not the client's one.
+ * Forwarded, an explicit `connection: keep-alive` overrode the client's own
+ * `Connection: close`, so Node kept the socket open until its idle timeout.
+ */
 const HOP_BY_HOP_HEADERS = [
   "connection",
   "keep-alive",

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

@@ -1,8 +1,3 @@
-// A backend redirect is the browser's to follow. Followed server-side, a
-// redirect to another site served that site's page, and set its cookies, on
-// the frontend's origin, and a redirect on the backend lost its Location.
-// The proxy fetches with `redirect: "manual"` and relays the redirect instead.
-
 /** The statuses that send the client to their `Location`. */
 export const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 
@@ -32,6 +27,13 @@ export function isBackendUrl(
  * declared backend proxy) stays an absolute backend URL, which the browser
  * follows to the backend. Another site's location is kept.
  *
+ * A backend redirect is the browser's to follow. Followed server-side, a
+ * redirect to another site served that site's page, and set its cookies, on the
+ * frontend's origin, and a redirect on the backend lost its Location. The proxy
+ * fetches with `redirect: "manual"` and relays the redirect instead.
+ *
+ * `//host` would name another host, so `/.` keeps the location a path.
+ *
  * @param location The backend's `Location`
  * @param fetchedUrl The backend URL the answer came from
  * @param isProxiedPath `(pathname) => boolean`, whether the frontend server
@@ -51,7 +53,6 @@ export function relayedLocation(
   if (target.origin !== originOf(fetchedUrl)) return location;
   if (!isProxiedPath(target.pathname)) return target.href;
   const path = `${target.pathname}${target.search}${target.hash}`;
-  // `//host` would name another host: `/.` keeps it a path.
   return path.startsWith("//") ? `/.${path}` : path;
 }
 

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

@@ -1,17 +1,15 @@
-// Large transfers through the proxy, a file upload above all. The request
-// body is streamed to the backend, never buffered, and held to the
-// `maxBodyBytes` of the proxy it reached: a declared Content-Length over the
-// limit is refused before a byte is passed on, a chunked body is cut off as
-// soon as it goes over.
-
 const PAYLOAD_TOO_LARGE = 413;
 const TOO_LARGE_BODY = JSON.stringify({ message: "Payload Too Large" });
-// The refused body is never passed on: the iteration stops where it went
-// over, and the request stream stays open for the lingering close below.
+/**
+ * The refused body is never passed on: the iteration stops where it went
+ * over, and the request stream stays open for the lingering close below.
+ */
 const BODY_ITERATION = { destroyOnReturn: false };
-// How long a refused body is read and dropped before the connection closes
-// anyway: long enough for a client to finish sending what was in flight,
-// short enough to bound what a refused client can make the server read.
+/**
+ * How long a refused body is read and dropped before the connection closes
+ * anyway: long enough for a client to finish sending what was in flight,
+ * short enough to bound what a refused client can make the server read.
+ */
 const LINGER_MS = 5_000;
 
 const BODILESS_METHODS = new Set(["GET", "HEAD"]);
@@ -92,6 +90,12 @@ function refuseTooLargeBody(request, response) {
 /**
  * Sends a proxied request, its body held to `maxBodyBytes`.
  *
+ * Large transfers through the proxy, a file upload above all. The request body
+ * is streamed to the backend, never buffered, and held to the `maxBodyBytes` of
+ * the proxy it reached: a declared Content-Length over the limit is refused
+ * before a byte is passed on, a chunked body is cut off as soon as it goes
+ * over.
+ *
  * @param send `(body) => Promise<Response>`, the backend request with the
  *   body to stream: none for a GET or a HEAD, the request itself, or its
  *   bytes cut off past the limit