@antelopejs/dms-frontend 0.7.1 → 0.9.0

package/templates/vue/server/in-place-render.mjs

@@ -0,0 +1,110 @@
+// A page that completes its query as it renders, rendered at that query in
+// the same request rather than answered with a redirect.
+//
+// Lives apart from server.mjs so the file stays under the size the linter
+// allows.
+
+import { ofetch } from "ofetch";
+
+/**
+ * How many times one request renders a page in place of a same-path redirect
+ * before it answers the redirect: a page that keeps changing its query.
+ */
+const IN_PLACE_RENDERS = 2;
+
+/**
+ * The key of a backend read a later render of the same request may reuse: a
+ * plain JSON `GET`, without hooks that would expect to see the response.
+ */
+function reusableReadKey(path, options, headers) {
+  const method = (options.method ?? "GET").toUpperCase();
+  if (method !== "GET" || options.body !== undefined) return undefined;
+  if (options.responseType && options.responseType !== "json") return undefined;
+  if (Object.keys(options).some((name) => /^on[A-Z]/.test(name)))
+    return undefined;
+  return JSON.stringify([
+    path,
+    options.query ?? options.params ?? null,
+    [...headers],
+  ]);
+}
+
+/**
+ * The backend reads of a request's server renders, sent with the request's
+ * `backendHeaders()` and the read's own. After `reuseCompletedReads()`, a later
+ * render of the same request is given a copy of each read a previous render
+ * completed instead of reading the backend again.
+ */
+export function serverReads(backendHeaders) {
+  const completed = new Map();
+  let reuse = false;
+  const read = (path, options = {}) => {
+    const headers = new Headers(backendHeaders());
+    new Headers(options.headers).forEach((value, name) => {
+      headers.set(name, value);
+    });
+    const key = reusableReadKey(path, options, headers);
+    if (reuse && key && completed.has(key))
+      return Promise.resolve(structuredClone(completed.get(key)));
+    const reading = ofetch(path, {
+      ...options,
+      baseURL: process.env.DMS_API_BASE_URL,
+      headers,
+    });
+    if (!key) return reading;
+    // A copy: the render that read it may still change the object it got. A
+    // body that cannot be copied is read again.
+    return reading.then((data) => {
+      try {
+        completed.set(key, structuredClone(data));
+      } catch {}
+      return data;
+    });
+  };
+  return Object.assign(read, {
+    reuseCompletedReads: () => {
+      reuse = true;
+    },
+  });
+}
+
+/**
+ * Whether a document request renders `location` in place of redirecting to
+ * it: a `GET` whose page only completes its query (`?workspace=`), on the
+ * same path. Any other redirect keeps its own response.
+ */
+function rendersInPlace(request, from, location) {
+  if (request.method !== "GET" || location.includes("#")) return false;
+  const current = new URL(from, "http://frontend.local");
+  const target = new URL(location, current);
+  return (
+    target.origin === current.origin && target.pathname === current.pathname
+  );
+}
+
+/**
+ * Renders a page document with `render(page)`. A page that completes its
+ * query as it renders (`router.replace` to the same path) is rendered again at
+ * that query, with the props `propsAt(props, url)` gives, reusing the reads
+ * the first render made (`fetch`), instead of being answered with a redirect
+ * the browser would follow with a whole new request. The page served then
+ * names the URL the document shows, which the browser puts in the address bar.
+ */
+export async function renderInPlace(request, page, fetch, render, propsAt) {
+  let rendered = await render(page);
+  let served = page;
+  for (
+    let pass = 0;
+    rendered.redirect &&
+    pass < IN_PLACE_RENDERS &&
+    rendersInPlace(request, served.url, rendered.redirect);
+    pass++
+  ) {
+    const url = new URL(rendered.redirect, "http://frontend.local");
+    const props = await propsAt(served.props, url);
+    served = { ...served, url: `${url.pathname}${url.search}`, props };
+    fetch.reuseCompletedReads();
+    rendered = await render(served);
+  }
+  return { rendered, served };
+}

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

