@antelopejs/dms-frontend 0.9.2 → 0.10.0

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

@@ -1,6 +1,10 @@
 /** The statuses that send the client to their `Location`. */
 export const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 
+/**
+ * @param {string | URL | undefined} url
+ * @returns {string | undefined}
+ */
 function originOf(url) {
   try {
     return new URL(url).origin;
@@ -9,7 +13,13 @@ function originOf(url) {
   }
 }
 
-/** Whether `url` is on the backend's origin. */
+/**
+ * Whether `url` is on the backend's origin.
+ *
+ * @param {string} url
+ * @param {string} [backendBaseUrl]
+ * @returns {boolean}
+ */
 export function isBackendUrl(
   url,
   backendBaseUrl = process.env.DMS_API_BASE_URL,
@@ -34,16 +44,18 @@ export function isBackendUrl(
  *
  * `//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
- *   sends that path to the backend
+ * @param {string} location The backend's `Location`
+ * @param {string | URL} fetchedUrl The backend URL the answer came from
+ * @param {(pathname: string) => boolean} [isProxiedPath] Whether the frontend
+ *   server sends that path to the backend
+ * @returns {string}
  */
 export function relayedLocation(
   location,
   fetchedUrl,
   isProxiedPath = () => false,
 ) {
+  /** @type {URL} */
   let target;
   try {
     target = new URL(location, fetchedUrl);
@@ -60,6 +72,9 @@ export function relayedLocation(
  * The cookies of a `Response` a module route returns. A fetch that followed a
  * redirect to another site would set that site's cookies on the frontend's
  * origin: those are dropped.
+ *
+ * @param {Response} answer
+ * @returns {string[]}
  */
 export function relayableCookies(answer) {
   if (answer.redirected && !isBackendUrl(answer.url)) return [];

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

@@ -0,0 +1,57 @@
+import { backendHeaders } from "./backend-request.mjs";
+import { PLAIN_ANSWER_HEADERS, relayAnswer } from "./proxy-compression.mjs";
+import { sendWithinLimit } from "./proxy-transfers.mjs";
+import { proxyAccess, refuseCrossOrigin } from "./public-endpoints.mjs";
+import { backendUrl } from "./request-target.mjs";
+
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/**
+ * Sends a request to the backend through the proxy it reached.
+ * `isProxiedPath` says which backend paths a relayed `Location` may name on
+ * the frontend's origin.
+ *
+ * A client that left while the request was routed closed the response already,
+ * and would never abort the request below.
+ *
+ * Cancelling the body alone misses a client that leaves before the backend
+ * answers: its stream, an SSE feed above all, then stayed open for good.
+ *
+ * A backend redirect is the browser's to follow: Media sends a file's link to
+ * the storage's signed URL, on the public origin the server itself may not
+ * reach, which turned every download into a 502.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {import("./backend-proxies.mjs").BackendProxy} backendProxy
+ * @param {(path: string) => boolean} isProxiedPath
+ * @returns {Promise<true | undefined>}
+ */
+export async function proxy(request, response, backendProxy, isProxiedPath) {
+  const access = proxyAccess(request, SAFE_METHODS, backendProxy);
+  if (access.isRefused) {
+    refuseCrossOrigin(response);
+    return true;
+  }
+  if (response.closed) return;
+  const abandoned = new AbortController();
+  response.once("close", () => abandoned.abort());
+  const init = {
+    signal: abandoned.signal,
+    method: request.method,
+    headers: { ...backendHeaders(request, access), ...PLAIN_ANSWER_HEADERS },
+    duplex: "half",
+    redirect: "manual",
+  };
+  const upstream = await sendWithinLimit(
+    request,
+    response,
+    backendProxy.maxBodyBytes,
+    (body) => fetch(backendUrl(request.url), { ...init, body }),
+  );
+  if (!upstream) return true;
+  await relayAnswer(request, response, upstream, {
+    fetched: true,
+    isProxiedPath,
+  });
+}

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

@@ -26,6 +26,11 @@ export const SERVER_OPTIONS = Object.freeze({
 
 class BodyTooLargeError extends Error {}
 
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {number} maxBodyBytes
+ * @returns {AsyncGenerator<Buffer>}
+ */
 async function* limitedChunks(request, maxBodyBytes) {
   let received = 0;
   for await (const chunk of request.iterator(BODY_ITERATION)) {
@@ -35,6 +40,10 @@ async function* limitedChunks(request, maxBodyBytes) {
   }
 }
 
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {number | undefined} maxBodyBytes
+ */
 function requestBody(request, maxBodyBytes) {
   if (BODILESS_METHODS.has(request.method)) return undefined;
   return maxBodyBytes === undefined
@@ -42,6 +51,11 @@ function requestBody(request, maxBodyBytes) {
     : limitedChunks(request, maxBodyBytes);
 }
 
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {number | undefined} maxBodyBytes
+ * @returns {boolean}
+ */
 function declaresTooLargeBody(request, maxBodyBytes) {
   return (
     maxBodyBytes !== undefined &&
@@ -49,6 +63,10 @@ function declaresTooLargeBody(request, maxBodyBytes) {
   );
 }
 
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
 function isBodyTooLarge(error) {
   return (
     error instanceof BodyTooLargeError ||
@@ -65,6 +83,9 @@ function isBodyTooLarge(error) {
  * the browser's upload failing without a reason. The rest of the body is read
  * and dropped instead (RFC 9112, section 9.6, "tear-down"), for `LINGER_MS`
  * at most; the response ends with it and the connection then closes cleanly.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
  */
 function refuseTooLargeBody(request, response) {
   response.writeHead(PAYLOAD_TOO_LARGE, {
@@ -96,11 +117,18 @@ function refuseTooLargeBody(request, response) {
  * 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
- * @returns The backend's answer, or `undefined` once the body went over and
- *   `response` got the 413
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {number | undefined} maxBodyBytes
+ * @param {(
+ *   body: import("node:http").IncomingMessage | AsyncGenerator<Buffer> | undefined
+ * ) => Promise<Response>} send 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
+ * @returns {Promise<Response | import("node:http").ServerResponse | undefined>}
+ *   The backend's answer, or once the body went over and `response` got the
+ *   413: `undefined`, or `response` itself when the request had been read
+ *   already (`response.end()`'s own return)
  */
 export async function sendWithinLimit(request, response, maxBodyBytes, send) {
   if (declaresTooLargeBody(request, maxBodyBytes))

package/templates/vue/server/public-endpoints.mjs

@@ -1,6 +1,33 @@
 import { readFileSync } from "node:fs";
 import { json } from "./auth/backend.mjs";
 import { CROSS_ORIGIN_ERROR, isSameOrigin } from "./auth/client-ip.mjs";
+import { PROXY_AUTH_MODES } from "./backend-proxies.mjs";
+import {
+  isNonNullObject,
+  isNumber,
+  isObjectLike,
+  isRecord,
+  isString,
+} from "./type-guards.mjs";
+
+/**
+ * A public endpoint, compiled from a declaration that passed every check.
+ *
+ * @typedef {object} PublicEndpoint
+ * @property {string} path
+ * @property {string[]} methods
+ * @property {string[]} headers
+ * @property {RegExp} matcher
+ */
+
+/**
+ * A declaration as the manifest or the environment holds it, before any check.
+ *
+ * @typedef {object} PublicEndpointDeclaration
+ * @property {unknown} [path]
+ * @property {unknown} [methods]
+ * @property {unknown} [headers]
+ */
 
 /**
  * Written at the workspace root by the loader, from the endpoints each
@@ -41,39 +68,101 @@ const HEADER_NAME = /^x-[a-z0-9-]+$/;
 const RESERVED_HEADER =
   /^x-(?:forwarded-|real-ip$|dms-|inertia|http-method|method-override|original-|rewrite-)/;
 
+/** @type {unknown[] | undefined} */
 let declaredEndpoints;
+/** @type {import("./backend-proxies.mjs").ManifestProxy[] | undefined} */
 let declaredProxies;
 
 /**
  * The public endpoints the modules of this deployment declared, unchecked.
  *
- * @param file Generated file to read
- * @returns The declared entries, or none when the file is absent or broken
+ * @param {URL | string} [file] Generated file to read
+ * @returns {unknown[]} The declared entries, or none when the file is absent or broken
  */
 export function readDeclaredPublicEndpoints(file = DECLARED_ENDPOINTS_FILE) {
   try {
+    /** @type {unknown} */
     const parsed = JSON.parse(readFileSync(file, "utf8"));
-    return Array.isArray(parsed?.endpoints) ? parsed.endpoints : [];
+    const endpoints = isObjectLike(parsed) ? parsed.endpoints : undefined;
+    return Array.isArray(endpoints) ? endpoints : [];
   } catch {
     return [];
   }
 }
 
+/**
+ * Whether `entry` names a path and, when it says so, an auth mode and a body
+ * limit of the right type. The path pattern and the limit's range are judged
+ * when the proxies are resolved.
+ *
+ * @param {unknown} entry
+ * @returns {entry is { path: string, auth?: "session" | "none", maxBodyBytes?: number }}
+ */
+function isProxyDeclaration(entry) {
+  return (
+    isRecord(entry) &&
+    !Array.isArray(entry) &&
+    isString(entry.path) &&
+    (entry.auth === undefined ||
+      PROXY_AUTH_MODES.some((mode) => mode === entry.auth)) &&
+    (entry.maxBodyBytes === undefined || isNumber(entry.maxBodyBytes))
+  );
+}
+
+/**
+ * @param {unknown[]} entries
+ * @param {string} source Where they were declared, for the warning
+ * @param {(entry: unknown) => boolean} isUsable
+ */
+function warnUnusableProxies(entries, source, isUsable) {
+  const unusable = entries.filter((entry) => !isUsable(entry)).length;
+  if (unusable)
+    console.warn(
+      `Ignoring ${unusable} ${unusable === 1 ? "entry" : "entries"} of ${source}: not a backend proxy declaration (a path, an auth of session or none, a body limit in bytes)`,
+    );
+}
+
+/**
+ * @param {unknown} entry
+ * @returns {entry is import("./backend-proxies.mjs").ManifestProxy}
+ */
+function isDeclaredProxy(entry) {
+  return (
+    isRecord(entry) &&
+    isProxyDeclaration(entry) &&
+    (entry.module === undefined || isString(entry.module))
+  );
+}
+
 /**
  * The backend proxies the backend modules declared in the manifest, as
- * `{ module, path, auth?, maxBodyBytes? }`, unchecked.
+ * `{ module, path, auth?, maxBodyBytes? }`. An entry that is not one is
+ * reported and left out.
  *
  * A missing or broken file declares no proxy.
  *
- * @param file Generated file to read
+ * @param {URL | string} [file] Generated file to read
+ * @returns {import("./backend-proxies.mjs").ManifestProxy[]}
  */
 export function readDeclaredBackendProxies(file = DECLARED_ENDPOINTS_FILE) {
   if (file === DECLARED_ENDPOINTS_FILE && declaredProxies)
     return declaredProxies;
+  /** @type {import("./backend-proxies.mjs").ManifestProxy[]} */
   let proxies = [];
   try {
+    /** @type {unknown} */
     const parsed = JSON.parse(readFileSync(file, "utf8"));
-    if (Array.isArray(parsed?.proxies)) proxies = parsed.proxies;
+    const listed = isObjectLike(parsed) ? parsed.proxies : undefined;
+    if (Array.isArray(listed)) {
+      /** @type {unknown[]} */
+      const entries = listed;
+      warnUnusableProxies(
+        entries,
+        "the generated manifest file",
+        isDeclaredProxy,
+      );
+      proxies = entries.filter(isDeclaredProxy);
+    }
   } catch {}
   if (file === DECLARED_ENDPOINTS_FILE) declaredProxies = proxies;
   return proxies;
@@ -82,29 +171,40 @@ export function readDeclaredBackendProxies(file = DECLARED_ENDPOINTS_FILE) {
 /**
  * The backend proxies `DMS_BACKEND_PROXIES` adds: a JSON array of
  * `{ path, auth?, maxBodyBytes? }`, as the manifest's `backendProxies`, for an
- * operator. A value that is not a JSON array is reported and ignored.
+ * operator. A value that is not a JSON array is reported and ignored, and so
+ * is each entry that is not a declaration.
  *
- * @param declaration The variable's value
+ * @param {string} [declaration] The variable's value
+ * @returns {import("./backend-proxies.mjs").ManifestProxy[]}
  */
 export function environmentBackendProxies(
   declaration = process.env.DMS_BACKEND_PROXIES,
 ) {
   if (!declaration?.trim()) return [];
   try {
+    /** @type {unknown} */
     const parsed = JSON.parse(declaration);
-    if (Array.isArray(parsed))
-      return parsed.map((entry) => ({
-        ...entry,
-        module: "DMS_BACKEND_PROXIES",
-      }));
+    if (Array.isArray(parsed)) {
+      /** @type {unknown[]} */
+      const entries = parsed;
+      warnUnusableProxies(entries, "DMS_BACKEND_PROXIES", isProxyDeclaration);
+      return entries
+        .filter(isProxyDeclaration)
+        .map((entry) => ({ ...entry, module: "DMS_BACKEND_PROXIES" }));
+    }
   } catch {}
   console.warn("Ignoring DMS_BACKEND_PROXIES: not a JSON array");
   return [];
 }
 
+/**
+ * @param {string | undefined} declaration
+ * @returns {unknown[]}
+ */
 function environmentEndpoints(declaration) {
   if (!declaration?.trim()) return [];
   try {
+    /** @type {unknown} */
     const parsed = JSON.parse(declaration);
     return Array.isArray(parsed) ? parsed : [];
   } catch {
@@ -113,6 +213,7 @@ function environmentEndpoints(declaration) {
   }
 }
 
+/** @param {unknown} methods */
 function normalizedMethods(methods) {
   if (methods === undefined) return DEFAULT_METHODS;
   if (!Array.isArray(methods) || methods.length === 0) return undefined;
@@ -122,6 +223,7 @@ function normalizedMethods(methods) {
     : undefined;
 }
 
+/** @param {unknown} headers */
 function normalizedHeaders(headers) {
   if (headers === undefined) return [];
   if (!Array.isArray(headers)) return undefined;
@@ -133,6 +235,7 @@ function normalizedHeaders(headers) {
     : undefined;
 }
 
+/** @param {string} path */
 function pathMatcher(path) {
   const pattern = path
     .split("/")
@@ -148,11 +251,13 @@ function pathMatcher(path) {
 /**
  * A declaration made usable, or `undefined` when any part of it is malformed:
  * a bad entry is dropped whole, never widened to what it might have meant.
+ *
+ * @param {PublicEndpointDeclaration | null | undefined} entry
+ * @returns {PublicEndpoint | undefined}
  */
 export function compilePublicEndpoint(entry) {
-  if (typeof entry !== "object" || entry === null) return undefined;
-  if (typeof entry.path !== "string" || !PUBLIC_PATH.test(entry.path))
-    return undefined;
+  if (!isNonNullObject(entry)) return undefined;
+  if (!isString(entry.path) || !PUBLIC_PATH.test(entry.path)) return undefined;
   const methods = normalizedMethods(entry.methods);
   const headers = normalizedHeaders(entry.headers);
   if (!methods || !headers) return undefined;
@@ -168,6 +273,10 @@ export function compilePublicEndpoint(entry) {
  * The backend endpoints this deployment serves to anyone: what the backend's
  * modules declared, plus what `DMS_PUBLIC_ENDPOINTS` adds (a JSON array of the
  * same `{ path, methods?, headers? }` entries).
+ *
+ * @param {string} [declaration]
+ * @param {unknown[]} [declared]
+ * @returns {PublicEndpoint[]}
  */
 export function allowedPublicEndpoints(
   declaration = process.env.DMS_PUBLIC_ENDPOINTS,
@@ -189,6 +298,8 @@ export function allowedPublicEndpoints(
 /**
  * Compiled once per value of the environment variable, so a malformed entry
  * is reported once rather than on every request.
+ *
+ * @type {{ declaration: string | undefined, endpoints: PublicEndpoint[] } | undefined}
  */
 let compiled;
 
@@ -202,9 +313,9 @@ function currentPublicEndpoints() {
 /**
  * The public endpoint a request reaches, if any.
  *
- * @param method The request's method
- * @param pathname The request's normalized path, without its query string
- * @param endpoints The endpoints to match, this deployment's by default
+ * @param {string} method The request's method
+ * @param {string} pathname The request's normalized path, without its query string
+ * @param {PublicEndpoint[]} [endpoints] The endpoints to match, this deployment's by default
  */
 export function matchPublicEndpoint(
   method,
@@ -227,9 +338,9 @@ export function matchPublicEndpoint(
  * it reaches a public endpoint, which is why the proxy never sends a public
  * endpoint the session: a cross-site form posting to it acts as nobody.
  *
- * @param request The incoming request
- * @param safeMethods Methods that change nothing and need no Origin
- * @param proxy The backend proxy the request reached
+ * @param {import("node:http").IncomingMessage} request The incoming request
+ * @param {ReadonlySet<string>} safeMethods Methods that change nothing and need no Origin
+ * @param {import("./backend-proxies.mjs").BackendProxy} proxy The backend proxy the request reached
  * @returns `{ anonymous, headers, isRefused }`
  */
 export function proxyAccess(request, safeMethods, proxy) {
@@ -252,7 +363,11 @@ export function proxyAccess(request, safeMethods, proxy) {
   };
 }
 
-/** Answers the 403 of a request `proxyAccess` refused. */
+/**
+ * Answers the 403 of a request `proxyAccess` refused.
+ *
+ * @param {import("node:http").ServerResponse} response
+ */
 export function refuseCrossOrigin(response) {
   json(response, 403, CROSS_ORIGIN_ERROR);
 }

package/templates/vue/server/public-options.mjs

@@ -1,15 +1,25 @@
+import { isRecord } from "./type-guards.mjs";
+
 const VARIABLE = "DMS_PUBLIC_OPTIONS";
 export const PUBLIC_OPTIONS_ELEMENT_ID = "dms-public-options";
 
+/**
+ * The registry the workspace was materialized with.
+ *
+ * @typedef {object} FrontendRegistry
+ * @property {{ id: string, options?: unknown }[]} modules The modules, highest priority first
+ */
+
+/**
+ * @param {string | undefined} raw
+ * @returns {Record<string, unknown> | undefined}
+ */
 function parse(raw) {
   if (!raw) return undefined;
   try {
+    /** @type {unknown} */
     const parsed = JSON.parse(raw);
-    return typeof parsed === "object" &&
-      parsed !== null &&
-      !Array.isArray(parsed)
-      ? parsed
-      : undefined;
+    return isRecord(parsed) && !Array.isArray(parsed) ? parsed : undefined;
   } catch {
     console.warn(`${VARIABLE} is not a JSON object of options by module id`);
     return undefined;
@@ -27,7 +37,11 @@ function parse(raw) {
  */
 export const RUNTIME_PUBLIC_OPTIONS = parse(process.env[VARIABLE]);
 
-/** The options of each module of the registry, the runtime ones first. */
+/**
+ * The options of each module of the registry, the runtime ones first.
+ *
+ * @param {FrontendRegistry} registry
+ */
 export function publicOptionsOf(registry) {
   return Object.fromEntries(
     registry.modules.map((module) => [

package/templates/vue/server/request-failure.mjs

@@ -1,9 +1,13 @@
+import { isNumber, isObjectLike } from "./type-guards.mjs";
+
 const FRONTEND_ORIGIN = "http://frontend.local";
 const TEXT_TYPE = "text/plain; charset=utf-8";
 
 /**
  * Whether the path of `url` holds a percent-escape no decoder accepts, such as
  * `/projects/%E0%A4%A`. Vite and the router decode the path, and throw on it.
+ *
+ * @param {string} url
  */
 export function hasMalformedPath(url) {
   try {
@@ -14,9 +18,23 @@ export function hasMalformedPath(url) {
   }
 }
 
+/**
+ * The status an error asks to be answered with: its integer `status`, else 502.
+ *
+ * @param {unknown} error
+ * @returns {number}
+ */
+export function failureStatus(error) {
+  const status = isObjectLike(error) ? error.status : undefined;
+  return isNumber(status) && Number.isInteger(status) ? status : 502;
+}
+
 /**
  * Whether a failed request can no longer be answered: the client went away, or
  * the response already started.
+ *
+ * @param {unknown} error
+ * @param {import("node:http").ServerResponse} response
  */
 export function isResponseGone(error, response) {
   return (
@@ -30,6 +48,8 @@ export function isResponseGone(error, response) {
 /**
  * Answers for requests the server cannot serve at all: an unreadable URL, or
  * a failure while it was already rendering the error page.
+ *
+ * @param {import("node:http").ServerResponse} response
  */
 export function writeBadRequest(response) {
   response.writeHead(400, { "content-type": TEXT_TYPE });
@@ -40,6 +60,9 @@ export function writeBadRequest(response) {
  * The last resort once even the error page failed: a bare 500, or a dropped
  * connection when the response already started. The server keeps running
  * either way.
+ *
+ * @param {unknown} error
+ * @param {import("node:http").ServerResponse} response
  */
 export function abandonResponse(error, response) {
   console.error("DMS error response failed", error);

package/templates/vue/server/request-routing.mjs

@@ -1,6 +1,19 @@
 import { matchBackendProxy } from "./backend-proxies.mjs";
 import { isRendererFilePath, moduleRouteMethods } from "./module-routes.mjs";
 
+/**
+ * @typedef {object} RoutingModules
+ * @property {import("./module-route-types.mjs").ServerRoute[]} routes
+ * @property {import("./backend-proxies.mjs").BackendProxy[]} [proxies]
+ */
+/**
+ * @typedef {{ kind: "renderer" }
+ *   | { kind: "module", id: string }
+ *   | { kind: "backend", proxy: import("./backend-proxies.mjs").BackendProxy }
+ *   | { kind: "page" }
+ *   | { kind: "not-found" }} RequestOwner
+ */
+
 const PAGE_METHODS = new Set(["GET", "HEAD"]);
 
 /**
@@ -14,12 +27,12 @@ const PAGE_METHODS = new Set(["GET", "HEAD"]);
  * `backendProxies`); 4. the pages, for everything else: a method other than
  * `GET` and `HEAD` on a page path is a `404`.
  *
- * @param method The request's method
- * @param pathname The request's normalized path
- * @param modules What `loadServerModules` returned: `routes` and `proxies`
- * @param hasRendererFile `(pathname) => boolean`, whether the renderer has a
+ * @param {string} method The request's method
+ * @param {string} pathname The request's normalized path
+ * @param {RoutingModules} modules What `loadServerModules` returned: `routes` and `proxies`
+ * @param {(pathname: string) => boolean} hasRendererFile `(pathname) => boolean`, whether the renderer has a
  *   file at that path
- * @returns `{ kind: "renderer" }`, `{ kind: "module", id }`,
+ * @returns {RequestOwner} `{ kind: "renderer" }`, `{ kind: "module", id }`,
  *   `{ kind: "backend", proxy }`, `{ kind: "page" }` or
  *   `{ kind: "not-found" }`
  */
@@ -41,9 +54,9 @@ export function requestOwner(method, pathname, modules, hasRendererFile) {
  * `Location` on such a path can become a frontend path (see
  * `proxy-redirects.mjs`).
  *
- * @param pathname A normalized path
- * @param modules What `loadServerModules` returned: `routes` and `proxies`
- * @param hasRendererFile `(pathname) => boolean`, whether the renderer has a
+ * @param {string} pathname A normalized path
+ * @param {RoutingModules} modules What `loadServerModules` returned: `routes` and `proxies`
+ * @param {(pathname: string) => boolean} [hasRendererFile] `(pathname) => boolean`, whether the renderer has a
  *   file at that path
  */
 export function reachesBackend(
@@ -56,7 +69,11 @@ export function reachesBackend(
   );
 }
 
-/** The `x-dms-route-owner` value of an owner, for the development server. */
+/**
+ * The `x-dms-route-owner` value of an owner, for the development server.
+ *
+ * @param {RequestOwner} owner
+ */
 export function ownerLabel(owner) {
   if (owner.kind === "module") return `module:${owner.id}`;
   if (owner.kind === "backend") return `backend:${owner.proxy.path}`;

package/templates/vue/server/request-target.mjs

@@ -1,4 +1,5 @@
 import { writeBadRequest } from "./request-failure.mjs";
+import { isString } from "./type-guards.mjs";
 
 const FRONTEND_ORIGIN = "http://frontend.local";
 
@@ -7,9 +8,11 @@ const FRONTEND_ORIGIN = "http://frontend.local";
  * query, that stays on this server once resolved. Anything else (an absolute
  * or authority form, `*`, a path a URL parser reads as another host) is not a
  * request a browser sends to the frontend.
+ *
+ * @param {string | undefined} target
  */
 export function isOriginForm(target) {
-  if (typeof target !== "string" || !target.startsWith("/")) return false;
+  if (!isString(target) || !target.startsWith("/")) return false;
   try {
     return new URL(target, FRONTEND_ORIGIN).origin === FRONTEND_ORIGIN;
   } catch {
@@ -22,8 +25,8 @@ export function isOriginForm(target) {
  * and query on the backend's origin. The path is set, not resolved, so a path
  * normalizing to `//host` (`/x/..//host`) stays a path on the backend.
  *
- * @param target The request target, origin-form
- * @param backendBaseUrl The backend's base URL
+ * @param {string} target The request target, origin-form
+ * @param {string} [backendBaseUrl] The backend's base URL
  */
 export function backendUrl(
   target,
@@ -45,6 +48,9 @@ export function backendUrl(
  * form `http://host/x` all name another host once resolved, which turned the
  * proxy into an open one. Every routing decision and the URL sent to the
  * backend read the same normalized path from here.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
  */
 export function refuseForeignTarget(request, response) {
   if (isOriginForm(request.url)) return false;