@antelopejs/dms-frontend 0.7.1 → 0.9.0

package/templates/vue/server/auth/backend.mjs

@@ -1,9 +1,16 @@
-import { clientCountryHeader, clientIp } from "./client-ip.mjs";
+import { REDIRECT_STATUSES } from "../proxy-redirects.mjs";
+import { clientCountryHeader, clientIp, clientIpHeader } from "./client-ip.mjs";
 
-const FORWARDED_HEADERS = [
+/**
+ * The client headers every backend request carries, the proxy's and a module
+ * route's alike: the browser's user agent, the interface language, and the
+ * realtime session and the browser connection it rides on.
+ */
+export const CLIENT_HEADERS = [
   "user-agent",
   "x-content-language",
   "x-realtime-session",
+  "x-realtime-connection",
 ];
 
 export class UpstreamError extends Error {
@@ -48,6 +55,7 @@ export function relayedHeaders(request, names) {
  *
  * `options.headers` adds request headers; the client's address and the
  * relayed client headers are set after them, so no caller replaces those.
+ * A redirect is not followed: it is no JSON answer, so it fails with a 502.
  */
 export async function backend(path, request, options = {}) {
   const headers = Object.fromEntries(
@@ -56,8 +64,9 @@ export async function backend(path, request, options = {}) {
       String(value),
     ]),
   );
-  Object.assign(headers, relayedHeaders(request, FORWARDED_HEADERS));
+  Object.assign(headers, relayedHeaders(request, CLIENT_HEADERS));
   headers["x-forwarded-for"] = clientIp(request);
+  Object.assign(headers, clientIpHeader(request));
   if (options.token) headers.authorization = `Bearer ${options.token}`;
   if (options.relay)
     headers["x-dms-oauth-relay"] = process.env.DMS_OAUTH_RELAY_SECRET ?? "";
@@ -66,7 +75,15 @@ export async function backend(path, request, options = {}) {
     method: options.method ?? "GET",
     headers,
     body: options.body === undefined ? undefined : JSON.stringify(options.body),
+    redirect: "manual",
   });
+  if (REDIRECT_STATUSES.has(response.status)) {
+    await response.body?.cancel();
+    console.error(
+      `DMS backend request redirected: ${response.status} ${options.method ?? "GET"} ${path}`,
+    );
+    throw new UpstreamError(502, GENERIC_ERROR_MESSAGE);
+  }
   const text = await response.text();
   let data;
   try {

package/templates/vue/server/auth/client-ip.mjs

@@ -1,10 +1,36 @@
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;
+
+function headerName(value) {
+  const name = (value ?? "").trim().toLowerCase();
+  return HEADER_NAME.test(name) ? name : undefined;
+}
+
 function trustedHops() {
   const value = Number.parseInt(process.env.DMS_TRUSTED_PROXY_HOPS ?? "0", 10);
   return Number.isSafeInteger(value) && value > 0 ? value : 0;
 }
 
+/**
+ * The client's address as the platform wrote it in the header
+ * `DMS_CLIENT_IP_HEADER` names (antelopejs.cloud: `X-Client-IP`), if the
+ * request carries it. The platform overwrites that header on every request,
+ * so its presence also vouches for the platform's `X-Forwarded-*`. On a path
+ * the platform does not front (a private call from another service), it is
+ * absent and the request falls back to `DMS_TRUSTED_PROXY_HOPS`.
+ */
+function platformClientIp(request) {
+  const name = headerName(process.env.DMS_CLIENT_IP_HEADER);
+  if (!name) return undefined;
+  const value = request.headers?.[name];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function isProxyTrusted(request) {
+  return Boolean(platformClientIp(request)) || trustedHops() > 0;
+}
+
 export function requestScheme(request) {
-  if (trustedHops()) {
+  if (isProxyTrusted(request)) {
     const forwarded = String(request.headers["x-forwarded-proto"] ?? "")
       .split(",")
       .map((value) => value.trim().toLowerCase())
@@ -16,7 +42,7 @@ export function requestScheme(request) {
 }
 
 function requestHost(request) {
-  if (!trustedHops()) return request.headers.host;
+  if (!isProxyTrusted(request)) return request.headers.host;
   return (
     String(request.headers["x-forwarded-host"] ?? "")
       .split(",")
@@ -31,12 +57,26 @@ function requestHost(request) {
  * the client a request comes from: its address, to limit each client, and
  * the scheme and host it asked, to check an Origin against.
  *
- * The client's own `X-Forwarded-For` is extended only when a trusted reverse
+ * Behind the platform, `X-Forwarded-For` is the address it wrote. Otherwise
+ * the client's own `X-Forwarded-For` is extended only when a trusted reverse
  * proxy wrote it (`DMS_TRUSTED_PROXY_HOPS` above `0`): otherwise any caller
  * could have, and the socket's address replaces it. The scheme and the host
  * are read the same way as the CSRF origin check reads them.
  */
 export function forwardedHeaders(request) {
+  const headers = {
+    "x-forwarded-for": forwardedFor(request),
+    "x-forwarded-proto": requestScheme(request),
+    ...clientIpHeader(request),
+  };
+  const host = requestHost(request);
+  if (host) headers["x-forwarded-host"] = host;
+  return headers;
+}
+
+function forwardedFor(request) {
+  const platformIp = platformClientIp(request);
+  if (platformIp) return platformIp;
   const socketIp = request.socket?.remoteAddress || "unknown";
   const incoming = trustedHops()
     ? String(request.headers["x-forwarded-for"] ?? "")
@@ -44,13 +84,18 @@ export function forwardedHeaders(request) {
         .map((value) => value.trim())
         .filter(Boolean)
     : [];
-  const headers = {
-    "x-forwarded-for": [...incoming, socketIp].join(", "),
-    "x-forwarded-proto": requestScheme(request),
-  };
-  const host = requestHost(request);
-  if (host) headers["x-forwarded-host"] = host;
-  return headers;
+  return [...incoming, socketIp].join(", ");
+}
+
+/**
+ * The `DMS_CLIENT_IP_HEADER` header of a backend request, set to the client
+ * address this server resolved, so the backend reads the same address
+ * without counting hops. Always written, never relayed: a value the caller
+ * sent is replaced. None when the variable is unset.
+ */
+export function clientIpHeader(request) {
+  const name = headerName(process.env.DMS_CLIENT_IP_HEADER);
+  return name ? { [name]: clientIp(request) } : {};
 }
 
 export function isSameOrigin(request) {
@@ -67,6 +112,8 @@ export function isSameOrigin(request) {
 }
 
 export function clientIp(request) {
+  const platformIp = platformClientIp(request);
+  if (platformIp) return platformIp;
   const socketIp = request.socket?.remoteAddress || "unknown";
   const hops = trustedHops();
   if (!hops) return socketIp;
@@ -79,14 +126,6 @@ export function clientIp(request) {
 }
 
 const DEFAULT_COUNTRY_HEADER = "CF-IPCountry";
-const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;
-
-function countryHeader() {
-  const name = (process.env.DMS_COUNTRY_HEADER ?? DEFAULT_COUNTRY_HEADER)
-    .trim()
-    .toLowerCase();
-  return HEADER_NAME.test(name) ? name : undefined;
-}
 
 /**
  * The client's country header, as the backend request headers to add.
@@ -94,12 +133,15 @@ function countryHeader() {
  * The header is the one `DMS_COUNTRY_HEADER` names (`CF-IPCountry` by
  * default, empty to relay none), the name the DMS reads from
  * `auth.signInCountry.header`. Like `X-Forwarded-For`, it is only believed
- * from a trusted reverse proxy: with `DMS_TRUSTED_PROXY_HOPS` at `0`, any
- * caller could have set it, so nothing is relayed.
+ * from a trusted reverse proxy (the platform's client IP header, or
+ * `DMS_TRUSTED_PROXY_HOPS` above `0`): otherwise any caller could have set
+ * it, so nothing is relayed.
  */
 export function clientCountryHeader(request) {
-  const name = countryHeader();
-  if (!name || !trustedHops()) return {};
+  const name = headerName(
+    process.env.DMS_COUNTRY_HEADER ?? DEFAULT_COUNTRY_HEADER,
+  );
+  if (!name || !isProxyTrusted(request)) return {};
   const value = request.headers?.[name];
   return typeof value === "string" && value.trim()
     ? { [name]: value.trim() }

package/templates/vue/server/auth/session.mjs

@@ -92,16 +92,9 @@ function attributes(maxAge, path = "/") {
   return `Path=${path}; HttpOnly; SameSite=Lax${lifetime}${secure}`;
 }
 
-/**
- * Whether a session outlives the browser. Only a session written with
- * `persistent: false` says no.
- */
-function isPersistent(session) {
-  return session?.persistent !== false;
-}
-
-function lifetime(persistent) {
-  return persistent ? MAX_AGE : undefined;
+/** A session outlives the browser only when it is written `persistent: true`. */
+function lifetime(session) {
+  return session.persistent === true ? MAX_AGE : undefined;
 }
 
 function appendCookie(response, name, value, cookieAttributes) {
@@ -130,7 +123,7 @@ export function writeSession(response, session) {
     response,
     SESSION_COOKIE,
     encode(session),
-    attributes(lifetime(isPersistent(session))),
+    attributes(lifetime(session)),
   );
 }
 

package/templates/vue/server/backend-proxies.mjs

@@ -39,6 +39,11 @@ export function proxyRejection(pattern, options) {
     return "its options are not an object";
   if (options?.auth !== undefined && !PROXY_AUTH_MODES.includes(options.auth))
     return `auth is not one of ${PROXY_AUTH_MODES.map((mode) => `"${mode}"`).join(", ")}`;
+  if (
+    options?.maxBodyBytes !== undefined &&
+    !(Number.isSafeInteger(options.maxBodyBytes) && options.maxBodyBytes > 0)
+  )
+    return "maxBodyBytes is not a positive whole number of bytes";
   return undefined;
 }
 
@@ -48,6 +53,7 @@ function compileProxy(pattern, options, owner) {
     path: pattern,
     owner,
     auth: options?.auth ?? DEFAULT_AUTH,
+    maxBodyBytes: options?.maxBodyBytes,
   };
 }
 
@@ -56,7 +62,8 @@ function compileProxy(pattern, options, owner) {
  *
  * @param declared `{ id, pattern, options }` per `registerBackendProxy` call,
  *   from the highest-priority module down
- * @param manifest `{ module, path, auth? }` per backend module declaration
+ * @param manifest `{ module, path, auth?, maxBodyBytes? }` per backend
+ *   module declaration
  * @param warn Reports a declaration problem
  * @returns The proxies, the most specific pattern first: a request reaches
  *   the first that matches
@@ -77,7 +84,11 @@ export function resolveBackendProxies(declared, manifest, warn) {
   for (const { id, pattern, options } of declared)
     add(pattern, options, `Frontend module ${id}`);
   for (const entry of manifest)
-    add(entry?.path, { auth: entry?.auth }, `Backend module ${entry?.module}`);
+    add(
+      entry?.path,
+      { auth: entry?.auth, maxBodyBytes: entry?.maxBodyBytes },
+      `Backend module ${entry?.module}`,
+    );
   return [...kept.values()].sort(
     (left, right) => right.pattern.specificity - left.pattern.specificity,
   );

package/templates/vue/server/backend-response.mjs

@@ -4,7 +4,6 @@
 // allows.
 
 import { GENERIC_ERROR_MESSAGE } from "./auth/backend.mjs";
-import { isWaitable } from "./backend-wake.mjs";
 import { isFrontendVisit, redirectFrontendVisit } from "./inertia.mjs";
 
 // What a JSON caller gets when the backend fails: the generic i18n key of the
@@ -20,13 +19,10 @@ const FORBIDDEN = 403;
 const FRONTEND_ORIGIN = "http://frontend.local";
 
 export class BackendResponseError extends Error {
-  constructor(status, code, retryAfter) {
+  constructor(status, code) {
     super(`DMS backend returned ${status}`);
     this.status = status;
     this.code = code;
-    // Set only for a cold-start answer, so the visitor is told when to try
-    // again instead of getting an opaque failure.
-    this.retryAfter = retryAfter;
   }
 }
 
@@ -47,14 +43,7 @@ async function refusalCode(response) {
 
 /** The error for a failed backend response, with its typed code if any. */
 export async function backendResponseError(response) {
-  const retryAfter = isWaitable(response)
-    ? (response.headers.get("retry-after") ?? undefined)
-    : undefined;
-  return new BackendResponseError(
-    response.status,
-    await refusalCode(response),
-    retryAfter,
-  );
+  return new BackendResponseError(response.status, await refusalCode(response));
 }
 
 /**

package/templates/vue/server/cli-report.mjs

@@ -2,7 +2,9 @@
 // `ajs dms start`, it reports over IPC and the CLI words what the user reads.
 // Started on its own, it prints the line itself.
 
+import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { stripVTControlCharacters } from "node:util";
 
 const WILDCARD_ADDRESSES = ["0.0.0.0", "::"];
 
@@ -45,31 +47,53 @@ export async function reportListenError(error, host, port) {
   process.exit(1);
 }
 
+/** The `[PARSE_ERROR] ` Rolldown puts in front of what it says. */
+const RULE_PREFIX = /^\[[A-Z_]+\]\s*/;
+
+/** The first problem Rolldown reports when it cannot bundle a config. */
+function bundlerError(error) {
+  const first = error?.errors?.[0];
+  return first && typeof first === "object" ? first : undefined;
+}
+
 /**
- * Where a startup error points, when it says: esbuild's location for a config
- * it could not bundle, Rollup's for a plugin that failed on a file.
+ * Where a startup error points, when it says: Rolldown's location for a config
+ * it could not bundle (the line is read back from the file, which Rolldown
+ * only draws in a colored frame), Rollup's for a plugin that failed on a file.
  */
 function errorLocation(error) {
-  const location = error?.errors?.[0]?.location;
-  if (location?.file) {
-    return {
-      file: resolve(location.file),
-      line: location.line,
-      column: location.column,
-      lineText: location.lineText,
-    };
-  }
-  const file = error?.loc?.file ?? error?.id;
+  const source = bundlerError(error) ?? error;
+  const file = source?.loc?.file ?? source?.id;
   if (typeof file !== "string") return undefined;
-  return { file, line: error.loc?.line, column: error.loc?.column };
+  const { line, column } = source.loc ?? {};
+  return {
+    file: resolve(file),
+    line,
+    column,
+    lineText: line === undefined ? undefined : readLine(file, line),
+  };
+}
+
+/** Line `line` (1-based) of `file`, `undefined` when it cannot be read. */
+function readLine(file, line) {
+  try {
+    return readFileSync(file, "utf8").split(/\r?\n/)[line - 1];
+  } catch {
+    return undefined;
+  }
 }
 
-/** The first line of what went wrong, without esbuild's error count. */
+/** The first line of what went wrong, without Rolldown's rule and frame. */
 function errorText(error) {
-  const text = error?.errors?.[0]?.text;
-  if (typeof text === "string") return text;
-  const message = error instanceof Error ? error.message : String(error);
-  return message.split(/\r?\n/)[0];
+  const reported = bundlerError(error);
+  const message = reported
+    ? String(reported.message)
+    : error instanceof Error
+      ? error.message
+      : String(error);
+  return stripVTControlCharacters(message)
+    .split(/\r?\n/)[0]
+    .replace(RULE_PREFIX, "");
 }
 
 /**

package/templates/vue/server/client-manifest.mjs

@@ -1,5 +1,5 @@
-// Reading the built client manifest and turning a rendered page into the style
-// and module-preload tags its HTML needs.
+// Reading the built client manifest and turning the components a server render
+// created into the stylesheet links its HTML needs.
 //
 // Lives apart from server.mjs so the file stays under the size the linter
 // allows. Production-only: in dev, Vite serves these itself.
@@ -30,29 +30,6 @@ export function productionHtmlTemplate() {
   return productionTemplate;
 }
 
-export function normalizeDmsName(name) {
-  return name
-    .replace(/^lazy/i, "")
-    .replace(/^dms[-_]?/i, "")
-    .replace(/[^a-z0-9]/gi, "")
-    .toLowerCase();
-}
-
-export function collectRenderedComponentNames(value, names) {
-  if (!value || typeof value !== "object") return;
-  if (Array.isArray(value)) {
-    value.forEach((entry) => {
-      collectRenderedComponentNames(entry, names);
-    });
-    return;
-  }
-  if (typeof value.componentName === "string")
-    names.add(normalizeDmsName(value.componentName));
-  Object.values(value).forEach((entry) => {
-    collectRenderedComponentNames(entry, names);
-  });
-}
-
 function productionClientManifest() {
   if (clientManifest) return clientManifest;
   if (!existsSync(CLIENT_MANIFEST_PATH)) return undefined;
@@ -60,34 +37,6 @@ function productionClientManifest() {
   return clientManifest;
 }
 
-function sourceComponentName(source) {
-  const filename =
-    source
-      .split("/")
-      .at(-1)
-      ?.replace(/\.vue$/, "") ?? "";
-  return normalizeDmsName(filename);
-}
-
-function matchedPageManifestEntries(page, manifest) {
-  const names = new Set();
-  const layout = page.props?.page?.layout;
-  collectRenderedComponentNames(layout, names);
-  [
-    page.props?.page?.componentName,
-    layout?.componentName,
-    layout?.layout?.componentName,
-  ].forEach((name) => {
-    if (typeof name === "string") names.add(normalizeDmsName(name));
-  });
-  return Object.entries(manifest)
-    .filter(
-      ([source, entry]) =>
-        entry.isDynamicEntry && names.has(sourceComponentName(source)),
-    )
-    .map(([key]) => key);
-}
-
 function collectManifestStyles(manifest, key, styles, visited) {
   if (visited.has(key)) return;
   visited.add(key);
@@ -98,19 +47,46 @@ function collectManifestStyles(manifest, key, styles, visited) {
     collectManifestStyles(manifest, imported, styles, visited);
 }
 
-export function pageModuleStyles(page) {
+/**
+ * The stylesheets the client build split out for the components a server
+ * render created, each named by the module id `@vitejs/plugin-vue` records in
+ * the render's `ssrContext.modules`. That id is the component's path from the
+ * workspace root, the very key the client manifest gives a lazily loaded
+ * component, so the lookup needs no guessing from names. A component bundled
+ * into another chunk is no key of its own: its stylesheet comes with that
+ * chunk's, reached through the `imports` of the component that loaded it.
+ */
+function renderedModuleStyles(modules = []) {
   const manifest = productionClientManifest();
   const styles = new Set();
   if (!manifest) return styles;
   const visited = new Set();
-  for (const key of matchedPageManifestEntries(page, manifest))
-    collectManifestStyles(manifest, key, styles, visited);
+  for (const id of modules)
+    collectManifestStyles(manifest, id, styles, visited);
   return styles;
 }
 
-export function pageModulePreloads(page, template) {
-  return [...pageModuleStyles(page)]
+/**
+ * Links the stylesheets of every component the server rendered and the built
+ * template does not link already, so that none of them waits for its chunk's
+ * JavaScript to arrive: the HTML would otherwise paint unstyled and shift once
+ * it does. A component the render did not reach gets no link.
+ */
+export function renderedModuleStyleTags(modules, template) {
+  return [...renderedModuleStyles(modules)]
     .filter((file) => !template.includes(`href="/${file}"`))
     .map((file) => `<link rel="stylesheet" href="/${file}">`)
     .join("");
 }
+
+/**
+ * The link that preloads the built catalog of `locale`, the one the page was
+ * rendered with: the browser fetches it next to the entry rather than once the
+ * entry runs and asks for it, which would put a round trip before hydration.
+ * Nothing without a production build (Vite serves the sources in development).
+ */
+export function localeCatalogPreloadTag(locale) {
+  const manifest = productionClientManifest();
+  const file = locale && manifest?.[`locales.generated/${locale}.ts`]?.file;
+  return file ? `<link rel="modulepreload" crossorigin href="/${file}">` : "";
+}

package/templates/vue/server/dev-private-files.mjs

@@ -5,7 +5,7 @@
 // written, and the modules' server code is materialized under it. Vite serves
 // any file under its root, as is, `?raw`, `?import` or `?url`. Its
 // `server.fs.deny` list covers most of these, but not every query combination
-// (`?import&raw` gets through in Vite 7.2), so a middleware ahead of Vite's own
+// (`?import&raw` got through in Vite 7.2; Vite 8.3 refuses it itself), so a middleware ahead of Vite's own
 // answers 403 by path, whatever the query, and a load guard refuses them to
 // any client request that reaches the transform pipeline another way.
 // `ssrLoadModule`, which loads the server modules, is left alone.

package/templates/vue/server/dev-styles.mjs

@@ -18,7 +18,7 @@
 
 import { join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { pageModulePreloads } from "./client-manifest.mjs";
+import { renderedModuleStyleTags } from "./client-manifest.mjs";
 
 const PROJECT_ROOT = fileURLToPath(new URL("../", import.meta.url));
 const STYLE_ATTRIBUTE = "data-dms-dev-style";
@@ -47,7 +47,18 @@ function ssrModuleGraph(devServer) {
   return devServer.environments?.ssr?.moduleGraph ?? devServer.moduleGraph;
 }
 
+// Vite only treats an id as a stylesheet when the language is the LAST thing in
+// it, and a component's style block ends in `&lang.css`. Appending `&direct`
+// after that makes Vite skip its stylesheet pipeline, so the block comes back
+// as written: `@import "package/dist/style.css"` is left for the browser, which
+// resolves it against the page URL and gets a 404. `direct` therefore goes in
+// front of the trailing language segment.
+const TRAILING_LANG = /&(lang\.[^&?]*)$/;
+
 function directUrl(url) {
+  if (SFC_STYLE.test(url) && TRAILING_LANG.test(url)) {
+    return url.replace(TRAILING_LANG, "&direct&$1");
+  }
   return `${url}${url.includes("?") ? "&" : "?"}direct`;
 }
 
@@ -96,11 +107,11 @@ export async function developmentStyleTags(devServer) {
 
 /**
  * The style tags a document needs, whichever server is answering it: collected
- * from the live module graph in development, read from the build manifest in
- * production.
+ * from the live module graph in development, read from the build manifest for
+ * the components the render created (`modules`) in production.
  */
-export async function documentStyleTags(devServer, page, template) {
+export async function documentStyleTags(devServer, modules, template) {
   return devServer
     ? developmentStyleTags(devServer)
-    : pageModulePreloads(page, template);
+    : renderedModuleStyleTags(modules, template);
 }

package/templates/vue/server/homepage.mjs

@@ -11,6 +11,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { publicOptionsOf } from "./public-options.mjs";
 
 const PROJECT_ROOT = fileURLToPath(new URL("../", import.meta.url));
 const REGISTRY_PATH = join(PROJECT_ROOT, "generated-frontend-modules.json");
@@ -26,7 +27,9 @@ function findHomepage(options) {
     .find((homepage) => homepage !== undefined);
 }
 
+const OPTIONS = publicOptionsOf(REGISTRY);
+
 export const HOMEPAGE =
   REGISTRY.modules
-    .map((module) => findHomepage(module.options))
+    .map((module) => findHomepage(OPTIONS[module.id]))
     .find(Boolean) ?? "/";