@@ -4,7 +4,6 @@
 // limit, `no-store`). See `server-module.ts` for the types a module reads.
 
 import { Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
 import { backend, json, RequestBodyError } from "./auth/backend.mjs";
 import {
   clientIp,
@@ -23,7 +22,13 @@ import {
   writeSession,
 } from "./auth/session.mjs";
 import { renderEmailTemplate } from "./email.mjs";
+import {
+  isBackendUrl,
+  relayableCookies,
+  relayedLocation,
+} from "./proxy-redirects.mjs";
 import { backendUrl } from "./request-target.mjs";
+import { pipeWebBody } from "./web-body.mjs";
 
 const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
 const COOKIE_NAME = /^[A-Za-z0-9_-]{1,64}$/;
@@ -218,15 +223,24 @@ function asResponse(result) {
 
 /**
  * Writes a handler's answer. The cookies the event wrote are already on the
- * Node response; those of a returned `Response` are added to them.
+ * Node response; those of a returned `Response` are added to them. A backend
+ * answer the handler relays goes out as the proxy relays one: its `Location`
+ * on the frontend's origin when the frontend proxies its path, no cookie of
+ * another site its fetch reached.
  */
-async function writeServerResponse(request, response, result) {
+async function writeServerResponse(request, response, result, isProxiedPath) {
   const answer = asResponse(result);
   const cookies = [response.getHeader("set-cookie") ?? []]
     .flat()
-    .concat(answer.headers.getSetCookie());
+    .concat(relayableCookies(answer));
   answer.headers.forEach((value, name) => {
-    if (name !== "set-cookie") response.setHeader(name, value);
+    if (name === "set-cookie") return;
+    response.setHeader(
+      name,
+      name === "location" && isBackendUrl(answer.url)
+        ? relayedLocation(value, answer.url, isProxiedPath)
+        : value,
+    );
   });
   if (cookies.length) response.setHeader("set-cookie", cookies);
   if (!answer.headers.has("cache-control"))
@@ -237,7 +251,7 @@ async function writeServerResponse(request, response, result) {
     response.end();
     return;
   }
-  await pipeline(Readable.fromWeb(answer.body), response);
+  await pipeWebBody(answer.body, response);
 }
 
 /**
@@ -247,7 +261,8 @@ async function writeServerResponse(request, response, result) {
  * through reaches the server's error handling with the cookies written so
  * far.
  *
- * @param context See `createServerEvent`
+ * @param context See `createServerEvent`, plus `isProxiedPath(pathname)`:
+ *   whether the frontend sends that path to the backend
  */
 export async function answerModuleRoute(context) {
   const { request, response, route } = context;
@@ -261,5 +276,5 @@ export async function answerModuleRoute(context) {
   }
   const event = createServerEvent(context);
   const result = await route.handler(event);
-  await writeServerResponse(request, response, result);
+  await writeServerResponse(request, response, result, context.isProxiedPath);
 }

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

@@ -20,7 +20,9 @@ import {
   environmentBackendProxies,
   readDeclaredBackendProxies,
 } from "./public-endpoints.mjs";
+import { reachesBackend } from "./request-routing.mjs";
 
+import { publicOptionsOf } from "./public-options.mjs";
 const WORKSPACE_ROOT = new URL("../", import.meta.url);
 const SOURCE_LOADER = "/server-modules.generated.ts";
 const BUILT_LOADER = new URL(
@@ -148,10 +150,7 @@ function readPrivateOptions(env = process.env) {
 }
 
 function readPublicOptions() {
-  const registry = readJsonFile(REGISTRY_FILE, { modules: [] });
-  return Object.fromEntries(
-    registry.modules.map((module) => [module.id, module.options]),
-  );
+  return publicOptionsOf(readJsonFile(REGISTRY_FILE, { modules: [] }));
 }
 
 async function loadDeclarations(devServer) {
@@ -281,6 +280,7 @@ export async function handleModuleRoute(request, response, pathname, modules) {
     route: reached.route,
     params: reached.params,
     view: modules.serverAuth.view,
+    isProxiedPath: (path) => reachesBackend(path, modules),
     ...modules.context(reached.route.id),
   });
   return true;

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

@@ -29,9 +29,11 @@ function writeFailure(error, response) {
  * @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
+ *   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
+ *   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 = {}) {

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

@@ -100,6 +100,16 @@ 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.
+ */
+export async function propsForQuery(props, url, backend, auth) {
+  const { page } = await loadPage(url, false, backend, auth.signInPath);
+  return { ...props, page };
+}
+
 /**
  * The props of the page a request visits, with the once props to declare.
  *

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

@@ -1,7 +1,6 @@
-import { Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
 import { acceptedEncoder, MINIMUM_COMPRESSION_BYTES } from "./content.mjs";
 import { writeProxyHeaders } from "./proxy-headers.mjs";
+import { pipeWebBody } from "./web-body.mjs";
 
 /**
  * Asks the backend for its answer uncompressed. fetch decodes a compressed
@@ -50,12 +49,15 @@ function proxyEncoder(request, upstream) {
     : undefined;
 }
 
-/** Relays a backend answer to the client, compressed when it should be. */
+/**
+ * Relays a backend answer to the client, compressed when it should be.
+ * `isProxiedPath` decides which backend `Location` becomes a frontend path.
+ */
 export async function relayAnswer(
   request,
   response,
   upstream,
-  { fetched = false } = {},
+  { fetched = false, isProxiedPath } = {},
 ) {
   // Only native fetch bodies are decoded. Synthetic/opaque responses may
   // still contain the encoded bytes, and unknown coding chains stay opaque.
@@ -85,7 +87,12 @@ export async function relayAnswer(
     headers.delete("content-length");
     const etag = headers.get("etag");
     if (etag && !etag.startsWith("W/")) headers.set("etag", `W/${etag}`);
-    upstream = { status: upstream.status, headers, body: upstream.body };
+    upstream = {
+      status: upstream.status,
+      headers,
+      body: upstream.body,
+      url: upstream.url,
+    };
   }
   const encoder = proxyEncoder(request, upstream);
   writeProxyHeaders(
@@ -93,9 +100,9 @@ export async function relayAnswer(
     upstream,
     encoder?.encoding,
     isCompressible(request, upstream),
+    isProxiedPath,
   );
   if (!upstream.body || request.method === "HEAD") return response.end();
-  const body = Readable.fromWeb(upstream.body);
-  if (encoder) await pipeline(body, encoder.stream, response);
-  else await pipeline(body, response);
+  if (encoder) await pipeWebBody(upstream.body, encoder.stream, response);
+  else await pipeWebBody(upstream.body, response);
 }

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

@@ -1,3 +1,5 @@
+import { relayedLocation } from "./proxy-redirects.mjs";
+
 // Hop-by-hop headers describe the backend connection, not the client's one.
 // Forwarded, an explicit `connection: keep-alive` overrode the client's own
 // `Connection: close`, so Node kept the socket open until its idle timeout.
@@ -25,13 +27,16 @@ function varyWithEncoding(vary) {
 /**
  * Writes the backend's status and end-to-end headers on `response`. With an
  * `encoding`, the proxy compresses the body itself: its length is no longer
- * known, and a strong validator no longer names these bytes.
+ * 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`).
  */
 export function writeProxyHeaders(
   response,
   upstream,
   encoding,
   varies = false,
+  isProxiedPath,
 ) {
   const headers = Object.fromEntries(upstream.headers);
   const named = (headers.connection ?? "")
@@ -41,6 +46,12 @@ export function writeProxyHeaders(
   delete headers["set-cookie"];
   const cookies = upstream.headers.getSetCookie?.() ?? [];
   if (cookies.length) headers["set-cookie"] = cookies;
+  if (headers.location && upstream.url)
+    headers.location = relayedLocation(
+      headers.location,
+      upstream.url,
+      isProxiedPath,
+    );
   if (encoding || varies) headers.vary = varyWithEncoding(headers.vary);
   if (encoding) {
     delete headers["content-length"];

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

@@ -0,0 +1,66 @@
+// A backend redirect is the browser's to follow. Followed server-side, a
+// redirect to another site served that site's page, and set its cookies, on
+// the frontend's origin, and a redirect on the backend lost its Location.
+// The proxy fetches with `redirect: "manual"` and relays the redirect instead.
+
+/** The statuses that send the client to their `Location`. */
+export const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+function originOf(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Whether `url` is on the backend's origin. */
+export function isBackendUrl(
+  url,
+  backendBaseUrl = process.env.DMS_API_BASE_URL,
+) {
+  const origin = originOf(url);
+  return origin !== undefined && origin === originOf(backendBaseUrl);
+}
+
+/**
+ * The `Location` the client gets for a backend answer fetched from
+ * `fetchedUrl`. The proxy keeps the path, so a location on the backend's
+ * origin becomes the same path on the frontend's when the frontend sends that
+ * path to the backend: the backend's origin is often unreachable from the
+ * browser. A backend path the frontend does not proxy (a route outside every
+ * declared backend proxy) stays an absolute backend URL, which the browser
+ * follows to the backend. Another site's location is kept.
+ *
+ * @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
+ */
+export function relayedLocation(
+  location,
+  fetchedUrl,
+  isProxiedPath = () => false,
+) {
+  let target;
+  try {
+    target = new URL(location, fetchedUrl);
+  } catch {
+    return location;
+  }
+  if (target.origin !== originOf(fetchedUrl)) return location;
+  if (!isProxiedPath(target.pathname)) return target.href;
+  const path = `${target.pathname}${target.search}${target.hash}`;
+  // `//host` would name another host: `/.` keeps it a path.
+  return path.startsWith("//") ? `/.${path}` : path;
+}
+
+/**
+ * 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.
+ */
+export function relayableCookies(answer) {
+  if (answer.redirected && !isBackendUrl(answer.url)) return [];
+  return answer.headers.getSetCookie();
+}

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

@@ -0,0 +1,110 @@
+// Large transfers through the proxy, a file upload above all. The request
+// body is streamed to the backend, never buffered, and held to the
+// `maxBodyBytes` of the proxy it reached: a declared Content-Length over the
+// limit is refused before a byte is passed on, a chunked body is cut off as
+// soon as it goes over.
+
+const PAYLOAD_TOO_LARGE = 413;
+const TOO_LARGE_BODY = JSON.stringify({ message: "Payload Too Large" });
+// The refused body is never passed on: the iteration stops where it went
+// over, and the request stream stays open for the lingering close below.
+const BODY_ITERATION = { destroyOnReturn: false };
+// How long a refused body is read and dropped before the connection closes
+// anyway: long enough for a client to finish sending what was in flight,
+// short enough to bound what a refused client can make the server read.
+const LINGER_MS = 5_000;
+
+const BODILESS_METHODS = new Set(["GET", "HEAD"]);
+const REQUEST_TIMEOUT_MS = 60 * 60 * 1000;
+
+/**
+ * The frontend server's options. Node's default request timeout (5 minutes to
+ * receive a whole request) cut off a large upload on a slow link: an hour lets
+ * 500 MiB through at about 150 KB/s. Headers keep Node's own minute.
+ */
+export const SERVER_OPTIONS = Object.freeze({
+  requestTimeout: REQUEST_TIMEOUT_MS,
+});
+
+class BodyTooLargeError extends Error {}
+
+async function* limitedChunks(request, maxBodyBytes) {
+  let received = 0;
+  for await (const chunk of request.iterator(BODY_ITERATION)) {
+    received += chunk.byteLength;
+    if (received > maxBodyBytes) throw new BodyTooLargeError();
+    yield chunk;
+  }
+}
+
+function requestBody(request, maxBodyBytes) {
+  if (BODILESS_METHODS.has(request.method)) return undefined;
+  return maxBodyBytes === undefined
+    ? request
+    : limitedChunks(request, maxBodyBytes);
+}
+
+function declaresTooLargeBody(request, maxBodyBytes) {
+  return (
+    maxBodyBytes !== undefined &&
+    Number(request.headers["content-length"] ?? 0) > maxBodyBytes
+  );
+}
+
+function isBodyTooLarge(error) {
+  return (
+    error instanceof BodyTooLargeError ||
+    error?.cause instanceof BodyTooLargeError
+  );
+}
+
+/**
+ * Answers 413 and closes the connection once the client stopped sending.
+ *
+ * Closing a socket with unread bytes makes the kernel reset the connection,
+ * and a client stack that drops what it had not read yet when the reset
+ * arrives (macOS, BSD, Windows) reports a network error instead of the 413,
+ * 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.
+ */
+function refuseTooLargeBody(request, response) {
+  response.writeHead(PAYLOAD_TOO_LARGE, {
+    "content-type": "application/json",
+    connection: "close",
+  });
+  response.write(TOO_LARGE_BODY);
+  if (request.complete) return response.end();
+  const close = () => {
+    clearTimeout(timer);
+    response.end();
+  };
+  const timer = setTimeout(() => {
+    response.end();
+    request.socket.destroy();
+  }, LINGER_MS);
+  timer.unref();
+  request.once("end", close);
+  request.once("error", close);
+  request.resume();
+}
+
+/**
+ * Sends a proxied request, its body held to `maxBodyBytes`.
+ *
+ * @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
+ */
+export async function sendWithinLimit(request, response, maxBodyBytes, send) {
+  if (declaresTooLargeBody(request, maxBodyBytes))
+    return refuseTooLargeBody(request, response);
+  try {
+    return await send(requestBody(request, maxBodyBytes));
+  } catch (error) {
+    if (!isBodyTooLarge(error)) throw error;
+    return refuseTooLargeBody(request, response);
+  }
+}

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

@@ -54,7 +54,7 @@ export function readDeclaredPublicEndpoints(file = DECLARED_ENDPOINTS_FILE) {
 
 /**
  * The backend proxies the backend modules declared in the manifest, as
- * `{ module, path, auth? }`, unchecked.
+ * `{ module, path, auth?, maxBodyBytes? }`, unchecked.
  *
  * @param file Generated file to read
  */
@@ -74,7 +74,7 @@ export function readDeclaredBackendProxies(file = DECLARED_ENDPOINTS_FILE) {
 
 /**
  * The backend proxies `DMS_BACKEND_PROXIES` adds: a JSON array of
- * `{ path, auth? }`, as the manifest's `backendProxies`, for an operator.
+ * `{ path, auth?, maxBodyBytes? }`, as the manifest's `backendProxies`, for an operator.
  *
  * @param declaration The variable's value
  */

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

@@ -0,0 +1,49 @@
+// The modules' public options the running server serves: computed by
+// `ajs dms start` from the project's configuration and handed over in
+// `DMS_PUBLIC_OPTIONS`, a JSON object of options by module id. A build never
+// holds them, so a deployment's variables reach the dashboard without a
+// rebuild. Unset (`ajs dms dev`), the registry's options stand.
+
+const VARIABLE = "DMS_PUBLIC_OPTIONS";
+export const PUBLIC_OPTIONS_ELEMENT_ID = "dms-public-options";
+
+function parse(raw) {
+  if (!raw) return undefined;
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "object" &&
+      parsed !== null &&
+      !Array.isArray(parsed)
+      ? parsed
+      : undefined;
+  } catch {
+    console.warn(`${VARIABLE} is not a JSON object of options by module id`);
+    return undefined;
+  }
+}
+
+/** The options by module id the server runs with, undefined when unset. */
+export const RUNTIME_PUBLIC_OPTIONS = parse(process.env[VARIABLE]);
+
+/** The options of each module of the registry, the runtime ones first. */
+export function publicOptionsOf(registry) {
+  return Object.fromEntries(
+    registry.modules.map((module) => [
+      module.id,
+      RUNTIME_PUBLIC_OPTIONS?.[module.id] ?? module.options,
+    ]),
+  );
+}
+
+/**
+ * The script a page document carries the runtime options in, for the
+ * browser's setup of the modules; nothing when the build's options stand.
+ */
+export function publicOptionsScript() {
+  if (!RUNTIME_PUBLIC_OPTIONS) return "";
+  const value = JSON.stringify(RUNTIME_PUBLIC_OPTIONS).replaceAll(
+    "<",
+    "\\u003c",
+  );
+  return `<script id="${PUBLIC_OPTIONS_ELEMENT_ID}" type="application/json">${value}</script>`;
+}

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

@@ -39,6 +39,26 @@ export function requestOwner(method, pathname, modules, hasRendererFile) {
   return PAGE_METHODS.has(method) ? { kind: "page" } : { kind: "not-found" };
 }
 
+/**
+ * Whether the server sends a request for `pathname` to the backend: a backend
+ * `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
+ *   file at that path
+ */
+export function reachesBackend(
+  pathname,
+  modules,
+  hasRendererFile = () => false,
+) {
+  return (
+    requestOwner("GET", pathname, modules, hasRendererFile).kind === "backend"
+  );
+}
+
 /** 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}`;

package/templates/vue/server/web-body.mjs

@@ -0,0 +1,24 @@
+// Writes a Web-standard body, a backend answer above all, to a Node response.
+//
+// Lives apart from the proxy and the module routes, which both send one.
+
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+/**
+ * Sends `body` through `streams` to the response, the last of them. A
+ * response the client already left is not piped: `pipeline` refuses it
+ * before it listens to the body, which then stayed unread with no `error`
+ * listener, and its next failure (the backend closing, or undici's body
+ * timeout on an event stream gone quiet) ended the whole server. The body is
+ * cancelled instead, which closes its backend connection too.
+ */
+export async function pipeWebBody(body, ...streams) {
+  const response = streams.at(-1);
+  if (response.closed || response.destroyed) {
+    for (const stream of streams.slice(0, -1)) stream.destroy();
+    await body.cancel().catch(() => {});
+    return;
+  }
+  await pipeline(Readable.fromWeb(body), ...streams);
+}