@jsenv/server 17.6.0 → 17.6.2

package/src/internal/server_origins.js

@@ -0,0 +1,78 @@
+import { isIP } from "node:net";
+import { applyDnsResolution } from "./dns_resolution.js";
+import { parseHostname } from "./hostname_parser.js";
+import { createIpGetters } from "./server_ips.js";
+
+// Decides what the server listens to and the origins it can be reached at:
+// - local: favors the hostname (an https certificate is for a hostname, not an ip)
+// - localip: the ip behind the hostname
+// - externalip: the machine ip on the network, when the server accepts it
+// The port is not known yet: the origins are completed once listening.
+export const resolveServerOrigins = async ({
+  https,
+  hostname,
+  acceptAnyIp,
+  preferIpv6,
+}) => {
+  const createOrigin = (host) => {
+    const protocol = https ? "https" : "http";
+    if (isIP(host) === 6) {
+      return `${protocol}://[${host}]`;
+    }
+    return `${protocol}://${host}`;
+  };
+
+  const serverOrigins = {
+    local: "",
+  };
+  const ipGetters = createIpGetters();
+  let hostnameToListen;
+  if (acceptAnyIp) {
+    const firstInternalIp = ipGetters.getFirstInternalIp({ preferIpv6 });
+    serverOrigins.local = createOrigin(firstInternalIp);
+    serverOrigins.localip = createOrigin(firstInternalIp);
+    const firstExternalIp = ipGetters.getFirstExternalIp({ preferIpv6 });
+    serverOrigins.externalip = createOrigin(firstExternalIp);
+    hostnameToListen = preferIpv6 ? "::" : "0.0.0.0";
+  } else {
+    hostnameToListen = hostname;
+  }
+  const hostnameInfo = parseHostname(hostname);
+  if (hostnameInfo.type === "ip") {
+    if (acceptAnyIp) {
+      throw new Error(
+        `hostname cannot be an ip when acceptAnyIp is enabled, got ${hostname}`,
+      );
+    }
+
+    preferIpv6 = hostnameInfo.version === 6;
+    const firstInternalIp = ipGetters.getFirstInternalIp({ preferIpv6 });
+    serverOrigins.local = createOrigin(firstInternalIp);
+    serverOrigins.localip = createOrigin(firstInternalIp);
+    if (hostnameInfo.label === "unspecified") {
+      const firstExternalIp = ipGetters.getFirstExternalIp({ preferIpv6 });
+      serverOrigins.externalip = createOrigin(firstExternalIp);
+    } else if (hostnameInfo.label === "loopback") {
+      // nothing
+    } else {
+      serverOrigins.local = createOrigin(hostname);
+    }
+  } else {
+    const hostnameDnsResolution = await applyDnsResolution(hostname, {
+      verbatim: true,
+    });
+    if (hostnameDnsResolution) {
+      const hostnameIp = hostnameDnsResolution.address;
+      serverOrigins.localip = createOrigin(hostnameIp);
+      serverOrigins.local = createOrigin(hostname);
+    } else {
+      const firstInternalIp = ipGetters.getFirstInternalIp({ preferIpv6 });
+      // fallback to internal ip because there is no ip
+      // associated to this hostname on operating system (in hosts file)
+      hostname = firstInternalIp;
+      hostnameToListen = firstInternalIp;
+      serverOrigins.local = createOrigin(firstInternalIp);
+    }
+  }
+  return { hostname, hostnameToListen, serverOrigins };
+};

package/src/internal/{server-polyglot.js → server_polyglot.js}

@@ -1,12 +1,18 @@
-/**
-
-https://stackoverflow.com/a/42019773/2634179
-
-*/
+/*
+ * A net server accepting both http and tls on the same port: the first byte
+ * of each connection tells which one it is (0x16 is a TLS handshake) and the
+ * socket is handed to the matching http or tls server.
+ * https://stackoverflow.com/a/42019773/2634179
+ *
+ * The http and tls servers are exposed as _httpServer/_tlsServer because
+ * "request", "upgrade" and "clientError" are emitted on them, not on the net
+ * server (see listen_request.js).
+ */
 
 import http from "node:http";
 import net from "node:net";
