@antelopejs/dms-frontend 0.9.2 → 0.10.0

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

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 import { allowedEstablishEndpoints } from "./auth/establish-endpoints.mjs";
 import { serverAuth } from "./auth-hooks.mjs";
 import { answerModuleRoute } from "./module-event.mjs";
+import { isNonNullObject, isString } from "./type-guards.mjs";
 import {
   matchModuleRoute,
   mayHaveModuleRoute,
@@ -16,7 +17,30 @@ import {
 } from "./public-endpoints.mjs";
 import { reachesBackend } from "./request-routing.mjs";
 
+import { frontendRegistryOf, serverOptionsOf } from "./generated-files.mjs";
 import { publicOptionsOf } from "./public-options.mjs";
+/** @typedef {import("./module-route-types.mjs").ServerModuleDeclaration} ServerModuleDeclaration */
+/**
+ * What a handler of a module reads besides its request.
+ *
+ * @typedef {object} ModuleContext
+ * @property {{ id: string, options: unknown, privateOptions: unknown }} module
+ * @property {{ authEstablishEndpoints: readonly string[] }} app
+ * @property {string | undefined} authOwner The module that owns sign-in
+ */
+/**
+ * A deployment's data, which the server hands to a set of server modules.
+ *
+ * @typedef {object} Deployment
+ * @property {Record<string, unknown>} [publicOptions] Each module's public options by id
+ * @property {Record<string, unknown>} [privateOptions] Each module's private options by id
+ * @property {() => readonly string[]} [authEstablishEndpoints]
+ * @property {import("./public-endpoints.mjs").PublicEndpoint[]} [publicEndpoints]
+ * @property {import("./backend-proxies.mjs").ManifestProxy[]} [backendProxies]
+ * @property {(message: string) => void} warn
+ */
+/** @typedef {ReturnType<typeof createServerModules>} ServerModules */
+
 const WORKSPACE_ROOT = new URL("../", import.meta.url);
 const SOURCE_LOADER = "/server-modules.generated.ts";
 const BUILT_LOADER = new URL(
@@ -32,11 +56,20 @@ const SERVER_OPTIONS_FILE = new URL(
   WORKSPACE_ROOT,
 );
 
+/** @type {Promise<ServerModuleDeclaration[]> | undefined} */
 let builtDeclarations;
+/** @type {ServerModuleDeclaration[]} */
 let lastDeclarations = [];
+/** @type {string | undefined} */
 let lastLoadError;
+/** @type {WeakMap<ServerModuleDeclaration[], ServerModules>} */
 const resolved = new WeakMap();
 
+/**
+ * @param {URL} url
+ * @param {unknown} fallback
+ * @returns {unknown} The file's JSON, the fallback when it cannot be read
+ */
 function readJsonFile(url, fallback) {
   try {
     return JSON.parse(readFileSync(url, "utf8"));
@@ -47,18 +80,29 @@ function readJsonFile(url, fallback) {
 
 const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
-/** The object holding `path`'s last key, when every key up to it is own. */
+/**
+ * The object holding `path`'s last key, when every key up to it is own.
+ *
+ * @param {Record<string, unknown>} target
+ * @param {string[]} path
+ */
 function holderOf(target, path) {
   let node = target;
   for (const key of path.slice(0, -1)) {
     if (UNSAFE_KEYS.has(key) || !Object.hasOwn(node, key)) return undefined;
     node = node[key];
-    if (typeof node !== "object" || node === null) return undefined;
+    if (!isNonNullObject(node)) return undefined;
   }
   return UNSAFE_KEYS.has(path.at(-1)) ? undefined : node;
 }
 
-/** Sets `value` at `path` when the object holding it exists but lacks it. */
+/**
+ * Sets `value` at `path` when the object holding it exists but lacks it.
+ *
+ * @param {Record<string, unknown>} target
+ * @param {string[]} path
+ * @param {string} value
+ */
 function fillPath(target, path, value) {
   const holder = holderOf(target, path);
   const key = path.at(-1);
@@ -66,7 +110,13 @@ function fillPath(target, path, value) {
     holder[key] = value;
 }
 
-/** Sets `value` at `path` only where the build left an empty string. */
+/**
+ * Sets `value` at `path` only where the build left an empty string.
+ *
+ * @param {Record<string, unknown>} target
+ * @param {string[]} path
+ * @param {string} value
+ */
 function fillEmptied(target, path, value) {
   const holder = holderOf(target, path);
   const key = path.at(-1);
@@ -79,10 +129,10 @@ function fillEmptied(target, path, value) {
  * the environment variable of a secret (`DMS_HTML_RENDER_SECRET`,
  * `DMS_OAUTH_RELAY_SECRET`) only fills in a section that carries none.
  *
- * @param modules The private options by module id, as the manifest published
+ * @param {Record<string, Record<string, unknown>>} modules The private options by module id, as the manifest published
  *   them
- * @param environment The variables by the path of the secret they stand for
- * @param env The process environment
+ * @param {Record<string, string[]>} environment The variables by the path of the secret they stand for
+ * @param {NodeJS.ProcessEnv} env The process environment
  */
 export function privateOptionsWithFallbacks(modules, environment, env) {
   for (const options of Object.values(modules))
@@ -91,10 +141,16 @@ export function privateOptionsWithFallbacks(modules, environment, env) {
   return modules;
 }
 
-/** Each string leaf of `value`, array items included, with its path. */
+/**
+ * Each string leaf of `value`, array items included, with its path.
+ *
+ * @param {unknown} value
+ * @param {string[]} [path]
+ * @returns {Generator<[string[], string]>}
+ */
 function* stringLeaves(value, path = []) {
-  if (typeof value === "string") yield [path, value];
-  else if (typeof value === "object" && value !== null)
+  if (isString(value)) yield [path, value];
+  else if (isNonNullObject(value))
     for (const [key, child] of Object.entries(value))
       yield* stringLeaves(child, [...path, key]);
 }
@@ -107,19 +163,20 @@ function* stringLeaves(value, path = []) {
  * a value the build emptied is filled, array items included: a value the
  * manifest carries wins, and no option or section is added or replaced.
  *
- * @param modules The private options by module id
- * @param json The variable's value; nothing is filled when unset
- * @param warn Reports a value that is not a JSON object, never its content
+ * @param {Record<string, Record<string, unknown>>} modules The private options by module id
+ * @param {string | undefined} json The variable's value; nothing is filled when unset
+ * @param {(message: string) => void} warn Reports a value that is not a JSON object, never its content
  */
 export function privateOptionsFromJson(modules, json, warn) {
   if (!json) return modules;
+  /** @type {unknown} */
   let given;
   try {
     given = JSON.parse(json);
   } catch {
     given = undefined;
   }
-  if (typeof given !== "object" || given === null || Array.isArray(given)) {
+  if (!isNonNullObject(given) || Array.isArray(given)) {
     warn("DMS_PRIVATE_OPTIONS is not a JSON object of options by module id");
     return modules;
   }
@@ -131,10 +188,10 @@ export function privateOptionsFromJson(modules, json, warn) {
   return modules;
 }
 
+/** @param {NodeJS.ProcessEnv} [env] */
 function readPrivateOptions(env = process.env) {
-  const { modules = {}, environment = {} } = readJsonFile(
-    SERVER_OPTIONS_FILE,
-    {},
+  const { modules, environment } = serverOptionsOf(
+    readJsonFile(SERVER_OPTIONS_FILE, {}),
   );
   return privateOptionsFromJson(
     privateOptionsWithFallbacks(modules, environment, env),
@@ -144,14 +201,22 @@ function readPrivateOptions(env = process.env) {
 }
 
 function readPublicOptions() {
-  return publicOptionsOf(readJsonFile(REGISTRY_FILE, { modules: [] }));
+  return publicOptionsOf(
+    frontendRegistryOf(readJsonFile(REGISTRY_FILE, { modules: [] })),
+  );
 }
 
+/**
+ * @param {import("vite").ViteDevServer | undefined} devServer
+ * @returns {Promise<ServerModuleDeclaration[]>}
+ */
 async function loadDeclarations(devServer) {
   if (devServer)
+    // oxlint-disable-next-line typescript/no-unsafe-return -- `ssrLoadModule` types every module `Record<string, any>`; the loader is the generated `server-modules.generated.ts`, which exports `serverModules`.
     return (await devServer.ssrLoadModule(SOURCE_LOADER)).serverModules;
   if (!existsSync(fileURLToPath(BUILT_LOADER))) return [];
   builtDeclarations ??= import(BUILT_LOADER.href).then(
+    // oxlint-disable-next-line typescript/no-unsafe-return -- the build of that same generated module is imported by a URL computed at run time, so it is untyped.
     (loaded) => loaded.serverModules,
   );
   return builtDeclarations;
@@ -161,6 +226,8 @@ async function loadDeclarations(devServer) {
  * The declarations to serve. A module entry that fails to load in development
  * (a syntax error being typed) is reported once, and the last routes that
  * loaded keep answering meanwhile.
+ *
+ * @param {import("vite").ViteDevServer | undefined} devServer
  */
 async function currentDeclarations(devServer) {
   try {
@@ -181,8 +248,8 @@ async function currentDeclarations(devServer) {
  *
  * `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,
+ * @param {readonly ServerModuleDeclaration[]} declarations `{ id, priority, setup }` per module with a dms.server.ts
+ * @param {Deployment} deployment `{ publicOptions, privateOptions, authEstablishEndpoints,
  *   publicEndpoints, backendProxies, warn }`: each module's options by id,
  *   the session-opening endpoints as a function (the environment can change
  *   them), the public endpoints, the backend proxies the manifest declares
@@ -198,7 +265,7 @@ export function createServerModules(declarations, deployment) {
     deployment.publicEndpoints ?? [],
     deployment.backendProxies ?? [],
   );
-  const context = (id) => ({
+  const context = (/** @type {string} */ id) => ({
     module: {
       id,
       options: deployment.publicOptions?.[id],
@@ -216,7 +283,11 @@ export function createServerModules(declarations, deployment) {
   };
 }
 
-/** Resolved once per set of declarations: in development, once per edit. */
+/**
+ * Resolved once per set of declarations: in development, once per edit.
+ *
+ * @param {ServerModuleDeclaration[]} declarations
+ */
 function serverModules(declarations) {
   let modules = resolved.get(declarations);
   if (!modules) {
@@ -245,7 +316,7 @@ function serverModules(declarations) {
  * 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
+ * @param {import("vite").ViteDevServer | undefined} devServer Vite in development, `undefined` in production
  */
 export async function loadServerModules(devServer) {
   return serverModules(await currentDeclarations(devServer));
@@ -256,10 +327,10 @@ export async function loadServerModules(devServer) {
  * module route serves is the module's for every method: another method is
  * answered `405`.
  *
- * @param request The Node request
- * @param response The Node response
- * @param pathname The request's normalized path
- * @param modules What `loadServerModules` or `createServerModules` returned
+ * @param {import("node:http").IncomingMessage} request The Node request
+ * @param {import("node:http").ServerResponse} response The Node response
+ * @param {string} pathname The request's normalized path
+ * @param {ServerModules} modules What `loadServerModules` or `createServerModules` returned
  * @returns Whether a module route answered
  */
 export async function handleModuleRoute(request, response, pathname, modules) {

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

@@ -2,10 +2,16 @@ import { createServer } from "node:http";
 import { RequestBodyError, UpstreamError } from "./auth/backend.mjs";
 import { UNEXPECTED_ERROR_BODY } from "./backend-response.mjs";
 import { createServerModules, handleModuleRoute } from "./module-server.mjs";
+import { failureStatus } from "./request-failure.mjs";
 
-/** What the frontend server answers an API request whose handler failed. */
+/**
+ * What the frontend server answers an API request whose handler failed.
+ *
+ * @param {unknown} error
+ * @param {import("node:http").ServerResponse} response
+ */
 function writeFailure(error, response) {
-  const status = Number.isInteger(error?.status) ? error.status : 502;
+  const status = failureStatus(error);
   const body =
     error instanceof UpstreamError || error instanceof RequestBodyError
       ? { message: error.message }
@@ -26,9 +32,9 @@ function writeFailure(error, response) {
  * `DMS_API_BASE_URL` and `DMS_SESSION_SECRET` from the environment, as in
  * production.
  *
- * @param declarations `{ id, priority?, setup }` per module, `setup` being
+ * @param {readonly import("./module-server.mjs").ServerModuleDeclaration[]} declarations `{ id, priority?, setup }` per module, `setup` being
  *   the default export of its `dms.server.ts`
- * @param deployment `{ publicOptions?, privateOptions?, authEstablishEndpoints?,
+ * @param {Omit<import("./module-server.mjs").Deployment, "warn" | "authEstablishEndpoints"> & { authEstablishEndpoints?: readonly string[] }} [deployment] `{ publicOptions?, privateOptions?, authEstablishEndpoints?,
  *   publicEndpoints?, backendProxies? }`, options by module id, and the
  *   manifest's backend proxies (`{ module, path, auth? }`), which decide
  *   the backend redirects relayed as frontend paths. The private options are
@@ -37,6 +43,7 @@ function writeFailure(error, response) {
  * @returns `{ url, modules, warnings, close() }`
  */
 export async function serveModuleRoutes(declarations, deployment = {}) {
+  /** @type {string[]} */
   const warnings = [];
   const endpoints = deployment.authEstablishEndpoints ?? [];
   const modules = createServerModules(declarations, {
@@ -50,7 +57,9 @@ export async function serveModuleRoutes(declarations, deployment = {}) {
       .then((answered) => {
         if (!answered) response.writeHead(404).end();
       })
-      .catch((error) => writeFailure(error, response));
+      .catch(
+        /** @param {unknown} error */ (error) => writeFailure(error, response),
+      );
   });
   await new Promise((settle) => server.listen(0, "127.0.0.1", settle));
   const { port } = server.address();

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

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
 import { readSession } from "./auth/session.mjs";
+import { GENERIC_ERROR_MESSAGE, UpstreamError } from "./auth/backend.mjs";
 import { BackendResponseError } from "./backend-response.mjs";
 import { heldOnceProps, requestedProps } from "./inertia.mjs";
+import { isObjectLike, isRecord } from "./type-guards.mjs";
 
 export const SHARED_PROP = "shared";
 /**
@@ -15,10 +17,58 @@ export const SHARED_PROP_TTL_MS = 5 * 60 * 1000;
 const SITE_LAYOUT_PATH = "/dms/sitelayout";
 const NOT_FOUND = 404;
 
+/**
+ * The props of a page, each only when the request asks for it.
+ *
+ * @typedef {{
+ *   path?: string,
+ *   user?: unknown,
+ *   session?: unknown,
+ *   page?: unknown,
+ *   shared?: unknown
+ * }} PageProps
+ */
+
+/**
+ * What a page request reads of the backend: its JSON for a path (any value;
+ * `loadPage` refuses a page answer that is not an object), and whether the
+ * frontend itself serves a path.
+ *
+ * @typedef {{
+ *   fetchJson: (path: string) => Promise<unknown>,
+ *   isFrontendPage: (pathname: string) => Promise<boolean>
+ * }} PageBackend
+ */
+
+/**
+ * What a page request reads of the auth hooks: where sign-in is, and what a
+ * session shows a page.
+ *
+ * @typedef {{
+ *   signInPath: string,
+ *   view: (session: unknown) => { user?: unknown, session?: unknown }
+ * }} PageAuth
+ */
+
+/**
+ * The route the backend described for the page of `props`, as the backend
+ * sent it: any JSON value, `undefined` when the page has none.
+ *
+ * @param {PageProps} props
+ * @returns {unknown}
+ */
+export function pageRoute(props) {
+  return isObjectLike(props.page) ? props.page.route : undefined;
+}
+
 /**
  * The once-prop key of the site layout: one per account and workspace. A
  * browser holding the layout of another account or workspace, after a sign-in,
  * a sign-out or a switch, holds another key, so it is sent the right one.
+ *
+ * @param {unknown} session The sealed session: any JSON value, since only its
+ *   `accountId` and `activeTenantId` are read, as empty when it holds none
+ * @returns {string}
  */
 export function sharedOnceKey(session) {
   const identity = `${session?.accountId ?? ""}\n${session?.activeTenantId ?? ""}`;
@@ -30,6 +80,10 @@ export function sharedOnceKey(session) {
  * Whether the browser holds this session's layout and no other: a browser
  * that holds another session's key too (a switch back and forth without a
  * full visit) may show that one under `shared`, so it is sent this one.
+ *
+ * @param {Set<string>} held
+ * @param {string} sharedKey
+ * @returns {boolean}
  */
 function holdsOnlyThisLayout(held, sharedKey) {
   if (!held.has(sharedKey)) return false;
@@ -50,9 +104,14 @@ const PAGE_REQUEST_PARAMETERS = new Set(["path", SHARED_PROP]);
  * on), so the layout is resolved for the query the browser shows and the
  * browser does not ask it again. One value per name, the last, as the
  * browser's own page layout request sends it.
+ *
+ * @param {URL} url
+ * @param {boolean} withShared
+ * @returns {string}
  */
 function pagePath(url, withShared) {
   const query = new URLSearchParams({ path: url.pathname });
+  /** @type {Map<string, string>} */
   const pageQuery = new Map();
   for (const [name, value] of url.searchParams) {
     if (!PAGE_REQUEST_PARAMETERS.has(name)) pageQuery.set(name, value);
@@ -62,7 +121,12 @@ function pagePath(url, withShared) {
   return `/dms/page?${query}`;
 }
 
-/** A page only the frontend has: a custom page, with no backend data. */
+/**
+ * A page only the frontend has: a custom page, with no backend data.
+ *
+ * @param {string} pathname
+ * @param {string} signInPath
+ */
 function frontendOnlyPage(pathname, signInPath) {
   return {
     componentName: pathname,
@@ -76,6 +140,13 @@ function frontendOnlyPage(pathname, signInPath) {
   };
 }
 
+/**
+ * @param {URL} url
+ * @param {boolean} withShared
+ * @param {PageBackend} backend
+ * @param {string} signInPath
+ * @returns {Promise<{ page: PageProps["page"], shared: unknown }>}
+ */
 async function loadPage(
   url,
   withShared,
@@ -84,7 +155,10 @@ async function loadPage(
 ) {
   const { pathname } = url;
   try {
-    const { shared, ...page } = await fetchJson(pagePath(url, withShared));
+    const answer = await fetchJson(pagePath(url, withShared));
+    if (!isRecord(answer) || Array.isArray(answer))
+      throw new UpstreamError(502, GENERIC_ERROR_MESSAGE);
+    const { shared, ...page } = answer;
     return { page, shared };
   } catch (error) {
     if (!(error instanceof BackendResponseError) || error.status !== NOT_FOUND)
@@ -101,6 +175,12 @@ async function loadPage(
  * The props of the same page at another query of its path (`url`): the page
  * is read again, since its layout reads the query, and the rest is kept,
  * the site layout included.
+ *
+ * @param {PageProps} props
+ * @param {URL} url
+ * @param {PageBackend} backend
+ * @param {PageAuth} auth
+ * @returns {Promise<PageProps>}
  */
 export async function propsForQuery(props, url, backend, auth) {
   const { page } = await loadPage(url, false, backend, auth.signInPath);
@@ -125,6 +205,14 @@ export async function propsForQuery(props, url, backend, auth) {
  * 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.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {PageBackend} backend
+ * @param {PageAuth} auth
+ * @returns {Promise<{
+ *   props: PageProps,
+ *   onceProps: import("./inertia.mjs").OnceProps | undefined
+ * }>}
  */
 export async function loadPageProps(request, backend, auth) {
   const url = new URL(request.url, "http://frontend.local");
@@ -135,10 +223,12 @@ export async function loadPageProps(request, backend, auth) {
   const sharedKey = sharedOnceKey(sealed);
   const holdsShared = holdsOnlyThisLayout(heldOnceProps(request), sharedKey);
   const withShared = (partial && wants(SHARED_PROP)) || !holdsShared;
+  /** @type {PageProps} */
   const props = {};
   if (wants("path")) props.path = pathname;
   if (wants("user") && (user || partial)) props.user = user ?? null;
   if (wants("session") && (session || partial)) props.session = session ?? null;
+  /** @type {unknown} */
   let shared;
   if (wants("page")) {
     const loaded = await loadPage(url, withShared, backend, auth.signInPath);

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

@@ -0,0 +1,37 @@
+import { readSession } from "./auth/session.mjs";
+import { HOMEPAGE } from "./homepage.mjs";
+import { redirectFrontendVisit } from "./inertia.mjs";
+import { pageRoute } from "./page-props.mjs";
+import { isObjectLike } from "./type-guards.mjs";
+
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+export function redirectToHomepage(request, response, pathname) {
+  if (pathname !== "/" || HOMEPAGE === "/") return false;
+  redirectFrontendVisit(request, response, HOMEPAGE);
+  return true;
+}
+
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {import("./page-props.mjs").PageProps} props
+ * @param {import("./module-server.mjs").ServerModules["serverAuth"]} auth
+ * @returns {boolean}
+ */
+export function redirectSignedOutPrivatePage(request, response, props, auth) {
+  const route = pageRoute(props);
+  if (
+    !isObjectLike(route) ||
+    route.publicAccess === true ||
+    route.hasAccess !== false ||
+    readSession(request)
+  )
+    return false;
+  redirectFrontendVisit(request, response, auth.signInLocation(request.url));
+  return true;
+}

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

@@ -1,5 +1,14 @@
+import { isString } from "./type-guards.mjs";
+
 const SEGMENT = /^[A-Za-z0-9._~-]+$/;
 
+/**
+ * @typedef {object} CompiledPathPattern
+ * @property {string} pattern The pattern as declared
+ * @property {number} specificity Orders patterns from the least to the most specific
+ * @property {(pathname: string) => boolean} test Whether the pattern covers `pathname`
+ */
+
 /**
  * A pattern made usable, or `undefined` when it is malformed.
  *
@@ -9,9 +18,12 @@ const SEGMENT = /^[A-Za-z0-9._~-]+$/;
  * 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.
+ *
+ * @param {unknown} pattern
+ * @returns {CompiledPathPattern | undefined}
  */
 export function compilePathPattern(pattern) {
-  if (typeof pattern !== "string" || !pattern.startsWith("/")) return undefined;
+  if (!isString(pattern) || !pattern.startsWith("/")) return undefined;
   const segments = pattern === "/" ? [] : pattern.slice(1).split("/");
   const deep = segments.at(-1) === "**";
   const literal = deep ? segments.slice(0, -1) : segments;

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

@@ -20,11 +20,22 @@ const COMPRESSIBLE_TYPE =
   /^(?:text\/(?!event-stream)[\w.+-]+|application\/(?:[\w.-]+\+)?(?:json|xml|javascript|ecmascript)|image\/svg\+xml)\s*(?:;|$)/i;
 const BODILESS_STATUSES = new Set([204, 205, 304]);
 
+/**
+ * What the proxy relays of a backend answer: a fetched `Response`, or the
+ * same fields without its content coding.
+ *
+ * @typedef {Pick<Response, "status" | "headers" | "body" | "url">} ProxiedAnswer
+ */
+
 /**
  * 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.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {ProxiedAnswer} upstream
+ * @returns {boolean}
  */
 function isCompressible(request, upstream) {
   if (request.method === "HEAD" || !upstream.body) return false;
@@ -48,6 +59,9 @@ function isCompressible(request, upstream) {
  *
  * Streaming: an answer of unknown length (chunked JSON, streamed text) reaches
  * the client part by part, as the backend writes it.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {ProxiedAnswer} upstream
  */
 function proxyEncoder(request, upstream) {
   return isCompressible(request, upstream)
@@ -64,6 +78,14 @@ function proxyEncoder(request, upstream) {
  *
  * A decoded partial representation cannot retain the encoded byte offsets, and
  * a complete 200 response is not manufactured from a partial 206 either.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {ProxiedAnswer} upstream
+ * @param {{
+ *   fetched?: boolean,
+ *   isProxiedPath?: (pathname: string) => boolean
+ * }} [options]
  */
 export async function relayAnswer(
   request,

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

@@ -15,7 +15,11 @@ const HOP_BY_HOP_HEADERS = [
   "upgrade",
 ];
 
-/** `Accept-Encoding` added to the backend's own `Vary`, once. */
+/**
+ * `Accept-Encoding` added to the backend's own `Vary`, once.
+ *
+ * @param {string | undefined} vary
+ */
 function varyWithEncoding(vary) {
   const names = (vary ?? "")
     .split(",")
@@ -32,6 +36,12 @@ function varyWithEncoding(vary) {
  * known, and a strong validator no longer names these bytes. A `Location` on
  * the backend's origin becomes the same path on the frontend's when
  * `isProxiedPath` says the frontend proxies it (see `relayedLocation`).
+ *
+ * @param {import("node:http").ServerResponse} response
+ * @param {Pick<Response, "status" | "headers" | "url">} upstream
+ * @param {string | undefined} encoding
+ * @param {boolean} [varies]
+ * @param {(pathname: string) => boolean} [isProxiedPath]
  */
 export function writeProxyHeaders(
   response,