@antelopejs/dms-frontend 0.9.3 → 0.10.0

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,

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))