-import { listenEvent } from "./listenEvent.js";
+import { listenEvent } from "./listen_event.js";
+import { createSecureServer } from "./secure_server.js";
 
 export const createPolyglotServer = async ({
   http2 = false,
@@ -60,38 +66,11 @@ export const createPolyglotServer = async ({
   return netServer;
 };
 
-// The async part is just to lazyly import "http2" or "https"
-// so that these module are parsed only if used.
-// https://nodejs.org/api/tls.html#tlscreatesecurecontextoptions
-const createSecureServer = async ({
-  certificate,
-  privateKey,
-  http2,
-  http1Allowed,
-}) => {
-  if (http2) {
-    const { createSecureServer } = await import("node:http2");
-    return createSecureServer({
-      cert: certificate,
-      key: privateKey,
-      allowHTTP1: http1Allowed,
-    });
-  }
-
-  const { createServer } = await import("node:https");
-  return createServer({
-    cert: certificate,
-    key: privateKey,
-  });
-};
-
 const detectSocketProtocol = (socket, protocolDetectedCallback) => {
-  let removeOnceReadableListener = () => {};
-
   const tryToRead = () => {
     const buffer = socket.read(1);
     if (buffer === null) {
-      removeOnceReadableListener = socket.once("readable", tryToRead);
+      socket.once("readable", tryToRead);
       return;
     }
 
@@ -109,8 +88,4 @@ const detectSocketProtocol = (socket, protocolDetectedCallback) => {
   };
 
   tryToRead();
-
-  return () => {
-    removeOnceReadableListener();
-  };
 };

package/src/internal/track_server_pending_connections.js

@@ -0,0 +1,50 @@
+import { listenEvent } from "./listen_event.js";
+
+export const trackServerPendingConnections = (nodeServer) => {
+  const pendingConnections = new Set();
+
+  const removeConnectionListener = listenEvent(
+    nodeServer,
+    "connection",
+    (connection) => {
+      pendingConnections.add(connection);
+      listenEvent(
+        connection,
+        "close",
+        () => {
+          pendingConnections.delete(connection);
+        },
+        { once: true },
+      );
+    },
+  );
+
+  const stop = async (reason) => {
+    removeConnectionListener();
+    const pendingConnectionsArray = Array.from(pendingConnections);
+    pendingConnections.clear();
+    await Promise.all(
+      pendingConnectionsArray.map((pendingConnection) => {
+        return destroyConnection(pendingConnection, reason);
+      }),
+    );
+  };
+
+  return { stop };
+};
+
+const destroyConnection = (connection, reason) => {
+  return new Promise((resolve, reject) => {
+    connection.destroy(reason, (error) => {
+      if (error) {
+        if (error === reason || error.code === "ENOTCONN") {
+          resolve();
+        } else {
+          reject(error);
+        }
+      } else {
+        resolve();
+      }
+    });
+  });
+};

package/src/internal/track_server_pending_requests.js

@@ -0,0 +1,47 @@
+import { listenRequest } from "./listen_request.js";
+import { asReasonPhrase } from "./reason_phrase.js";
+
+export const trackServerPendingRequests = (nodeServer) => {
+  const pendingClients = new Set();
+
+  const removeRequestListener = listenRequest(
+    nodeServer,
+    (nodeRequest, nodeResponse) => {
+      const client = { nodeRequest, nodeResponse };
+      pendingClients.add(client);
+      nodeResponse.once("close", () => {
+        pendingClients.delete(client);
+      });
+    },
+  );
+
+  const stop = async ({ status, reason }) => {
+    removeRequestListener();
+    const pendingClientsArray = Array.from(pendingClients);
+    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();
+            return;
+          }
+          nodeResponse.once("close", () => {
+            resolve();
+          });
+          nodeResponse.destroy();
+        });
+      }),
+    );
+  };
+
+  return { stop };
+};

package/src/plugins/cors/server_plugin_cors.js

@@ -13,6 +13,32 @@ export const jsenvAccessControlAllowedMethods = [
   "OPTIONS",
 ];
 
