@jsenv/server 17.6.6 → 17.6.8

package/docs/cors.md

@@ -0,0 +1,32 @@
+# CORS
+
+Cross-origin requests are refused by browsers unless the response carries the access control headers. `serverPluginCORS` adds them to every response, including errors — a 500 without them shows up as a CORS failure in the browser, which hides the actual problem.
+
+```js
+import {
+  serverPluginCORS,
+  serverPluginErrorHandler,
+  startServer,
+} from "@jsenv/server";
+
+await startServer({
+  plugins: [
+    serverPluginErrorHandler(),
+    serverPluginCORS({
+      accessControlAllowedOrigins: ["https://my-app.example"],
+      accessControlAllowRequestMethod: true,
+      accessControlAllowRequestHeaders: true,
+      accessControlAllowCredentials: true,
+    }),
+  ],
+});
+```
+
+The plugin stays off (returns no plugin) unless `accessControlAllowedOrigins` lists an origin or `accessControlAllowRequestOrigin` is true. The options are in its JSDoc; the ones worth a word:
+
+- `accessControlAllowedOrigins` — the origins allowed to read the responses. `*` stands for any run of characters except `/`, so `"https://pr-*-my-app.fly.dev"` covers every preview deployment. The request origin is reflected back when it is allowed, with `vary: origin`. An origin that is not allowed gets the first literal origin of the list, which the browser rejects, or no `access-control-allow-origin` at all when the list only has patterns.
+- `accessControlAllowRequestOrigin` — reflect any origin. Fine for a public API, not with credentials.
+- `accessControlAllowRequestMethod`, `accessControlAllowRequestHeaders` — also allow whatever a preflight asks for, on top of `accessControlAllowedMethods` (GET, POST, PUT, DELETE, OPTIONS) and `accessControlAllowedHeaders` (`x-requested-with`).
+- `accessControlMaxAge` — seconds a browser may cache a preflight (600).
+
+Preflight `OPTIONS` requests are answered by the router itself (see [handling requests](./handling_requests.md)); the plugin only adds the headers.

package/docs/demos/cluster/cluster_demo_primary.mjs

@@ -0,0 +1,31 @@
+import cluster from "node:cluster";
+import { cpus } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const numCPUs = cpus().length;
+
+const workerFileUrl = new URL("./cluster_demo_server.mjs", import.meta.url);
+
+cluster.setupPrimary({
+  exec: fileURLToPath(workerFileUrl),
+});
+
+console.log(`Primary ${process.pid} is running`);
+for (let i = 0; i < numCPUs; i++) {
+  cluster.fork();
+}
+
+cluster.on("online", (worker) => {
+  console.log(`Worker ${worker.process.pid} is online`);
+});
+
+cluster.on("exit", (worker, code, signal) => {
+  // https://nodejs.org/dist/latest-v16.x/docs/api/cluster.html#workerexitedafterdisconnect
+  if (worker.exitedAfterDisconnect) {
+    console.log(
+      `Worker ${worker.process.pid} died with code: ${code}, and signal: ${signal}`,
+    );
+    console.log(`Starting a new worker`);
+    cluster.fork();
+  }
+});

package/docs/demos/cluster/cluster_demo_primary_watch.mjs

