@jsenv/server 12.7.4 → 13.0.0

package/src/{startServer.js → server.js}

@@ -8,6 +8,8 @@ import {
 } from "@jsenv/abort"
 import { memoize } from "@jsenv/utils/src/memoize/memoize.js"
 
+import { createServiceController } from "./service_controller.js"
+import { timingToServerTimingResponseHeaders } from "./server_timing/timing_header.js"
 import { createPolyglotServer } from "./internal/server-polyglot.js"
 import { trackServerPendingConnections } from "./internal/trackServerPendingConnections.js"
 import { trackServerPendingRequests } from "./internal/trackServerPendingRequests.js"
@@ -26,7 +28,6 @@ import { listen, stopListening } from "./internal/listen.js"
 import { composeTwoResponses } from "./internal/response_composition.js"
 import { listenRequest } from "./internal/listenRequest.js"
 import { listenServerConnectionError } from "./internal/listenServerConnectionError.js"
-import { applyDefaultErrorToResponse } from "./error_to_response_default.js"
 import {
   STOP_REASON_INTERNAL_ERROR,
   STOP_REASON_PROCESS_SIGHUP,
@@ -36,6 +37,7 @@ import {
   STOP_REASON_PROCESS_EXIT,
   STOP_REASON_NOT_SPECIFIED,
 } from "./stopReasons.js"
+import { composeTwoHeaders } from "./internal/headers_composition.js"
 
 export const startServer = async ({
   signal = new AbortController().signal,
@@ -48,8 +50,8 @@ export const startServer = async ({
   http1Allowed = true,
   redirectHttpToHttps,
   allowHttpRequestOnHttps = false,
-  listenAnyIp = false,
-  ip = listenAnyIp ? undefined : "127.0.0.1",
+  acceptAnyIp = false,
+  host = acceptAnyIp ? undefined : "localhost",
   port = 0, // assign a random available port
   portHint,
   privateKey,
@@ -64,16 +66,21 @@ export const startServer = async ({
   // auto close when requestToResponse throw an error
   stopOnInternalError = false,
   keepProcessAlive = true,
-  requestToResponse = () => null,
-  plugins = {},
-
-  sendErrorDetails = false,
-  errorToResponse = () => null,
-
-  onListenStart = () => {},
-  onListenEnd = () => {},
-  onStop = () => {},
+  services = [],
   nagle = true,
+  serverTiming = false,
+  requestWaitingMs = 0,
+  requestWaitingCallback = ({ request, warn, requestWaitingMs }) => {
+    warn(
+      createDetailedMessage(
+        `still no response found for request after ${requestWaitingMs} ms`,
+        {
+          "request url": `${request.origin}${request.ressource}`,
+          "request headers": JSON.stringify(request.headers, null, "  "),
+        },
+      ),
+    )
+  },
 } = {}) => {
   if (protocol !== "http" && protocol !== "https") {
     throw new Error(`protocol must be http or https, got ${protocol}`)
@@ -114,6 +121,8 @@ export const startServer = async ({
     allowHttpRequestOnHttps = false
   }
 
+  const serviceController = createServiceController(services)
+
   const processTeardownEvents = {
     SIGHUP: stopOnExit,
     SIGTERM: stopOnExit,
@@ -151,15 +160,14 @@ export const startServer = async ({
       nodeServer.unref()
     }
 
-    onListenStart()
     port = await listen({
       signal: startServerOperation.signal,
       server: nodeServer,
       port,
       portHint,
-      ip,
+      host,
     })
-    onListenEnd(port)
+    serviceController.callHooks("serverListening", { port })
     startServerOperation.addAbortCallback(async () => {
       await stopListening(nodeServer)
     })
@@ -177,7 +185,6 @@ export const startServer = async ({
   stopCallbackList.add(({ reason }) => {
     logger.info(`${serverName} stopping server (reason: ${reason})`)
   })
-  stopCallbackList.add(onStop)
   stopCallbackList.add(async () => {
     await stopListening(nodeServer)
   })
@@ -188,6 +195,7 @@ export const startServer = async ({
   const stop = memoize(async (reason = STOP_REASON_NOT_SPECIFIED) => {
     status = "stopping"
     await Promise.all(stopCallbackList.notify({ reason }))
+    serviceController.callHooks("serverStopped", { reason })
     status = "stopped"
     stoppedResolve(reason)
   })
@@ -208,8 +216,8 @@ export const startServer = async ({
   }
 
   status = "opened"
-  const serverOrigins = getServerOrigins({ protocol, ip, port })
-  const serverOrigin = serverOrigins.internal
+  const serverOrigins = await getServerOrigins({ protocol, host, port })
+  const serverOrigin = serverOrigins.local
 
   const removeConnectionErrorListener = listenServerConnectionError(
     nodeServer,
@@ -467,13 +475,16 @@ export const startServer = async ({
     }
 
     const handleRequest = async (request, { requestNode }) => {
+      let requestReceivedMeasure
+      if (serverTiming) {
+        requestReceivedMeasure = performance.now()
+      }
       addRequestLog(requestNode, {
         type: "info",
         value: request.parent
           ? `Push ${request.ressource}`
           : `${request.method} ${request.origin}${request.ressource}`,
       })
-
       const warn = (value) => {
         addRequestLog(requestNode, {
           type: "warn",
@@ -481,36 +492,39 @@ export const startServer = async ({
         })
       }
 
-      const requestPlugins = []
-      let responseFromShortcircuit
-      const shortcircuitResponse = (value) => {
-        responseFromShortcircuit = value
-      }
-      const redirectRequest = (requestRedirection) => {
-        request = applyRedirectionToRequest(request, requestRedirection)
+      let requestWaitingTimeout
+      if (requestWaitingMs) {
+        requestWaitingTimeout = setTimeout(
+          () => requestWaitingCallback({ request, warn, requestWaitingMs }),
+          requestWaitingMs,
+        ).unref()
       }
-      Object.keys(plugins).forEach((pluginName) => {
-        const { onRequest } = plugins[pluginName]
-        if (onRequest) {
-          const returnValue = onRequest(request, {
-            warn,
-            logger,
-            shortcircuitResponse,
-            redirectRequest,
-          })
-          if (returnValue) {
-            requestPlugins.push({
-              pluginName,
-              ...returnValue,
+
+      serviceController.callHooks(
+        "redirectRequest",
+        request,
+        { warn },
+        (newRequestProperties) => {
+          if (newRequestProperties) {
+            request = applyRedirectionToRequest(request, {
+              original: request.original || request,
+              previous: request,
+              ...newRequestProperties,
             })
           }
-        }
-      })
-      const result = responseFromShortcircuit
-        ? { returnValue: responseFromShortcircuit }
-        : await generateResponseDescription({
-            requestToResponse,
-            request,
+        },
+      )
+
+      let handleRequestReturnValue
+      let errorWhileHandlingRequest = null
+      let handleRequestTimings = serverTiming ? {} : null
+      try {
+        handleRequestReturnValue = await serviceController.callAsyncHooksUntil(
+          "handleRequest",
+          request,
+          {
+            timing: handleRequestTimings,
+            warn,
             pushResponse: async ({ path, method }) => {
               if (typeof path !== "string" || path[0] !== "/") {
                 addRequestLog(requestNode, {
@@ -535,22 +549,24 @@ export const startServer = async ({
                 return
               }
 
-              let prevented = false
+              let preventedByService = null
               const prevent = () => {
-                prevented = true
+                preventedByService = serviceController.getCurrentService()
               }
-              const preventedByPlugin = requestPlugins.find((requestPlugin) => {
-                const { onPushResponse } = requestPlugin
-                if (!onPushResponse) {
-                  return false
-                }
-                onPushResponse({ path, method }, { prevent })
-                return prevented
-              })
-              if (prevented) {
+              serviceController.callHooksUntil(
+                "onResponsePush",
+                { path, method },
+                {
+                  request,
+                  warn,
+                  prevent,
+                },
+                () => preventedByService,
+              )
+              if (preventedByService) {
                 addRequestLog(requestNode, {
                   type: "debug",
-                  value: `response push prevented by "${preventedByPlugin.pluginName}" plugin`,
+                  value: `response push prevented by "${preventedByService.name}" service`,
                 })
                 return
               }
@@ -565,16 +581,21 @@ export const startServer = async ({
                 },
               )
             },
-          })
-
-      const { aborted } = result
-      if (aborted) {
-        return ABORTED_RESPONSE_PROPERTIES
+          },
+        )
+      } catch (error) {
+        errorWhileHandlingRequest = error
       }
-      const readResponseProperties = async () => {
-        const { error } = result
-        // internal error, create 500 response
-        if (error) {
+
+      let responseProperties
+      if (errorWhileHandlingRequest) {
+        if (
+          errorWhileHandlingRequest.name === "AbortError" &&
+          request.signal.aborted
+        ) {
+          responseProperties = ABORTED_RESPONSE_PROPERTIES
+        } else {
+          // internal error, create 500 response
           if (
             // stopOnInternalError stops server only if requestToResponse generated
             // a non controlled error (internal error).
@@ -585,25 +606,28 @@ export const startServer = async ({
             // il faudrais pouvoir stop que les autres response ?
             stop(STOP_REASON_INTERNAL_ERROR)
           }
-          const responseDescriptionFromError =
-            (await errorToResponse(error, {
-              request,
-              sendErrorDetails,
-            })) ||
-            (await applyDefaultErrorToResponse(error, {
-              request,
-              sendErrorDetails,
-            }))
+          const handleErrorReturnValue =
+            await serviceController.callAsyncHooksUntil(
+              "handleError",
+              errorWhileHandlingRequest,
+              {
+                request,
+                warn,
+              },
+            )
+          if (!handleErrorReturnValue) {
+            throw errorWhileHandlingRequest
+          }
           addRequestLog(requestNode, {
             type: "error",
             value: createDetailedMessage(
               `internal error while handling request`,
               {
-                "error stack": error.stack,
+                "error stack": errorWhileHandlingRequest.stack,
               },
             ),
           })
-          return composeTwoResponses(
+          responseProperties = composeTwoResponses(
             {
               status: 500,
               statusText: "Internal Server Error",
@@ -613,10 +637,10 @@ export const startServer = async ({
                 "content-type": "text/plain",
               },
             },
-            responseDescriptionFromError,
+            handleErrorReturnValue,
           )
         }
-
+      } else {
         const {
           status = 501,
           statusText,
@@ -624,8 +648,8 @@ export const startServer = async ({
           headers = {},
           body,
           ...rest
-        } = result.returnValue || {}
-        const responseProperties = {
+        } = handleRequestReturnValue || {}
+        responseProperties = {
           status,
           statusText,
           statusMessage,
@@ -633,23 +657,25 @@ export const startServer = async ({
           body,
           ...rest,
         }
-        return responseProperties
       }
 
-      let responseProperties = await readResponseProperties()
-      // call every plugin "onResponse" hook
-      requestPlugins.forEach((requestPlugin) => {
-        const { onResponse } = requestPlugin
-        if (onResponse) {
-          const returnValue = onResponse(responseProperties)
-          if (returnValue) {
-            responseProperties = composeTwoResponses(
-              responseProperties,
-              returnValue,
-            )
-          }
+      if (serverTiming) {
+        const responseReadyMeasure = performance.now()
+        const timeToStartResponding =
+          responseReadyMeasure - requestReceivedMeasure
+        const serverTiming = {
+          ...handleRequestTimings,
+          ...responseProperties.timing,
+          "time to start responding": timeToStartResponding,
         }
-      })
+        responseProperties.headers = composeTwoHeaders(
+          responseProperties.headers,
+          timingToServerTimingResponseHeaders(serverTiming),
+        )
+      }
+      if (requestWaitingMs) {
+        clearTimeout(requestWaitingTimeout)
+      }
       if (
         request.method !== "HEAD" &&
         responseProperties.headers["content-length"] > 0 &&
@@ -660,6 +686,26 @@ export const startServer = async ({
           value: `content-length header is ${responseProperties.headers["content-length"]} but body is empty`,
         })
       }
+      serviceController.callHooks(
+        "injectResponseHeaders",
+        responseProperties,
+        {
+          request,
+          warn,
+        },
+        (returnValue) => {
+          if (returnValue) {
+            responseProperties.headers = composeTwoHeaders(
+              responseProperties.headers,
+              returnValue,
+            )
+          }
+        },
+      )
+      serviceController.callHooks("responseReady", responseProperties, {
+        request,
+        warn,
+      })
       return responseProperties
     }
 
@@ -759,9 +805,13 @@ export const startServer = async ({
   stopCallbackList.add(removeRequestListener)
 
   if (startLog) {
-    logger.info(
-      `${serverName} started at ${serverOrigin} (${serverOrigins.external})`,
-    )
+    if (serverOrigins.network) {
+      logger.info(
+        `${serverName} started at ${serverOrigins.local} (${serverOrigins.network})`,
+      )
+    } else {
+      logger.info(`${serverName} started at ${serverOrigins.local}`)
+    }
   }
 
   const addEffect = (callback) => {
@@ -773,6 +823,7 @@ export const startServer = async ({
 
   return {
     getStatus: () => status,
+    port,
     origin: serverOrigin,
     origins: serverOrigins,
     nodeServer,
@@ -811,29 +862,6 @@ const createNodeServer = async ({
   })
 }
 
-const generateResponseDescription = async ({
-  requestToResponse,
-  request,
-  pushResponse,
-}) => {
-  try {
-    const returnValue = await requestToResponse(request, {
-      pushResponse,
-    })
-    return {
-      returnValue,
-    }
-  } catch (error) {
-    if (error.name === "AbortError" && request.signal.aborted) {
-      return {
-        aborted: true,
-      }
-    }
-    return {
-      error,
-    }
-  }
-}
 const testCanPushStream = (http2Stream) => {
   if (!http2Stream.pushAllowed) {
     return {

package/src/service_controller.js

@@ -0,0 +1,173 @@
+import { timeStart } from "./server_timing/timing_measure.js"
+
+const HOOK_NAMES = [
+  "serverListening",
+  "redirectRequest",
+  "handleRequest",
+  "handleError",
+  "onResponsePush",
+  "injectResponseHeaders",
+  "responseReady",
+  "serverStopped",
+]
+
+export const createServiceController = (services) => {
+  const flatServices = flattenAndFilterServices(services)
+  const hookGroups = {}
+
+  const addService = (service) => {
+    Object.keys(service).forEach((key) => {
+      if (key === "name") return
+      const isHook = HOOK_NAMES.includes(key)
+      if (!isHook) {
+        console.warn(
+          `Unexpected "${key}" property on "${service.name}" service`,
+        )
+      }
+      const hookName = key
+      const hookValue = service[hookName]
+      if (hookValue) {
+        const group = hookGroups[hookName] || (hookGroups[hookName] = [])
+        group.push({
+          service,
+          name: hookName,
+          value: hookValue,
+        })
+      }
+    })
+  }
+  flatServices.forEach((service) => {
+    addService(service)
+  })
+
+  let currentService = null
+  let currentHookName = null
+  const callHook = (hook, info, context) => {
+    const hookFn = hook.value
+    if (!hookFn) {
+      return null
+    }
+    currentService = hook.service
+    currentHookName = hook.name
+    let timeEnd
+    if (context && context.timing) {
+      timeEnd = timeStart(
+        `${currentService.name.replace("jsenv:", "")}.${currentHookName}`,
+      )
+    }
+    let valueReturned = hookFn(info, context)
+    if (context && context.timing) {
+      Object.assign(context.timing, timeEnd())
+    }
+    currentService = null
+    currentHookName = null
+    return valueReturned
+  }
+  const callAsyncHook = async (hook, info, context) => {
+    const hookFn = hook.value
+    if (!hookFn) {
+      return null
+    }
+    currentService = hook.service
+    currentHookName = hook.name
+    let timeEnd
+    if (context && context.timing) {
+      timeEnd = timeStart(
+        `${currentService.name.replace("jsenv:", "")}.${currentHookName}`,
+      )
+    }
+    let valueReturned = await hookFn(info, context)
+    if (context && context.timing) {
+      Object.assign(context.timing, timeEnd())
+    }
+    currentService = null
+    currentHookName = null
+    return valueReturned
+  }
+
+  const callHooks = (hookName, info, context, callback = () => {}) => {
+    const hooks = hookGroups[hookName]
+    if (hooks) {
+      for (const hook of hooks) {
+        const returnValue = callHook(hook, info, context)
+        if (returnValue) {
+          callback(returnValue)
+        }
+      }
+    }
+  }
+  const callHooksUntil = (
+    hookName,
+    info,
+    context,
+    until = (returnValue) => returnValue,
+  ) => {
+    const hooks = hookGroups[hookName]
+    if (hooks) {
+      for (const hook of hooks) {
+        const returnValue = callHook(hook, info, context)
+        const untilReturnValue = until(returnValue)
+        if (untilReturnValue) {
+          return untilReturnValue
+        }
+      }
+    }
+    return null
+  }
+  const callAsyncHooksUntil = (hookName, info, context) => {
+    const hooks = hookGroups[hookName]
+    if (!hooks) {
+      return null
+    }
+    if (hooks.length === 0) {
+      return null
+    }
+    return new Promise((resolve, reject) => {
+      const visit = (index) => {
+        if (index >= hooks.length) {
+          return resolve()
+        }
+        const hook = hooks[index]
+        const returnValue = callAsyncHook(hook, info, context)
+        return Promise.resolve(returnValue).then((output) => {
+          if (output) {
+            return resolve(output)
+          }
+          return visit(index + 1)
+        }, reject)
+      }
+      visit(0)
+    })
+  }
+
+  return {
+    services: flatServices,
+
+    callHooks,
+    callHooksUntil,
+    callAsyncHooksUntil,
+
+    getCurrentService: () => currentService,
+    getCurrentHookName: () => currentHookName,
+  }
+}
+
+const flattenAndFilterServices = (services) => {
+  const flatServices = []
+  const visitServiceEntry = (serviceEntry) => {
+    if (Array.isArray(serviceEntry)) {
+      serviceEntry.forEach((value) => visitServiceEntry(value))
+      return
+    }
+    if (typeof serviceEntry === "object" && serviceEntry !== null) {
+      if (!serviceEntry.name) {
+        serviceEntry.name = "anonymous"
+      }
+      flatServices.push(serviceEntry)
+      return
+    }
+    throw new Error(`services must be objects, got ${serviceEntry}`)
+  }
+  services.forEach((serviceEntry) => visitServiceEntry(serviceEntry))
+  return flatServices
+}