@jsenv/server 17.6.7 → 17.6.8

package/dist/jsenv_server.js

@@ -3034,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();
@@ -3050,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();
         });
       }),
     );
@@ -3143,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
@@ -3199,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
@@ -3268,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);
@@ -3511,6 +3517,7 @@ const createServerEvents = ({
     close,
     open,
   });
+  open();
   return serverEventSource;
 };
 
@@ -4681,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
@@ -6846,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`);
   }
@@ -7065,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,
@@ -7367,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
@@ -7400,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"`.
@@ -7692,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) => {
@@ -8475,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]
@@ -8645,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;
@@ -8691,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);
@@ -8743,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(", ") } : {}),
@@ -9001,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

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.

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-----