@@ -0,0 +1,52 @@
+import { registerFileLifecycle } from "@jsenv/filesystem";
+import cluster from "node:cluster";
+import { cpus } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const numCPUs = cpus().length;
+
+const workerFileUrl = new URL("./cluster_demo_server.mjs", import.meta.url);
+
+cluster.setupPrimary({
+  exec: fileURLToPath(workerFileUrl),
+});
+
+console.log(`Primary ${process.pid} is running`);
+for (let i = 0; i < numCPUs; i++) {
+  cluster.fork();
+}
+
+cluster.on("online", (worker) => {
+  console.log(`Worker ${worker.process.pid} is online`);
+});
+
+cluster.on("exit", (worker, code, signal) => {
+  // https://nodejs.org/dist/latest-v16.x/docs/api/cluster.html#workerexitedafterdisconnect
+  if (worker.exitedAfterDisconnect) {
+    console.log(
+      `Worker ${worker.process.pid} died with code: ${code}, and signal: ${signal}`,
+    );
+    console.log(`Starting a new worker`);
+    cluster.fork();
+  }
+});
+
+registerFileLifecycle(workerFileUrl, {
+  updated: () => {
+    console.log("Server file updated, restarting servers...");
+
+    Object.keys(cluster.workers).forEach((workerId) => {
+      const worker = cluster.workers[workerId];
+
+      // force kill if graceful exit fails
+      const timeout = setTimeout(() => {
+        worker.kill("SIGKILL");
+      }, 5000);
+      worker.once("exit", () => {
+        clearTimeout(timeout);
+      });
+      // try gracefull exit
+      worker.kill();
+    });
+  },
+});

package/docs/demos/cluster/cluster_demo_server.mjs

@@ -0,0 +1,10 @@
+import { createFileSystemFetch, startServer } from "@jsenv/server";
+
+await startServer({
+  routes: [
+    {
+      endpoint: "GET *",
+      fetch: createFileSystemFetch(import.meta.resolve("./")),
+    },
+  ],
+});

package/docs/demos/cors/cors_error_demo.mjs

@@ -0,0 +1,29 @@
+import {
+  serverPluginCORS,
+  serverPluginErrorHandler,
+  startServer,
+} from "@jsenv/server";
+
+const server = await startServer({
+  plugins: [
+    serverPluginErrorHandler(),
+    serverPluginCORS({
+      accessControlAllowRequestOrigin: true,
+      accessControlAllowRequestMethod: true,
+      accessControlAllowRequestHeaders: true,
+      accessControlAllowCredentials: true,
+    }),
+  ],
+  routes: [
+    {
+      endpoint: "GET *",
+      fetch: () => {
+        throw new Error("test");
+      },
+    },
+  ],
+});
+
+const response = await fetch(server.origin);
+console.log(response.status); // 500
+console.log(response.headers.has("access-control-allow-origin")); // true

package/docs/demos/https/https_file_demo.mjs

@@ -0,0 +1,21 @@
+import { startServer } from "@jsenv/server";
+import { readFileSync } from "node:fs";
+
+await startServer({
+  https: {
+    certificate: readFileSync(new URL("./server.crt", import.meta.url), "utf8"),
+    privateKey: readFileSync(new URL("./server.key", import.meta.url), "utf8"),
+  },
+  allowHttpRequestOnHttps: true,
+  routes: [
+    {
+      endpoint: "GET *",
+      fetch: (request) => {
+        const clientUsesHttp = request.origin.startsWith("http:");
+        return new Response(
+          clientUsesHttp ? `Welcome http user` : `Welcome https user`,
+        );
+      },
+    },
+  ],
+});

package/docs/demos/https/server.crt