+/**
+ * Server plugin adding the CORS response headers to every response, including
+ * errors (a browser treats a 500 without them as a CORS failure). Disabled
+ * (returns no plugin) unless `accessControlAllowRequestOrigin` is true or
+ * `accessControlAllowedOrigins` is non empty.
+ *
+ * @param {Object} [params]
+ * @param {Array<string>} [params.accessControlAllowedOrigins=[]] - Origins allowed to
+ *   read responses. `*` stands for any run of characters except "/":
+ *   `"https://pr-*-my-app.fly.dev"` matches every preview deployment.
+ * @param {Array<string>} [params.accessControlAllowedMethods] - Defaults to
+ *   GET, POST, PUT, DELETE, OPTIONS.
+ * @param {Array<string>} [params.accessControlAllowedHeaders] - Defaults to `["x-requested-with"]`.
+ * @param {boolean} [params.accessControlAllowRequestOrigin=false] - Reflect any request
+ *   origin, whatever `accessControlAllowedOrigins` says.
+ * @param {boolean} [params.accessControlAllowRequestMethod=false] - Also allow the method a
+ *   preflight asks for (`access-control-request-method`).
+ * @param {boolean} [params.accessControlAllowRequestHeaders=false] - Also allow the headers a
+ *   preflight asks for (`access-control-request-headers`).
+ * @param {boolean} [params.accessControlAllowCredentials=false] - Send
+ *   `access-control-allow-credentials: true`.
+ * @param {number} [params.accessControlMaxAge=600] - Seconds a browser may cache the preflight.
+ * @param {boolean} [params.timingAllowOrigin=false] - Send `timing-allow-origin` so the
+ *   allowed origin can read resource timing.
+ * @returns {Object|Array} The plugin, or `[]` when CORS stays disabled.
+ */
 export const serverPluginCORS = ({
   accessControlAllowedOrigins = [],
   accessControlAllowedMethods = jsenvAccessControlAllowedMethods,
@@ -126,12 +152,7 @@ const generateAccessControlHeaders = ({
   // If no origin matches we fall back to "*" (only when not using credentials).
   let allowOrigin = null;
 
-  const requestOrigin =
-    "origin" in headers && headers.origin !== "null"
-      ? headers.origin
-      : "referer" in headers
-        ? new URL(headers.referer).origin
-        : null;
+  const requestOrigin = readRequestOrigin(headers);
 
   if (requestOrigin) {
     if (allowedOriginChecker.isAllowed(requestOrigin)) {
@@ -191,3 +212,15 @@ const generateAccessControlHeaders = ({
     ...(vary.length ? { vary: vary.join(", ") } : {}),
   };
 };
+
+// the referer is a fallback for clients not sending "origin"; it comes from
+// the network and may not be a url at all
+const readRequestOrigin = (headers) => {
+  if ("origin" in headers && headers.origin !== "null") {
+    return headers.origin;
+  }
+  if ("referer" in headers && URL.canParse(headers.referer)) {
+    return new URL(headers.referer).origin;
+  }
+  return null;
+};

package/src/plugins/default_body_4xx_5xx/server_plugin_default_body_4xx_5xx.js

@@ -1,9 +1,22 @@
+import { STATUS_CODES } from "node:http";
 import { readFileSync } from "node:fs";
 
 import { pickContentType } from "../../content_negotiation/pick_content_type.js";
+import { escapeHtml } from "../../internal/escape_html.js";
+import { asReasonPhrase } from "../../internal/reason_phrase.js";
 import { replacePlaceholdersInHtml } from "../../replace_placeholder_in_html.js";
 
 const clientErrorHtmlTemplateFileUrl = import.meta.resolve("./client/4xx.html");
+let clientErrorHtmlTemplate;
+const readClientErrorHtmlTemplate = () => {
+  if (clientErrorHtmlTemplate === undefined) {
+    clientErrorHtmlTemplate = readFileSync(
+      new URL(clientErrorHtmlTemplateFileUrl),
+      "utf8",
+    );
+  }
+  return clientErrorHtmlTemplate;
+};
 
 export const serverPluginDefaultBody4xx5xx = () => {
   return {
@@ -13,10 +26,7 @@ export const serverPluginDefaultBody4xx5xx = () => {
       if (responseProperties.body !== undefined) {
         return null;
       }
-      if (responseProperties.status >= 400 && responseProperties.status < 500) {
-        return generateBadStatusResponse(request, responseProperties);
-      }
-      if (responseProperties.status >= 500 && responseProperties.status < 600) {
+      if (responseProperties.status >= 400 && responseProperties.status < 600) {
         return generateBadStatusResponse(request, responseProperties);
       }
       return null;
@@ -28,38 +38,17 @@ const generateBadStatusResponse = (
   request,
   { status, statusText, statusMessage },
 ) => {
+  statusText = asReasonPhrase(statusText || STATUS_CODES[status] || "");
   const contentTypeNegotiated = pickContentType(request, [
     "text/html",
     "text/plain",
     "application/json",
   ]);
   if (contentTypeNegotiated === "text/html") {
-    const htmlTemplate = readFileSync(
-      new URL(clientErrorHtmlTemplateFileUrl),
-      "utf8",
-    );
-    if (statusMessage) {
-      statusMessage = statusMessage.replace(/https?:\/\/\S+/g, (url) => {
-        return `<a href="${url}">${url}</a>`;
-      });
-      statusMessage = statusMessage.replace(
-        /(^|\s)(\/\S+)/g,
-        (match, startOrSpace, resource) => {
-          let end = "";
-          if (resource[resource.length - 1] === ".") {
-            resource = resource.slice(0, -1);
-            end = ".";
-          }
-          return `${startOrSpace}<a href="${resource}">${resource}</a>${end}`;
-        },
-      );
-      statusMessage = statusMessage.replace(/\r\n|\r|\n/g, "<br />");
-    }
-
-    const html = replacePlaceholdersInHtml(htmlTemplate, {
+    const html = replacePlaceholdersInHtml(readClientErrorHtmlTemplate(), {
       status,
-      statusText,
-      statusMessage: statusMessage || "",
+      statusText: escapeHtml(statusText),
+      statusMessage: statusMessage ? statusMessageToHtml(statusMessage) : "",
     });
     return new Response(html, {
       headers: { "content-type": "text/html" },
@@ -81,3 +70,22 @@ const generateBadStatusResponse = (
     },
   );
 };
+
+// A status message echoes the request (its url for instance): it is escaped
+// before urls and resources are turned into links.
+const statusMessageToHtml = (statusMessage) => {
+  let html = escapeHtml(statusMessage);
+  html = html.replace(/https?:\/\/\S+/g, (url) => {
+    return `<a href="${url}">${url}</a>`;
+  });
+  html = html.replace(/(^|\s)(\/\S+)/g, (match, startOrSpace, resource) => {
+    let end = "";
+    if (resource[resource.length - 1] === ".") {
+      resource = resource.slice(0, -1);
+      end = ".";
+    }
+    return `${startOrSpace}<a href="${resource}">${resource}</a>${end}`;
+  });
+  html = html.replace(/\r\n|\r|\n/g, "<br />");
+  return html;
+};

package/src/plugins/error_handler/server_plugin_error_handler.js

@@ -4,7 +4,30 @@ import { pickContentType } from "../../content_negotiation/pick_content_type.js"
 import { replacePlaceholdersInHtml } from "../../replace_placeholder_in_html.js";
 
 const internalErrorHtmlFileUrl = import.meta.resolve("./client/500.html");
+let internalErrorHtmlTemplate;
+const readInternalErrorHtmlTemplate = () => {
+  if (internalErrorHtmlTemplate === undefined) {
+    internalErrorHtmlTemplate = readFileSync(
+      new URL(internalErrorHtmlFileUrl),
+      "utf8",
+    );
+  }
+  return internalErrorHtmlTemplate;
+};
 
+/**
+ * Server plugin turning an error thrown while handling a request into a 500
+ * response (html, text or json depending on what the request accepts).
+ * Without a plugin handling errors, a route that throws makes the process
+ * exit. Put it last: it catches every error, so plugins handling a subset of
+ * them must come before. (An error exposing `asResponse()` never reaches it:
+ * the server answers it directly.)
+ *
+ * @param {Object} [params]
+ * @param {boolean} [params.sendErrorDetails=false] - Put the error stack (and
+ *   its own properties for json) in the response. Development only: a stack
+ *   reveals file paths and code.
+ */
 export const serverPluginErrorHandler = ({ sendErrorDetails = false } = {}) => {
   return {
     name: "jsenv:error_handler",
@@ -13,9 +36,6 @@ export const serverPluginErrorHandler = ({ sendErrorDetails = false } = {}) => {
         serverInternalError === null ||
         (typeof serverInternalError !== "object" &&
           typeof serverInternalError !== "function");
-      if (!serverInternalErrorIsAPrimitive && serverInternalError.asResponse) {
-        return serverInternalError.asResponse();
-      }
       const dataToSend = serverInternalErrorIsAPrimitive
         ? {
             code: "VALUE_THROWED",
@@ -34,18 +54,14 @@ export const serverPluginErrorHandler = ({ sendErrorDetails = false } = {}) => {
       const availableContentTypes = {
         "text/html": () => {
           const renderHtmlForErrorWithoutDetails = () => {
-            return `<p>Details not available: to enable them use jsenvServiceErrorHandler({ sendErrorDetails: true }).</p>`;
+            return `<p>Details not available: to enable them use serverPluginErrorHandler({ sendErrorDetails: true }).</p>`;
           };
           const renderHtmlForErrorWithDetails = () => {
             return errorToHTML(serverInternalError);
           };
 
-          const internalErrorHtmlTemplate = readFileSync(
-            new URL(internalErrorHtmlFileUrl),
-            "utf8",
-          );
           const internalErrorHtml = replacePlaceholdersInHtml(
-            internalErrorHtmlTemplate,
+            readInternalErrorHtmlTemplate(),
             {
               errorMessage: serverInternalErrorIsAPrimitive
                 ? `Code inside server has thrown a literal.`
@@ -79,7 +95,7 @@ export const serverPluginErrorHandler = ({ sendErrorDetails = false } = {}) => {
               internalErrorMessage += `\n${serverInternalError.stack}`;
             }
           } else {
-            internalErrorMessage += `\nDetails not available: to enable them use jsenvServiceErrorHandler({ sendErrorDetails: true }).`;
+            internalErrorMessage += `\nDetails not available: to enable them use serverPluginErrorHandler({ sendErrorDetails: true }).`;
           }
 
           return {

package/src/plugins/filesystem/fetch_directory.js

@@ -1,7 +1,19 @@
 import { lstatSync, readdirSync } from "node:fs";
 
 import { pickContentType } from "../../content_negotiation/pick_content_type.js";
+import { escapeHtml } from "../../internal/escape_html.js";
 
+/**
+ * Response listing a directory, as json (an array of names) or as an html
+ * page of links depending on what the request accepts (json by default).
+ *
+ * @param {string|URL} url - The directory.
+ * @param {Object} [params]
+ * @param {Object} [params.headers={}] - Request headers, read for `accept`.
+ * @param {string|URL} [params.rootDirectoryUrl] - Directory served at "/", so
+ *   that the html links are relative to the server.
+ * @returns {{ status: number, headers: Object, body: string }}
+ */
 export const fetchDirectory = (
   url,
   { headers = {}, rootDirectoryUrl } = {},
@@ -20,7 +32,7 @@ export const fetchDirectory = (
         status: 200,
         headers: {
           "content-type": "application/json",
-          "content-length": directoryContentJson.length,
+          "content-length": Buffer.byteLength(directoryContentJson),
         },
         body: directoryContentJson,
       };
@@ -35,7 +47,7 @@ export const fetchDirectory = (
   </head>
 
   <body>
-    <h1>Content of directory ${url}</h1>
+    <h1>Content of directory ${escapeHtml(url)}</h1>
     <ul>
       ${directoryContentArray.map((filename) => {
         const fileUrlObject = new URL(filename, url);
@@ -46,8 +58,9 @@ export const fetchDirectory = (
         if (lstatSync(fileUrlObject).isDirectory()) {
           fileUrlRelativeToServer += "/";
         }
+        const linkHtml = escapeHtml(fileUrlRelativeToServer);
         return `<li>
-        <a href="/${fileUrlRelativeToServer}">${fileUrlRelativeToServer}</a>
+        <a href="/${linkHtml}">${linkHtml}</a>
       </li>`;
       }).join(`
       `)}