@jsenv/server 15.5.3 → 16.0.0

package/README.md

@@ -1,112 +1,109 @@
 # server [![npm package](https://img.shields.io/npm/v/@jsenv/server.svg?logo=npm&label=package)](https://www.npmjs.com/package/@jsenv/server)
 
-`@jsenv/server` helps to write flexible server code with a declarative API.
+> A modern, flexible Node.js HTTP server with declarative routing, content negotiation, and WebSocket support.
+
+`@jsenv/server` simplifies server development with a declarative API that handles common web server needs like routing, content negotiation, file serving, and real-time communication.
 
 ```js
 import { startServer } from "@jsenv/server";
 
 await startServer({
   port: 8080,
-  services: [
+  routes: [
     {
-      handleRequest: () => {
-        return {
-          status: 200,
-          headers: {
-            "content-type": "text/plain",
-          },
-          body: "Hello world",
-        };
-      },
+      endpoint: "GET *",
+      response: () => new Response("Hello world"),
     },
   ],
 });
 ```
 
-# Examples
+# Features
+
+- [*] Declarative routing with path parameters and pattern matching
+- [*] Content negotiation for type, language, version and encoding
+- [*] Real-time communication via WebSockets and Server-Sent Events
+- [*] File serving with ETags, conditional requests, and compression
+- [*] Security with HTTPS and automatic HTTP-to-HTTPS redirection
+- [*] HTTP/2 support including server push
+- [*] CORS handling built-in
+- [*] Performance monitoring with server timing
+- [*] Sacalability through cluster mode for multi-core utilization
+- [ ] Request authentification with JWT, OAuth etc
+
+# Installation
+
+```console
+npm install @jsenv/server
+```
+
+**Requirements:**
+
+- Node.js 22.13.1 or higher
+- ES modules support
 
-_Code starting a server with 2 request handlers:_
+# Quick Examples
+
+**Basic API Server**
 
 ```js
-/*
- * starts a server which:
- * - when requested at "/"
- *   -> respond with 200
- * - otherwise
- *   -> respond with 404
- */
-import { startServer, composeServices } from "@jsenv/server";
-
-const server = await startServer({
-  services: [
+import { startServer } from "@jsenv/server";
+
+await startServer({
+  port: 3000,
+  routes: [
     {
-      name: "index",
-      handleRequest: (request) => {
-        if (request.resource === "/") {
-          return { status: 200 };
-        }
-        return null;
-      },
+      endpoint: "GET /api/users",
+      response: () => Response.json([{ id: 1, name: "John" }]),
     },
     {
-      name: "otherwise",
-      handleRequest: () => {
-        return { status: 404 };
-      },
+      endpoint: "GET /api/users/:id",
+      response: (request) =>
+        Response.json({ id: request.params.id, name: "John" }),
+    },
+    {
+      endpoint: "GET *",
+      response: () => new Response("Not found", { status: 404 }),
     },
   ],
 });
-
-const fetch = await import("node-fetch");
-const responseForOrigin = await fetch(server.origin);
-responseForOrigin.status; // 200
-
-const responseForFoo = await fetch(`${server.origin}/foo`);
-responseForFoo.status; // 404
 ```
 
-_Code starting a server in https:_
+**Static File Server**
 
 ```js
-import { readFileSync } from "node:fs";
-import { startServer } from "@jsenv/server";
+import { startServer, createFileSystemFetch } from "@jsenv/server";
 
 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,
-  services: [
+  routes: [
     {
-      handleRequest: (request) => {
-        const clientUsesHttp = request.origin.startsWith("http:");
-
-        return {
-          status: 200,
-          headers: {
-            "content-type": "text/plain",
-          },
-          body: clientUsesHttp ? `Welcome http user` : `Welcome https user`,
-        };
-      },
+      endpoint: "GET *",
+      response: createFileSystemFetch(import.meta.resolve("./")),
     },
   ],
 });
 ```
 
