@jsenv/server 17.4.1 → 17.5.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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/server",
-  "version": "17.4.1",
+  "version": "17.5.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/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) {