@jsenv/server 16.3.6 → 17.0.0

package/src/plugins_controller.js

@@ -0,0 +1,341 @@
+import { performance } from "node:perf_hooks";
+
+// createPluginsController manages an ordered list of plugins.
+// "plugins" is a generic term: it can refer to jsenv core plugins,
+// server plugins, or any extensibility mechanism using the same pattern.
+export const createPluginsController = async ({
+  plugins,
+  pluginDescription = {},
+  filterPlugin,
+  getInitPluginArgs,
+  getHookFunction = defaultGetHookFunction,
+  getTimingKey = defaultGetTimingKey,
+  getEffectArgs = defaultGetEffectArgs,
+  meta = {},
+}) => {
+  const { name: pluginName = "plugin", properties = {} } = pluginDescription;
+
+  const hookSetMap = new Map();
+
+  const addHook = (hook) => {
+    let hookSet = hookSetMap.get(hook.name);
+    if (!hookSet) {
+      hookSet = new Set();
+      hookSetMap.set(hook.name, hookSet);
+    }
+    hookSet.add(hook);
+  };
+
+  const addPluginToHookSetMap = (plugin) => {
+    for (const key of Object.keys(plugin)) {
+      if (
+        key === "name" ||
+        key === "init" ||
+        key === "destroy" ||
+        key === "meta" ||
+        key === "effect"
+      ) {
+        continue;
+      }
+      const propDef = properties[key];
+      if (propDef === undefined) {
+        console.warn(
+          `Unexpected "${key}" property on "${plugin.name}" ${pluginName}`,
+        );
+        continue;
+      }
+      if (propDef.type !== "hook") {
+        // non-hook key, silently skip
+        continue;
+      }
+      const hookValue = plugin[key];
+      if (!hookValue) {
+        continue;
+      }
+      addHook({
+        plugin,
+        name: key,
+        value: hookValue,
+      });
+    }
+  };
+
+  const activatePlugin = (plugin) => {
+    if (plugin.meta) {
+      const pluginMeta = plugin.meta;
+      if (typeof pluginMeta !== "object" || pluginMeta === null) {
+        console.warn(`${pluginName}.meta must be an object, got ${pluginMeta}`);
+      } else {
+        Object.assign(meta, pluginMeta);
+        Object.freeze(pluginMeta);
+      }
+    }
+    addPluginToHookSetMap(plugin);
+  };
+
+  const pluginCandidates = plugins;
+  const activePlugins = [];
+  const pluginsWithEffect = [];
+
+  for (const pluginCandidate of pluginCandidates) {
+    if (filterPlugin && !filterPlugin(pluginCandidate)) {
+      pluginCandidate.destroy?.();
+      continue;
+    }
+    const active = await callInitOnPlugin(pluginCandidate, getInitPluginArgs);
+    if (!active) {
+      pluginCandidate.destroy?.();
+      continue;
+    }
+    if (pluginCandidate.effect) {
+      pluginsWithEffect.push(pluginCandidate);
+    } else {
+      activePlugins.push(pluginCandidate);
+    }
+  }
+
+  for (const pluginWithEffect of pluginsWithEffect) {
+    const effectArgs = getEffectArgs({ otherPlugins: activePlugins });
+    const returnValue = pluginWithEffect.effect(...effectArgs);
+    if (!returnValue) {
+      continue;
+    }
+    activePlugins.push(pluginWithEffect);
+    if (typeof returnValue === "function" && !pluginWithEffect.destroy) {
+      pluginWithEffect.destroy = returnValue;
+    }
+  }
+
+  // Preserve original declaration order
+  activePlugins.sort(
+    (a, b) => pluginCandidates.indexOf(a) - pluginCandidates.indexOf(b),
+  );
+
+  for (const activePlugin of activePlugins) {
+    activatePlugin(activePlugin);
+  }
+
+  const assertAndNormalizeReturnValue = (valueReturned, info, { hook }) => {
+    if (valueReturned === null || valueReturned === undefined) {
+      // all hooks are allowed to return null/undefined as a signal of "I don't do anything"
+      return valueReturned;
+    }
+    const propDef = properties[hook.name];
+    if (!propDef || !propDef.assertAndNormalize) {
+      return valueReturned;
+    }
+    const assertAndNormalizeResult = propDef.assertAndNormalize(
+      valueReturned,
+      info,
+      { hook },
+    );
+    return assertAndNormalizeResult;
+  };
+
+  let lastPluginUsed = null;
+  let currentPlugin = null;
+  let currentHookName = null;
+
+  const callHook = (hook, info, secondArg) => {
+    const hookFn = getHookFunction(hook, info);
+    if (!hookFn) {
+      return null;
+    }
+    lastPluginUsed = hook.plugin;
+    currentPlugin = hook.plugin;
+    currentHookName = hook.name;
+    let startTimestamp;
+    if (info && info.timing) {
+      startTimestamp = performance.now();
+    }
+    let valueReturned = hookFn(info, secondArg);
+    if (startTimestamp !== undefined) {
+      info.timing[getTimingKey(hook)] = performance.now() - startTimestamp;
+    }
+    valueReturned = assertAndNormalizeReturnValue(valueReturned, info, {
+      hook,
+    });
+    currentPlugin = null;
+    currentHookName = null;
+    return valueReturned;
+  };
+  const callAsyncHook = async (hook, info, secondArg) => {
+    const hookFn = getHookFunction(hook, info);
+    if (!hookFn) {
+      return null;
+    }
+    lastPluginUsed = hook.plugin;
+    currentPlugin = hook.plugin;
+    currentHookName = hook.name;
+    let startTimestamp;
+    if (info && info.timing) {
+      startTimestamp = performance.now();
+    }
+    let valueReturned = await hookFn(info, secondArg);
+    if (startTimestamp !== undefined) {
+      info.timing[getTimingKey(hook)] = performance.now() - startTimestamp;
+    }
+    valueReturned = assertAndNormalizeReturnValue(valueReturned, info, {
+      hook,
+    });
+    currentPlugin = null;
+    currentHookName = null;
+    return valueReturned;
+  };
+  // callHooks(hookName, info, callback)
+  // callHooks(hookName, info, secondArg, callback)
+  const callHooks = (hookName, info, secondArgOrCallback, callback) => {
+    const hookSet = hookSetMap.get(hookName);
+    if (!hookSet) {
+      return;
+    }
+    let secondArg;
+    if (typeof secondArgOrCallback === "function") {
+      callback = secondArgOrCallback;
+      secondArg = undefined;
+    } else {
+      secondArg = secondArgOrCallback;
+    }
+    const setHookParams = (firstArg = info) => {
+      info = firstArg;
+    };
+    for (const hook of hookSet) {
+      const returnValue = callHook(hook, info, secondArg);
+      if (returnValue && callback) {
+        callback(returnValue, hook.plugin, setHookParams);
+      }
+    }
+  };
+  // callAsyncHooks(hookName, info, callback)
+  // callAsyncHooks(hookName, info, secondArg, callback)
+  const callAsyncHooks = async (
+    hookName,
+    info,
+    secondArgOrCallback,
+    callback,
+  ) => {
+    const hookSet = hookSetMap.get(hookName);
+    if (!hookSet) {
+      return;
+    }
+    let secondArg;
+    if (typeof secondArgOrCallback === "function") {
+      callback = secondArgOrCallback;
+      secondArg = undefined;
+    } else {
+      secondArg = secondArgOrCallback;
+    }
+    for (const hook of hookSet) {
+      const returnValue = await callAsyncHook(hook, info, secondArg);
+      if (returnValue && callback) {
+        await callback(returnValue, hook.plugin);
+      }
+    }
+  };
+  // callHooksUntil(hookName, info)
+  // callHooksUntil(hookName, info, secondArg)
+  // callHooksUntil(hookName, info, secondArg, until)
+  const callHooksUntil = (hookName, info, secondArgOrUntil, until) => {
+    const hookSet = hookSetMap.get(hookName);
+    if (!hookSet) {
+      return null;
+    }
+    let secondArg;
+    if (typeof secondArgOrUntil === "function") {
+      until = secondArgOrUntil;
+      secondArg = undefined;
+    } else {
+      secondArg = secondArgOrUntil;
+    }
+    for (const hook of hookSet) {
+      const returnValue = callHook(hook, info, secondArg);
+      if (until) {
+        const untilValue = until(returnValue);
+        if (untilValue) {
+          return untilValue;
+        }
+      } else if (returnValue) {
+        return returnValue;
+      }
+    }
+    return null;
+  };
+  // callAsyncHooksUntil(hookName, info)
+  // callAsyncHooksUntil(hookName, info, secondArg)
+  const callAsyncHooksUntil = async (hookName, info, secondArg) => {
+    const hookSet = hookSetMap.get(hookName);
+    if (!hookSet) {
+      return null;
+    }
+    if (hookSet.size === 0) {
+      return null;
+    }
+    const iterator = hookSet.values()[Symbol.iterator]();
+    let result;
+    const visit = async () => {
+      const { done, value: hook } = iterator.next();
+      if (done) {
+        return;
+      }
+      const returnValue = await callAsyncHook(hook, info, secondArg);
+      if (returnValue) {
+        result = returnValue;
+        return;
+      }
+      await visit();
+    };
+    await visit();
+    return result;
+  };
+
+  return {
+    activePlugins,
+
+    callHook,
+    callAsyncHook,
+    callHooks,
+    callHooksUntil,
+    callAsyncHooks,
+    callAsyncHooksUntil,
+
+    getPluginMeta: (pluginName) => meta[pluginName],
+    getMeta: () => meta,
+    getLastPluginUsed: () => lastPluginUsed,
+    getCurrentPlugin: () => currentPlugin,
+    getCurrentHookName: () => currentHookName,
+  };
+};
+
+const callInitOnPlugin = async (plugin, getInitPluginArgs) => {
+  const { init } = plugin;
+  if (!init) {
+    return true;
+  }
+  const initArgs = getInitPluginArgs ? getInitPluginArgs(plugin) : [];
+  const initReturnValue = await init(...initArgs);
+  if (initReturnValue === false) {
+    return false;
+  }
+  if (typeof initReturnValue === "function" && !plugin.destroy) {
+    plugin.destroy = initReturnValue;
+  }
+  return true;
+};
+
+const defaultGetTimingKey = (hook) =>
+  `${hook.name}-${hook.plugin.name.replace("jsenv:", "")}`;
+const defaultGetEffectArgs = ({ otherPlugins }) => [{ otherPlugins }];
+
+// By default, hook values can be a function or an object keyed by info.type.
+// When an object, the hook for the matching type (or "*") is used.
+const defaultGetHookFunction = (hook, info = {}) => {
+  const hookValue = hook.value;
+  if (typeof hookValue === "object") {
+    const hookForType = hookValue[info.type] || hookValue["*"];
+    if (!hookForType) {
+      return null;
+    }
+    return hookForType;
+  }
+  return hookValue;
+};