@@ -0,0 +1,24 @@
+-----BEGIN CERTIFICATE-----
+MIIECjCCAvKgAwIBAgIBATANBgkqhkiG9w0BAQsFADCBkTEuMCwGA1UEAxMlaHR0
+cHM6Ly9naXRodWIuY29tL2pzZW52L2pzZW52LXNlcnZlcjELMAkGA1UEBhMCRlIx
+GDAWBgNVBAgTD0FscGVzIE1hcml0aW1lczERMA8GA1UEBxMIVmFsYm9ubmUxDjAM
+BgNVBAoTBWpzZW52MRUwEwYDVQQLEwxqc2VudiBzZXJ2ZXIwHhcNMjEwNjEwMDgz
+NDM4WhcNMjIwNzExMDgzNDM5WjCBkTEuMCwGA1UEAxMlaHR0cHM6Ly9naXRodWIu
+Y29tL2pzZW52L2pzZW52LXNlcnZlcjELMAkGA1UEBhMCRlIxGDAWBgNVBAgTD0Fs
+cGVzIE1hcml0aW1lczERMA8GA1UEBxMIVmFsYm9ubmUxDjAMBgNVBAoTBWpzZW52
+MRUwEwYDVQQLEwxqc2VudiBzZXJ2ZXIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAw
+ggEKAoIBAQDDaJLXCSyLm5zWi/J2vcNrhRfHpDcBnydRMxEqqmc+zazd80pqeGEy
+znVQDnjrJ0cymFXVvelw15UnB5kKhRpsJMzh/5c1rIXU2Ti5cpnWDb599I44vPdJ
+APf8L7d2z0keLLn6gQMdIQKFv68jIM1rWer3FFyA3W4RP16UhtYCDNwO4WeHvryE
+4bBkYInYo6CKTTUR3pv0BB9oNdQdiSGDgDy/JX6n/DF2y6QfyznICW0rtITG52Gg
+NLAS/0SY//xmE7sApv/fdy8IHtZ1WB7tbvZPjpwcTy4ISAmxUbSs8ratcCD8JEhP
+OSKWybp22EFssdDuF8mRApJ46Wbu+VWrAgMBAAGjazBpMB8GA1UdIwQYMBaAFDs2
+JcFL/Bn0mqi7rt7DZuNnpPajMA4GA1UdDwEB/wQEAwIFoDATBgNVHSUEDDAKBggr
+BgEFBQcDATAhBgNVHREEGjAYhwR/AAABgglsb2NhbGhvc3SCBWpzZW52MA0GCSqG
+SIb3DQEBCwUAA4IBAQB7OabCeian7zIrW2uQc66VI/jO1Ol6vPugtmywPtYiSKkC
+EXG3xuXFi8klPy7tPMJucMPCTZmBy9ymNkaxzrhrZqNvFcdfrJanEaSltu96Yoti
+PTwoqxX0ymAbVTwnulxLiaJqu0z3rQkSogIdeo4InPxqqTA1gYAakMZPkS5JNFgz
+aSlzvxK6rKXD+b2PxclMBvD9CL5eq9StHppD9rYgY39islxRcaQPazXSCTNhU/TN
+Y1gUngqE7PJoBgjJjsVp4MmIjDv9snR12RbIVpm+o2szg2rSN0D0SamjW2hH3MtN
+si/Ce9UYvwS3Bijm/CuxxZX5JKMAGQzLvGhMu1KT
+-----END CERTIFICATE-----

package/docs/demos/https/server.key

