@jsenv/server 16.4.0 → 17.0.0

package/index.js

@@ -16,8 +16,8 @@ export {
   STOP_REASON_PROCESS_BEFORE_EXIT,
   STOP_REASON_PROCESS_EXIT,
   STOP_REASON_NOT_SPECIFIED,
-} from "./src/stopReasons.js";
-export { jsenvServiceErrorHandler } from "./src/services/error_handler/jsenv_service_error_handler.js";
+} from "./src/stop_reasons.js";
+export { serverPluginErrorHandler } from "./src/plugins/error_handler/server_plugin_error_handler.js";
 
 // webSocket
 export { WebSocketResponse } from "./src/web_socket_response.js";
@@ -28,26 +28,29 @@ export { ServerEvents, LazyServerEvents } from "./src/server_events.js";
 
 // CORS
 export {
-  jsenvServiceCORS,
+  serverPluginCORS,
   jsenvAccessControlAllowedHeaders,
   jsenvAccessControlAllowedMethods,
-} from "./src/services/cors/jsenv_service_cors.js";
+} from "./src/plugins/cors/server_plugin_cors.js";
 
 // filesystem
 export {
   createFileSystemFetch,
   fetchFileSystem,
-} from "./src/services/filesystem/fetch_filesystem.js";
-export { serveDirectory } from "./src/services/filesystem/serve_directory.js";
-export { jsenvServiceStaticFiles } from "./src/services/filesystem/jsenv_service_static_files.js";
+} from "./src/plugins/filesystem/fetch_filesystem.js";
+export { serveDirectory } from "./src/plugins/filesystem/serve_directory.js";
+export { serverPluginStaticFiles } from "./src/plugins/filesystem/server_plugin_static_files.js";
 
 // content-negotiation
 export { pickContentType } from "./src/content_negotiation/pick_content_type.js";
 export { pickContentEncoding } from "./src/content_negotiation/pick_content_encoding.js";
 export { pickContentLanguage } from "./src/content_negotiation/pick_content_language.js";
-export { jsenvServiceResponseAcceptanceCheck } from "./src/services/response_acceptance_check/jsenv_service_response_acceptance_check.js";
+export { serverPluginResponseAcceptanceCheck } from "./src/plugins/response_acceptance_check/server_plugin_response_acceptance_check.js";
 
 // others
 export { composeTwoResponses } from "./src/internal/response_composition.js";
-export { jsenvServiceRequestAliases } from "./src/services/request_aliases/jsenv_service_request_aliases.js";
+export { serverPluginRequestAliases } from "./src/plugins/request_aliases/server_plugin_request_aliases.js";
 export { findFreePort } from "./src/internal/listen.js";
+
+// internal (used by @jsenv/core)
+export { createPluginsController } from "./src/plugins_controller.js";

package/package.json

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

package/src/{services/autoreload_on_server_restart/jsenv_service_autoreload_on_server_restart.js → plugins/autoreload_on_server_restart/server_plugin_autoreload_on_server_restart.js}

@@ -1,6 +1,6 @@
 import { LazyServerEvents } from "../../server_events.js";
 