-_Code starting a server for static files:_
+**HTTPS Server**
 
 ```js
-import { startServer, fetchFileSystem } from "@jsenv/server";
+import { readFileSync } from "node:fs";
+import { startServer } from "@jsenv/server";
 
 await startServer({
-  services: [
+  https: {
+    certificate: readFileSync(new URL("./server.crt", import.meta.url), "utf8"),
+    privateKey: readFileSync(new URL("./server.key", import.meta.url), "utf8"),
+  },
+  allowHttpRequestOnHttps: true, // will disable https redirection and let you handle http request
+  routes: [
     {
-      handleRequest: async (request) => {
-        const fileUrl = new URL(request.resource.slice(1), import.meta.url);
-        const response = await fetchFileSystem(fileUrl, request);
-        return response;
+      endpoint: "GET *",
+      response: (request) => {
+        const clientUsesHttp = request.origin.startsWith("http:");
+        return new Response(
+          clientUsesHttp ? `Welcome http user` : `Welcome https user`,
+        );
       },
     },
   ],
@@ -115,20 +112,16 @@ await startServer({
 
 # Documentation
 
-- [Handling requests](./docs/handling_requests.md)
-- [Handling errors](./docs/handling_errors.md)
-- [Server timing](./docs/server_timing.md)
-- [CORS](./docs/cors.md)
-- [https](./docs/https.md)
-- [Serving files](./docs/serving_files.md)
-- [Content negotiation](./docs/content_negotiation.md)
-- [Websocket](./docs/websocket.md)
-- [Server Sent Events](./docs/server_sent_events.md)
-- [Cluster](./docs/cluster.md)
-- [Http2 push](./docs/http2_push.md)
-
-# Installation
-
-```console
-npm install @jsenv/server
-```
+| Topic                                                | Description                                      |
+| ---------------------------------------------------- | ------------------------------------------------ |
+| [Handling requests](./docs/handling_requests.md)     | Process HTTP requests and generate responses     |
+| [Handling errors](./docs/handling_errors.md)         | Error handling strategies and custom responses   |
+| [Server timing](./docs/server_timing.md)             | Measure and report server performance metrics    |
+| [CORS](./docs/cors.md)                               | Configure Cross-Origin Resource Sharing          |
+| [HTTPS](./docs/https.md)                             | Set up secure HTTPS connections                  |
+| [Serving files](./docs/serving_files.md)             | Static file serving with caching and compression |
+| [Content negotiation](./docs/content_negotiation.md) | Content type, language and encoding negotiation  |
+| [Websocket](./docs/websocket.md)                     | Bi-directional real-time communication           |
+| [Server Sent Events](./docs/server_sent_events.md)   | Push updates to clients over HTTP                |
+| [Cluster](./docs/cluster.md)                         | Scale your server across multiple CPU cores      |
+| [HTTP/2 Push](./docs/http2_push.md)                  | Optimize loading with server push                |

package/dist/html/4xx.html

@@ -0,0 +1,196 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${status} ${statusText}</title>
+    <style>body {
+  color: #333;
+  background-color: #f8f9fa;
+  justify-content: center;
+  align-items: center;
+  min-height: 100vh;
+  margin: 0;
+  font-family: Arial, sans-serif;
+  display: flex;
+}
+
+.error_container {
+  text-align: center;
+  background: #fff;
+  border-radius: 8px;
+  padding: 20px;
+  box-shadow: 0 4px 6px #0000001a;
+}
+
+.error_status {
+  color: #dc3545;
+  margin: 0;
+  font-size: 5rem;
+}
+
+.error_status_text {
+  word-break: break-word;
+  text-align: left;
+  margin: 10px 0;
+  font-size: 1.5rem;
+}
+
+.error_message {
+  color: #555;
+  word-break: break-word;
+  text-align: left;
+  font-size: 1rem;
+}
+
+.home_link {
+  color: #fff;
+  background-color: #007bff;
+  border-radius: 5px;
+  margin-top: 15px;
+  padding: 10px 15px;
+  text-decoration: none;
+  display: inline-block;
+}
+
+.home_link:hover {
+  background-color: #0056b3;
+}
+</style>
+  </head>
+  <body>
+    <div class="error_container">
+      <p class="error_status">${status}</p>
+      <p class="error_status_text">${statusText}</p>
+      <p class="error_message">${statusMessage}</p>
+      <a href="/" jsenv-ignore="" class="home_link">Return to Home</a>
+    </div>
+    <script>
+      const css = /* css */ `
+      dialog {
+        opacity: 0;
+        transition: all 0.3s allow-discrete;
+      }
+      dialog::backdrop {
+         background-image: linear-gradient(
+          45deg,
+          magenta,
+          rebeccapurple,
+          dodgerblue,
+          green
+        );
+        opacity: 0;
+        transition: all 0.3s allow-discrete;
+      }
+      dialog:open {
+        opacity: 1;
+      }
+      dialog:open::backdrop {
+        opacity: 0.75;
+      }`;
+      
+      const html = /* html */ `<style>
+          ${css}
+      </style>
+      <dialog>
+          <p>Connection with server is lost</p>
+          <button autofocus name="reconnect">Retry</button>
+      </dialog>`;
+      
+      class JsenvAutoreloadOnServerRestart extends HTMLElement {
+        constructor({ url } = {}) {
+          super();
+          const root = this.attachShadow({ mode: "open" });
+          root.innerHTML = html;
+      
+          const dialog = root.querySelector("dialog");
+          const reconnectButton = dialog.querySelector('button[name="reconnect"]');
+      
+          (async () => {
+            const connect = () => {
+              const websocket = new WebSocket(url);
+              const connectedPromise = new Promise((resolve) => {
+                websocket.onerror = () => {
+                  resolve(null);
+                };
+                websocket.onopen = () => {
+                  resolve(websocket);
+                };
+              });
+              return connectedPromise;
+            };
+      
+            const initialWebSocket = await connect();
+            initialWebSocket.onclose = async () => {
+              console.info("connection to server lost, trying to reconnect");
+              const retry = async () => {
+                let attemptCount = 0;
+                let timeToWait = 100;
+                const tryToReconnect = async () => {
+                  const newWebsocket = await connect();
+                  if (newWebsocket) {
+                    dialog.close();
+                    console.info("reconnected to server, reloading the page...");
+                    window.location.reload(true);
+                    return;
+                  }
+                  attemptCount++;
+                  if (attemptCount === 10) {
+                    dialog.showModal();
+                    reconnectButton.onclick = async () => {
+                      reconnectButton.disabled = true;
+                      const previousContext = reconnectButton.textContent;
+                      reconnectButton.textContent = "Retrying...";
+                      await retry();
+                      reconnectButton.textContent = previousContext;
+                      reconnectButton.disabled = false;
+                    };
+                    return;
+                  }
+                  timeToWait += 100;
+                  await new Promise((resolve) => setTimeout(resolve, timeToWait));
+                  await tryToReconnect();
+                };
+                await tryToReconnect();
+              };
+              retry();
+            };
+          })();
+        }
+      }
+      if (!customElements.get("jsenv-autoreload-on-server-restart")) {
+        customElements.define(
+          "jsenv-autoreload-on-server-restart",
+          JsenvAutoreloadOnServerRestart,
+        );
+      }
+      
+      const jsenvAutoreloadOnServerRestartElement =
+        new JsenvAutoreloadOnServerRestart({
+          url: (() => {
+            const websocketScheme =
+              self.location.protocol === "https:" ? "wss" : "ws";
+            const websocketUrl = `${websocketScheme}://${self.location.host}/.internal/alive.websocket`;
+            return websocketUrl;
+          })(),
+        });
+      
+      // script is injected into document.body
+      if (document.body) {
+        document.currentScript.parentNode.replaceChild(
+          jsenvAutoreloadOnServerRestartElement,
+          document.currentScript,
+        );
+      }
+      // script injected outisde document.body (likely in head)
+      else {
+        document.currentScript.parentNode.removeChild(document.currentScript);
+        document.onreadystatechange = () => {
+          if (document.readyState === "interactive") {
+            document.body.appendChild(jsenvAutoreloadOnServerRestartElement);
+          }
+        };
+      }
+    </script>
+  </body>
+</html>

package/dist/html/500.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Internal server error</title>
+    <meta charset="utf-8">
+    <link rel="icon" href="data:,">
+  </head>
+
+  <body>
+    <h1>Internal server error</h1>
+    <p>${errorMessage}</p>
+    <details>
+      <summary>See internal error details</summary>
+      ${errorDetailsContent}
+    </details>
+  </body>
+</html>