@jsenv/server 17.6.7 → 17.6.8

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" }),
+];
+```

package/docs/https.md

@@ -0,0 +1,77 @@
+# HTTPS
+
+```js
+import { startServer } from "@jsenv/server";
+
+const server = await startServer();
+server.origin.startsWith("http://"); // true
+```
+
+```js
+import { readFileSync } from "node:fs";
+import { startServer } from "@jsenv/server";
+
+const server = await startServer({
+  https: {
+    certificate: readFileSync(new URL("./server.crt", import.meta.url), "utf8"),
+    privateKey: readFileSync(new URL("./server.key", import.meta.url), "utf8"),
+  },
+});
+server.origin.startsWith("https://"); // true
+```
+
+Without certificate files, [@jsenv/https-local](https://github.com/jsenv/core/tree/main/packages/tooling/https-local) generates one for localhost, signed by an authority it can install on the machine:
+
+```js
+import { requestCertificate } from "@jsenv/https-local";
+import { startServer } from "@jsenv/server";
+
+const { certificate, privateKey } = requestCertificate();
+await startServer({ https: { certificate, privateKey } });
+```
+
+## Http requests on an https server
+
+By default an https server also accepts http on the same port and redirects it (301) to the https origin. `redirectHttpToHttps: false` refuses http instead. To serve both:
+
+```js
+await startServer({
+  https: { certificate, privateKey },
+  allowHttpRequestOnHttps: true,
+  routes: [
+    {
+      endpoint: "GET *",
+      fetch: (request) => {
+        return new Response(
+          request.origin.startsWith("http:")
+            ? `Welcome http user`
+            : `Welcome https user`,
+        );
+      },
+    },
+  ],
+});
+```
+
+## http2
+
+```js
+await startServer({
+  https: { certificate, privateKey },
+  http2: true,
+});
+```
+
+Http2 needs https (browsers do not speak it in clear). Http/1.1 clients are still accepted, unless `http1Allowed: false`.
+
+**When it is worth it.** A browser opens at most 6 http/1.1 connections per origin, http2 multiplexes everything on one. Measured with Chromium loading a page of 300 ES modules served by this package:
+
+| network                               | http/1.1 | http2  |
+| ------------------------------------- | -------- | ------ |
+| localhost                             | 80 ms    | 83 ms  |
+| 5 ms of latency (a phone on the wifi) | 369 ms   | 131 ms |
+| 20 ms of latency                      | 1300 ms  | 135 ms |
+
+Nothing to gain on the machine itself; a lot as soon as there is latency, so serving other devices (`acceptAnyIp`) is the case for it. The price is a certificate the device trusts.
+
+**What is lost.** Http2 has no reason phrase (RFC 9113): the `statusText` of a response only reaches the server logs and the body of 4xx/5xx responses, browser devtools show the status code alone. Http/1.1 stays the default for that reason: during development the status line is where the server explains a 404 or a 403 at a glance.

package/docs/lifecycle.md

@@ -0,0 +1,52 @@
+# Lifecycle
+
+```js
+import { startServer } from "@jsenv/server";
+
+const server = await startServer({ port: 3000 });
+server.origin; // "http://localhost:3000"
+server.origins; // { local: "http://localhost:3000", localip: "http://127.0.0.1:3000" }
+server.port; // 3000
+server.getStatus(); // "opened"
+```
+
+`startServer` resolves once the server listens. With `port: 0` (the default) the OS picks a free port, `server.port` tells which one; `portHint` asks for a port and takes the next free one when it is busy. `hostname` ("localhost" by default) can be an ip. `acceptAnyIp: true` listens on every interface so that other machines reach the server, at `server.origins.externalip`.
+
+## Stopping
+
+```js
+await server.stop();
+server.getStatus(); // "stopped"
+```
+
+`stop` answers every request still running with 503, then closes every connection, and resolves once everything is closed. A response already being written is cut short: its status is already sent. It takes a reason, anything, which `stoppedPromise` resolves with:
+
+```js
+import { startServer, STOP_REASON_PROCESS_SIGINT } from "@jsenv/server";
+
+const server = await startServer();
+server.stoppedPromise.then((reason) => {
+  if (reason === STOP_REASON_PROCESS_SIGINT) {
+    console.log("stopped by ctrl+c");
+  }
+});
+```
+
+The server stops by itself on SIGINT (`stopOnSIGINT`, off inside a cluster worker where the primary process is in charge) and on SIGHUP, SIGTERM, beforeExit, exit (`stopOnExit`); the reasons are the `STOP_REASON_PROCESS_*` exports. `stopOnInternalError` stops it when a route throws. The `signal` option cancels the start itself.
+
+## Keeping the process alive
+
+A listening server keeps the process alive. `keepProcessAlive: false` lets the process exit when nothing else runs — tests want that: the server stops on its own once the test is done.
+
+## Running something as long as the server runs
+
+```js
+server.addEffect(() => {
+  const interval = setInterval(doSomething, 1000);
+  return () => {
+    clearInterval(interval);
+  };
+});
+```
+
+The callback runs right away, the function it returns runs when the server stops. Plugins have `serverListening` and `serverStopped` hooks for the same purpose (see [plugins](./plugins.md)).

package/docs/plugins.md

@@ -0,0 +1,53 @@
+# Plugins
+
+A server plugin is an object with a `name` and some of the hooks below. Plugins run in the order they are given, after the built-in ones. An array of plugins is flattened, so a function can return several plugins, or none (`serverPluginCORS` returns `[]` when CORS stays disabled).
+
+```js
+await startServer({
+  plugins: [
+    {
+      name: "my_plugin",
+      routes: [{ endpoint: "GET /health", fetch: () => new Response("ok") }],
+      injectResponseProperties: () => {
+        return { headers: { "x-powered-by": "jsenv" } };
+      },
+    },
+  ],
+});
+```
+
+## Hooks
+
+In the order they run for a request:
+
+| hook                         | signature                                                                       | role                                                                                                                                                       |
+| ---------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `serverListening`            | `({ port })`                                                                    | once, when the server listens                                                                                                                              |
+| `redirectRequest`            | `(request) => { resource } \| { pathname } \| { ...requestProperties } \| null` | replace the request seen by the routes; `request.original` keeps the first one                                                                             |
+| `augmentRouteFetchSecondArg` | `async (request, helpers) => { ...moreHelpers } \| null`                        | add helpers for the routes                                                                                                                                 |
+| `grantPermissions`           | `async (request) => ["permission", …] \| null`                                  | called lazily, at most once per request, only when a route declares permissions                                                                            |
+| `routes`                     | an array of route descriptors                                                   | appended after the routes given to `startServer`                                                                                                           |
+| `handleError`                | `async (error, { request }) => response \| null`                                | answer a route that threw; the first response wins ([handling errors](./handling_errors.md))                                                               |
+| `injectResponseProperties`   | `(request, response) => responseToCompose \| null`                              | compose something into every response — headers mostly, see `composeTwoResponses`                                                                          |
+| `inspectResponse`            | `(request, { response, warn })`                                                 | look at the final response, after every injection, before it is sent (`response` is `{ status, statusText, headers, body }`); `warn` logs for that request |
+| `serverStopped`              | `({ reason })`                                                                  | once, when the server stopped                                                                                                                              |
+
+`redirectRequest` and `injectResponseProperties` are synchronous; `augmentRouteFetchSecondArg`, `grantPermissions` and `handleError` may return a promise.
+
+Lifecycle properties: `init()` runs before the server starts (returning `false` disables the plugin, returning a function registers it as `destroy`), `destroy()` runs when the server stops, `effect({ otherPlugins })` runs after every `init` (returning nothing disables the plugin).
+
+## Built-in plugins
+
+Always on:
+
+- response cookies — `helpers.responseCookies.set(name, value, options)` and `.delete(name)`,
+- default body for 4xx/5xx — a response without body for such a status gets one from its `statusText`/`statusMessage`,
+- route inspector — `GET /.internal/route_inspector` and `GET /.internal/routes.json`.
+
+With `canExposeSensitiveData` (development only, see [security](./security.md)):
+
+- open file — `GET /.internal/open_file/*` opens a file of the machine in the editor,
+- internal client files — `GET /@jsenv/server/*` serves this package's client files,
+- autoreload on restart — `GET /.internal/alive.websocket` and `GET /.internal/alive.eventsource` close when the server stops, so a client reloads.
+
+Exported, to add yourself: `serverPluginCORS`, `serverPluginErrorHandler`, `serverPluginRequestAliases`, `serverPluginResponseAcceptanceCheck`. Their options are in their JSDoc.

package/docs/security.md

@@ -0,0 +1,32 @@
+# Security
+
+What the server takes care of, and what it leaves to the code around it.
+
+## What it does
+
+- A malformed header (`forwarded`, `cookie`, `referer`, `accept`…) never takes the server down: a request that cannot be read is answered 500 and logged.
+- **The `host` header is checked.** A request whose host is not one of the names the server is reached at (localhost, `hostname`, the machine name and ips, `allowedHosts`) is answered 403. Without this a page served by another site reads the responses once its DNS name is rebound to this machine — the request comes from the developer's own browser, so listening on localhost is no protection. A custom name (an `/etc/hosts` entry, a tunnel) goes in `hostname` or `allowedHosts`; `allowedHosts: true` disables the check.
+- **Request bodies are bounded.** `request.json()`, `text()`, `buffer()` and `queryString()` answer 413 past `requestBodyMaxSize` (1 MiB by default), from the `content-length` when there is one, else while reading; the rest of the body is drained for a few seconds so that the client gets the 413, then the connection is cut. A route accepting more passes its own `{ maxSize }`. `request.body` (the observable) is never limited: who streams it takes the responsibility. `formData()` is bounded by formidable (200 MB per file, 20 MB of fields).
+- What a response echoes from the request (the url in a 404 message, a file path in a status text) is escaped in the html error pages, and status texts are reduced to what a status line accepts.
+- `createFileSystemFetch` refuses to leave its directory (403).
+- A route declaring permissions hides every route that declares none: forgetting `permissionsRequired` cannot expose a route ([handling requests](./handling_requests.md)).
+- Once one route has permissions, the route inspector only lists what the requester may see.
+
+## `canExposeSensitiveData`
+
+This option lets the server hand out what belongs to the machine it runs on. It is meant for the developer's machine, never for a server others can reach. It unlocks:
+
+- file paths in status texts (a 404 from `createFileSystemFetch` says which path);
+- the declaration source of every route in the route inspector, where every route is listed whatever its permissions;
+- `GET /.internal/open_file/*`, which opens any file of the machine in the editor;
+- `GET /@jsenv/server/*`, which serves this package's own files;
+- `/.internal/alive.websocket` and `/.internal/alive.eventsource`, telling clients when the server restarts.
+
+`sendErrorDetails` of `serverPluginErrorHandler` is of the same kind: a stack reveals file paths and code.
+
+## What it leaves to you
+
+- **Forwarded headers are trusted as-is.** `request.ipForwarded`, `protoForwarded` and `hostForwarded` are what the `forwarded` / `x-forwarded-*` headers say; any client can send them. Read them only behind a proxy you control, `request.ip` is the socket address.
+- **Uploaded files are not cleaned up.** `formData()` writes them to the temp directory and leaves them there.
+- **A route that throws with no error handler exits the process.** Always run with `serverPluginErrorHandler` (or a `handleError` plugin), see [handling errors](./handling_errors.md).
+- **No rate limiting, no authentication.** `grantPermissions` is where a session or a token becomes permissions; what it checks is up to you.