nexus-shared 3.1.0 → 4.0.0

package/dist/Interfaces/TableInterfaces.d.ts

@@ -1,5 +1,7 @@
+import type { IconNode } from "nexus-icons";
 import type { CSSProperties, ReactNode, Ref } from "react";
 import type { TableStore } from "../Helpers/TableStore.ts";
+import type { ApiEndpoint } from "./ApiInterfaces.ts";
 import type { ExcelEndpoints } from "./ExcelInterfaces.ts";
 import type { InputParams } from "./FormInterfaces.ts";
 import type { Size, Tone } from "./TypeInterfaces.ts";
@@ -16,6 +18,11 @@ export interface TableColumnOption {
     /** Draws the value as a tag with a dot of this color. */
     tone?: Tone;
 }
+/** A short tag after a cell's value (`TableColumn.tag`): its words and the color of its dot. */
+export interface TableTag {
+    label: string;
+    tone?: Tone;
+}
 /** One column: which field it shows, how, and what the user can do with it. */
 export interface TableColumn<TRow extends TableRow = TableRow> {
     /** The field: `"name"`, or a path into the row, `"guest.name"`. It is also the column's id and its sort name. */
@@ -37,6 +44,11 @@ export interface TableColumn<TRow extends TableRow = TableRow> {
     decimals?: number;
     /** Text before a number, such as "Rs. ". */
     prefix?: string;
+    /**
+     * A `money` column's currency, written before the figures with a space: "Rs." gives "Rs. 1,250.00". A text, or the
+     * row's own (`row => row.currencyText`). Default the table's `currency`, so a page sets its company's once.
+     */
+    currency?: string | ((row: TRow) => string | null | undefined);
     /** Text after a number, such as " kg". */
     suffix?: string;
     /** Labels for the values the column holds, such as the names of an enum's numbers. */
@@ -65,6 +77,8 @@ export interface TableColumn<TRow extends TableRow = TableRow> {
     hideable?: boolean;
     /** Long text wraps onto more lines instead of ending in "…". */
     wrap?: boolean;
+    /** Its text is Markdown: the table shows the text, and a record's details show it formatted. */
+    markdown?: boolean;
     /** The user can drag the heading to another place, or move it from its menu. Default true. */
     movable?: boolean;
     /** The user can drag the edge of the heading to change the width. Default true; `false` for a column that must keep its width. */
@@ -73,6 +87,61 @@ export interface TableColumn<TRow extends TableRow = TableRow> {
     pinnable?: boolean;
     /** Pinned before the user pins anything: `left` keeps it at the start, `right` at the end. */
     pinned?: TablePinSide;
+    /**
+     * The value is another record's, looked up by the key this row holds: a country's sub-region named from the
+     * sub-regions' `FindListing`. The table collects every key its rows hold, asks once for the ones it has not got, keeps
+     * the answers for every table on the page, and shows the field once they are in - searched and sorted like any other
+     * column. A key the source does not answer shows as "Not found". (A join the database already made needs none of
+     * this: the row carries the name, and `tag` reads its status.)
+     */
+    join?: TableJoin;
+    /**
+     * A short tag after the value: "Trashed" beside a parent that is in the trash. Given the row and, on a `join` column,
+     * the record it looked up; nothing when it answers nothing. `crudColumns.dbJoin` and `crudColumns.clientJoin` set it.
+     */
+    tag?: (row: TRow, joined?: TableJoinedRecord) => TableTag | null | undefined;
+    /**
+     * The value is another record's name the database joined into the row, by the key this row holds in `from`
+     * (`crudColumns.dbJoin`). The table shows the row as it is; a CRUD that saved the row writes the name - and the status
+     * in `status` - again from the record picked for that key, with no call (`crudJoinedNames`). Without `from`, or where
+     * no record is known for the key, it reads the saved record back once (`details`) instead (`crudJoinsMissing`).
+     */
+    dbJoin?: TableDbJoin;
+}
+/** Where a column the database joined takes its name from (`TableColumn.dbJoin`). */
+export interface TableDbJoin {
+    /**
+     * The field of this row that holds the other record's key, and the form's input for it: `"parentId"`. Without it a
+     * save cannot tell whose name the column shows, and a new record is read back once for it.
+     */
+    from?: string;
+    /** The field of this row that holds the other record's status: `"parentRecordStatus"`. */
+    status?: string;
+}
+/** A record a `join` looked up: whatever its source answers for one key. */
+export type TableJoinedRecord = Readonly<Record<string, unknown>>;
+/** Where a `join` looks records up: the records behind a set of keys, in any status. */
+export interface TableJoinSource {
+    /** One name per source. Every column and table that names it shares its answers and its calls. */
+    readonly name: string;
+    /** The records behind these keys; a key with no record is left out. One call for every key the page needs at once. */
+    load(keys: readonly string[], signal: AbortSignal): Promise<readonly TableJoinedRecord[]>;
+    /** The field of a loaded record that holds its key. Default `id`. */
+    readonly key?: string;
+    /** How long an answer is kept, in milliseconds, before it is asked again. Default 5 minutes. */
+    readonly lifetime?: number;
+}
+/** A column whose value is another record's (`TableColumn.join`). */
+export interface TableJoin {
+    /** The field of this row that holds the other record's key: `"subRegionId"`. */
+    from: string;
+    /** The field of the other record the column shows. Default: the column's own `key`. */
+    field?: string;
+    /**
+     * Where the records come from: an endpoint the keys are POSTed to as an array (a Nexus controller's `findListing`),
+     * or a source of the page's own.
+     */
+    source: ApiEndpoint | TableJoinSource;
 }
 /** Which side a pinned column stays on while the others scroll. */
 export type TablePinSide = "left" | "right";
@@ -117,6 +186,8 @@ export interface TablePage<TRow extends TableRow = TableRow> {
 export type TableLoader<TRow extends TableRow = TableRow> = (query: TableQuery, signal: AbortSignal) => TablePage<TRow> | readonly TRow[] | Promise<TablePage<TRow> | readonly TRow[]>;
 /** `client`: the table has every row and pages them itself. `server`: each page comes from the loader. */
 export type TablePaging = "client" | "server";
+/** Where a table keeps its paging (`DataTableProps.pager`): the rows per page in the bar or in the footer, or every row on one page. */
+export type TablePagerMode = "bar" | "footer" | "none";
 /** `loading`: the first rows are on their way. `ready`: rows (or none) are shown. `error`: the rows could not load. */
 export type TableStatus = "loading" | "ready" | "error";
 /** What the table shows now. A new object after every change. */
@@ -137,6 +208,8 @@ export interface TableState<TRow extends TableRow = TableRow> {
     query: TableQuery;
     /** The selected rows by key (keys as text), in the order they were picked. */
     selected: ReadonlyMap<string, TRow>;
+    /** The one row the user picked (`DataTable` `onPick`), as the table has it now: its newest copy. `null` for none. */
+    picked: TRow | null;
     /** Rows with an action running. */
     busy: ReadonlySet<string>;
     /** Rows just added or changed, highlighted for a moment. */
@@ -155,6 +228,12 @@ export interface TableViewColumn<TRow extends TableRow = TableRow> {
     column: TableColumn<TRow>;
     /** The side it stays on, or null when it scrolls with the rest. */
     pin: TablePinSide | null;
+    /**
+     * The side it is pinned to (the person's choice or the column's): where it is drawn, among which columns it moves,
+     * and what its menu offers. `pin` is the same unless the table is too narrow for it to stay (`PINNED_SHARE`): then
+     * `pin` is null and it scrolls with the rest until there is room again.
+     */
+    side: TablePinSide | null;
     /** Pixels from that edge, once the table has measured the columns before it. */
     offset: number;
     /** The last pinned column of its side: the one that shows the shadow while columns scroll under it. */
@@ -212,6 +291,30 @@ export interface TableMenuAction {
     separator?: boolean;
     onSelect: () => void;
 }
+/**
+ * Rows kept in a section above the page, which the user folds open and shut: the records they pinned, their
+ * favourites. They are the rows as they came from their own endpoint, the same records also show in the list below,
+ * and each section's row wears the section's icon where the rows of the page show their number.
+ */
+export interface TableRowSection<TRow extends TableRow = TableRow> {
+    /** Tells the sections apart; the table remembers each one's fold under it. */
+    key: string;
+    /** What the section is called: "Pinned rooms". */
+    label: string;
+    /** The section's icon, in its head and on each of its rows. */
+    icon: IconNode;
+    rows: readonly TRow[];
+    /** The rows are on their way: the section shows that it is loading. */
+    loading?: boolean;
+    /** Most rows the section can hold, shown beside the count so the user knows the limit. */
+    max?: number;
+}
+/** A mark a row carries for this user - pinned, a favourite - drawn in its first column where its number would be. */
+export interface TableRowMark {
+    icon: IconNode;
+    /** What the mark says: "Pinned". */
+    label: string;
+}
 /** A way to select rows by what they are, such as "Pinned" or "Not flagged". */
 export interface TableSelectBy<TRow extends TableRow = TableRow> {
     label: string;
@@ -270,6 +373,11 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
     searchable?: boolean;
     /** Default "Search…". */
     searchPlaceholder?: string;
+    /**
+     * A line at the top of the table, inside its frame and over its bar, saying what its rows are: whose records a narrowed
+     * `Crud` shows ("Places of: Ram Thapa"). Beside another table, the two frames still start level.
+     */
+    caption?: ReactNode;
     /** On the left of the bar, after the Add section: tabs, filters. On a narrow table the line under the search. */
     toolbar?: ReactNode;
     /** The page's own buttons, in the Add section after the table's Add: first in the bar, last on a phone. */
@@ -277,10 +385,19 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
     /**
      * The table's Add, first in the bar. With `excel`, its arrow holds the template, the import and the export, which
      * then leave the options menu.
+     *
+     * Its `description` is its tooltip and what a screen reader hears after its name. `disabled` with a `description`
+     * says why nothing can be added yet: the button stays in the Tab order, looks unavailable, and a press - a click, a
+     * tap, Enter - shows the description in a note under it, as a `TreeView`'s own button does; the spreadsheet items then
+     * wait in the options menu, without Bulk insert. `onDisabledPress` answers such a press first: when it returns true the
+     * page has answered it itself (a CRUD narrowed by a box of its own moves the cursor to that box), and no note shows.
      */
     add?: {
         label: ReactNode;
         onClick: () => void;
+        disabled?: boolean;
+        description?: string;
+        onDisabledPress?: () => boolean;
     };
     /** The Columns panel, where columns are shown, hidden, and dragged into another order. Default true. */
     columnsMenu?: boolean;
@@ -340,8 +457,32 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
      */
     openOnClick?: boolean;
     /**
-     * Rows kept in a section above the page, which the user folds open: the records they pinned. They are the rows as
-     * they came from their own endpoint, and the same records also show in the list below. Leave it out for no section.
+     * Rows the user picks one of, for a page that shows what belongs to the picked one beside the table: a person's
+     * places beside the people. A click on a row picks it (a double-click still opens it, and `openOnClick` gives way); the
+     * keyboard reaches the rows through a radio button each, read with the row's name: Tab to the picked one, the arrow
+     * keys to move the pick. The picked row is tinted as a selected one is, and the rows are numbered unless `numbered` is
+     * false.
+     *
+     * The pick lives in the table's store (`TableState.picked`, `TableStore.pick`) and follows the record: a search, a
+     * sort or another page keep it; an edit hands the page its new copy; it is let go when the record leaves the rows
+     * (trashed, deleted, gone after a reload) and when another list starts over (`loadKey`). Called with every change,
+     * `null` included.
+     */
+    onPick?: (row: TRow | null) => void;
+    /**
+     * Sections above the page, in this order, each folding open and shut on its own: the records the user pinned, then
+     * their favourites. A section with no rows and none on their way does not show.
+     */
+    sections?: readonly TableRowSection<TRow>[];
+    /**
+     * The marks each row carries (pinned, a favourite), in its first column in place of its number, one under the
+     * other - in the list and in the sections alike, so no column of their own is needed. A row with none shows its
+     * number; a section's row with none shows the section's icon.
+     */
+    rowMarks?: (row: TRow) => readonly TableRowMark[];
+    /**
+     * One section of pinned rows, before any `sections`: the same as a section with the key `pins` and the pin icon.
+     * Leave it out for no such section.
      */
     pinnedRows?: readonly TRow[];
     /** The pinned rows are on their way: the section shows that it is loading. */
@@ -350,6 +491,14 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
     pinnedLabel?: string;
     /** Most rows that can be pinned, shown beside the count so the user knows the limit. */
     pinnedMax?: number;
+    /**
+     * How the rows are paged on screen (`TablePagerMode`). `"bar"` (default): rows per page inside the search box, or in the
+     * bar without a search, and the pager in the footer. `"footer"`: rows per page beside the pager, so a table with nothing
+     * else above its rows draws no bar. `"none"`: every row on one page, for a short list read whole (a record's notes, at
+     * most 50): no pager, no rows per page, and no footer unless a search or the filters leave rows out (a screen reader
+     * still hears the count). A server's pages cannot all be shown: with `paging="server"`, `"none"` is `"footer"`.
+     */
+    pager?: TablePagerMode;
     /** Rows per page. Default 10, or the user's last choice with `stateKey`. */
     pageSize?: number;
     /** Choices of rows per page. Default 10, 25, 50, 100. */
@@ -358,12 +507,18 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
     defaultSort?: TableSort | null;
     /**
      * Row numbers in the first column. Default: on when `selectable`, where the number becomes the row's checkbox as soon
-     * as the pointer is over the row or anything is selected.
+     * as the pointer is over the row or anything is selected, and when rows are picked (`onPick`), where the first column
+     * also holds each row's radio button.
      */
     numbered?: boolean;
-    /** Remembers the page size, the sort, hidden columns, the order, widths, and pins of the columns, and whether the
-     * pinned section is open, on this device. */
+    /** Remembers the page size, the sort, hidden columns, the order, widths, and pins of the columns, and which sections
+     * are open, on this device. */
     stateKey?: string;
+    /**
+     * The currency of every `money` column without its own (`TableColumn.currency`): "Rs." writes "Rs. 1,250.00" in the
+     * cells, the details, the CSV and the print. Set once per table from the company's settings.
+     */
+    currency?: string | null;
     /** Milliseconds after the last key before a search goes to a server. Default 300; a table with every row searches at once. */
     searchDelay?: number;
     /**

package/dist/Services/ApiProxy.d.ts

@@ -1,4 +1,6 @@
 import type { ApiModuleValue } from "../Interfaces/ApiInterfaces.ts";
+import { type ApiProxyCode, type ApiProxyFailure } from "./ApiProxyRules.ts";
+export { DEFAULT_PROXY_BODY_LIMIT, DEFAULT_PROXY_REDIRECTS, DEFAULT_PROXY_RESPONSE_HEADERS, lastForwardedAddress, nexusFailure, PROXY_REFUSALS, readIpAddress, type ApiProxyCode, type ApiProxyFailure } from "./ApiProxyRules.ts";
 export interface ApiProxyOptions {
     /** The user's token for the backend, such as from the session cookie. Without one, the request's own Authorization header goes on. */
     token?: (request: Request) => string | null | undefined | Promise<string | null | undefined>;
@@ -6,10 +8,34 @@ export interface ApiProxyOptions {
     headers?: (request: Request) => Record<string, string> | undefined | Promise<Record<string, string> | undefined>;
     /** Serves only these modules, of those the app's `ApiModules` sends through the proxy. Default: all of those. */
     allow?: readonly ApiModuleValue[];
-    /** Milliseconds to wait for the backend to start answering. Default 60,000. */
+    /** Milliseconds to wait for the backend to start answering, its redirects included. Default 60,000. */
     timeout?: number;
     /** The `fetch` to use. Default: the global one. */
     fetch?: typeof fetch;
+    /**
+     * More of the backend's response headers to pass on, besides `DEFAULT_PROXY_RESPONSE_HEADERS` and the Nexus backend's
+     * own `X-Nexus-*`: `["X-Total-Count"]`. A header that names the backend or carries its own policies (Server,
+     * X-Powered-By, X-AspNet-*, Via, Alt-Svc, Strict-Transport-Security, CORS, Location, Link) is dropped even when named.
+     */
+    responseHeaders?: readonly string[];
+    /** Passes the backend's Set-Cookie headers to the browser. Default false: the app keeps its own session. */
+    passCookies?: boolean;
+    /** The most bytes a request body may have; a bigger one is refused with 413 before it reaches the backend. Default 100 MB. */
+    maxBodySize?: number;
+    /** How many redirects inside a module to follow for one call; 0 refuses every redirect. Default 3. */
+    maxRedirects?: number;
+    /**
+     * The client's IP address, sent to the backend as X-Forwarded-For for its sign-in lockout and rate limits. Default:
+     * the last address of the X-Forwarded-For the app received, the one Next.js or the app's own reverse proxy wrote. Pass
+     * it behind more than one proxy of the app's own, or behind a CDN that names the client in a header of its own.
+     */
+    clientAddress?: (request: Request) => string | null | undefined | Promise<string | null | undefined>;
+    /** Lets pages of other sites call through the proxy. Default false: the app's own pages, links followed, and non-browser callers. */
+    allowCrossSite?: boolean;
+    /** Builds the answer to a refusal of the proxy's own, for a backend whose envelope is not Nexus's. Default `nexusFailure`. */
+    failure?: (failure: ApiProxyFailure) => Response;
+    /** Hears what the proxy hid or refused, on the server. Default: one line in `console.error`. */
+    onProblem?: (problem: ApiProxyProblem) => void;
 }
 /** What a Next.js route handler for `[module]/[...path]` receives. */
 export interface ApiProxyContext {
@@ -18,6 +44,15 @@ export interface ApiProxyContext {
         path?: string[];
     }>;
 }
+/** What the proxy hid or refused, for the server's log. It never holds the user's token or a query string. */
+export interface ApiProxyProblem {
+    /** The refusal's code, the one the browser got: "BACKEND_REDIRECT_REFUSED". */
+    messageCode: ApiProxyCode;
+    /** The call, as the browser made it: "POST configuration/Region/MassRecover". */
+    call: string;
+    /** What happened, for a developer: the backend's address and status, a piece of its error page, why it failed. */
+    detail: string;
+}
 /**
  * Makes the route handlers of the proxy. Only the modules' configured roots can be reached: a path cannot climb out of
  * its module (`..` is refused), and the query goes on unchanged.

package/dist/Services/ApiProxy.js

@@ -2,71 +2,160 @@ import { DEFAULT_API_TIMEOUT, isFrameworkError } from "../Helpers/ApiClient.js";
 import { getApiModules } from "../Helpers/ApiModules.js";
 import { joinUrl } from "../Helpers/ApiRoutes.js";
 import { buildMessage } from "../Helpers/MessageBuilder.js";
-import { serverModuleRoot } from "./ServerApi.js";
+import { BODY_HEADERS, DEFAULT_PROXY_BODY_LIMIT, DEFAULT_PROXY_REDIRECTS, ERROR_BODY_LIMIT, filterResponseHeaders, forwardRequestHeaders, harden, isCrossSiteCall, isRedirect, isUnsafeSegment, lastForwardedAddress, logSnippet, logUrl, methodAfterRedirect, nexusFailure, ownOrigin, PROXY_REFUSALS, readBody, readIpAddress, redirectInsideModule, whyHidden, } from "./ApiProxyRules.js";
+import { serverAppOrigin, serverModuleRoot } from "./ServerApi.js";
+export { DEFAULT_PROXY_BODY_LIMIT, DEFAULT_PROXY_REDIRECTS, DEFAULT_PROXY_RESPONSE_HEADERS, lastForwardedAddress, nexusFailure, PROXY_REFUSALS, readIpAddress } from "./ApiProxyRules.js";
 const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
-/** Request headers that belong to this hop, or to the app (its cookies), not to the backend. */
-const REQUEST_HEADERS_TO_SKIP = new Set(["host", "connection", "content-length", "transfer-encoding", "keep-alive", "upgrade", "cookie", "te", "trailer", "proxy-authorization", "proxy-connection", "accept-encoding"]);
+/** Statuses whose answer has no body. */
+const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
+/** What a call does, for the plain words of a refusal: a GET loads, a DELETE deletes, the rest save. */
+function actionOf(method) {
+    if (method === "GET" || method === "HEAD")
+        return "load";
+    return method === "DELETE" ? "delete" : "save";
+}
+/** Whether an answer reaches the browser as it came, without being read first: a success, or a 304. */
+function passesUnread(status) {
+    return (status >= 200 && status < 300) || status === 304;
+}
+/** Why a `fetch` failed, from its cause ("ECONNREFUSED", "DEPTH_ZERO_SELF_SIGNED_CERT"), with what to do about a certificate. */
+function describeFetchError(error) {
+    const cause = error?.cause;
+    let text = error instanceof Error ? error.message : String(error);
+    if (typeof cause?.code === "string")
+        text = cause.code;
+    else if (typeof cause?.message === "string")
+        text = cause.message;
+    if (!/CERT|SELF_SIGNED|UNABLE_TO_VERIFY|ERR_TLS/i.test(text))
+        return text;
+    return `${text}: this server does not trust the backend's certificate. Start Node.js with NODE_USE_SYSTEM_CA=1 (or NODE_EXTRA_CA_CERTS) so it trusts the certificates this machine trusts, or give the module a root it trusts`;
+}
+/** A redirect's target for the log, without its query. */
+function logLocation(location, from) {
+    try {
+        return logUrl(new URL(location, from));
+    }
+    catch {
+        return "a Location that is not a URL";
+    }
+}
+function logProblem(problem) {
+    console.error(`[apiProxy] ${problem.call}: ${problem.messageCode}, ${problem.detail}`);
+}
 /**
- * Response headers that belong to the backend's hop. `content-encoding` and `content-length` go too: `fetch` has already
- * decompressed the body, so passing them on would make the browser decode it twice.
+ * The app's address as the backend is told it in X-Forwarded-Host and -Proto: the configured one
+ * (`configureServerApi({ origin })`, URL_CURRENT), else this request's, which Next.js builds from its own host and port
+ * (never the Host header) but with the protocol X-Forwarded-Proto names. Never where a call goes: that is `ownOrigin`.
  */
-const RESPONSE_HEADERS_TO_SKIP = new Set(["connection", "transfer-encoding", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "upgrade", "content-encoding", "content-length"]);
-/** An answer the client reads like the backend's own. */
-function failure(status, message, messageCode) {
-    return Response.json({ isSuccess: false, code: status, message, messageCode }, { status });
-}
-/** A backend redirect to its own host, pointed back through the proxy. */
-function rewriteLocation(location, root, module, proxyPath) {
-    const target = new URL(location, root);
-    if (target.host !== root.host)
-        return location;
-    const base = root.pathname.replace(/\/+$/, "");
-    const relative = target.pathname.startsWith(`${base}/`) ? target.pathname.slice(base.length + 1) : target.pathname.replace(/^\/+/, "");
-    return `${joinUrl(joinUrl(proxyPath, module), relative)}${target.search}`;
+async function appOriginOf(incoming) {
+    try {
+        const configured = await serverAppOrigin();
+        if (configured)
+            return new URL(configured);
+    }
+    catch (error) {
+        if (isFrameworkError(error))
+            throw error;
+    }
+    return incoming;
 }
 /**
  * Makes the route handlers of the proxy. Only the modules' configured roots can be reached: a path cannot climb out of
  * its module (`..` is refused), and the query goes on unchanged.
  */
 export function createApiProxy(options = {}) {
+    const maxBodySize = options.maxBodySize ?? DEFAULT_PROXY_BODY_LIMIT;
+    const maxRedirects = options.maxRedirects ?? DEFAULT_PROXY_REDIRECTS;
+    const timeout = options.timeout ?? DEFAULT_API_TIMEOUT;
+    /** A refusal of the proxy's own, in the app's envelope (Nexus's by default). */
+    function refuse(messageCode, message, status = PROXY_REFUSALS[messageCode].status) {
+        return harden((options.failure ?? nexusFailure)({ status, message, messageCode, errorCode: PROXY_REFUSALS[messageCode].errorCode }));
+    }
+    function report(problem) {
+        try {
+            (options.onProblem ?? logProblem)(problem);
+        }
+        catch {
+            // A log that fails must not change the answer.
+        }
+    }
     async function handle(request, context) {
         const method = request.method.toUpperCase();
-        if (!METHODS.has(method))
-            return failure(405, buildMessage("reason", { status: 405 }), "METHOD_NOT_ALLOWED");
         const { module: key, path = [] } = await context.params;
+        // The call as the log names it: the module and path the browser asked for, never the query. Encoded, so a line
+        // break the browser put in the path cannot start a line of its own in the log.
+        const call = `${method} ${[key, ...path].map(encodeURIComponent).join("/")}`;
+        const action = actionOf(method);
+        if (!METHODS.has(method)) {
+            const refusal = refuse("METHOD_NOT_ALLOWED", buildMessage("reason", { status: 405 }));
+            refusal.headers.set("Allow", [...METHODS].join(", "));
+            return refusal;
+        }
+        if (!options.allowCrossSite && isCrossSiteCall(request.headers, method))
+            return refuse("CROSS_SITE_REFUSED", buildMessage("reason", { action, status: 403 }));
         // Asked on every request, so the app's modules count even when they were registered after this route was made.
         const modules = getApiModules();
         const info = modules.info(key);
         if (!info || (options.allow && !options.allow.includes(info.module)))
-            return failure(404, `No API module is named "${key}".`, "MODULE_NOT_FOUND");
+            return refuse("MODULE_NOT_FOUND", `No API module is named "${key}".`);
         if (!modules.proxies(info.module))
-            return failure(404, `The ${info.label} API is not called through this app's proxy.`, "MODULE_NOT_PROXIED");
-        if (path.some(segment => segment === "." || segment === ".." || /[\\/]/.test(segment)))
-            return failure(400, "The API path is not valid.", "INVALID_PATH");
+            return refuse("MODULE_NOT_PROXIED", `The ${info.label} API is not available at this address.`);
+        if (path.some(isUnsafeSegment))
+            return refuse("INVALID_PATH", "The API path is not valid.");
+        // The app's address as the backend is told it, in X-Forwarded-Host and -Proto. The configured one comes first:
+        // Next.js takes a request URL's protocol from X-Forwarded-Proto, which anyone can send.
         const incoming = new URL(request.url);
+        const app = await appOriginOf(incoming);
+        // The module's root. One that is a path on this app is called at this server's own host and port, never at the
+        // configured origin, which an app may build from the Host header. What is wrong with a root (an environment
+        // variable's name, an address) is for the log only.
         let root;
         try {
-            root = new URL(await serverModuleRoot(info.module, incoming.origin));
+            root = new URL(await serverModuleRoot(info.module, ownOrigin(incoming)));
+            if (root.protocol !== "http:" && root.protocol !== "https:")
+                throw new Error(`The ${info.label} API's root is not an http or https address.`);
         }
         catch (error) {
             if (isFrameworkError(error))
                 throw error;
-            return failure(500, error instanceof Error ? error.message : String(error), "MODULE_NOT_CONFIGURED");
+            report({ messageCode: "MODULE_NOT_CONFIGURED", call, detail: error instanceof Error ? error.message : String(error) });
+            return refuse("MODULE_NOT_CONFIGURED", `The ${info.label} API is not set up on this server.`);
         }
         const target = new URL(joinUrl(root.toString(), path.map(encodeURIComponent).join("/")));
         target.search = incoming.search;
-        const headers = new Headers();
-        request.headers.forEach((value, name) => {
-            if (!REQUEST_HEADERS_TO_SKIP.has(name.toLowerCase()))
-                headers.set(name, value);
-        });
+        // The body, read whole so a 307 or 308 can send it again. A declared length over the limit is refused before a
+        // byte is read; an undeclared one is counted as it arrives.
+        let body;
+        if (method !== "GET" && method !== "HEAD") {
+            let read;
+            try {
+                read = Number(request.headers.get("content-length")) > maxBodySize ? null : await readBody(request.body, maxBodySize);
+            }
+            catch (error) {
+                if (isFrameworkError(error))
+                    throw error;
+                return refuse("REQUEST_UNREADABLE", buildMessage("reason", { status: 400 }));
+            }
+            if (!read)
+                return refuse("REQUEST_TOO_LARGE", buildMessage("reason", { action, status: 413 }));
+            body = read;
+        }
+        // The headers: the browser's, less this hop's, the app's cookies and everything the browser says about where it
+        // came from; then who the client is and where the app is, as the app knows them; then the app's own and the token.
+        const headers = forwardRequestHeaders(request.headers);
+        const client = readIpAddress(options.clientAddress ? await options.clientAddress(request) : lastForwardedAddress(request.headers));
+        if (client)
+            headers.set("X-Forwarded-For", client);
+        headers.set("X-Forwarded-Host", app.host);
+        headers.set("X-Forwarded-Proto", app.protocol.replace(":", ""));
         for (const [name, value] of Object.entries((await options.headers?.(request)) ?? {}))
             headers.set(name, value);
         const token = await options.token?.(request);
         if (token)
             headers.set("Authorization", /^bearer /i.test(token) ? token : `Bearer ${token}`);
+        // The token as the backend got it, to keep it out of the log and to spot an error page that repeats it.
+        const sentToken = token ? token.replace(/^bearer\s+/i, "") : undefined;
         const controller = new AbortController();
-        const timeout = options.timeout ?? DEFAULT_API_TIMEOUT;
         let timedOut = false;
         const timer = setTimeout(() => {
             timedOut = true;
@@ -75,37 +164,78 @@ export function createApiProxy(options = {}) {
         // The browser left: stop waiting for the backend.
         const leave = () => controller.abort();
         request.signal?.addEventListener("abort", leave, { once: true });
+        const send = options.fetch ?? globalThis.fetch;
+        let url = target;
+        let hopMethod = method;
+        let hopBody = body;
         let answer;
+        // An error answer, read whole (up to a limit) to see whether it may reach the browser as it came; null when larger.
+        let errorBody;
         try {
-            answer = await (options.fetch ?? globalThis.fetch)(target, {
-                method,
-                headers,
-                body: method === "GET" || method === "HEAD" ? undefined : await request.arrayBuffer(),
-                redirect: "manual",
-                cache: "no-store",
-                signal: controller.signal,
-            });
+            const ask = () => send(url, { method: hopMethod, headers, body: hopBody, redirect: "manual", cache: "no-store", signal: controller.signal });
+            answer = await ask();
+            let hops = 0;
+            while (isRedirect(answer.status)) {
+                // A redirect never reaches the browser: followed here while it stays inside the module, refused otherwise.
+                await answer.body?.cancel().catch(() => undefined);
+                const location = answer.headers.get("location");
+                const next = location ? redirectInsideModule(location, url, root) : undefined;
+                if (!next) {
+                    const where = location ? `to ${logLocation(location, url)}, outside the module's root ${logUrl(root)}` : "with no Location";
+                    report({ messageCode: "BACKEND_REDIRECT_REFUSED", call, detail: `${logUrl(url)} answered ${answer.status} ${where}` });
+                    return refuse("BACKEND_REDIRECT_REFUSED", buildMessage("reason", { status: 502 }));
+                }
+                if (hops >= maxRedirects) {
+                    report({ messageCode: "BACKEND_REDIRECT_LIMIT", call, detail: `more than ${maxRedirects} redirects; the last from ${logUrl(url)} to ${logUrl(next)}` });
+                    return refuse("BACKEND_REDIRECT_LIMIT", buildMessage("reason", { status: 502 }));
+                }
+                const nextMethod = methodAfterRedirect(answer.status, hopMethod);
+                if (nextMethod !== hopMethod) {
+                    // A 303, or a 301 or 302 after a POST: the request becomes a GET and leaves its body behind.
+                    hopBody = undefined;
+                    for (const name of BODY_HEADERS)
+                        headers.delete(name);
+                }
+                hopMethod = nextMethod;
+                url = next;
+                hops++;
+                answer = await ask();
+            }
+            if (hopMethod !== "HEAD" && !passesUnread(answer.status))
+                errorBody = await readBody(answer.body, ERROR_BODY_LIMIT);
         }
         catch (error) {
             if (isFrameworkError(error))
                 throw error;
-            if (timedOut)
-                return failure(504, buildMessage("reason", { timeout: true }), "BACKEND_TIMEOUT");
-            return failure(502, `The ${info.label} API cannot be reached. Try again in a moment.`, "BACKEND_UNREACHABLE");
+            if (timedOut) {
+                report({ messageCode: "BACKEND_TIMEOUT", call, detail: `${logUrl(url)} did not answer within ${timeout} ms` });
+                return refuse("BACKEND_TIMEOUT", buildMessage("reason", { timeout: true }));
+            }
+            // When the browser left, nobody reads the answer, and nothing failed on the backend's side.
+            if (!request.signal?.aborted)
+                report({ messageCode: "BACKEND_UNREACHABLE", call, detail: `${logUrl(url)}: ${describeFetchError(error)}` });
+            return refuse("BACKEND_UNREACHABLE", `The ${info.label} API cannot be reached. Try again in a moment.`);
         }
         finally {
-            // The timeout covers the wait for the answer to start; a long download then streams through.
+            // The timeout covers the wait for the answer to start, its redirects and the reading of an error answer included;
+            // a long download then streams through.
             clearTimeout(timer);
             request.signal?.removeEventListener("abort", leave);
         }
-        const responseHeaders = new Headers();
-        answer.headers.forEach((value, name) => {
-            const lower = name.toLowerCase();
-            if (RESPONSE_HEADERS_TO_SKIP.has(lower))
-                return;
-            responseHeaders.append(name, lower === "location" ? rewriteLocation(value, root, info.key, modules.proxyPath) : value);
-        });
-        return new Response(method === "HEAD" ? null : answer.body, { status: answer.status, statusText: answer.statusText, headers: responseHeaders });
+        const status = answer.status;
+        const responseHeaders = filterResponseHeaders(answer.headers, { extra: options.responseHeaders, passCookies: options.passCookies });
+        if (errorBody === undefined) {
+            const noBody = hopMethod === "HEAD" || NULL_BODY_STATUSES.has(status);
+            return harden(new Response(noBody ? null : answer.body, { status, headers: responseHeaders }));
+        }
+        // An error answer passes as it came when it is empty, or JSON that says nothing about the backend; anything else
+        // is replaced with the failure envelope, in plain words for the status, and the real cause is logged.
+        const text = errorBody === null ? "" : new TextDecoder().decode(errorBody);
+        const reason = errorBody === null ? `it was over ${ERROR_BODY_LIMIT} bytes` : whyHidden(answer.headers.get("content-type") ?? "", text, sentToken);
+        if (reason === undefined)
+            return harden(new Response(text === "" ? null : errorBody, { status, headers: responseHeaders }));
+        report({ messageCode: "BACKEND_ERROR_PAGE", call, detail: `${logUrl(url)} answered ${status}, and ${reason}: ${logSnippet(text, sentToken)}` });
+        return refuse("BACKEND_ERROR_PAGE", buildMessage("reason", { action, status }), status);
     }
     return { GET: handle, HEAD: handle, POST: handle, PUT: handle, PATCH: handle, DELETE: handle };
 }