@antelopejs/dms-frontend 0.5.6 → 0.6.1

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

@@ -0,0 +1,225 @@
+// Loads what the frontend modules declare in their `dms.server.ts` and hands
+// a request to the module route it reaches. In development the declarations
+// come from Vite (`ssrLoadModule`), so an edited entry or handler answers on
+// the next request; in production from the bundle `ajs dms build` makes
+// (`dist/server-modules`). A workspace built before the feature has none.
+
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { allowedEstablishEndpoints } from "./auth/establish-endpoints.mjs";
+import { serverAuth } from "./auth-hooks.mjs";
+import { answerModuleRoute } from "./module-event.mjs";
+import {
+  matchModuleRoute,
+  mayHaveModuleRoute,
+  moduleRouteMethods,
+  resolveServerDeclarations,
+} from "./module-routes.mjs";
+import {
+  allowedPublicEndpoints,
+  environmentBackendProxies,
+  readDeclaredBackendProxies,
+} from "./public-endpoints.mjs";
+
+const WORKSPACE_ROOT = new URL("../", import.meta.url);
+const SOURCE_LOADER = "/server-modules.generated.ts";
+const BUILT_LOADER = new URL(
+  "dist/server-modules/server-modules.generated.js",
+  WORKSPACE_ROOT,
+);
+const REGISTRY_FILE = new URL(
+  "generated-frontend-modules.json",
+  WORKSPACE_ROOT,
+);
+const SERVER_OPTIONS_FILE = new URL(
+  "generated-server-options.json",
+  WORKSPACE_ROOT,
+);
+
+let builtDeclarations;
+let lastDeclarations = [];
+let lastLoadError;
+const resolved = new WeakMap();
+
+function readJsonFile(url, fallback) {
+  try {
+    return JSON.parse(readFileSync(url, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+/** Sets `value` at `path` when the object holding it exists but lacks it. */
+function fillPath(target, path, value) {
+  let node = target;
+  for (const key of path.slice(0, -1)) {
+    if (typeof node[key] !== "object" || node[key] === null) return;
+    node = node[key];
+  }
+  const key = path.at(-1);
+  if (typeof node[key] !== "string" || node[key] === "") node[key] = value;
+}
+
+/**
+ * Each module's private options, the secrets the manifest publishes first:
+ * the environment variable of a secret (`DMS_HTML_RENDER_SECRET`,
+ * `DMS_OAUTH_RELAY_SECRET`) only fills in a section that carries none.
+ *
+ * @param modules The private options by module id, as the manifest published
+ *   them
+ * @param environment The variables by the path of the secret they stand for
+ * @param env The process environment
+ */
+export function privateOptionsWithFallbacks(modules, environment, env) {
+  for (const options of Object.values(modules))
+    for (const [name, path] of Object.entries(environment))
+      if (env[name]) fillPath(options, path, env[name]);
+  return modules;
+}
+
+function readPrivateOptions(env = process.env) {
+  const { modules = {}, environment = {} } = readJsonFile(
+    SERVER_OPTIONS_FILE,
+    {},
+  );
+  return privateOptionsWithFallbacks(modules, environment, env);
+}
+
+function readPublicOptions() {
+  const registry = readJsonFile(REGISTRY_FILE, { modules: [] });
+  return Object.fromEntries(
+    registry.modules.map((module) => [module.id, module.options]),
+  );
+}
+
+async function loadDeclarations(devServer) {
+  if (devServer)
+    return (await devServer.ssrLoadModule(SOURCE_LOADER)).serverModules;
+  if (!existsSync(fileURLToPath(BUILT_LOADER))) return [];
+  builtDeclarations ??= import(BUILT_LOADER.href).then(
+    (loaded) => loaded.serverModules,
+  );
+  return builtDeclarations;
+}
+
+/**
+ * The declarations to serve. A module entry that fails to load in development
+ * (a syntax error being typed) is reported once, and the last routes that
+ * loaded keep answering meanwhile.
+ */
+async function currentDeclarations(devServer) {
+  try {
+    lastDeclarations = (await loadDeclarations(devServer)) ?? [];
+    lastLoadError = undefined;
+  } catch (error) {
+    if (!devServer) throw error;
+    const message = error instanceof Error ? error.message : String(error);
+    if (message !== lastLoadError)
+      console.error("DMS server modules failed to load", error);
+    lastLoadError = message;
+  }
+  return lastDeclarations;
+}
+
+/**
+ * A set of server modules, resolved for a deployment.
+ *
+ * @param declarations `{ id, priority, setup }` per module with a dms.server.ts
+ * @param deployment `{ publicOptions, privateOptions, authEstablishEndpoints,
+ *   publicEndpoints, backendProxies, warn }`: each module's options by id,
+ *   the session-opening endpoints as a function (the environment can change
+ *   them), the public endpoints, the backend proxies the manifest declares
+ *   (`{ module, path, auth? }`), and where declaration problems are reported
+ * @returns `{ routes, auth, context(id), serverAuth }`: `context` is what a
+ *   handler of that module reads besides its request, `serverAuth` the
+ *   session logic the module owning sign-in provides (see `auth-hooks.mjs`)
+ */
+export function createServerModules(declarations, deployment) {
+  const resolution = resolveServerDeclarations(
+    declarations,
+    deployment.warn,
+    deployment.publicEndpoints ?? [],
+    deployment.backendProxies ?? [],
+  );
+  const context = (id) => ({
+    module: {
+      id,
+      options: deployment.publicOptions?.[id],
+      privateOptions: deployment.privateOptions?.[id],
+    },
+    app: {
+      authEstablishEndpoints: deployment.authEstablishEndpoints?.() ?? [],
+    },
+    // The module whose sealed cookies are the `dms_*` ones.
+    authOwner: resolution.auth?.id,
+  });
+  return {
+    ...resolution,
+    context,
+    serverAuth: serverAuth(resolution.auth, context),
+  };
+}
+
+/** Resolved once per set of declarations: in development, once per edit. */
+function serverModules(declarations) {
+  let modules = resolved.get(declarations);
+  if (!modules) {
+    modules = createServerModules(declarations, {
+      publicOptions: readPublicOptions(),
+      privateOptions: readPrivateOptions(),
+      authEstablishEndpoints: () => allowedEstablishEndpoints(),
+      publicEndpoints: allowedPublicEndpoints(),
+      backendProxies: [
+        ...readDeclaredBackendProxies(),
+        ...environmentBackendProxies(),
+      ],
+      warn: (message) => console.warn(message),
+    });
+    resolved.set(declarations, modules);
+  }
+  return modules;
+}
+
+/**
+ * The server modules of this deployment, resolved.
+ *
+ * @param devServer Vite in development, `undefined` in production
+ */
+export async function loadServerModules(devServer) {
+  return serverModules(await currentDeclarations(devServer));
+}
+
+/**
+ * Answers `request` with the module route it reaches, if any. A path a
+ * module route serves is the module's for every method: another method is
+ * answered `405`.
+ *
+ * @param request The Node request
+ * @param response The Node response
+ * @param pathname The request's normalized path
+ * @param modules What `loadServerModules` or `createServerModules` returned
+ * @returns Whether a module route answered
+ */
+export async function handleModuleRoute(request, response, pathname, modules) {
+  if (!mayHaveModuleRoute(pathname)) return false;
+  const reached = matchModuleRoute(modules.routes, request.method, pathname);
+  if (!reached) {
+    const allowed = moduleRouteMethods(modules.routes, pathname);
+    if (!allowed.length) return false;
+    response.writeHead(405, {
+      allow: allowed.join(", "),
+      "content-type": "application/json",
+    });
+    response.end(JSON.stringify({ message: "Method not allowed" }));
+    return true;
+  }
+  await answerModuleRoute({
+    request,
+    response,
+    route: reached.route,
+    params: reached.params,
+    view: modules.serverAuth.view,
+    ...modules.context(reached.route.id),
+  });
+  return true;
+}

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

@@ -0,0 +1,65 @@
+// Serves a frontend module's `dms.server.ts` routes the way the frontend
+// server does, for the module's own tests: same router, same event, same
+// cookie jar and the same defaults. Imported from
+// `@antelopejs/dms-frontend/templates/vue/server/module-testing.mjs`; the
+// server reads `DMS_API_BASE_URL` and `DMS_SESSION_SECRET` from the
+// environment, as in production.
+
+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";
+
+/** What the frontend server answers an API request whose handler failed. */
+function writeFailure(error, response) {
+  const status = Number.isInteger(error?.status) ? error.status : 502;
+  const body =
+    error instanceof UpstreamError || error instanceof RequestBodyError
+      ? { message: error.message }
+      : UNEXPECTED_ERROR_BODY;
+  if (!response.headersSent)
+    response.writeHead(status, { "content-type": "application/json" });
+  response.end(JSON.stringify(body));
+}
+
+/**
+ * Starts an HTTP server on a free local port answering the modules' routes,
+ * and `404` to anything else.
+ *
+ * @param declarations `{ id, priority?, setup }` per module, `setup` being
+ *   the default export of its `dms.server.ts`
+ * @param deployment `{ publicOptions?, privateOptions?, authEstablishEndpoints?,
+ *   publicEndpoints? }`, options by module id. The private options are used
+ *   as given, as the server uses the manifest's: no environment variable
+ *   replaces a secret they hold
+ * @returns `{ url, modules, warnings, close() }`
+ */
+export async function serveModuleRoutes(declarations, deployment = {}) {
+  const warnings = [];
+  const endpoints = deployment.authEstablishEndpoints ?? [];
+  const modules = createServerModules(declarations, {
+    ...deployment,
+    authEstablishEndpoints: () => endpoints,
+    warn: (message) => warnings.push(message),
+  });
+  const server = createServer((request, response) => {
+    const { pathname } = new URL(request.url, "http://frontend.local");
+    handleModuleRoute(request, response, pathname, modules)
+      .then((answered) => {
+        if (!answered) response.writeHead(404).end();
+      })
+      .catch((error) => writeFailure(error, response));
+  });
+  await new Promise((settle) => server.listen(0, "127.0.0.1", settle));
+  const { port } = server.address();
+  return {
+    url: `http://127.0.0.1:${port}`,
+    modules,
+    warnings,
+    close: () =>
+      new Promise((settle) => {
+        server.closeAllConnections();
+        server.close(() => settle());
+      }),
+  };
+}

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

@@ -0,0 +1,151 @@
+// The props of a DMS page visit, and which of them the browser already has.
+//
+// Lives apart from server.mjs so the file stays under the size the linter
+// allows.
+
+import { createHash } from "node:crypto";
+import { readSession } from "./auth/session.mjs";
+import { BackendResponseError } from "./backend-response.mjs";
+import { heldOnceProps, requestedProps } from "./inertia.mjs";
+
+export const SHARED_PROP = "shared";
+/**
+ * How long a browser reuses the site layout it was sent before a visit asks
+ * for it again. The layout is the whole menu with each entry's access, the
+ * bulk of every page object; a change the backend announces (`menu-changed`)
+ * reloads it sooner, and the backend checks access on every request whatever
+ * the menu shows.
+ */
+export const SHARED_PROP_TTL_MS = 5 * 60 * 1000;
+const SITE_LAYOUT_PATH = "/dms/sitelayout";
+const NOT_FOUND = 404;
+
+/**
+ * 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.
+ */
+export function sharedOnceKey(session) {
+  const identity = `${session?.accountId ?? ""}\n${session?.activeTenantId ?? ""}`;
+  const digest = createHash("sha256").update(identity).digest("base64url");
+  return `${SHARED_PROP}:${digest.slice(0, 16)}`;
+}
+
+/**
+ * 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.
+ */
+function holdsOnlyThisLayout(held, sharedKey) {
+  if (!held.has(sharedKey)) return false;
+  return ![...held].some(
+    (key) => key !== sharedKey && key.startsWith(`${SHARED_PROP}:`),
+  );
+}
+
+// The parameters of the page request itself, which a page query of the same
+// name cannot override.
+const PAGE_REQUEST_PARAMETERS = new Set(["path", SHARED_PROP]);
+
+/**
+ * The backend request of a page, with the query of the visit: a header
+ * button's availability reads it (`?workspace=` names the record a page acts
+ * 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.
+ */
+function pagePath(url, withShared) {
+  const query = new URLSearchParams({ path: url.pathname });
+  const pageQuery = new Map();
+  for (const [name, value] of url.searchParams) {
+    if (!PAGE_REQUEST_PARAMETERS.has(name)) pageQuery.set(name, value);
+  }
+  for (const [name, value] of pageQuery) query.set(name, value);
+  if (!withShared) query.set(SHARED_PROP, "false");
+  return `/dms/page?${query}`;
+}
+
+/** A page only the frontend has: a custom page, with no backend data. */
+function frontendOnlyPage(pathname, signInPath) {
+  return {
+    componentName: pathname,
+    isFrontendOnly: true,
+    route: {
+      fullId: pathname.slice(1).replaceAll("/", "."),
+      fullSlug: pathname,
+      hasAccess: pathname.startsWith(`${signInPath}/`),
+    },
+    layout: { layout: { componentName: "DefaultLayout" } },
+  };
+}
+
+async function loadPage(
+  url,
+  withShared,
+  { fetchJson, isFrontendPage },
+  signInPath,
+) {
+  const { pathname } = url;
+  try {
+    const { shared, ...page } = await fetchJson(pagePath(url, withShared));
+    return { page, shared };
+  } catch (error) {
+    if (!(error instanceof BackendResponseError) || error.status !== NOT_FOUND)
+      throw error;
+    if (!(await isFrontendPage(pathname))) throw error;
+    return {
+      page: frontendOnlyPage(pathname, signInPath),
+      shared: undefined,
+    };
+  }
+}
+
+/**
+ * The props of the page a request visits, with the once props to declare.
+ *
+ * The site layout (`shared`) is a once prop: a visit sends it when the browser
+ * does not hold it for this account and workspace, or when a partial reload
+ * asks for it, and otherwise asks the backend for the page alone. A partial
+ * reload gets the props it names, and the layout too when the browser's copy
+ * is not this session's.
+ */
+export async function loadPageProps(request, backend, auth) {
+  const url = new URL(request.url, "http://frontend.local");
+  const { pathname } = url;
+  const sealed = readSession(request);
+  const { user, session } = auth.view(sealed);
+  const { partial, wants } = requestedProps(request);
+  // The sealed session names the account and workspace, whatever the module
+  // owning sign-in shows a page of it.
+  const sharedKey = sharedOnceKey(sealed);
+  const holdsShared = holdsOnlyThisLayout(heldOnceProps(request), sharedKey);
+  const withShared = (partial && wants(SHARED_PROP)) || !holdsShared;
+  const props = {};
+  if (wants("path")) props.path = pathname;
+  // A partial reload merges what it gets into the page on screen: a session
+  // that ended has to be sent as one, not left out.
+  if (wants("user") && (user || partial)) props.user = user ?? null;
+  if (wants("session") && (session || partial)) props.session = session ?? null;
+  let shared;
+  if (wants("page")) {
+    const loaded = await loadPage(url, withShared, backend, auth.signInPath);
+    props.page = loaded.page;
+    shared = loaded.shared;
+  } else if (withShared) {
+    shared = await backend.fetchJson(SITE_LAYOUT_PATH);
+  }
+  if (shared) props[SHARED_PROP] = shared;
+  // 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.
+  const onceProps =
+    shared || holdsShared
+      ? {
+          [sharedKey]: {
+            prop: SHARED_PROP,
+            expiresAt: shared ? Date.now() + SHARED_PROP_TTL_MS : null,
+          },
+        }
+      : undefined;
+  return { props, onceProps };
+}

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

@@ -0,0 +1,38 @@
+// 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.
+
+const SEGMENT = /^[A-Za-z0-9._~-]+$/;
+
+/**
+ * A pattern made usable, or `undefined` when it is malformed.
+ *
+ * `specificity` orders matching patterns from the least to the most specific:
+ * more literal segments first, then a single-segment `*` over `**`.
+ */
+export function compilePathPattern(pattern) {
+  if (typeof pattern !== "string" || !pattern.startsWith("/")) return undefined;
+  const segments = pattern === "/" ? [] : pattern.slice(1).split("/");
+  const deep = segments.at(-1) === "**";
+  const literal = deep ? segments.slice(0, -1) : segments;
+  if (
+    literal.some(
+      (segment) =>
+        segment !== "*" &&
+        (!SEGMENT.test(segment) || segment === "." || segment === ".."),
+    )
+  )
+    return undefined;
+  const body = literal
+    .map((segment) =>
+      segment === "*" ? "/[^/]+" : `/${segment.replaceAll(".", "\\.")}`,
+    )
+    .join("");
+  const matcher = new RegExp(`^${body}${deep ? "(?:/.*)?" : ""}/?$`);
+  const literals = literal.filter((segment) => segment !== "*").length;
+  return {
+    pattern,
+    specificity: literals * 4 + literal.length * 2 + (deep ? 0 : 1),
+    test: (pathname) => matcher.test(pathname === "" ? "/" : pathname),
+  };
+}

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

@@ -35,6 +35,7 @@ const RESERVED_HEADER =
   /^x-(?:forwarded-|real-ip$|dms-|inertia|http-method|method-override|original-|rewrite-)/;
 
 let declaredEndpoints;
+let declaredProxies;
 
 /**
  * The public endpoints the modules of this deployment declared, unchecked.
@@ -51,6 +52,50 @@ export function readDeclaredPublicEndpoints(file = DECLARED_ENDPOINTS_FILE) {
   }
 }
 
+/**
+ * The backend proxies the backend modules declared in the manifest, as
+ * `{ module, path, auth? }`, unchecked.
+ *
+ * @param file Generated file to read
+ */
+export function readDeclaredBackendProxies(file = DECLARED_ENDPOINTS_FILE) {
+  if (file === DECLARED_ENDPOINTS_FILE && declaredProxies)
+    return declaredProxies;
+  let proxies = [];
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    if (Array.isArray(parsed?.proxies)) proxies = parsed.proxies;
+  } catch {
+    // No file, or a broken one: no proxy declared.
+  }
+  if (file === DECLARED_ENDPOINTS_FILE) declaredProxies = proxies;
+  return proxies;
+}
+
+/**
+ * The backend proxies `DMS_BACKEND_PROXIES` adds: a JSON array of
+ * `{ path, auth? }`, as the manifest's `backendProxies`, for an operator.
+ *
+ * @param declaration The variable's value
+ */
+export function environmentBackendProxies(
+  declaration = process.env.DMS_BACKEND_PROXIES,
+) {
+  if (!declaration?.trim()) return [];
+  try {
+    const parsed = JSON.parse(declaration);
+    if (Array.isArray(parsed))
+      return parsed.map((entry) => ({
+        ...entry,
+        module: "DMS_BACKEND_PROXIES",
+      }));
+  } catch {
+    // Reported below.
+  }
+  console.warn("Ignoring DMS_BACKEND_PROXIES: not a JSON array");
+  return [];
+}
+
 function environmentEndpoints(declaration) {
   if (!declaration?.trim()) return [];
   try {
@@ -165,25 +210,38 @@ export function matchPublicEndpoint(
 }
 
 /**
- * How the proxy treats a request: the public endpoint it reaches, if any, and
- * whether it is refused for lacking a same-site Origin. A state-changing
- * request needs one, unless 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.
+ * How the proxy treats a request to a backend proxy: whether it sends the
+ * session, the extra headers it relays, and whether it refuses the request
+ * for lacking a same-site Origin.
+ *
+ * A proxy with `auth: "none"` never sends the session, so it needs no
+ * Origin. Under `auth: "session"`, a state-changing request needs one unless
+ * 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
+ * @returns `{ anonymous, headers, isRefused }`
  */
-export function proxyAccess(request, safeMethods) {
+export function proxyAccess(request, safeMethods, proxy) {
+  if (proxy.auth === "none")
+    return { anonymous: true, headers: [], isRefused: false };
   const publicEndpoint = matchPublicEndpoint(
     request.method,
     new URL(request.url, "http://frontend.local").pathname,
   );
-  const isRefused =
-    !publicEndpoint &&
-    !safeMethods.has(request.method) &&
-    !isSameOrigin(request);
-  return { publicEndpoint, isRefused };
+  if (publicEndpoint)
+    return {
+      anonymous: true,
+      headers: publicEndpoint.headers,
+      isRefused: false,
+    };
+  return {
+    anonymous: false,
+    headers: [],
+    isRefused: !safeMethods.has(request.method) && !isSameOrigin(request),
+  };
 }
 
 /** Answers the 403 of a request `proxyAccess` refused. */

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

@@ -0,0 +1,47 @@
+// Who answers a request: one owner per path, whoever asks and whatever the
+// method, in this order:
+//
+// 1. the renderer: its icon endpoint, Vite's URLs and the built assets, and
+//    any file it has (a development source, a built asset);
+// 2. the module routes of the modules' `dms.server.ts`;
+// 3. the backend proxies the modules declare (`registerBackendProxy`, the
+//    manifest's `backendProxies`);
+// 4. the pages, for everything else: a method other than `GET` and `HEAD` on a
+//    page path is a `404`.
+
+import { matchBackendProxy } from "./backend-proxies.mjs";
+import { isRendererFilePath, moduleRouteMethods } from "./module-routes.mjs";
+
+const PAGE_METHODS = new Set(["GET", "HEAD"]);
+
+/**
+ * The owner of a request.
+ *
+ * @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
+ *   file at that path
+ * @returns `{ kind: "renderer" }`, `{ kind: "module", id }`,
+ *   `{ kind: "backend", proxy }`, `{ kind: "page" }` or
+ *   `{ kind: "not-found" }`
+ */
+export function requestOwner(method, pathname, modules, hasRendererFile) {
+  if (isRendererFilePath(pathname) || hasRendererFile(pathname))
+    return { kind: "renderer" };
+  const route = modules.routes.find((candidate) =>
+    candidate.matcher.test(pathname),
+  );
+  if (route && moduleRouteMethods(modules.routes, pathname).length)
+    return { kind: "module", id: route.id };
+  const proxy = matchBackendProxy(modules.proxies ?? [], pathname);
+  if (proxy) return { kind: "backend", proxy };
+  return PAGE_METHODS.has(method) ? { kind: "page" } : { kind: "not-found" };
+}
+
+/** The `x-dms-route-owner` value of an owner, for the development server. */
+export function ownerLabel(owner) {
+  if (owner.kind === "module") return `module:${owner.id}`;
+  if (owner.kind === "backend") return `backend:${owner.proxy.path}`;
+  return owner.kind;
+}