@jsenv/server 17.4.1 → 17.6.0

package/dist/jsenv_server.js

@@ -2564,6 +2564,9 @@ const RESPONSE_KEYS_COMPOSITION = {
   headers: composeTwoHeaders,
   body: (prevBody, body) => body,
   bodyEncoding: (prevEncoding, encoding) => encoding,
+  // measures a response hands back, merged into the server-timing header when
+  // the server has serverTiming enabled (see finalizeResponseProperties)
+  timing: (prevTiming, timing) => ({ ...prevTiming, ...timing }),
 };
 
 /**
@@ -3373,8 +3376,9 @@ const createEventHistory = (limit) => {
 
   const add = (data) => {
     events.push(data);
-
-    if (events.length >= limit) {
+    // Strictly above, not "as many as": shifting at `>= limit` keeps one less
+    // than asked for.
+    if (events.length > limit) {
       events.shift();
     }
   };
@@ -6147,6 +6151,9 @@ It should be should be one of route.${routePropertyName}: ${availableValues.join
       let statusMessage;
       let headers;
       let body;
+      // measures the route hands back, merged into the server-timing header
+      // when serverTiming is enabled (see finalizeResponseProperties)
+      let timing;
 
       if (fetchReturnValue instanceof Response) {
         status = fetchReturnValue.status;
@@ -6162,6 +6169,7 @@ It should be should be one of route.${routePropertyName}: ${availableValues.join
         statusMessage = fetchReturnValue.statusMessage;
         headers = fetchReturnValue.headers || {};
         body = fetchReturnValue.body;
+        timing = fetchReturnValue.timing;
       } else {
         throw new TypeError(
           `response must be a Response, or an Object, received ${fetchReturnValue}`,
@@ -6194,7 +6202,7 @@ It should be should be one of route.${routePropertyName}: ${availableValues.join
 
       onRouteMatch(route);
       onResponseHeaders(request, route, headers);
-      return { status, statusText, statusMessage, headers, body };
+      return { status, statusText, statusMessage, headers, body, timing };
     };
 
     const matchRoutes = async (request) => {
@@ -6944,11 +6952,19 @@ The list of existing endpoints is available at ${routeInspectorUrl}.`,
 const timingToServerTimingResponseHeaders = (timing) => {
   const serverTimingHeader = {};
   Object.keys(timing).forEach((key, index) => {
-    const name = letters[index] || "zz";
-    serverTimingHeader[name] = {
-      desc: key,
-      dur: timing[key],
-    };
+    // "a".."z" then "aa", "ab", …: names must be unique — they are the keys of
+    // the header object, so a shared fallback would overwrite every entry past
+    // it with the last one.
+    const name =
+      index < letters.length
+        ? letters[index]
+        : letters[Math.floor(index / letters.length) - 1] +
+          letters[index % letters.length];
+    const dur = timing[key];
+    // a non-number duration is a marker ("served from memory cache"): it has
+    // something to say (desc) but nothing to measure
+    serverTimingHeader[name] =
+      typeof dur === "number" ? { desc: key, dur } : { desc: key };
   });
   const serverTimingHeaderString =
     stringifyServerTimingHeader(serverTimingHeader);
@@ -7235,6 +7251,10 @@ const startServer = async ({
   // This param should be enabled ONLY during development on your machine
   canExposeSensitiveData = false,
   nagle = true,
+  // false | true | { minDuration }: server-timing response headers.
+  // minDuration (ms) drops entries that took less — 0 keeps everything, which
+  // is what a test wants; a human reading devtools usually wants the noise
+  // gone (the jsenv dev server passes 0.5 for that).
   serverTiming = false,
   requestWaitingMs = 0,
   requestWaitingCallback = ({ request, requestWaitingMs }) => {
@@ -7588,6 +7608,10 @@ const startServer = async ({
     sendResponseOperation.addAbortSignal(receiveRequestOperation.signal);
     return [receiveRequestOperation, sendResponseOperation];
   };
+  const serverTimingMinDuration =
+    serverTiming && typeof serverTiming === "object"
+      ? serverTiming.minDuration || 0
+      : 0;
   const getResponseProperties = async (request, { pushResponse }) => {
     const timings = {};
     const timing = serverTiming
@@ -7629,9 +7653,32 @@ const startServer = async ({
     const finalizeResponseProperties = (responseProperties) => {
       if (serverTiming) {
         startRespondingTiming.end();
+        // A response can hand back measures of its own (a `timing` property —
+        // durations keyed by description, null for a plain marker): they join
+        // the server's own in the same server-timing header.
+        if (responseProperties.timing) {
+          Object.assign(timings, responseProperties.timing);
+          delete responseProperties.timing;
+        }
+        // serverTiming.minDuration drops what took less: a request crosses
+        // every registered route, and a wall of sub-millisecond ".routing"
+        // entries buries the measures worth reading. Markers (null) and the
+        // overall "time to start responding" — the summary the rest details —
+        // always stay.
+        const timingsWorthReading = {};
+        for (const name of Object.keys(timings)) {
+          const duration = timings[name];
+          if (
+            name === startRespondingTiming.name ||
+            typeof duration !== "number" ||
+            duration >= serverTimingMinDuration
+          ) {
+            timingsWorthReading[name] = duration;
+          }
+        }
         responseProperties.headers = composeTwoHeaders(
           responseProperties.headers,
-          timingToServerTimingResponseHeaders(timings),
+          timingToServerTimingResponseHeaders(timingsWorthReading),
         );
       }
       if (requestWaitingMs) {
@@ -8438,12 +8485,16 @@ const serverPluginCORS = ({
     return [];
   }
 
+  const allowedOriginChecker = createAllowedOriginChecker(
+    accessControlAllowedOrigins,
+  );
+
   return {
     name: "jsenv:cors",
     injectResponseProperties: (request) => {
       const accessControlHeaders = generateAccessControlHeaders({
         request,
-        accessControlAllowedOrigins,
+        allowedOriginChecker,
         accessControlAllowRequestOrigin,
         accessControlAllowedMethods,
         accessControlAllowRequestMethod,
@@ -8460,11 +8511,53 @@ const serverPluginCORS = ({
   };
 };
 
+/**
+ * An origin ("scheme://host:port") can never contain "*", so it is free to be
+ * used as a wildcard standing for any run of characters except "/":
+ * "https://pr-*-my-app.fly.dev" matches "https://pr-12-my-app.fly.dev".
+ */
+const createAllowedOriginChecker = (allowedOrigins) => {
+  const literalOrigins = [];
+  const originRegExps = [];
+  for (const allowedOrigin of allowedOrigins) {
+    if (allowedOrigin.includes("*")) {
+      originRegExps.push(originPatternToRegExp(allowedOrigin));
+    } else {
+      literalOrigins.push(allowedOrigin);
+    }
+  }
+
+  return {
+    // when the request origin cannot be reflected back we must still send a
+    // single valid origin, never a pattern
+    defaultOrigin: literalOrigins[0] ?? "*",
+    isAllowed: (origin) => {
+      if (literalOrigins.includes(origin)) {
+        return true;
+      }
+      for (const originRegExp of originRegExps) {
+        if (originRegExp.test(origin)) {
+          return true;
+        }
+      }
+      return false;
+    },
+  };
+};
+
+const originPatternToRegExp = (originPattern) => {
+  const source = originPattern
+    .split("*")
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("[^/]*");
+  return new RegExp(`^${source}$`);
+};
+
 // https://www.w3.org/TR/cors/
 // https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
 const generateAccessControlHeaders = ({
   request: { headers },
-  accessControlAllowedOrigins,
+  allowedOriginChecker,
   accessControlAllowRequestOrigin,
   accessControlAllowedMethods,
   accessControlAllowRequestMethod,
@@ -8491,7 +8584,7 @@ const generateAccessControlHeaders = ({
         : null;
 
   if (requestOrigin) {
-    if (accessControlAllowedOrigins.includes(requestOrigin)) {
+    if (allowedOriginChecker.isAllowed(requestOrigin)) {
       allowOrigin = requestOrigin;
       vary.push("origin");
     } else if (accessControlAllowRequestOrigin) {
@@ -8503,7 +8596,7 @@ const generateAccessControlHeaders = ({
   }
 
   if (allowOrigin === null) {
-    allowOrigin = accessControlAllowedOrigins[0] ?? "*";
+    allowOrigin = allowedOriginChecker.defaultOrigin;
   }
 
   const allowedMethodArray = [...accessControlAllowedMethods];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/server",
-  "version": "17.4.1",
+  "version": "17.6.0",
   "type": "module",
   "description": "A modern Node.js HTTP server with declarative routing, content negotiation, and WebSocket support",
   "repository": {

package/src/internal/response_composition.js

@@ -31,4 +31,7 @@ const RESPONSE_KEYS_COMPOSITION = {
   headers: composeTwoHeaders,
   body: (prevBody, body) => body,
   bodyEncoding: (prevEncoding, encoding) => encoding,
+  // measures a response hands back, merged into the server-timing header when
+  // the server has serverTiming enabled (see finalizeResponseProperties)
+  timing: (prevTiming, timing) => ({ ...prevTiming, ...timing }),
 };

package/src/plugins/cors/server_plugin_cors.js

@@ -35,12 +35,16 @@ export const serverPluginCORS = ({
     return [];
   }
 
+  const allowedOriginChecker = createAllowedOriginChecker(
+    accessControlAllowedOrigins,
+  );
+
   return {
     name: "jsenv:cors",
     injectResponseProperties: (request) => {
       const accessControlHeaders = generateAccessControlHeaders({
         request,
-        accessControlAllowedOrigins,
+        allowedOriginChecker,
         accessControlAllowRequestOrigin,
         accessControlAllowedMethods,
         accessControlAllowRequestMethod,
@@ -57,11 +61,53 @@ export const serverPluginCORS = ({
   };
 };
 
+/**
+ * An origin ("scheme://host:port") can never contain "*", so it is free to be
+ * used as a wildcard standing for any run of characters except "/":
+ * "https://pr-*-my-app.fly.dev" matches "https://pr-12-my-app.fly.dev".
+ */
+const createAllowedOriginChecker = (allowedOrigins) => {
+  const literalOrigins = [];
+  const originRegExps = [];
+  for (const allowedOrigin of allowedOrigins) {
+    if (allowedOrigin.includes("*")) {
+      originRegExps.push(originPatternToRegExp(allowedOrigin));
+    } else {
+      literalOrigins.push(allowedOrigin);
+    }
+  }
+
+  return {
+    // when the request origin cannot be reflected back we must still send a
+    // single valid origin, never a pattern
+    defaultOrigin: literalOrigins[0] ?? "*",
+    isAllowed: (origin) => {
+      if (literalOrigins.includes(origin)) {
+        return true;
+      }
+      for (const originRegExp of originRegExps) {
+        if (originRegExp.test(origin)) {
+          return true;
+        }
+      }
+      return false;
+    },
+  };
+};
+
+const originPatternToRegExp = (originPattern) => {
+  const source = originPattern
+    .split("*")
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("[^/]*");
+  return new RegExp(`^${source}$`);
+};
+
 // https://www.w3.org/TR/cors/
 // https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
 const generateAccessControlHeaders = ({
   request: { headers },
-  accessControlAllowedOrigins,
+  allowedOriginChecker,
   accessControlAllowRequestOrigin,
   accessControlAllowedMethods,
   accessControlAllowRequestMethod,
@@ -88,7 +134,7 @@ const generateAccessControlHeaders = ({
         : null;
 
   if (requestOrigin) {
-    if (accessControlAllowedOrigins.includes(requestOrigin)) {
+    if (allowedOriginChecker.isAllowed(requestOrigin)) {
       allowOrigin = requestOrigin;
       vary.push("origin");
     } else if (accessControlAllowRequestOrigin) {
@@ -100,7 +146,7 @@ const generateAccessControlHeaders = ({
   }
 
   if (allowOrigin === null) {
-    allowOrigin = accessControlAllowedOrigins[0] ?? "*";
+    allowOrigin = allowedOriginChecker.defaultOrigin;
   }
 
   const allowedMethodArray = [...accessControlAllowedMethods];

package/src/plugins/filesystem/fetch_file.js

@@ -4,11 +4,7 @@
  * It is meant to be used inside "requestToResponse"
  */
 
-import {
-  urlIsOrIsInsideOf,
-  urlToExtension,
-  urlToPathname,
-} from "@jsenv/urls";
+import { urlIsOrIsInsideOf, urlToExtension, urlToPathname } from "@jsenv/urls";
 import { CONTENT_TYPE } from "@jsenv/utils/src/content_type/content_type.js";
 import { createReadStream, readFile, statSync } from "node:fs";
 

package/src/router/router.js

@@ -279,6 +279,9 @@ It should be should be one of route.${routePropertyName}: ${availableValues.join
       let statusMessage;
       let headers;
       let body;
+      // measures the route hands back, merged into the server-timing header
+      // when serverTiming is enabled (see finalizeResponseProperties)
+      let timing;
 
       if (fetchReturnValue instanceof Response) {
         status = fetchReturnValue.status;
@@ -294,6 +297,7 @@ It should be should be one of route.${routePropertyName}: ${availableValues.join
         statusMessage = fetchReturnValue.statusMessage;
         headers = fetchReturnValue.headers || {};
         body = fetchReturnValue.body;
+        timing = fetchReturnValue.timing;
       } else {
         throw new TypeError(
           `response must be a Response, or an Object, received ${fetchReturnValue}`,
@@ -326,7 +330,7 @@ It should be should be one of route.${routePropertyName}: ${availableValues.join
 
       onRouteMatch(route);
       onResponseHeaders(request, route, headers);
-      return { status, statusText, statusMessage, headers, body };
+      return { status, statusText, statusMessage, headers, body, timing };
     };
 
     const matchRoutes = async (request) => {

package/src/server_events.js

@@ -412,8 +412,9 @@ const createEventHistory = (limit) => {
 
   const add = (data) => {
     events.push(data);
-
-    if (events.length >= limit) {
+    // Strictly above, not "as many as": shifting at `>= limit` keeps one less
+    // than asked for.
+    if (events.length > limit) {
       events.shift();
     }
   };

package/src/server_timing/timing_header.js

@@ -12,11 +12,19 @@ import {
 export const timingToServerTimingResponseHeaders = (timing) => {
   const serverTimingHeader = {};
   Object.keys(timing).forEach((key, index) => {
-    const name = letters[index] || "zz";
-    serverTimingHeader[name] = {
-      desc: key,
-      dur: timing[key],
-    };
+    // "a".."z" then "aa", "ab", …: names must be unique — they are the keys of
+    // the header object, so a shared fallback would overwrite every entry past
+    // it with the last one.
+    const name =
+      index < letters.length
+        ? letters[index]
+        : letters[Math.floor(index / letters.length) - 1] +
+          letters[index % letters.length];
+    const dur = timing[key];
+    // a non-number duration is a marker ("served from memory cache"): it has
+    // something to say (desc) but nothing to measure
+    serverTimingHeader[name] =
+      typeof dur === "number" ? { desc: key, dur } : { desc: key };
   });
   const serverTimingHeaderString =
     stringifyServerTimingHeader(serverTimingHeader);

package/src/start_server.js

@@ -149,6 +149,10 @@ export const startServer = async ({
   // This param should be enabled ONLY during development on your machine
   canExposeSensitiveData = false,
   nagle = true,
+  // false | true | { minDuration }: server-timing response headers.
+  // minDuration (ms) drops entries that took less — 0 keeps everything, which
+  // is what a test wants; a human reading devtools usually wants the noise
+  // gone (the jsenv dev server passes 0.5 for that).
   serverTiming = false,
   requestWaitingMs = 0,
   requestWaitingCallback = ({ request, requestWaitingMs }) => {
@@ -502,6 +506,10 @@ export const startServer = async ({
     sendResponseOperation.addAbortSignal(receiveRequestOperation.signal);
     return [receiveRequestOperation, sendResponseOperation];
   };
+  const serverTimingMinDuration =
+    serverTiming && typeof serverTiming === "object"
+      ? serverTiming.minDuration || 0
+      : 0;
   const getResponseProperties = async (request, { pushResponse }) => {
     const timings = {};
     const timing = serverTiming
@@ -543,9 +551,32 @@ export const startServer = async ({
     const finalizeResponseProperties = (responseProperties) => {
       if (serverTiming) {
         startRespondingTiming.end();
+        // A response can hand back measures of its own (a `timing` property —
+        // durations keyed by description, null for a plain marker): they join
+        // the server's own in the same server-timing header.
+        if (responseProperties.timing) {
+          Object.assign(timings, responseProperties.timing);
+          delete responseProperties.timing;
+        }
+        // serverTiming.minDuration drops what took less: a request crosses
+        // every registered route, and a wall of sub-millisecond ".routing"
+        // entries buries the measures worth reading. Markers (null) and the
+        // overall "time to start responding" — the summary the rest details —
+        // always stay.
+        const timingsWorthReading = {};
+        for (const name of Object.keys(timings)) {
+          const duration = timings[name];
+          if (
+            name === startRespondingTiming.name ||
+            typeof duration !== "number" ||
+            duration >= serverTimingMinDuration
+          ) {
+            timingsWorthReading[name] = duration;
+          }
+        }
         responseProperties.headers = composeTwoHeaders(
           responseProperties.headers,
-          timingToServerTimingResponseHeaders(timings),
+          timingToServerTimingResponseHeaders(timingsWorthReading),
         );
       }
       if (requestWaitingMs) {