-export const jsenvServiceAutoreloadOnRestart = () => {
+export const serverPluginAutoreloadOnRestart = () => {
   const aliveServerEvents = new LazyServerEvents(() => {});
 
   return {

package/src/{services/cors/jsenv_service_cors.js → plugins/cors/server_plugin_cors.js}

@@ -13,7 +13,7 @@ export const jsenvAccessControlAllowedMethods = [
   "OPTIONS",
 ];
 
-export const jsenvServiceCORS = ({
+export const serverPluginCORS = ({
   accessControlAllowedOrigins = [],
   accessControlAllowedMethods = jsenvAccessControlAllowedMethods,
   accessControlAllowedHeaders = jsenvAccessControlAllowedHeaders,

package/src/{services → plugins}/default_body_4xx_5xx/client/4xx.html

@@ -60,6 +60,6 @@
       <p class="error_message">${statusMessage}</p>
       <a href="/" jsenv-ignore class="home_link">Return to Home</a>
     </div>
-    <script src="/@jsenv/server/src/services/autoreload_on_server_restart/client/autoreload_on_server_restart.js?inline"></script>
+    <script src="/@jsenv/server/src/plugins/autoreload_on_server_restart/client/autoreload_on_server_restart.js?inline"></script>
   </body>
 </html>

package/src/{services/default_body_4xx_5xx/jsenv_service_default_body_4xx_5xx.js → plugins/default_body_4xx_5xx/server_plugin_default_body_4xx_5xx.js}

@@ -1,10 +1,11 @@
 import { readFileSync } from "node:fs";
+
 import { pickContentType } from "../../content_negotiation/pick_content_type.js";
 import { replacePlaceholdersInHtml } from "../../replace_placeholder_in_html.js";
 
 const clientErrorHtmlTemplateFileUrl = import.meta.resolve("./client/4xx.html");
 
-export const jsenvServiceDefaultBody4xx5xx = () => {
+export const serverPluginDefaultBody4xx5xx = () => {
   return {
     name: "jsenv:default_body_4xx_5xx",
 

package/src/{services/error_handler/jsenv_service_error_handler.js → plugins/error_handler/server_plugin_error_handler.js}

@@ -5,7 +5,7 @@ import { replacePlaceholdersInHtml } from "../../replace_placeholder_in_html.js"
 
 const internalErrorHtmlFileUrl = import.meta.resolve("./client/500.html");
 
-export const jsenvServiceErrorHandler = ({ sendErrorDetails = false } = {}) => {
+export const serverPluginErrorHandler = ({ sendErrorDetails = false } = {}) => {
   return {
     name: "jsenv:error_handler",
     handleError: (serverInternalError, { request }) => {

package/src/{services/filesystem/jsenv_service_static_files.js → plugins/filesystem/server_plugin_static_files.js}

@@ -2,9 +2,9 @@ import { urlToExtension, urlToPathname } from "@jsenv/urls";
 
 import { createFileSystemFetch } from "./fetch_filesystem.js";
 
-export const jsenvServiceStaticFiles = ({ directoryUrl, mainFilePath }) => {
+export const serverPluginStaticFiles = ({ directoryUrl, mainFilePath }) => {
   return {
-    name: "jsenv:file_service",
+    name: "jsenv:static_files",
     routes: [
       {
         endpoint: "GET *",

package/src/{services/internal_client_files/jsenv_service_internal_client_files.js → plugins/internal_client_files/server_plugin_internal_client_files.js}

@@ -3,7 +3,7 @@ import { readFileSync } from "node:fs";
 
 const jsenvServerRootDirectoryUrl = import.meta.resolve("../../../");
 
-export const jsenvServiceInternalClientFiles = () => {
+export const serverPluginInternalClientFiles = () => {
   return {
     name: "jsenv:internal_client_files",
 

package/src/{services/open_file/jsenv_service_open_file.js → plugins/open_file/server_plugin_open_file.js}

@@ -1,7 +1,7 @@
 import { urlToFileSystemPath } from "@jsenv/urls";
 import { createRequire } from "node:module";
 
-export const jsenvServiceOpenFile = () => {
+export const serverPluginOpenFile = () => {
   return {
     name: "jsenv:open_file",
     routes: [

package/src/{services/request_aliases/jsenv_service_request_aliases.js → plugins/request_aliases/server_plugin_request_aliases.js}

@@ -1,6 +1,6 @@
 import { URL_META } from "@jsenv/url-meta";
 
-export const jsenvServiceRequestAliases = (resourceAliases) => {
+export const serverPluginRequestAliases = (resourceAliases) => {
   const aliases = {};
   Object.keys(resourceAliases).forEach((key) => {
     aliases[asFileUrl(key)] = asFileUrl(resourceAliases[key]);

package/src/{services/response_acceptance_check/jsenv_service_response_acceptance_check.js → plugins/response_acceptance_check/server_plugin_response_acceptance_check.js}

@@ -2,7 +2,7 @@ import { pickContentEncoding } from "@jsenv/server/src/content_negotiation/pick_
 import { pickContentLanguage } from "@jsenv/server/src/content_negotiation/pick_content_language.js";
 import { pickContentType } from "@jsenv/server/src/content_negotiation/pick_content_type.js";
 
-export const jsenvServiceResponseAcceptanceCheck = () => {
+export const serverPluginResponseAcceptanceCheck = () => {
   return {
     name: "jsenv:response_acceptance_check",
     inspectResponse: (request, { response, warn }) => {

package/src/{services → plugins}/route_inspector/client/route_inspector.html

@@ -14,8 +14,8 @@
         }
       }
     </script>
-    <script src="/@jsenv/server/src/services/route_inspector/client/code_block.js?inline"></script>
-    <script src="/@jsenv/server/src/services/autoreload_on_server_restart/client/autoreload_on_server_restart.js?inline"></script>
+    <script src="/@jsenv/server/src/plugins/route_inspector/client/code_block.js?inline"></script>
+    <script src="/@jsenv/server/src/plugins/autoreload_on_server_restart/client/autoreload_on_server_restart.js?inline"></script>
   </head>
   <body>
     <style>

package/src/{services/route_inspector/jsenv_service_route_inspector.js → plugins/route_inspector/server_plugin_route_inspector.js}

@@ -3,7 +3,7 @@ import { readFileSync } from "node:fs";
 const routeInspectorHtmlFileUrl = import.meta
   .resolve("./client/route_inspector.html");
 
-export const jsenvServiceRouteInspector = () => {
+export const serverPluginRouteInspector = () => {
   return {
     name: "jsenv:route_inspector",
     routes: [

package/src/plugins/server_plugins_controller.js

@@ -0,0 +1,21 @@
+import { createPluginsController } from "../plugins_controller.js";
+
+export const createServerPluginsController = async (serverPlugins) => {
+  const jsenvServerPluginsController = await createPluginsController({
+    plugins: serverPlugins,
+    pluginDescription: {
+      name: "server plugin",
+      properties: {
+        serverListening: { type: "hook" },
+        redirectRequest: { type: "hook" },
+        augmentRouteFetchSecondArg: { type: "hook" },
+        handleError: { type: "hook" },
+        onResponsePush: { type: "hook" },
+        injectResponseProperties: { type: "hook" },
+        serverStopped: { type: "hook" },
+        routes: {}, // routes are handled separately (used to populate the router)
+      },
+    },
+  });
+  return jsenvServerPluginsController;
+};

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,