@jsenv/core 26.0.1 → 27.0.0-alpha.2

package/src/omega/omega_server.js

@@ -0,0 +1,129 @@
+import {
+  jsenvAccessControlAllowedHeaders,
+  startServer,
+  composeServices,
+  pluginServerTiming,
+  pluginRequestWaitingCheck,
+  pluginCORS,
+} from "@jsenv/server"
+import { convertFileSystemErrorToResponseProperties } from "@jsenv/server/src/internal/convertFileSystemErrorToResponseProperties.js"
+import { createCallbackListNotifiedOnce } from "@jsenv/abort"
+import { loggerToLogLevel } from "@jsenv/logger"
+
+import { createFileService } from "./server/file_service.js"
+
+export const startOmegaServer = async ({
+  signal,
+  handleSIGINT,
+  logger,
+  protocol = "http",
+  http2 = protocol === "https",
+  privateKey,
+  certificate,
+  listenAnyIp,
+  ip,
+  port = 0,
+  keepProcessAlive = false,
+  onStop = () => {},
+  serverPlugins,
+  services,
+
+  rootDirectoryUrl,
+  scenario,
+  urlGraph,
+  kitchen,
+}) => {
+  const serverStopCallbackList = createCallbackListNotifiedOnce()
+  const coreServices = {
+    "service:file": createFileService({
+      rootDirectoryUrl,
+      urlGraph,
+      kitchen,
+      scenario,
+    }),
+  }
+  const server = await startServer({
+    signal,
+    stopOnExit: false,
+    stopOnSIGINT: handleSIGINT,
+    stopOnInternalError: false,
+    keepProcessAlive,
+    logLevel: loggerToLogLevel(logger),
+    startLog: false,
+
+    protocol,
+    http2,
+    certificate,
+    privateKey,
+    listenAnyIp,
+    ip,
+    port,
+    plugins: {
+      ...serverPlugins,
+      ...pluginCORS({
+        accessControlAllowRequestOrigin: true,
+        accessControlAllowRequestMethod: true,
+        accessControlAllowRequestHeaders: true,
+        accessControlAllowedRequestHeaders: [
+          ...jsenvAccessControlAllowedHeaders,
+          "x-jsenv-execution-id",
+        ],
+        accessControlAllowCredentials: true,
+      }),
+      ...pluginServerTiming(),
+      ...pluginRequestWaitingCheck({
+        requestWaitingMs: 60 * 1000,
+      }),
+    },
+    sendErrorDetails: true,
+    errorToResponse: (error, { request }) => {
+      const getResponseForError = () => {
+        if (error && error.asResponse) {
+          return error.asResponse()
+        }
+        if (error && error.statusText === "Unexpected directory operation") {
+          return {
+            status: 403,
+          }
+        }
+        return convertFileSystemErrorToResponseProperties(error)
+      }
+      const response = getResponseForError()
+      if (!response) {
+        return null
+      }
+      const isInspectRequest = new URL(
+        request.ressource,
+        request.origin,
+      ).searchParams.has("__inspect__")
+      if (!isInspectRequest) {
+        return response
+      }
+      const body = JSON.stringify({
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+        body: response.body,
+      })
+      return {
+        status: 200,
+        headers: {
+          "content-type": "application/json",
+          "content-length": Buffer.byteLength(body),
+        },
+        body,
+      }
+    },
+    requestToResponse: composeServices({
+      ...services,
+      ...coreServices,
+    }),
+    onStop: (reason) => {
+      onStop()
+      serverStopCallbackList.notify(reason)
+    },
+  })
+  return {
+    ...server,
+  }
+}

package/src/omega/plugin_controller.js