package/src/router/router.js

@@ -188,19 +188,20 @@ export const createRouter = (
       upgrade: false,
     };
 
-    let currentService;
+    let currentServerPlugin;
     let currentRoutingTiming;
     const onRouteMatchStart = (route) => {
-      if (route.service === currentService) {
+      const { serverPlugin } = route;
+      if (serverPlugin === currentServerPlugin) {
         return;
       }
       onRouteGroupEnd(route);
       currentRoutingTiming = fetchSecondArg.timing(
-        route.service
-          ? `${route.service.name.replace("jsenv:", "")}.routing`
+        serverPlugin && serverPlugin.name
+          ? `${serverPlugin.name.replace("jsenv:", "")}.routing`
           : "routing",
       );
-      currentService = route.service;
+      currentServerPlugin = serverPlugin;
     };
     const onRouteGroupEnd = () => {
       if (currentRoutingTiming) {
@@ -540,6 +541,7 @@ const createRoute = ({
   description,
   headers,
   service,
+  serverPlugin,
   availableMediaTypes = [],
   availableLanguages = [],
   availableVersions = [],
@@ -589,6 +591,7 @@ const createRoute = ({
     resource,
     description,
     service,
+    serverPlugin,
     availableMediaTypes,
     availableLanguages,
     availableVersions,

package/src/start_server.js

@@ -23,17 +23,14 @@ import { composeTwoResponses } from "./internal/response_composition.js";
 import { createPolyglotServer } from "./internal/server-polyglot.js";
 import { trackServerPendingConnections } from "./internal/trackServerPendingConnections.js";
 import { trackServerPendingRequests } from "./internal/trackServerPendingRequests.js";
+import { serverPluginAutoreloadOnRestart } from "./plugins/autoreload_on_server_restart/server_plugin_autoreload_on_server_restart.js";
+import { serverPluginDefaultBody4xx5xx } from "./plugins/default_body_4xx_5xx/server_plugin_default_body_4xx_5xx.js";
+import { serverPluginInternalClientFiles } from "./plugins/internal_client_files/server_plugin_internal_client_files.js";
+import { serverPluginOpenFile } from "./plugins/open_file/server_plugin_open_file.js";
+import { serverPluginRouteInspector } from "./plugins/route_inspector/server_plugin_route_inspector.js";
+import { createServerPluginsController } from "./plugins/server_plugins_controller.js";
 import { createRouter } from "./router/router.js";
 import { timingToServerTimingResponseHeaders } from "./server_timing/timing_header.js";
-import {
-  createServiceController,
-  flattenAndFilterServices,
-} from "./service_controller.js";
-import { jsenvServiceAutoreloadOnRestart } from "./services/autoreload_on_server_restart/jsenv_service_autoreload_on_server_restart.js";
-import { jsenvServiceDefaultBody4xx5xx } from "./services/default_body_4xx_5xx/jsenv_service_default_body_4xx_5xx.js";
-import { jsenvServiceInternalClientFiles } from "./services/internal_client_files/jsenv_service_internal_client_files.js";
-import { jsenvServiceOpenFile } from "./services/open_file/jsenv_service_open_file.js";
-import { jsenvServiceRouteInspector } from "./services/route_inspector/jsenv_service_route_inspector.js";
 import {
   STOP_REASON_INTERNAL_ERROR,
   STOP_REASON_NOT_SPECIFIED,
@@ -42,7 +39,7 @@ import {
   STOP_REASON_PROCESS_SIGHUP,
   STOP_REASON_PROCESS_SIGINT,
   STOP_REASON_PROCESS_SIGTERM,
-} from "./stopReasons.js";
+} from "./stop_reasons.js";
 import { getWebSocketHandler } from "./web_socket_response.js";
 
 import { applyDnsResolution } from "./internal/dns_resolution.js";
@@ -81,7 +78,7 @@ export const startServer = async ({
   stopOnInternalError = false,
   keepProcessAlive = true,
   routes = [],
-  services = [],
+  plugins = [],
   nagle = true,
   serverTiming = false,
   requestWaitingMs = 0,
@@ -155,25 +152,26 @@ export const startServer = async ({
     }
   }
 
-  services = [
-    jsenvServiceOpenFile(),
-    jsenvServiceDefaultBody4xx5xx(),
-    jsenvServiceRouteInspector(),
-    jsenvServiceInternalClientFiles(),
-    jsenvServiceAutoreloadOnRestart(),
-    ...flattenAndFilterServices(services),
+  plugins = [
+    serverPluginOpenFile(),
+    serverPluginDefaultBody4xx5xx(),
+    serverPluginRouteInspector(),
+    serverPluginInternalClientFiles(),
+    serverPluginAutoreloadOnRestart(),
+    ...plugins,
   ];
 
+  const serverPluginsController = await createServerPluginsController(plugins);
   const allRouteArray = [];
   for (const route of routes) {
     allRouteArray.push(route);
   }
-  for (const service of services) {
-    const serviceRoutes = service.routes;
-    if (serviceRoutes) {
-      for (const serviceRoute of serviceRoutes) {
-        serviceRoute.service = service;
-        allRouteArray.push(serviceRoute);
+  for (const serverPlugin of serverPluginsController.activePlugins) {
+    const routes = serverPlugin.routes;
+    if (routes) {
+      for (const route of routes) {
+        route.serverPlugin = serverPlugin;
+        allRouteArray.push(route);
       }
     }
   }
@@ -184,8 +182,6 @@ export const startServer = async ({
   });
 
   const server = {};
-
-  const serviceController = createServiceController(services);
   const processTeardownEvents = {
     SIGHUP: stopOnExit,
     SIGTERM: stopOnExit,
@@ -296,7 +292,7 @@ export const startServer = async ({
       serverOrigins[key] = new URL(`${serverOrigins[key]}:${port}`).origin;
     });
 
-    serviceController.callHooks("serverListening", { port });
+    serverPluginsController.callHooks("serverListening", { port });
     startServerOperation.addAbortCallback(async () => {
       await stopListening(nodeServer);
     });
@@ -341,7 +337,7 @@ export const startServer = async ({
     }
     stopCallbackSet.clear();
     await Promise.all(promises);
-    serviceController.callHooks("serverStopped", { reason });
+    serverPluginsController.callHooks("serverStopped", { reason });
     status = "stopped";
     stoppedResolve(reason);
   });
@@ -396,7 +392,7 @@ export const startServer = async ({
   });
 
   const applyRequestInternalRedirection = (request) => {
-    serviceController.callHooks(
+    serverPluginsController.callHooks(
       "redirectRequest",
       request,
       {},
@@ -501,7 +497,7 @@ export const startServer = async ({
           headersToInject,
         );
       }
-      serviceController.callHooks(
+      serverPluginsController.callHooks(
         "injectResponseProperties",
         request,
         responseProperties,
@@ -559,7 +555,7 @@ export const startServer = async ({
             );
           },
         };
-        await serviceController.callAsyncHooks(
+        await serverPluginsController.callAsyncHooks(
           "augmentRouteFetchSecondArg",
           request,
           fetchSecondArg,
@@ -599,7 +595,7 @@ export const startServer = async ({
         stop(STOP_REASON_INTERNAL_ERROR);
       }
       const handleErrorReturnValue =
-        await serviceController.callAsyncHooksUntil("handleError", e, {
+        await serverPluginsController.callAsyncHooksUntil("handleError", e, {
           request,
         });
       if (!handleErrorReturnValue) {
@@ -718,19 +714,19 @@ export const startServer = async ({
               return;
             }
 
-            let preventedByService = null;
+            let preventedByPlugin = null;
             const prevent = () => {
-              preventedByService = serviceController.getCurrentService();
+              preventedByPlugin = serverPluginsController.getCurrentPlugin();
             };
-            serviceController.callHooksUntil(
+            serverPluginsController.callHooksUntil(
               "onResponsePush",
               { path, method },
               { request, prevent },
-              () => preventedByService,
+              () => preventedByPlugin,
             );
-            if (preventedByService) {
+            if (preventedByPlugin) {
               pushRequestLogger.debug(
-                `response push prevented by "${preventedByService.name}" service`,
+                `response push prevented by "${preventedByPlugin.name}" plugin`,
               );
               return;
             }

package/src/main.js

@@ -1,52 +0,0 @@
-/*
- * This file is the first file executed by code using the package
- * Its responsability is to export what is documented
- * Ideally this file should be kept simple to help discovering codebase progressively.
- */
-
-// tslint:disable:ordered-imports
-
-export { startServer } from "./start_server.js";
-
-export {
-  STOP_REASON_INTERNAL_ERROR,
-  STOP_REASON_PROCESS_SIGHUP,
-  STOP_REASON_PROCESS_SIGTERM,
-  STOP_REASON_PROCESS_SIGINT,
-  STOP_REASON_PROCESS_BEFORE_EXIT,
-  STOP_REASON_PROCESS_EXIT,
-  STOP_REASON_NOT_SPECIFIED,
-} from "./stopReasons.js";
-export { jsenvServiceErrorHandler } from "./services/error_handler/jsenv_service_error_handler.js";
-
-// filesystem
-export {
-  createFileSystemFetch,
-  fetchFileSystem,
-} from "./filesystem/fetch_filesystem.js";
-
-// webSocket
-export { WebSocketResponse } from "./web_socket_response.js";
-// long polling
-export { ProgressiveResponse } from "./progressive_response.js";
-// Server event (can be used to push events to clients that can be connected with WebSocket or EventSource)
-export { ServerEvents, LazyServerEvents } from "./server_events.js";
-
-// CORS
-export {
-  jsenvServiceCORS,
-  jsenvAccessControlAllowedHeaders,
-  jsenvAccessControlAllowedMethods,
-} from "./services/cors/jsenv_service_cors.js";
-
-// content-negotiation
-export { pickContentType } from "./content_negotiation/pick_content_type.js";
-export { pickContentEncoding } from "./content_negotiation/pick_content_encoding.js";
-export { pickContentLanguage } from "./content_negotiation/pick_content_language.js";
-export { jsenvServiceResponseAcceptanceCheck } from "./services/response_acceptance_check/jsenv_service_response_acceptance_check.js";
-
-// others
-export { serveDirectory } from "./filesystem/serve_directory.js";
-export { composeTwoResponses } from "./internal/response_composition.js";
-export { jsenvServiceRequestAliases } from "./services/request_aliases/jsenv_service_request_aliases.js";
-export { findFreePort } from "./internal/listen.js";