@@ -0,0 +1,27 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIEpAIBAAKCAQEAw2iS1wksi5uc1ovydr3Da4UXx6Q3AZ8nUTMRKqpnPs2s3fNK
+anhhMs51UA546ydHMphV1b3pcNeVJweZCoUabCTM4f+XNayF1Nk4uXKZ1g2+ffSO
+OLz3SQD3/C+3ds9JHiy5+oEDHSEChb+vIyDNa1nq9xRcgN1uET9elIbWAgzcDuFn
+h768hOGwZGCJ2KOgik01Ed6b9AQfaDXUHYkhg4A8vyV+p/wxdsukH8s5yAltK7SE
+xudhoDSwEv9EmP/8ZhO7AKb/33cvCB7WdVge7W72T46cHE8uCEgJsVG0rPK2rXAg
+/CRITzkilsm6dthBbLHQ7hfJkQKSeOlm7vlVqwIDAQABAoIBABu6tzu0nZGiH3uC
+mIGpJBYZ6On3r6aXQykOqhz32XbcEO/eGm1Jb+GZ0qPtqdMU29GeNHAEZyAQN6Y2
+Oc14XeuCvWBEuNxxAvzVZmtKi/IIOUP+dEAw8JZ3gLlUvCAsAiA6EJovvJVhnc4F
+CYFeokfdlq5BQW83/OqNp4pEKBJaKVAzCon0EuqudHbIVk6pZvrxgNCAYtL/ADG+
+3GNwhG16jqcokU5xan0tfHi9wwgmT6mRt8WHqdH4tVPysMckHrlUDy3Nf089PWXE
+gmJ8Fm1f6aEkpW7Io/8Z4cMEhJbFPSw8gvhpkTrmac8g2kz4dOvy7uzGlRQX84NB
+UHG0SeECgYEA5ZCzzYM/2zA9zraB7tb3h3aXZSXvH9X/O239SEFzxwRfyKf3HaWO
+zeLnKVXwJt5/42Yt90aVnEUuT0dMZufzNU4llcc9YRYw42APXuCGpOyhrdh8ML2C
+IdBFZskXQV9U1rheJsqJy2uYk0RhbWe1B6jw+sYPnH+mTRUgE11Z4R8CgYEA2ej5
+AUVjG/Es4PwGGqYSH1f2rBTcyP1EVbKtT8mrp2gkaenWnEZJ6KBV2FGOji4Y50GU
+K05YnY/OkqgF+ii2Sr4BgqeAYcQxzEoWEcJx4M2lyCkpzSlXfIkbm2UjOoHeEa9v
+ly6Bcr8U0FpfO5yo9EaQo/SR+sj9z0QprcYfvfUCgYEAqfmbeCafSF8O1JjD2iFn
+A/EmJemRhaQAqHNHH5H+9LPjbAIZ8eScuQsxl6Se/VivnqMQk8+6hQugP2kOQ/+o
+T6a+I4lzhAhXSHPezaQ3bbQb/kmVos0epoS8bl+kjW3Vtmqqo9RBdNIFFb2C2ev4
+2WQYkcXG11yYuOhUaKItI4cCgYAgVQz9P0phTvuVtk9BjPqLZAXZqo7H06xb+tL0
+T7wEbtNYU7XgIh29Qmz6V7+LIRPY3EYb1tgXKMtBv2SDpZ7GoEKhHDFUUEQDR8rW
+f79d16WNeW4WXtf4Rm+uMudzOum0Pg+UovXaDLgN4hrXQXtgI0g6y4MNbt0Z78cv
+XYJAMQKBgQCXjfNHXZ3XHaT+lrHlfDOfEyRh7oRQ5CJVgzfRBQMI4bW5M0OzvMie
+O0EugYcoCtdxyMCUWg/CurbHFQ49lSHASYQnTRgLdyq0825vhxVzj+1kYFK1I6vP
+B8FHFiUWjsgrqNgBAC/PhIDbZ4VtPrdlPBQjWwdSNpEHIL6b+rP7hA==
+-----END RSA PRIVATE KEY-----

package/docs/demos/node_fetch_demo.mjs

@@ -0,0 +1,14 @@
+import { startServer } from "@jsenv/server";
+
+const server = await startServer({
+  routes: [
+    {
+      endpoint: "GET *",
+      fetch: () => new Response("Hello world"),
+    },
+  ],
+});
+
+const response = await fetch(server.origin);
+const responseBodyAsText = await response.text();
+console.log(responseBodyAsText); // "Hello world"

package/docs/demos/server_sent_events/client.js

@@ -0,0 +1,6 @@
+import { EventSource } from "eventsource";
+
+const eventSource = new EventSource("http://localhost:3456/events");
+eventSource.addEventListener("ping", (event) => {
+  console.log("> ping from server", event.lastEventId, JSON.parse(event.data));
+});

package/docs/demos/server_sent_events/run.js

@@ -0,0 +1,2 @@
+import("./server.js");
+import("./client.js");

package/docs/demos/server_sent_events/server.js

@@ -0,0 +1,20 @@
+import { ServerEvents, startServer } from "@jsenv/server";
+
+const serverEvents = new ServerEvents();
+setInterval(() => {
+  serverEvents.sendEventToAllClients({
+    type: "ping",
+    data: JSON.stringify({ ts: Date.now() }),
+  });
+}, 1000);
+
+await startServer({
+  logLevel: "warn",
+  port: 3456,
+  routes: [
+    {
+      endpoint: "GET /events",
+      fetch: serverEvents.fetch,
+    },
+  ],
+});

