@antelopejs/dms-frontend 0.7.1 → 0.8.0

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/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,84 @@
+// 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 read, 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" });
+// Reading on after the refusal would take the whole body the limit exists to
+// refuse, so the request stream is left as it is and the connection closed.
+const BODY_ITERATION = { destroyOnReturn: false };
+
+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, the rest of the body unread. */
+function refuseTooLargeBody(response) {
+  response.writeHead(PAYLOAD_TOO_LARGE, {
+    "content-type": "application/json",
+    connection: "close",
+  });
+  response.end(TOO_LARGE_BODY);
+}
+
+/**
+ * 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(response);
+  try {
+    return await send(requestBody(request, maxBodyBytes));
+  } catch (error) {
+    if (!isBodyTooLarge(error)) throw error;
+    return refuseTooLargeBody(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);
+}

package/templates/vue/server-module.ts

@@ -29,8 +29,8 @@ export interface DmsSession {
   refreshToken?: string;
   accountId?: string;
   activeTenantId?: string;
-  /** False when the session ends with the browser. */
-  persistent?: boolean;
+  /** True when the session outlives the browser (30 days), false when it ends with it. */
+  persistent: boolean;
   /** Stamped by the frontend server on every write. */
   updatedAt?: number;
   [key: string]: unknown;
@@ -84,8 +84,8 @@ export interface DmsServerEvent {
      */
     view(): DmsPublicSession;
     /**
-     * Writes the session cookie, stamped with `updatedAt`; it ends with the
-     * browser unless `persistent` is true or unset.
+     * Writes the session cookie, stamped with `updatedAt`. It lasts 30 days
+     * when `persistent` is true and ends with the browser when it is false.
      */
     write(session: DmsSession): void;
     clear(): void;
@@ -112,16 +112,21 @@ export interface DmsServerEvent {
   /**
    * Calls the backend, JSON in and out. A refusal throws an error carrying
    * the status and the backend's public `error.*` message, which the server
-   * answers as is when the handler lets it through.
+   * answers as is when the handler lets it through. A redirect is not
+   * followed: it throws a 502.
    */
   backend<T = unknown>(path: string, init?: DmsBackendRequest): Promise<T>;
   /**
    * The backend URL of an absolute path, for a call `backend` cannot make (a
    * raw response, no relayed header): always on the backend's origin,
-   * whatever the path holds.
+   * whatever the path holds. Fetch it with `redirect: "manual"` to relay a
+   * backend redirect: the browser then follows it.
    */
   backendUrl(path: string): URL;
-  /** The client's address, behind `DMS_TRUSTED_PROXY_HOPS` proxies. */
+  /**
+   * The client's address, from the `DMS_CLIENT_IP_HEADER` header or behind
+   * `DMS_TRUSTED_PROXY_HOPS` proxies.
+   */
   clientIp(): string;
   /** This module, and only this one. */
   module: {
@@ -273,6 +278,13 @@ export interface DmsBackendProxyOptions {
    * needed.
    */
   auth?: "session" | "none";
+  /**
+   * The largest request body, in bytes, the server streams to the backend.
+   * A larger declared `Content-Length` gets a `413` before any byte is read;
+   * a chunked body is cut off with a `413` as soon as it goes over. No limit
+   * by default: the backend applies its own.
+   */
+  maxBodyBytes?: number;
 }
 
 export type DmsServerSetup = (server: DmsServer) => void;