@jsenv/server 17.6.6 → 17.6.8

package/dist/jsenv_server.js

@@ -1150,6 +1150,62 @@ const stringifyHeaderProperty = ({ name, value }) => {
   return `${name}=${value}`;
 };
 
+/*
+ * A request target is the text between the method and the http version on the
+ * request line (RFC 9112 section 3.2), or the ":path" pseudo header in http2.
+ * It is a path, not a url reference, and the two must never be confused:
+ * "//wp-includes/x" is an origin-form target whose first path segment is
+ * empty, but `new URL("//wp-includes/x", origin)` reads it as a
+ * protocol-relative reference and turns "wp-includes" into the host. So the
+ * path is assigned onto the origin instead, and what a client sends can never
+ * replace that origin.
+ *
+ * The one form that legitimately names an origin is absolute-form
+ * ("GET http://host/path", sent by proxies and open-proxy scanners); it is
+ * read as such so the origin it names goes through the allowedHosts check
+ * like any other host, instead of reaching the routes unchecked.
+ */
+
+const ABSOLUTE_FORM_REGEX = /^[a-z][a-z0-9+\-.]*:\/\//i;
+
+/**
+ * @param {string} target the raw request target
+ * @returns {{ origin: string|null, host: string|null, resource: string }|null}
+ *   null when the target cannot be read; the server answers 400
+ */
+const readRequestTarget = (target) => {
+  if (!ABSOLUTE_FORM_REGEX.test(target)) {
+    // origin-form ("/path?query"), asterisk-form ("*") or authority-form
+    return { origin: null, host: null, resource: target };
+  }
+  if (!URL.canParse(target)) {
+    return null;
+  }
+  const urlObject = new URL(target);
+  if (urlObject.protocol !== "http:" && urlObject.protocol !== "https:") {
+    return null;
+  }
+  return {
+    origin: urlObject.origin,
+    host: urlObject.host,
+    resource: `${urlObject.pathname}${urlObject.search}`,
+  };
+};
+
+// the search of baseUrl is dropped: the resource carries its own
+const resourceToUrlObject = (resource, baseUrl) => {
+  const urlObject = new URL(baseUrl);
+  const searchSeparatorIndex = resource.indexOf("?");
+  if (searchSeparatorIndex === -1) {
+    urlObject.pathname = resource;
+    urlObject.search = "";
+  } else {
+    urlObject.pathname = resource.slice(0, searchSeparatorIndex);
+    urlObject.search = resource.slice(searchSeparatorIndex);
+  }
+  return urlObject;
+};
+
 // https://wicg.github.io/observable/#core-infrastructure
 
 if ("observable" in Symbol === false) {
@@ -1329,8 +1385,13 @@ const fromNodeRequest = (
   nodeRequest.pause();
   const body = observableFromNodeStream(nodeRequest);
 
+  // an absolute-form target names the origin the request is for; the host
+  // header is ignored in that case (RFC 9112 section 3.3)
+  const requestTarget = readRequestTarget(nodeRequest.url);
   let requestOrigin;
-  if (nodeRequest.upgrade) {
+  if (requestTarget.origin) {
+    requestOrigin = requestTarget.origin;
+  } else if (nodeRequest.upgrade) {
     requestOrigin = serverOrigin;
   } else if (nodeRequest.authority) {
     requestOrigin = nodeRequest.connection.encrypted
@@ -1463,7 +1524,7 @@ const fromNodeRequest = (
     http2: Boolean(nodeRequest.stream),
     origin: requestOrigin,
     ...getPropertiesFromResource({
-      resource: nodeRequest.url,
+      resource: requestTarget.resource,
       baseUrl: requestOrigin,
     }),
     method: nodeRequest.method,
@@ -1690,13 +1751,12 @@ const applyRedirectionToRequest = (
   };
 };
 const getPropertiesFromResource = ({ resource, baseUrl }) => {
-  const urlObject = new URL(resource, baseUrl);
-  let pathname = urlObject.pathname;
+  const urlObject = resourceToUrlObject(resource, baseUrl);
 
   return {
     url: String(urlObject),
     searchParams: urlObject.searchParams,
-    pathname,
+    pathname: urlObject.pathname,
     resource,
   };
 };
@@ -2974,14 +3034,6 @@ const trackServerPendingRequests = (nodeServer) => {
     pendingClients.clear();
     await Promise.all(
       pendingClientsArray.map(({ nodeRequest, nodeResponse }) => {
-        if (nodeResponse.headersSent === false) {
-          if (nodeRequest.stream) {
-            // http2 has no reason phrase
-            nodeResponse.writeHead(status);
-          } else {
-            nodeResponse.writeHead(status, asReasonPhrase(reason));
-          }
-        }
         return new Promise((resolve) => {
           if (nodeResponse.destroyed) {
             resolve();
@@ -2990,7 +3042,20 @@ const trackServerPendingRequests = (nodeServer) => {
           nodeResponse.once("close", () => {
             resolve();
           });
-          nodeResponse.destroy();
+          if (nodeResponse.headersSent) {
+            // a status already sent cannot be replaced: the response is cut
+            nodeResponse.destroy();
+            return;
+          }
+          if (nodeRequest.stream) {
+            // http2 has no reason phrase, nor a connection header
+            nodeResponse.writeHead(status);
+          } else {
+            nodeResponse.writeHead(status, asReasonPhrase(reason), {
+              connection: "close",
+            });
+          }
+          nodeResponse.end();
         });
       }),
     );
@@ -3083,7 +3148,7 @@ const getWebSocketHandler = (responseProperties) => {
  * @class
  * @param {Object} options - Configuration options for the SSE controller
  * @param {String} [options.logLevel] - Controls logging verbosity ('debug', 'info', 'warn', 'error', etc.)
- * @param {Boolean} [options.keepProcessAlive=false] - If true, prevents Node.js from exiting while SSE connections are active
+ * @param {Boolean} [options.keepProcessAlive=false] - If true, the keepalive timer keeps the process alive until `close()`
  * @param {Number} [options.keepaliveDuration=30000] - Milliseconds between keepalive messages to prevent connection timeout
  * @param {Number} [options.retryDuration=1000] - Suggested client reconnection delay in milliseconds
  * @param {Number} [options.historyLength=1000] - Maximum number of events to keep in history for reconnecting clients
@@ -3139,7 +3204,7 @@ class ServerEvents {
  * @param {Function} producer - Function called when first client connects
  * @param {Object} [options] - Configuration options for the SSE controller
  * @param {String} [options.logLevel] - Controls logging verbosity ('debug', 'info', 'warn', 'error', etc.)
- * @param {Boolean} [options.keepProcessAlive=false] - If true, prevents Node.js from exiting while SSE connections are active
+ * @param {Boolean} [options.keepProcessAlive=false] - If true, the keepalive timer keeps the process alive until `close()`
  * @param {Number} [options.keepaliveDuration=30000] - Milliseconds between keepalive messages to prevent connection timeout
  * @param {Number} [options.retryDuration=1000] - Suggested client reconnection delay in milliseconds
  * @param {Number} [options.historyLength=1000] - Maximum number of events to keep in history for reconnecting clients
@@ -3208,8 +3273,9 @@ const createServerEvents = ({
 } = {}) => {
   const logger = createLogger({ logLevel });
 
+  // starts closed: open() below installs the keepalive interval
   const serverEventSource = {
-    closed: false,
+    closed: true,
   };
   const clientArray = [];
   const eventHistory = createEventHistory(historyLength);
@@ -3451,6 +3517,7 @@ const createServerEvents = ({
     close,
     open,
   });
+  open();
   return serverEventSource;
 };
 
@@ -4621,10 +4688,10 @@ const SERVER_PLUGIN_PROPERTIES = {
   grantPermissions: { type: "hook" },
   // async (error, { request }) => response | null
   handleError: { type: "hook" },
-  // (request, { response, warn }) to look at the response before it is sent
-  inspectResponse: { type: "hook" },
   // (request, response) => responseToCompose | null
   injectResponseProperties: { type: "hook" },
+  // (request, { response, warn }) to look at the final response before it is sent
+  inspectResponse: { type: "hook" },
   // ({ reason }) once the server is stopped
   serverStopped: { type: "hook" },
   // route descriptors, appended after the routes given to startServer
@@ -5833,8 +5900,17 @@ const createResourcePattern = (pattern) => {
   }
 
   const patternEndsWithSlash = pathnamePatternString.endsWith("/");
+  // a pattern constraining nothing: every resource matches it, so whoever uses
+  // it cannot name the resource that matched
+  const matchesEveryResource =
+    !searchPattern &&
+    !hashPattern &&
+    (pathnamePatternString === "*" ||
+      pathnamePatternString === "/" ||
+      pathnamePatternString === "/*");
 
   return {
+    matchesEveryResource,
     match: (resource) => {
       const [pathname, search, hash] = resourceToParts(resource);
       let decodedPathname = decodeURIComponent(pathname);
@@ -6477,9 +6553,9 @@ It should be should be one of route.${routePropertyName}: ${availableValues.join
         }
         if (!route.matchMethod(request.method)) {
           // a 405 asserts the resource exists with other methods: a route
-          // matching any resource ("GET *") cannot assert that, so it does
-          // not turn an unknown resource into a 405
-          if (!route.isFallback && route.resource !== "*") {
+          // matching every resource ("GET *", "GET /") names no resource, so
+          // it cannot make that assertion and an unknown address stays a 404
+          if (!route.isFallback && !route.matchesEveryResource) {
             wouldHaveMatched.methodSet.add(route.method);
           }
           continue;
@@ -6777,7 +6853,8 @@ const createRoute = ({
   if (!endpoint || typeof endpoint !== "string") {
     throw new TypeError(`endpoint must be a string, received ${endpoint}`);
   }
-  const [method, resource] = endpoint === "*" ? ["* *"] : endpoint.split(" ");
+  const [method, resource] =
+    endpoint === "*" ? ["*", "*"] : endpoint.split(" ");
   if (method !== "*" && !HTTP_METHODS.includes(method)) {
     throw new TypeError(`"${method}" is not an HTTP method`);
   }
@@ -6827,6 +6904,8 @@ const createRoute = ({
         : (requestResource) => {
             return resourcePattern.match(requestResource);
           },
+    matchesEveryResource:
+      resource === "*" || resourcePattern.matchesEveryResource,
     matchHeaders:
       headers === undefined
         ? () => true
@@ -6994,8 +7073,9 @@ const createResourceOptionsResponse = (request, resourceOptions) => {
  * @param {Object} params - Content negotiation parameters
  * @param {Array<string>} params.availableMediaTypes - Content types the server can produce
  * @param {Array<string>} params.availableLanguages - Languages the server can respond with
+ * @param {Array<string|number|Function>} params.availableVersions - Versions the server can respond with
  * @param {Array<string>} params.availableEncodings - Encodings the server supports
- * @returns {Response} A 406 Not Acceptable response
+ * @returns {Object} 406 response properties
  */
 const createNotAcceptableResponse = (
   request,
@@ -7296,8 +7376,9 @@ const TIMING_NOOP = () => {
  * @param {boolean} [params.stopOnSIGINT] - Stop on SIGINT (ctrl+c). Defaults to true, except
  *   inside a cluster worker where the primary process is in charge.
  * @param {boolean} [params.stopOnExit=true] - Stop on SIGHUP, SIGTERM, beforeExit and exit.
- * @param {boolean} [params.stopOnInternalError=false] - Stop when a route throws (after the
- *   "handleError" plugins answered).
+ * @param {boolean} [params.stopOnInternalError=false] - Stop as soon as a route throws. The
+ *   request that threw and every other pending request are answered 500 with no body, the
+ *   "handleError" plugins' response is not sent.
  * @param {boolean} [params.keepProcessAlive=true] - When false the server alone does not keep
  *   the process alive.
  * @param {boolean} [params.canExposeSensitiveData=false] - Lets the server hand out what
@@ -7329,8 +7410,9 @@ const TIMING_NOOP = () => {
  * @returns {Promise<Object>} The server: `{ origin, origins, port, hostname, nodeServer,
  *   webSocketOrigin, stop, stoppedPromise, getStatus, addEffect }`.
  *   - `origins`: `{ local, localip, externalip }`, `origin` being `origins.local`.
- *   - `stop(reason)`: resolves once every connection is closed; `reason` can be anything
- *     and defaults to `STOP_REASON_NOT_SPECIFIED`.
+ *   - `stop(reason)`: answers the pending requests with 503, closes every connection and
+ *     resolves once done; `reason` can be anything, becomes the 503 status text and
+ *     defaults to `STOP_REASON_NOT_SPECIFIED`.
  *   - `stoppedPromise`: resolves with the reason the server stopped for (one of the
  *     `STOP_REASON_*` exports or what was given to `stop`).
  *   - `getStatus()`: `"starting"`, `"opened"`, `"stopping"` or `"stopped"`.
@@ -7621,16 +7703,16 @@ const startServer = async ({
   stopCallbackSet.add(removeConnectionErrorListener);
 
   const connectionsTracker = trackServerPendingConnections(nodeServer);
-  // opened connection must be shutdown before the close event is emitted
-  stopCallbackSet.add(connectionsTracker.stop);
-
   const pendingRequestsTracker = trackServerPendingRequests(nodeServer);
-  // ensure pending requests got a response from the server
-  stopCallbackSet.add((reason) => {
-    pendingRequestsTracker.stop({
+  // The pending requests are answered before any connection is destroyed:
+  // destroyed first, their clients would only see a socket error. The
+  // connections must still be shut down for the close event to be emitted.
+  stopCallbackSet.add(async ({ reason }) => {
+    await pendingRequestsTracker.stop({
       status: reason === STOP_REASON_INTERNAL_ERROR ? 500 : 503,
       reason,
     });
+    await connectionsTracker.stop(reason);
   });
 
   const applyRequestInternalRedirection = (request) => {
@@ -7972,7 +8054,14 @@ const startServer = async ({
 
   {
     const requestEventHandler = async (nodeRequest, nodeResponse) => {
-      const requestHost = nodeRequest.authority || nodeRequest.headers.host;
+      const requestTarget = readRequestTarget(nodeRequest.url);
+      if (!requestTarget) {
+        nodeResponse.writeHead(400, "Request url is not supported");
+        nodeResponse.end();
+        return;
+      }
+      const requestHost =
+        requestTarget.host || nodeRequest.authority || nodeRequest.headers.host;
       if (!isHostAllowed(requestHost)) {
         logger.warn(
           `${nodeRequest.method} ${nodeRequest.url} refused: host "${requestHost}" is not allowed (see the allowedHosts option)`,
@@ -7983,19 +8072,11 @@ const startServer = async ({
       }
       if (redirectHttpToHttps && !nodeRequest.connection.encrypted) {
         nodeResponse.writeHead(301, {
-          location: `${serverOrigin}${nodeRequest.url}`,
+          location: `${serverOrigin}${requestTarget.resource}`,
         });
         nodeResponse.end();
         return;
       }
-      try {
-        // eslint-disable-next-line no-new
-        new URL(nodeRequest.url, "http://example.com");
-      } catch {
-        nodeResponse.writeHead(400, "Request url is not supported");
-        nodeResponse.end();
-        return;
-      }
 
       const [receiveRequestOperation, sendResponseOperation] =
         prepareHandleRequestOperations(nodeRequest, nodeResponse);
@@ -8072,7 +8153,13 @@ const startServer = async ({
     };
     // https://github.com/websockets/ws/blob/b92745a9d6760e6b4b2394bfac78cbcd258a8c8d/lib/websocket-server.js#L491
     const upgradeEventHandler = async (nodeRequest, socket, head) => {
-      const requestHost = nodeRequest.headers.host;
+      const requestTarget = readRequestTarget(nodeRequest.url);
+      if (!requestTarget) {
+        socket.write(`HTTP/1.1 400 Request url is not supported\r\n\r\n`);
+        socket.destroy();
+        return;
+      }
+      const requestHost = requestTarget.host || nodeRequest.headers.host;
       if (!isHostAllowed(requestHost)) {
         logger.warn(
           `${nodeRequest.method} ${nodeRequest.url} refused: host "${requestHost}" is not allowed (see the allowedHosts option)`,
@@ -8399,7 +8486,7 @@ const serverPluginErrorHandler = ({ sendErrorDetails = false } = {}) => {
  *
  * @param {(body: { write: (chunk: string|Uint8Array) => void, end: () => void }) => void | (() => void)} responseBodyHandler
  *   Receives `write` and `end`. If it returns a function, that function runs
- *   when the client disconnects before `end` was called (cleanup).
+ *   once the response is over: after `end()`, or when the client disconnects.
  * @param {Object} [init]
  * @param {number} [init.status=200]
  * @param {string} [init.statusText]
@@ -8569,9 +8656,10 @@ const createAllowedOriginChecker = (allowedOrigins) => {
   }
 
   return {
-    // when the request origin cannot be reflected back we must still send a
-    // single valid origin, never a pattern
-    defaultOrigin: literalOrigins[0] ?? "*",
+    // sent when the request origin cannot be reflected back: a single valid
+    // origin, never a pattern, and never "*" which would allow every origin.
+    // With only patterns there is nothing to send.
+    defaultOrigin: literalOrigins[0] ?? null,
     isAllowed: (origin) => {
       if (literalOrigins.includes(origin)) {
         return true;
@@ -8615,7 +8703,6 @@ const generateAccessControlHeaders = ({
 
   // Access-Control-Allow-Origin must be a single value (not a list).
   // We reflect back the request's origin if it is in the allowed list.
-  // If no origin matches we fall back to "*" (only when not using credentials).
   let allowOrigin = null;
 
   const requestOrigin = readRequestOrigin(headers);
@@ -8667,14 +8754,16 @@ const generateAccessControlHeaders = ({
   }
 
   return {
-    "access-control-allow-origin": allowOrigin,
+    ...(allowOrigin === null
+      ? {}
+      : { "access-control-allow-origin": allowOrigin }),
     "access-control-allow-methods": allowedMethodArray.join(", "),
     "access-control-allow-headers": allowedHeaderArray.join(", "),
     ...(accessControlAllowCredentials
       ? { "access-control-allow-credentials": true }
       : {}),
     "access-control-max-age": accessControlMaxAge,
-    ...(timingAllowOriginEnabled(request)
+    ...(allowOrigin !== null && timingAllowOriginEnabled(request)
       ? { "timing-allow-origin": allowOrigin }
       : {}),
     ...(vary.length ? { vary: vary.join(", ") } : {}),
@@ -8925,8 +9014,9 @@ const createFileSystemFetch = (directoryUrl, options) => {
  * @param {Object} [helpers] - The helpers given to a route `fetch` (used for `timing` and `canExposeSensitiveData`).
  * @param {string|URL} directoryUrl - `file://` url (or filesystem path) of the directory to serve.
  * @param {Object} [options]
- * @param {string} [options.mainFileRelativeUrl] - File served for the directory itself and,
- *   as a fallback, for extension-less urls that do not exist (client side routing).
+ * @param {string} [options.mainFileRelativeUrl] - File served for the root of `directoryUrl`
+ *   and, as a fallback, for extension-less urls that do not exist (client side routing).
+ *   A subdirectory still gets 403 unless `canReadDirectory`.
  * @param {boolean} [options.etagEnabled=false] - Send an `etag` (hash of the content) and
  *   answer 304 to a matching `if-none-match`.
  * @param {boolean} [options.etagMemory=true] - Remember etags per file (invalidated when the
@@ -8987,8 +9077,11 @@ const fetchFileSystem = async (
   if (request.params && "0" in request.params) {
     resource = request.params["0"];
   } else {
-    resource = request.resource.slice(1);
+    resource = request.resource;
   }
+  // the resource is resolved against the served directory, so it must stay a
+  // relative reference: a leading slash would resolve to the filesystem root
+  resource = resource.replace(/^\/+/, "");
   const filesystemUrl = new URL(resource, directoryUrlString);
   const urlString = asUrlString(filesystemUrl);
   if (!urlIsOrIsInsideOf(urlString, directoryUrlString)) {

package/docs/AI_INSTRUCTIONS.md

@@ -0,0 +1,29 @@
+# @jsenv/server for AI agents
+
+An http server for Node.js: `startServer({ routes, plugins })` where a route is `{ endpoint: "GET /users/:id", fetch: (request, helpers) => response }`.
+
+## What to read, in order
+
+1. The JSDoc of the export you use — `startServer` documents every option and the shape of a route; `createFileSystemFetch`, `serverPluginCORS`, `serverPluginErrorHandler`, `ServerEvents`, `WebSocketResponse`, `ProgressiveResponse`, `pickContentType`… document theirs. In a project both `node_modules/@jsenv/server/src/` (one file per concern, `index.js` lists the exports) and the bundle `dist/jsenv_server.js` are published with their JSDoc.
+2. The guideline docs of this directory, one per area:
+   - [handling_requests.md](./handling_requests.md) — routes, the `request` object, `helpers`, response formats, what the router answers by itself
+   - [handling_errors.md](./handling_errors.md) — a route that throws, `serverPluginErrorHandler`, timeouts
+   - [plugins.md](./plugins.md) — the hooks, the built-in plugins
+   - [serving_files.md](./serving_files.md) — `createFileSystemFetch`
+   - [content_negotiation.md](./content_negotiation.md) — `availableMediaTypes` & co
+   - [websocket.md](./websocket.md), [server_sent_events.md](./server_sent_events.md) — real time
+   - [cors.md](./cors.md), [https.md](./https.md), [server_timing.md](./server_timing.md), [lifecycle.md](./lifecycle.md), [security.md](./security.md), [cluster.md](./cluster.md)
+3. The tests in `tests/` of the package (only in the jsenv/core repository): one directory per feature, each test starts a real server and requests it.
+
+## Things that are easy to get wrong
+
+- A route responds with its `fetch` function (not `response`, not `handleRequest`). Returning `null`/`undefined` lets the next route try.
+- The request `headers` object has lowercased keys; `request.cookies` is a `Map`; `request.params` holds what `:name` and `*` captured.
+- A plain response object must give `status` (it defaults to 404). `statusMessage` is not `statusText`: it feeds the body of 4xx/5xx responses.
+- Without a plugin implementing `handleError` (`serverPluginErrorHandler`), a route that throws makes the process exit.
+- A plugin property that is not a hook name is ignored with a console warning (`Unexpected "handleRequest" property`): when a hook seems dead, read the console.
+- `ServerEvents` broadcasts to every connected client; there is no per-client send. A client → server message goes through a plain route (POST), or a `WebSocketResponse` when both directions are needed.
+- `canExposeSensitiveData: true` is for development on the developer's machine only (see [security.md](./security.md)).
+- A request whose `host` header is not a name of the server gets 403: a custom hostname goes in `hostname` or `allowedHosts`.
+- `request.json()` and the other readers answer 413 past 1 MiB (`requestBodyMaxSize`, or `{ maxSize }` per call).
+- Running from the jsenv/core repository: `node --conditions=dev:jsenv <file>`, otherwise the stale `dist/` bundle is used.

package/docs/cluster.md

@@ -0,0 +1,122 @@
+# Cluster
+
+One server per CPU core, with Node's cluster module: the workers share the port.
+
+_cluster_demo_server.mjs:_
+
+```js
+import { startServer, createFileSystemFetch } from "@jsenv/server";
+
+await startServer({
+  routes: [
+    {
+      endpoint: "GET *",
+      fetch: createFileSystemFetch(import.meta.resolve("./")),
+    },
+  ],
+});
+```
+
+_cluster_demo_primary.mjs_
+
+```js
+import cluster from "node:cluster";
+import { cpus } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const numCPUs = cpus().length;
+
+cluster.setupPrimary({
+  exec: fileURLToPath(new URL("./cluster_demo_server.mjs", import.meta.url)),
+});
+
+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/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();
+  }
+});
+```
+
+```console
+❯ node ./docs/demos/cluster/cluster_demo_primary.mjs
+Primary 42398 is running
+Worker 42399 is online
+Worker 42400 is online
+Worker 42401 is online
+Worker 42402 is online
+server started at http://localhost:60000 (http://192.168.1.15:60000)
+server started at http://localhost:60000 (http://192.168.1.15:60000)
+server started at http://localhost:60000 (http://192.168.1.15:60000)
+server started at http://localhost:60000 (http://192.168.1.15:60000)
+```
+
+## Restart on file change
+
+```diff
+import cluster from "node:cluster"
+import { cpus } from "node:os"
+import { fileURLToPath } from "node:url"
++ import { registerFileLifecycle } from "@jsenv/filesystem"
+
+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/content_negotiation.md

@@ -0,0 +1,78 @@
+# Content negotiation
+
+A route declares what it can produce; the router picks what the request prefers, sets the `vary` header and answers 406 when nothing fits.
+
+## Media type
+
+```js
+import { startServer } from "@jsenv/server";
+
+await startServer({
+  routes: [
+    {
+      endpoint: "GET /hello",
+      availableMediaTypes: ["application/json", "text/plain"],
+      fetch: (request, { contentNegotiation }) => {
+        if (contentNegotiation.mediaType === "application/json") {
+          return Response.json({ data: "Hello world" });
+        }
+        return new Response("Hello world");
+      },
+    },
+  ],
+});
+```
+
+`Accept: text/*` gets text, `Accept: application/json` gets json, `Accept: image/png` gets 406. Without an `accept` header the first media type wins. The media type of a route whose endpoint has an extension (`GET /data.json`) is inferred.
+
+The same can be done by hand with `pickContentType(request, availableMediaTypes)`, which returns the media type to use or `null` — then the 406 and the `vary` header are up to the route. Unlike the router, it also returns `null` when the request has no `accept` header.
+
+## Language, version, encoding
+
+`availableLanguages` (`accept-language`), `availableVersions` (`accept-version`) and `availableEncodings` (`accept-encoding`) work the same way, and combine:
+
+```js
+{
+  endpoint: "GET /hello",
+  availableMediaTypes: ["application/json", "text/plain"],
+  availableLanguages: ["fr", "en"],
+  fetch: (request, { contentNegotiation }) => {
+    const message =
+      contentNegotiation.language === "fr"
+        ? "Bonjour tout le monde"
+        : "Hello world";
+    const headers = { "content-language": contentNegotiation.language };
+    if (contentNegotiation.mediaType === "application/json") {
+      return Response.json({ data: message }, { headers });
+    }
+    return new Response(message, { headers });
+  },
+}
+```
+
+```js
+import { gzipSync } from "node:zlib";
+
+{
+  endpoint: "GET /hello",
+  availableEncodings: ["gzip", "identity"],
+  fetch: (request, { contentNegotiation }) => {
+    if (contentNegotiation.encoding === "gzip") {
+      return new Response(gzipSync(Buffer.from("Hello world!")), {
+        headers: { "content-encoding": "gzip" },
+      });
+    }
+    return new Response("Hello world!");
+  },
+}
+```
+
+A version can also be a function, `availableVersions: [(version) => version.startsWith("1.")]`.
+
+## When several negotiations fail
+
+The 406 explains each failure (media types, languages, versions, encodings) and lists what is available in `available-media-types`, `available-languages`, `available-versions`, `available-encodings` response headers.
+
+## Checking the response
+
+The router warns (at the request log level) when the response `content-type`, `content-language`, `content-version` or `content-encoding` is not among what the route declared. `serverPluginResponseAcceptanceCheck` goes further and warns when a response does not honor what the request accepted, whatever the route declared.