package/docs/demos/websocket/client.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <title>Title</title>
+    <link rel="icon" href="data:," />
+  </head>
+
+  <body>
+    <script>
+      const websocket = new WebSocket("ws://localhost:3000");
+      websocket.onmessage = (message) => {
+        document.body.appendChild(document.createTextNode(message.data));
+      };
+    </script>
+  </body>
+</html>

package/docs/demos/websocket/server.js

@@ -0,0 +1,26 @@
+import {
+  createFileSystemFetch,
+  startServer,
+  WebSocketResponse,
+} from "@jsenv/server";
+
+await startServer({
+  port: 3000,
+  routes: [
+    {
+      endpoint: "GET *",
+      headers: {
+        upgrade: "websocket",
+      },
+      fetch: () => {
+        return new WebSocketResponse((websocket) => {
+          websocket.send("Hello world");
+        });
+      },
+    },
+    {
+      endpoint: "GET *",
+      fetch: createFileSystemFetch(import.meta.resolve("./")),
+    },
+  ],
+});

package/docs/handling_errors.md

@@ -0,0 +1,75 @@
+# Handling errors
+
+A route that throws (or rejects) is answered by the first plugin whose `handleError` hook returns a response. **Without such a plugin the error is thrown and the process exits**: a server always runs with one. `serverPluginErrorHandler` is the generic one:
+
+```js
+import { serverPluginErrorHandler, startServer } from "@jsenv/server";
+
+await startServer({
+  plugins: [serverPluginErrorHandler()],
+  routes: [
+    {
+      endpoint: "GET *",
+      fetch: () => {
+        throw new Error("toto");
+      },
+    },
+  ],
+});
+```
+
+It answers 500 with an html page, a text or a json, depending on what the request accepts.
+
+![screenshot of internal error page](./screenshots/500.png)
+
+![screenshot of internal error page expanded](./screenshots/500_expanded.png)
+
+With `sendErrorDetails: true` the error stack (and its properties, in json) is sent. A stack reveals file paths and code: development only.
+
+![screenshot of internal error page with details expanded](./screenshots/500_expanded_and_details_enabled.png)
+
+The error responses get `cache-control: no-store`.
+
+## Handling some errors yourself
+
+`serverPluginErrorHandler` catches every error, so it comes last; a plugin handling a subset of them comes before:
+
+```js
+await startServer({
+  plugins: [
+    {
+      handleError: (error) => {
+        if (error.code === "FOO") {
+          return new Response('Custom response for error with code "FOO"', {
+            status: 500,
+          });
+        }
+        return null;
+      },
+    },
+    serverPluginErrorHandler(),
+  ],
+});
+```
+
+An error exposing an `asResponse()` method is answered with what it returns, with or without an error plugin: a way for a domain error to carry its own status (a request body too large is answered 413 that way).
+
+A route can also decide not to throw:
+
+```js
+fetch: async () => {
+  try {
+    return Response.json(await fetchExternalData());
+  } catch (error) {
+    return Response.json({ error: "Could not retrieve data" }, { status: 502 });
+  },
+};
+```
+
+## Timeouts
+
+A route that has not started responding after `responseTimeout` (10 minutes by default) is answered 504; the route keeps running and what it throws afterwards is logged.
+
+## Stopping on internal error
+
+`stopOnInternalError: true` stops the server as soon as a route throws, for a supervisor to restart it in a clean state. The request that threw, and every other request still running, is answered 500 with no body: the `handleError` plugins still run, but their response is not sent.

package/docs/handling_requests.md

