@antelopejs/dms-frontend 0.9.3 → 0.10.1

package/templates/vue/server-module.ts

@@ -101,7 +101,16 @@ export interface DmsServerEvent {
    * overwrites another's, and naming a `dms_*` cookie throws.
    */
   cookies: {
-    readSealed<T = unknown>(name: string): T | undefined;
+    /**
+     * The value a sealed cookie holds, when `accepts` takes it. A cookie that
+     * is absent, does not open, or holds a value `accepts` refuses reads as
+     * `undefined`. `accepts` receives the JSON the cookie was written from and
+     * is never called for an absent or unreadable cookie.
+     */
+    readSealed<T>(
+      name: string,
+      accepts: (value: unknown) => value is T,
+    ): T | undefined;
     writeSealed(
       name: string,
       value: unknown,
@@ -177,7 +186,8 @@ export interface DmsServerRouteOptions {
  * The session logic the frontend server runs outside any route, which the
  * module owning sign-in provides. Without `publicSession`, pages carry no
  * `user` and `session`; without `refreshSession`, a session the backend
- * refuses is not renewed; `signInPath` is `/auth` by default.
+ * refuses is not renewed; `signInPath` is `/auth` by default. The server
+ * calls each hook with the registered object as `this`.
  */
 export interface DmsServerAuth {
   /** Where a signed-out visit to a private page goes, with `?redirect=`. */

package/templates/vue/server.mjs

@@ -2,18 +2,14 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { createServer, maxHeaderSize } from "node:http";
 import { extname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { RequestBodyError, UpstreamError } from "./server/auth/backend.mjs";
 import {
-  CLIENT_HEADERS,
-  relayedHeaders,
-  RequestBodyError,
-  UpstreamError,
-} from "./server/auth/backend.mjs";
-import { forwardedHeaders } from "./server/auth/client-ip.mjs";
-import { proxyAccess, refuseCrossOrigin } from "./server/public-endpoints.mjs";
+  backendJson,
+  serverComponentFetch,
+} from "./server/backend-request.mjs";
 import { readSession } from "./server/auth/session.mjs";
 import {
   BackendResponseError,
-  backendResponseError,
   redirectAccessRefusal,
   UNEXPECTED_ERROR_BODY,
 } from "./server/backend-response.mjs";
@@ -21,6 +17,7 @@ import { handleClientError } from "./server/client-error.mjs";
 import {
   reportListenError,
   reportReady,
+  reportRouting,
   reportStartError,
 } from "./server/cli-report.mjs";
 import { publicBuildFile } from "./server/built-files.mjs";
@@ -50,20 +47,29 @@ import {
   handleModuleRoute,
   loadServerModules,
 } from "./server/module-server.mjs";
-import { HOMEPAGE } from "./server/homepage.mjs";
+import {
+  redirectSignedOutPrivatePage,
+  redirectToHomepage,
+} from "./server/page-redirects.mjs";
 import { publicOptionsScript } from "./server/public-options.mjs";
-import { renderInPlace, serverReads } from "./server/in-place-render.mjs";
-import { loadPageProps, propsForQuery } from "./server/page-props.mjs";
+import { renderInPlace } from "./server/in-place-render.mjs";
+import {
+  loadPageProps,
+  pageRoute,
+  propsForQuery,
+} from "./server/page-props.mjs";
 import { htmlTag } from "./server/html-tag.mjs";
+import { isString } from "./server/type-guards.mjs";
 import { listenHost } from "./server/listen-host.mjs";
 import * as icons from "./server/icons.mjs";
+import { ssrRenderer } from "./server/ssr-module.mjs";
 import * as requestFailure from "./server/request-failure.mjs";
+import { proxy } from "./server/proxy-request.mjs";
 import {
-  PLAIN_ANSWER_HEADERS,
-  relayAnswer,
-} from "./server/proxy-compression.mjs";
-import { backendUrl, refuseForeignTarget } from "./server/request-target.mjs";
-import { sendWithinLimit, SERVER_OPTIONS } from "./server/proxy-transfers.mjs";
+  hasOriginFormTarget,
+  isServerRequest,
+} from "./server/request-target.mjs";
+import { SERVER_OPTIONS } from "./server/proxy-transfers.mjs";
 import {
   createInertiaPage,
   htmlHeaders,
@@ -72,24 +78,29 @@ import {
   isFrontendVisit,
   redirectFrontendVisit,
   handleAssetVersionMismatch,
+  isSsrPage,
 } from "./server/inertia.mjs";
 export * from "./server/inertia.mjs";
 
+/** @typedef {import("node:http").IncomingMessage} IncomingMessage */
+/** @typedef {import("./server/request-target.mjs").ServerRequest} ServerRequest */
+/** @typedef {import("node:http").ServerResponse} ServerResponse */
+/** @typedef {import("vite").ViteDevServer} ViteDevServer */
+/** @typedef {import("./server/inertia.mjs").InertiaPage} InertiaPage */
+/** @typedef {import("./server/in-place-render.mjs").ServerReads} ServerReads */
+
 const INERTIA_HEADER = "x-inertia";
 const JSON_TYPE = "application/json";
 const PROJECT_ROOT = fileURLToPath(new URL(".", import.meta.url));
-const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+/**
+ * @type {[
+ *   (pathname: string) => boolean,
+ *   (request: ServerRequest, response: ServerResponse) => Promise<void>
+ * ][]}
+ */
 const LOCAL_ROUTES = [[icons.isIconRequest, icons.handleIcons]];
 const CLIENT_ROOT = join(PROJECT_ROOT, "dist/client");
 const SOURCE_TEMPLATE_PATH = join(PROJECT_ROOT, "index.html");
-/**
- * A URL, not a path: on Windows, `import()` reads `C:\...` as a URL whose
- * scheme is `c:` and refuses it.
- */
-const BUILT_SSR_RENDERER_URL = new URL(
-  "dist/ssr/ssr-renderer.js",
-  import.meta.url,
-);
 
 /**
  * The SSR bundle keeps vue-i18n external, so Node loads its esm-bundler build,
@@ -98,20 +109,26 @@ const BUILT_SSR_RENDERER_URL = new URL(
  * NODE_ENV=production throws a ReferenceError on the first render.
  */
 function defineVueCompileFlags() {
-  globalThis.__VUE_PROD_DEVTOOLS__ ??= false;
+  /** @type {typeof globalThis & { __VUE_PROD_DEVTOOLS__?: boolean }} */
+  const vueGlobals = globalThis;
+  vueGlobals.__VUE_PROD_DEVTOOLS__ ??= false;
 }
 
 defineVueCompileFlags();
-let productionSsrRenderer;
+/** @type {ViteDevServer | undefined} */
 let vite;
+/** @type {Promise<ViteDevServer> | undefined} */
 let vitePromise;
+/** @type {import("node:http").Server | undefined} */
 let frontendHttpServer;
 
+/** @returns {Promise<ViteDevServer | undefined>} */
 async function developmentServer() {
   if (process.env.DMS_DEV !== "true") return undefined;
   if (vite) return vite;
   vitePromise ??= import("vite")
     .then(({ createServer: createViteServer }) => {
+      /** @type {import("vite").ServerOptions} */
       const serverOptions = {
         middlewareMode: true,
         fs: { deny: DEV_FS_DENY },
@@ -127,57 +144,24 @@ async function developmentServer() {
       vite = server;
       return server;
     })
-    .catch((error) => {
-      vitePromise = undefined;
-      throw error;
-    });
+    .catch(
+      /** @param {unknown} error */ (error) => {
+        vitePromise = undefined;
+        throw error;
+      },
+    );
   return vitePromise;
 }
 
-/**
- * The headers of a backend request: the relayed client headers, the client's
- * Origin and Referer as received, the `X-Forwarded-*` headers (set last, so no
- * caller writes them), and the session's access token unless the request goes
- * anonymously.
- */
-function backendHeaders(request, access = { anonymous: false, headers: [] }) {
-  const headers = {
-    ...relayedHeaders(request, [
-      "accept",
-      "content-type",
-      "if-match",
-      "origin",
-      "referer",
-      ...CLIENT_HEADERS,
-      ...access.headers,
-    ]),
-    ...forwardedHeaders(request),
-  };
-  const session = access.anonymous ? undefined : readSession(request);
-  if (session?.accessToken)
-    headers.authorization = `Bearer ${session.accessToken}`;
-  return headers;
-}
-
-function serverComponentFetch(request) {
-  return serverReads(() => backendHeaders(request));
-}
-
-async function backendJson(path, request) {
-  const response = await fetch(new URL(path, process.env.DMS_API_BASE_URL), {
-    headers: backendHeaders(request),
-  });
-  if (!response.ok) {
-    throw await backendResponseError(response);
-  }
-  return response.json();
-}
-
 /** The session logic of the module that owns sign-in. */
 async function currentAuth() {
   return (await loadServerModules(await developmentServer())).serverAuth;
 }
 
+/**
+ * @param {ServerRequest} request
+ * @returns {import("./server/page-props.mjs").PageBackend}
+ */
 function pageBackend(request) {
   return {
     fetchJson: (path) => backendJson(path, request),
@@ -188,76 +172,23 @@ function pageBackend(request) {
   };
 }
 
-function pageProps(request, auth) {
-  return loadPageProps(request, pageBackend(request), auth);
-}
-
-function redirectToHomepage(request, response, pathname) {
-  if (pathname !== "/" || HOMEPAGE === "/") return false;
-  redirectFrontendVisit(request, response, HOMEPAGE);
-  return true;
-}
-
-function redirectSignedOutPrivatePage(request, response, props, auth) {
-  const route = props.page?.route;
-  if (
-    route?.publicAccess === true ||
-    route?.hasAccess !== false ||
-    readSession(request)
-  )
-    return false;
-  redirectFrontendVisit(request, response, auth.signInLocation(request.url));
-  return true;
-}
-
 /**
- * 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 {ServerRequest} request
+ * @param {import("./server/page-props.mjs").PageAuth} auth
  */
-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,
-  });
+function pageProps(request, auth) {
+  return loadPageProps(request, pageBackend(request), auth);
 }
 
 /**
  * Send the built file `pathname` names, or `false` when the build has none
  * there. `publicBuildFile` decides which file that is; `serveStaticFile` how
  * it goes out.
+ *
+ * @param {string} pathname
+ * @param {IncomingMessage} request
+ * @param {ServerResponse} response
+ * @returns {boolean}
  */
 function serveAsset(pathname, request, response) {
   const file = publicBuildFile(CLIENT_ROOT, pathname);
@@ -268,14 +199,10 @@ function serveAsset(pathname, request, response) {
   return true;
 }
 
-async function ssrRenderer(devServer) {
-  const renderer = devServer
-    ? await devServer.ssrLoadModule("/ssr-renderer.ts")
-    : await (productionSsrRenderer ??= import(BUILT_SSR_RENDERER_URL.href));
-  await icons.provideIconCollections(renderer);
-  return renderer;
-}
-
+/**
+ * @param {InertiaPage} page
+ * @returns {import("./ssr-renderer.ts").DmsSsrResult}
+ */
 function clientRenderedShell(page) {
   return {
     body: inertiaAppHtml(page),
@@ -285,9 +212,17 @@ function clientRenderedShell(page) {
   };
 }
 
+/**
+ * @param {InertiaPage} page
+ * @param {ServerReads} serverFetch
+ * @param {string | undefined} requestCookies
+ * @param {ViteDevServer | undefined} devServer
+ */
 async function serverRendered(page, serverFetch, requestCookies, devServer) {
   try {
     const renderer = await ssrRenderer(devServer);
+    if (!isSsrPage(page))
+      throw new TypeError("The page has no path and no page props to render");
     return await renderer.renderDmsPage(page, serverFetch, requestCookies);
   } catch (error) {
     console.error(
@@ -301,6 +236,13 @@ async function serverRendered(page, serverFetch, requestCookies, devServer) {
 /**
  * Renders a page document. With `{ ssr: false }` (a route rule), the client
  * renders the page from the shell instead.
+ *
+ * @param {InertiaPage} page
+ * @param {string} requestUrl
+ * @param {ServerReads} serverFetch
+ * @param {string | undefined} requestCookies
+ * @param {{ ssr?: false }} [options]
+ * @returns {Promise<{ html: string, status: number, redirect?: string }>}
  */
 export async function renderHtml(
   page,
@@ -330,7 +272,7 @@ export async function renderHtml(
     .replace("<title>Antelope DMS</title>", () =>
       withFaviconPlaceholder(rendered.head.headTags),
     )
-    .replace(/<html([^>]*)>/, (_, attributes) =>
+    .replace(/<html([^>]*)>/, (_, /** @type {string} */ attributes) =>
       htmlTag(attributes, rendered.head.htmlAttrs),
     )
     .replace("<body", `<body ${rendered.head.bodyAttrs}`)
@@ -343,6 +285,12 @@ export async function renderHtml(
   return { html, status: rendered.error?.statusCode ?? 200 };
 }
 
+/**
+ * @param {InertiaPage} page
+ * @param {ServerRequest} request
+ * @param {Pick<import("./server/route-rules.mjs").RouteRule, "ssr">} [rule]
+ * @param {ServerReads} [reads]
+ */
 function renderRequestHtml(page, request, rule = {}, reads) {
   const fetch = reads ?? serverComponentFetch(request);
   return renderHtml(page, request.url, fetch, request.headers.cookie, {
@@ -353,6 +301,11 @@ function renderRequestHtml(page, request, rule = {}, reads) {
 /**
  * Renders a page document, at the query the page completes as it renders:
  * see `renderInPlace`.
+ *
+ * @param {InertiaPage} page
+ * @param {ServerRequest} request
+ * @param {import("./server/route-rules.mjs").MergedRouteRule} rule
+ * @param {import("./server/page-props.mjs").PageAuth} auth
  */
 function renderDocument(page, request, rule, auth) {
   const fetch = serverComponentFetch(request);
@@ -365,9 +318,14 @@ function renderDocument(page, request, rule, auth) {
   );
 }
 
+/**
+ * @param {unknown} error
+ * @param {ServerRequest} request
+ * @param {ServerResponse} response
+ */
 async function writeBackendError(error, request, response) {
   const auth = await currentAuth();
-  const status = Number.isInteger(error?.status) ? error.status : 502;
+  const status = requestFailure.failureStatus(error);
   const pathname = new URL(request.url, "http://frontend.local").pathname;
   if (
     error instanceof BackendResponseError &&
@@ -410,6 +368,12 @@ async function writeBackendError(error, request, response) {
   response.end(JSON.stringify(payload));
 }
 
+/**
+ * @param {ViteDevServer} devServer
+ * @param {IncomingMessage} request
+ * @param {ServerResponse} response
+ * @returns {Promise<boolean>}
+ */
 async function answeredByVite(devServer, request, response) {
   const result = await runViteMiddlewares(devServer, request, response);
   if (result.status === "failed") writeViteError(response, result.error);
@@ -422,6 +386,10 @@ async function answeredByVite(devServer, request, response) {
  * production server serves. Only a path with an extension names one.
  *
  * The path is decoded as Vite and the asset server read it: `%2E` is a dot.
+ *
+ * @param {ViteDevServer | undefined} devServer
+ * @param {string} requested
+ * @returns {boolean}
  */
 function hasRendererFile(devServer, requested) {
   let pathname;
@@ -445,7 +413,15 @@ function hasRendererFile(devServer, requested) {
   });
 }
 
-/** Vite's files in development, the build's in production; else a 404. */
+/**
+ * Vite's files in development, the build's in production; else a 404.
+ *
+ * @param {ViteDevServer | undefined} devServer
+ * @param {IncomingMessage} request
+ * @param {ServerResponse} response
+ * @param {string} pathname
+ * @returns {Promise<void>}
+ */
 async function serveRendererFile(devServer, request, response, pathname) {
   const answered = devServer
     ? await answeredByVite(devServer, request, response)
@@ -455,11 +431,16 @@ async function serveRendererFile(devServer, request, response, pathname) {
   response.end("Not found");
 }
 
+/** @param {ServerResponse} response */
 function writeNotFound(response) {
   response.writeHead(404, { "content-type": JSON_TYPE });
   response.end(JSON.stringify({ message: "Not found" }));
 }
 
+/**
+ * @param {ServerRequest} request
+ * @param {ServerResponse} response
+ */
 export async function handleRequest(request, response) {
   const url = new URL(request.url, "http://frontend.local");
   const pathname = url.pathname;
@@ -467,6 +448,7 @@ export async function handleRequest(request, response) {
   if (localRoute) return localRoute[1](request, response);
   const devServer = await developmentServer();
   const modules = await loadServerModules(devServer);
+  /** @param {string} path */
   const hasFile = (path) => hasRendererFile(devServer, path);
   const owner = requestOwner(request.method, pathname, modules, hasFile);
   if (devServer) response.setHeader("x-dms-route-owner", ownerLabel(owner));
@@ -474,6 +456,7 @@ export async function handleRequest(request, response) {
     return serveRendererFile(devServer, request, response, pathname);
   if (owner.kind === "module")
     return handleModuleRoute(request, response, pathname, modules);
+  /** @param {string} path */
   const isProxiedPath = (path) => reachesBackend(path, modules, hasFile);
   if (owner.kind === "backend")
     return proxy(request, response, owner.proxy, isProxiedPath);
@@ -487,8 +470,9 @@ export async function handleRequest(request, response) {
   if (redirectSignedOutPrivatePage(request, response, props, auth)) return;
   const page = createInertiaPage(request.url, props, undefined, onceProps);
   const rule = routeRuleFor(rules, pathname);
+  /** @param {number} status */
   const headersFor = (status) =>
-    ruleHeaders(rule, request, props.page?.route, status);
+    ruleHeaders(rule, request, pageRoute(props), status);
   if (request.headers[INERTIA_HEADER]) {
     return writeContent(
       request,
@@ -513,8 +497,15 @@ export async function handleRequest(request, response) {
   );
 }
 
+/**
+ * @param {unknown} error
+ * @param {IncomingMessage & { dmsSessionRetry?: boolean }} request
+ * @param {ServerResponse} response
+ */
 async function writeRequestFailure(error, request, response) {
   if (requestFailure.isResponseGone(error, response)) return;
+  if (!isServerRequest(request))
+    return requestFailure.abandonResponse(error, response);
   if (
     error instanceof BackendResponseError &&
     error.status === 401 &&
@@ -531,14 +522,24 @@ async function writeRequestFailure(error, request, response) {
   await writeBackendError(error, request, response);
 }
 
-/** An error page failing too must not reject: that would end the process. */
+/**
+ * An error page failing too must not reject: that would end the process.
+ *
+ * @param {IncomingMessage} request
+ * @param {ServerResponse} response
+ * @returns {Promise<void>}
+ */
 export async function handleRequestSafely(request, response) {
   try {
-    if (refuseForeignTarget(request, response)) return;
+    if (!hasOriginFormTarget(request)) {
+      requestFailure.writeBadRequest(response);
+      return;
+    }
     await handleRequest(request, response);
   } catch (error) {
-    await writeRequestFailure(error, request, response).catch((failure) =>
-      requestFailure.abandonResponse(failure, response),
+    await writeRequestFailure(error, request, response).catch(
+      /** @param {unknown} failure */ (failure) =>
+        requestFailure.abandonResponse(failure, response),
     );
   }
 }
@@ -548,25 +549,26 @@ if (
   import.meta.url === new URL(`file://${process.argv[1]}`).href
 ) {
   frontendHttpServer = createServer(SERVER_OPTIONS, handleRequestSafely);
-  frontendHttpServer.on("clientError", (error, socket) =>
+  const server = frontendHttpServer;
+  server.on("clientError", (error, socket) =>
     handleClientError(error, socket, maxHeaderSize),
   );
   const port = Number(process.env.PORT ?? 3001);
   const host = listenHost();
+  /** @param {NodeJS.ErrnoException} error */
   const onListenError = (error) => void reportListenError(error, host, port);
-  frontendHttpServer.once("error", onListenError);
-  frontendHttpServer.listen(port, host, () => {
-    frontendHttpServer.off("error", onListenError);
+  server.once("error", onListenError);
+  server.listen(port, host, () => {
+    server.off("error", onListenError);
     void announceReady();
   });
 }
 
 /** Prints who owns which paths, once the server is up. */
-async function reportRouting() {
+async function reportServerModules() {
   try {
     const modules = await loadServerModules(await developmentServer());
-    for (const line of routingReport(modules.proxies, modules.routes.length))
-      console.log(line);
+    reportRouting(routingReport(modules.proxies, modules.routes.length));
   } catch (error) {
     console.error("DMS server modules failed to load", error);
   }
@@ -587,8 +589,11 @@ async function announceReady() {
     await reportStartError(error);
     return;
   }
-  const { address, port } = frontendHttpServer.address();
+  const listening = frontendHttpServer?.address();
+  if (!listening || isString(listening))
+    throw new TypeError("The DMS server is not listening on a port");
+  const { address, port } = listening;
   await reportReady(address, port);
-  await reportRouting();
+  await reportServerModules();
   if (process.env.DMS_DEV === "true") watchEmailBundle();
 }