@@ -0,0 +1,240 @@
+export const createPluginController = ({
+  plugins,
+  scenario,
+  hooks = [
+    "resolve",
+    "normalize",
+    "load",
+    "transform",
+    "transformReferencedUrl",
+    "formatReferencedUrl",
+    "finalize",
+    "cooked",
+    "destroy",
+  ],
+}) => {
+  plugins = flattenAndFilterPlugins(plugins, { scenario })
+  // precompute a list of hooks per hookName
+  // For one major reason:
+  // - When debugging, there is less iteration
+  // And also it should increase perf as there is less work to do
+  const hookGroups = {}
+  const addHook = (hookName) => {
+    const hooks = []
+    plugins.forEach((plugin) => {
+      const hook = plugin[hookName]
+      if (hook) {
+        hooks.push({
+          plugin,
+          hookName,
+          value: hook,
+        })
+      }
+    })
+    hookGroups[hookName] = hooks
+    return hooks
+  }
+  hooks.forEach((hookName) => {
+    addHook(hookName)
+  })
+
+  let currentPlugin = null
+  let currentHookName = null
+  const callHook = (hook, info, context) => {
+    const hookFn = getHookFunction(hook, info)
+    if (!hookFn) {
+      return null
+    }
+    currentPlugin = hook.plugin
+    currentHookName = hook.hookName
+    let valueReturned = hookFn(info, context)
+    valueReturned = assertAndNormalizeReturnValue(hook.hookName, valueReturned)
+    currentPlugin = null
+    currentHookName = null
+    return valueReturned
+  }
+  const callAsyncHook = async (hook, info, context) => {
+    const hookFn = getHookFunction(hook, info)
+    if (!hookFn) {
+      return null
+    }
+    currentPlugin = hook.plugin
+    currentHookName = hook.hookName
+    let valueReturned = await hookFn(info, context)
+    valueReturned = assertAndNormalizeReturnValue(hook.hookName, valueReturned)
+    currentPlugin = null
+    currentHookName = null
+    return valueReturned
+  }
+
+  const callHooks = (hookName, info, context, callback) => {
+    const hooks = hookGroups[hookName]
+    for (const hook of hooks) {
+      const returnValue = callHook(hook, info, context)
+      if (returnValue) {
+        callback(returnValue)
+      }
+    }
+  }
+  const callAsyncHooks = async (hookName, info, context, callback) => {
+    const hooks = hookGroups[hookName]
+    await hooks.reduce(async (previous, hook) => {
+      await previous
+      const returnValue = await callAsyncHook(hook, info, context)
+      if (returnValue && callback) {
+        await callback(returnValue)
+      }
+    }, Promise.resolve())
+  }
+
+  const callHooksUntil = (hookName, info, context) => {
+    const hooks = hookGroups[hookName]
+    for (const hook of hooks) {
+      const returnValue = callHook(hook, info, context)
+      if (returnValue) {
+        return returnValue
+      }
+    }
+    return null
+  }
+  const callAsyncHooksUntil = (hookName, info, context) => {
+    const hooks = hookGroups[hookName]
+    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 {
+    plugins,
+    addHook,
+    getHookFunction,
+    callHook,
+    callAsyncHook,
+
+    callHooks,
+    callHooksUntil,
+    callAsyncHooks,
+    callAsyncHooksUntil,
+
+    getCurrentPlugin: () => currentPlugin,
+    getCurrentHookName: () => currentHookName,
+  }
+}
+
+const flattenAndFilterPlugins = (pluginsRaw, { scenario }) => {
+  const plugins = []
+  const visitPluginEntry = (pluginEntry) => {
+    if (Array.isArray(pluginEntry)) {
+      pluginEntry.forEach((value) => visitPluginEntry(value))
+      return
+    }
+    if (typeof pluginEntry === "object" && pluginEntry !== null) {
+      const { appliesDuring } = pluginEntry
+      if (appliesDuring === undefined) {
+        console.warn(`"appliesDuring" is undefined on ${pluginEntry.name}`)
+      }
+      if (appliesDuring === "*") {
+        plugins.push(pluginEntry)
+        return
+      }
+      if (appliesDuring && appliesDuring[scenario]) {
+        plugins.push(pluginEntry)
+        return
+      }
+      if (pluginEntry.destroy) {
+        pluginEntry.destroy()
+      }
+      return
+    }
+    throw new Error(`plugin must be objects, got ${pluginEntry}`)
+  }
+  pluginsRaw.forEach((plugin) => visitPluginEntry(plugin))
+  return plugins
+}
+
+const getHookFunction = (
+  hook,
+  // can be undefined, reference, or urlInfo
+  info = {},
+) => {
+  const hookValue = hook.value
+  if (typeof hookValue === "object") {
+    const hookForType = hookValue[info.type] || hookValue["*"]
+    if (!hookForType) {
+      return null
+    }
+    return hookForType
+  }
+  return hookValue
+}
+
+const assertAndNormalizeReturnValue = (hookName, returnValue) => {
+  // all hooks are allowed to return null/undefined as a signal of "I don't do anything"
+  if (returnValue === null || returnValue === undefined) {
+    return returnValue
+  }
+  for (const returnValueAssertion of returnValueAssertions) {
+    if (!returnValueAssertion.appliesTo.includes(hookName)) {
+      continue
+    }
+    const assertionResult = returnValueAssertion.assertion(returnValue)
+    if (assertionResult !== undefined) {
+      // normalization
+      returnValue = assertionResult
+      break
+    }
+  }
+  return returnValue
+}
+
+const returnValueAssertions = [
+  {
+    name: "url_assertion",
+    appliesTo: ["resolve", "redirect"],
+    assertion: (valueReturned) => {
+      if (valueReturned instanceof URL) {
+        return valueReturned.href
+      }
+      if (typeof valueReturned === "string") {
+        return undefined
+      }
+      throw new Error(
+        `Unexpected value returned by plugin: it must be a string; got ${valueReturned}`,
+      )
+    },
+  },
+  {
+    name: "content_assertion",
+    appliesTo: ["load", "transform", "finalize"],
+    assertion: (valueReturned) => {
+      if (typeof valueReturned === "string" || Buffer.isBuffer(valueReturned)) {
+        return { content: valueReturned }
+      }
+      if (typeof valueReturned === "object") {
+        const { content } = valueReturned
+        if (typeof content !== "string" && !Buffer.isBuffer(content)) {
+          throw new Error(
+            `Unexpected "content" returned by plugin: it must be a string or a buffer; got ${content}`,
+          )
+        }
+        return undefined
+      }
+      throw new Error(
+        `Unexpected value returned by plugin: it must be a string, a buffer or an object; got ${valueReturned}`,
+      )
+    },
+  },
+]

package/src/omega/runtime_support/default_runtime_support.js

@@ -0,0 +1,13 @@
+// correspond to dynamic import
+export const defaultRuntimeSupport = {
+  // android: "8",
+  chrome: "63",
+  edge: "79",
+  electron: "8.1",
+  firefox: "67",
+  ios: "11",
+  opera: "50",
+  safari: "11.3",
+  node: "13.2",
+  samsung: "8.0",
+}

package/src/omega/runtime_support/features_compatibility.js

@@ -0,0 +1,91 @@
+export const featuresCompatMap = {
+  script_type_module: {
+    edge: "16",
+    firefox: "60",
+    chrome: "61",
+    safari: "10.1",
+    opera: "48",
+    ios: "10.3",
+    android: "61",
+    samsung: "8.2",
+  },
+  import_meta: {
+    chrome: "64",
+    edge: "79",
+    firefox: "62",
+    safari: "11.1",
+    opera: "51",
+    ios: "12",
+    android: "9",
+  },
+  import_dynamic: {
+    edge: "79",
+    firefox: "67",
+    chrome: "63",
+    safari: "11.3",
+    opera: "50",
+    android: "8",
+    node: "13.2",
+  },
+  top_level_await: {
+    edge: "89",
+    chrome: "89",
+    firefox: "89",
+    opera: "75",
+    safari: "15",
+    samsung: "15",
+    ios: "15",
+    node: "14.8",
+  },
+  // https://caniuse.com/import-maps
+  importmap: {
+    edge: "89",
+    chrome: "89",
+    opera: "76",
+    samsung: "15",
+  },
+  import_type_json: {
+    chrome: "91",
+    edge: "91",
+  },
+  import_type_css: {
+    chrome: "93",
+    edge: "93",
+  },
+  // https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet#browser_compatibility
+  new_stylesheet: {
+    chrome: "73",
+    edge: "79",
+    opera: "53",
+    android: "73",
+  },
+  worker_type_module: {
+    chrome: "80",
+    edge: "80",
+    opera: "67",
+    android: "80",
+  },
+  worker_importmap: {},
+  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis#browser_compatibility
+  global_this: {
+    edge: "79",
+    firefox: "65",
+    chrome: "71",
+    safari: "12.1",
+    opera: "58",
+    ios: "12.2",
+    android: "94",
+    node: "12",
+  },
+  async_generator_function: {
+    chrome: "63",
+    opera: "50",
+    edge: "79",
+    firefox: "57",
+    safari: "12",
+    node: "10",
+    ios: "12",
+    samsung: "8",
+    electron: "3",
+  },
+}

package/src/omega/runtime_support/runtime_support.js

@@ -0,0 +1,20 @@
+import { findHighestVersion } from "@jsenv/utils/semantic_versioning/highest_version.js"
+
+export const isFeatureSupportedOnRuntimes = (
+  runtimeSupport,
+  featureCompat = {},
+) => {
+  const runtimeNames = Object.keys(runtimeSupport)
+  return runtimeNames.every((runtimeName) => {
+    const runtimeVersion = runtimeSupport[runtimeName]
+    const runtimeVersionCompatible = featureCompat[runtimeName] || "Infinity"
+    const highestVersion = findHighestVersion(
+      runtimeVersion,
+      runtimeVersionCompatible,
+    )
+    if (highestVersion !== runtimeVersion) {
+      return false
+    }
+    return true
+  })
+}

package/src/omega/server/file_service.js

@@ -0,0 +1,155 @@
+import {
+  fetchFileSystem,
+  serveDirectory,
+  composeTwoResponses,
+} from "@jsenv/server"
+import { urlIsInsideOf, moveUrl } from "@jsenv/filesystem"
+
+import { parseUserAgentHeader } from "./user_agent.js"
+
+export const createFileService = ({
+  rootDirectoryUrl,
+  urlGraph,
+  kitchen,
+  scenario,
+}) => {
+  kitchen.pluginController.addHook("serve")
+  kitchen.pluginController.addHook("augmentResponse")
+  const serveContext = {
+    rootDirectoryUrl,
+    urlGraph,
+    scenario,
+  }
+
+  const getResponse = async (request) => {
+    // serve file inside ".jsenv" directory
+    const requestFileUrl = new URL(request.ressource.slice(1), rootDirectoryUrl)
+      .href
+    if (urlIsInsideOf(requestFileUrl, kitchen.jsenvDirectoryUrl)) {
+      return fetchFileSystem(requestFileUrl, {
+        headers: request.headers,
+      })
+    }
+    const responseFromPlugin =
+      await kitchen.pluginController.callAsyncHooksUntil(
+        "serve",
+        request,
+        serveContext,
+      )
+    if (responseFromPlugin) {
+      return responseFromPlugin
+    }
+    const { runtimeName, runtimeVersion } = parseUserAgentHeader(
+      request.headers["user-agent"],
+    )
+    const runtimeSupport = {
+      [runtimeName]: runtimeVersion,
+    }
+    const reference = kitchen.createReference({
+      parentUrl: inferParentFromRequest(request, rootDirectoryUrl),
+      type: "entry_point",
+      specifier: request.ressource,
+    })
+    const requestedUrlInfo = kitchen.resolveReference(reference)
+    const referenceFromGraph = urlGraph.inferReference(
+      reference.url,
+      reference.parentUrl,
+    )
+    try {
+      await kitchen.cook({
+        reference: referenceFromGraph || reference,
+        urlInfo: requestedUrlInfo,
+        outDirectoryUrl: `${rootDirectoryUrl}.jsenv/${scenario}/${runtimeName}@${runtimeVersion}/`,
+        runtimeSupport,
+      })
+      const { response, contentType, content } = requestedUrlInfo
+      if (response) {
+        return response
+      }
+      return {
+        url: reference.url,
+        status: 200,
+        headers: {
+          "content-type": contentType,
+          "content-length": Buffer.byteLength(content),
+          "cache-control": `private,max-age=0,must-revalidate`,
+        },
+        body: content,
+      }
+    } catch (e) {
+      const code = e.code
+      if (code === "PARSE_ERROR") {
+        // let the browser re-throw the syntax error
+        return {
+          url: reference.url,
+          status: 200,
+          statusText: e.reason,
+          statusMessage: e.message,
+          headers: {
+            "content-type": requestedUrlInfo.contentType,
+            "content-length": Buffer.byteLength(requestedUrlInfo.content),
+            "cache-control": "no-store",
+          },
+          body: requestedUrlInfo.content,
+        }
+      }
+      if (code === "EISDIR") {
+        return serveDirectory(reference.url, {
+          headers: {
+            accept: "text/html",
+          },
+          canReadDirectory: true,
+          rootDirectoryUrl,
+        })
+      }
+      if (code === "NOT_ALLOWED") {
+        return {
+          url: reference.url,
+          status: 403,
+          statusText: e.reason,
+        }
+      }
+      if (code === "NOT_FOUND") {
+        return {
+          url: reference.url,
+          status: 404,
+          statusText: e.reason,
+          statusMessage: e.message,
+        }
+      }
+      return {
+        url: reference.url,
+        status: 500,
+        statusText: e.reason,
+        statusMessage: e.stack,
+      }
+    }
+  }
+  return async (request) => {
+    let response = await getResponse(request)
+    if (response.url) {
+      kitchen.pluginController.callHooks(
+        "augmentResponse",
+        response,
+        {},
+        (returnValue) => {
+          response = composeTwoResponses(response, returnValue)
+        },
+      )
+    }
+    return response
+  }
+}
+
+const inferParentFromRequest = (request, rootDirectoryUrl) => {
+  const { referer } = request.headers
+  if (!referer) {
+    return rootDirectoryUrl
+  }
+  return moveUrl({
+    url: referer,
+    from: `${request.origin}/`,
+    to: rootDirectoryUrl,
+    preferAbsolute: true,
+  })
+}

package/src/omega/server/user_agent.js

@@ -0,0 +1,22 @@
+import { createRequire } from "node:module"
+
+const require = createRequire(import.meta.url)
+
+export const parseUserAgentHeader = (userAgent) => {
+  if (userAgent.includes("node-fetch/")) {
+    // it's not really node and conceptually we can't assume the node version
+    // but good enough for now
+    return {
+      runtimeName: "node",
+      runtimeVersion: process.version.slice(1),
+    }
+  }
+  const UA = require("@financial-times/polyfill-useragent-normaliser")
+  const { ua } = new UA(userAgent)
+  const { family, major, minor, patch } = ua
+  return {
+    runtimeName: family.toLowerCase(),
+    runtimeVersion:
+      family === "Other" ? "unknown" : `${major}.${minor}${patch}`,
+  }
+}