@@ -0,0 +1,201 @@
+# Handling requests
+
+A request is answered by the first route whose `fetch` returns a response.
+
+```js
+import { startServer } from "@jsenv/server";
+
+await startServer({
+  routes: [
+    {
+      endpoint: "GET /",
+      fetch: () => new Response("Hello world"),
+    },
+  ],
+});
+```
+
+## Routes
+
+`endpoint` is an http method (or `*`) followed by a resource pattern:
+
+| endpoint               | matches                                                             |
+| ---------------------- | ------------------------------------------------------------------- |
+| `GET /`                | exactly `/`                                                         |
+| `GET /users/:id`       | `/users/42`, with `request.params.id === "42"`                      |
+| `GET /assets/*`        | `/assets/css/main.css`, with `request.params[0] === "css/main.css"` |
+| `GET /search?q=:query` | `/search?q=hello`, with `request.params.query === "hello"`          |
+| `* /api/*`             | any method                                                          |
+| `GET *`                | anything: a catch-all, put it last                                  |
+
+Routes are tried in order. `fetch` can be async; returning `null` or `undefined` declines the request and the next route is tried.
+
+When no route answers, the router builds the response from what almost matched:
+
+- **405 Method Not Allowed** (with an `allow` header) when the resource matched routes for other methods — a catch-all `*` route does not count, it says nothing about the resource,
+- **415 Unsupported Media Type** when a POST/PATCH/PUT route wanted another `content-type` (see `acceptedMediaTypes` below),
+- **406 Not Acceptable** when the route cannot produce what the request accepts (see [content negotiation](./content_negotiation.md)),
+- **426 Upgrade Required** for a websocket route requested without an upgrade,
+- **404 Not Found** otherwise.
+
+`OPTIONS` requests are answered from the routes (`allow`, `accept-post`, `accept-patch` headers); `OPTIONS *` describes the whole server.
+
+The routes can be explored at `/.internal/route_inspector` (json at `/.internal/routes.json`); a route's `description` and `clientCodeExample` show up there.
+
+## The request object
+
+Frozen, passed as first argument to `fetch`:
+
+```js
+request.method; // "GET"
+request.url; // "http://127.0.0.1:8080/users/42?page=2"
+request.origin; // "http://127.0.0.1:8080"
+request.pathname; // "/users/42"
+request.resource; // "/users/42?page=2" (path and search, as received)
+request.searchParams; // URLSearchParams
+request.params; // { id: "42" }, captured by the endpoint pattern
+request.headers; // { accept: "text/html", ... } lowercased names
+request.cookies; // Map { "session" => "abc" }
+request.signal; // AbortSignal: the client left, or the server stops
+request.http2; // true when the request came over http2
+request.proto; // "http" or "https", from the connection
+request.host; // the host header
+request.ip; // address of the socket
+request.ipForwarded; // what the forwarded / x-forwarded-for header says, unverified
+request.protoForwarded; // idem (x-forwarded-proto)
+request.hostForwarded; // idem (x-forwarded-host)
+request.logger; // debug/info/warn/error scoped to this request
+```
+
+`request.logger` is what a route uses to log: its lines are buffered and written together with the response status line, so the logs of concurrent requests do not interleave.
+
+Reading the body, each returns a promise:
+
+- `request.json()`, `request.text()`, `request.buffer()`
+- `request.formData()` → `{ fields, files }` for `multipart/form-data` (files are written to the temp directory)
+- `request.queryString()` for `application/x-www-form-urlencoded`
+- `request.body` is an observable of chunks, for streaming or for reading with a size limit
+
+`json()`, `text()`, `buffer()` and `queryString()` refuse a body bigger than `requestBodyMaxSize` (1 MiB by default) with a 413 response; a route accepting more passes its own limit: `request.json({ maxSize: 50 * 1024 * 1024 })`. `request.body` is never limited (see [security](./security.md)).
+
+A route reading its body declares `acceptedMediaTypes`: an unsupported `content-type` is refused with 415 before `fetch` runs.
+
+```js
+{
+  endpoint: "PATCH /users/:id",
+  acceptedMediaTypes: ["application/json", "multipart/form-data"],
+  fetch: async (request) => {
+    if (request.headers["content-type"] === "application/json") {
+      const patch = await request.json();
+      return Response.json(patch);
+    }
+    const { fields, files } = await request.formData();
+    return Response.json({ fields, files: Object.keys(files) });
+  },
+}
+```
+
+## The helpers
+
+Second argument of `fetch`:
+
+```js
+fetch: async (request, helpers) => {
+  helpers.timing; // measure something, see server_timing.md
+  helpers.injectResponseHeader("vary", "accept"); // added to the response, whatever it ends up being
+  helpers.contentNegotiation; // { mediaType, language, version, encoding }, see content_negotiation.md
+  helpers.responseCookies.set("session", "abc", { httpOnly: true, path: "/" });
+  helpers.responseCookies.delete("session");
+  await helpers.hasPermissions(["admin"]); // true or false, see permissions below
+  await helpers.getAllPermissions(); // a Set of every permission granted
+  helpers.canExposeSensitiveData; // the startServer option
+  helpers.router; // router.inspect() lists the routes
+};
+```
+
+Plugins add their own with `augmentRouteFetchSecondArg` (see [plugins](./plugins.md)).
+
+## Responses
+
+`fetch` returns a standard `Response`:
+
+```js
+new Response("Hello", {
+  status: 200,
+  headers: { "content-type": "text/plain" },
+});
+Response.json({ hello: "world" });
+```
+
+or a plain object:
+
+```js
+{
+  status: 200, // defaults to 404
+  statusText: "OK", // the reason phrase of the status line (http/1.1 only)
+  statusMessage: "A longer explanation", // becomes the body of a 4xx/5xx response that has none
+  headers: { "content-type": "text/plain" },
+  body: "Hello",
+  timing: { "db query": 12.3 }, // joins the server-timing header, see server_timing.md
+}
+```
+
+`body` can be a string, a `Buffer`, a Node readable stream (`createReadStream(file)`), a web `ReadableStream`, a file handle, a promise of one of these, or be written over time:
+
+```js
+import { ProgressiveResponse } from "@jsenv/server";
+
+fetch: () =>
+  new ProgressiveResponse(({ write, end }) => {
+    write("a");
+    setTimeout(() => {
+      write("b");
+      end();
+    }, 100);
+  });
+```
+
+A 4xx/5xx response without body gets one — html, text or json depending on what the request accepts — made of `statusText` and `statusMessage`. What they say is escaped, so echoing the request in them is fine.
+
+## Permissions
+
+A plugin grants permissions to a request with the `grantPermissions` hook; each route declares what it needs:
+
+```js
+await startServer({
+  plugins: [
+    {
+      grantPermissions: async (request) => {
+        return (await isAdmin(request)) ? ["admin"] : [];
+      },
+    },
+  ],
+  routes: [
+    // 404 for anyone else: the route does not even exist for them
+    { endpoint: "GET /admin", permissionsRequired: ["admin"], fetch },
+    // 403 for anyone else: the route is known, access is denied
+    {
+      endpoint: "DELETE /users/:id",
+      permissionsRequired: ["admin"],
+      permissionsToSee: [],
+      fetch,
+    },
+    // everyone
+    { endpoint: "GET /", permissionsRequired: [], fetch },
+  ],
+});
+```
+
+As soon as one route declares permissions, a route without `permissionsRequired` is hidden (404) from everyone: forgetting it cannot expose a route. `permissionsToSee` decides between 404 (hidden) and 403 (known, denied). Permissions are computed lazily and at most once per request, whatever the number of routes checked.
+
+## Rewriting a request before routing
+
+The `redirectRequest` plugin hook replaces the request seen by the routes; the first one stays reachable as `request.original` (and the one just before as `request.previous`). `serverPluginRequestAliases` does it from url patterns:
+
+```js
+import { serverPluginRequestAliases } from "@jsenv/server";
+
+plugins: [
+  serverPluginRequestAliases({ "/": "/index.html", "/*.mjs": "/*.js" }),
+];
+```