@jsenv/core 25.6.2 → 27.0.0-alpha.0

package/src/{internal/node_launcher/createChildProcessOptions.js → execute/runtimes/node/child_exec_options.js}

@@ -1,18 +1,9 @@
 import { findFreePort } from "@jsenv/server"
 import { createDetailedMessage } from "@jsenv/logger"
 
-import { processOptionsFromExecArgv } from "./processOptions.js"
+import { ExecOptions } from "./exec_options.js"
 
-const AVAILABLE_DEBUG_MODE = [
-  "none",
-  "inherit",
-  "inspect",
-  "inspect-brk",
-  "debug",
-  "debug-brk",
-]
-
-export const createChildProcessOptions = async ({
+export const createChildExecOptions = async ({
   signal = new AbortController().signal,
   // https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_automatically-attach-debugger-to-nodejs-subprocesses
   processExecArgv = process.execArgv,
@@ -33,22 +24,28 @@ export const createChildProcessOptions = async ({
       }),
     )
   }
-
-  const childProcessOptions = processOptionsFromExecArgv(processExecArgv)
-
-  await mutateDebuggingOptions(childProcessOptions, {
+  const childExecOptions = ExecOptions.fromExecArgv(processExecArgv)
+  await mutateDebuggingOptions(childExecOptions, {
     signal,
     processDebugPort,
     debugMode,
     debugPort,
     debugModeInheritBreak,
   })
-
-  return childProcessOptions
+  return childExecOptions
 }
 
+const AVAILABLE_DEBUG_MODE = [
+  "none",
+  "inherit",
+  "inspect",
+  "inspect-brk",
+  "debug",
+  "debug-brk",
+]
+
 const mutateDebuggingOptions = async (
-  childProcessOptions,
+  childExecOptions,
   {
     // ensure multiline
     signal,
@@ -58,7 +55,7 @@ const mutateDebuggingOptions = async (
     debugModeInheritBreak,
   },
 ) => {
-  const parentDebugInfo = getDebugInfo(childProcessOptions)
+  const parentDebugInfo = getDebugInfo(childExecOptions)
   const parentDebugModeOptionName = parentDebugInfo.debugModeOptionName
   const parentDebugPortOptionName = parentDebugInfo.debugPortOptionName
   const childDebugModeOptionName = getChildDebugModeOptionName({
@@ -70,10 +67,10 @@ const mutateDebuggingOptions = async (
   if (!childDebugModeOptionName) {
     // remove debug mode and debug port fron child options
     if (parentDebugModeOptionName) {
-      delete childProcessOptions[parentDebugModeOptionName]
+      delete childExecOptions[parentDebugModeOptionName]
     }
     if (parentDebugPortOptionName) {
-      delete childProcessOptions[parentDebugPortOptionName]
+      delete childExecOptions[parentDebugPortOptionName]
     }
     return
   }
@@ -83,9 +80,9 @@ const mutateDebuggingOptions = async (
     parentDebugModeOptionName &&
     parentDebugModeOptionName !== childDebugModeOptionName
   ) {
-    delete childProcessOptions[parentDebugModeOptionName]
+    delete childExecOptions[parentDebugModeOptionName]
   }
-  childProcessOptions[childDebugModeOptionName] = ""
+  childExecOptions[childDebugModeOptionName] = ""
 
   // this is required because vscode does not
   // support assigning a child spawned without a specific port
@@ -95,9 +92,9 @@ const mutateDebuggingOptions = async (
       : debugPort
   // replace child debug port
   if (parentDebugPortOptionName) {
-    delete childProcessOptions[parentDebugPortOptionName]
+    delete childExecOptions[parentDebugPortOptionName]
   }
-  childProcessOptions[childDebugModeOptionName] = portToArgValue(
+  childExecOptions[childDebugModeOptionName] = portToArgValue(
     childDebugPortOptionValue,
   )
 }
@@ -110,22 +107,18 @@ const getChildDebugModeOptionName = ({
   if (debugMode === "none") {
     return undefined
   }
-
   if (debugMode !== "inherit") {
     return `--${debugMode}`
   }
-
   if (!parentDebugModeOptionName) {
     return undefined
   }
-
   if (!debugModeInheritBreak && parentDebugModeOptionName === "--inspect-brk") {
     return "--inspect"
   }
   if (!debugModeInheritBreak && parentDebugModeOptionName === "--debug-brk") {
     return "--debug"
   }
-
   return parentDebugModeOptionName
 }
 
@@ -144,7 +137,6 @@ const getDebugInfo = (processOptions) => {
       debugPortOptionName: "--inspect-port",
     }
   }
-
   const inspectBreakOption = processOptions["--inspect-brk"]
   if (inspectBreakOption !== undefined) {
     return {
@@ -152,7 +144,6 @@ const getDebugInfo = (processOptions) => {
       debugPortOptionName: "--inspect-port",
     }
   }
-
   const debugOption = processOptions["--debug"]
   if (debugOption !== undefined) {
     return {
@@ -160,7 +151,6 @@ const getDebugInfo = (processOptions) => {
       debugPortOptionName: "--debug-port",
     }
   }
-
   const debugBreakOption = processOptions["--debug-brk"]
   if (debugBreakOption !== undefined) {
     return {
@@ -168,10 +158,9 @@ const getDebugInfo = (processOptions) => {
       debugPortOptionName: "--debug-port",
     }
   }
-
   return {}
 }
 
-export const processIsExecutedByVSCode = () => {
-  return typeof process.env.VSCODE_PID === "string"
-}
+// export const processIsExecutedByVSCode = () => {
+//   return typeof process.env.VSCODE_PID === "string"
+// }

package/src/{internal/node_runtime/nodeControllableFile.mjs → execute/runtimes/node/controllable_file.mjs}

@@ -1,25 +1,8 @@
 import v8 from "node:v8"
 import { uneval } from "@jsenv/uneval"
 
-const NODE_EXECUTION_DYNAMIC_IMPORT_URL = new URL(
-  "./node_execution_dynamic_import.js",
-  import.meta.url,
-).href
-const NODE_EXECUTION_SYSTEMJS_URL = new URL(
-  "./node_execution_systemjs.js",
-  import.meta.url,
-).href
-
 const ACTIONS_AVAILABLE = {
-  "execute-using-dynamic-import": async (executeParams) => {
-    const { execute } = await import(NODE_EXECUTION_DYNAMIC_IMPORT_URL)
-    return execute(executeParams)
-  },
-  "execute-using-systemjs": async (executeParams) => {
-    const { execute } = await import(NODE_EXECUTION_SYSTEMJS_URL)
-    return execute(executeParams)
-  },
-  "execute-using-import": async ({ fileUrl }) => {
+  "execute-using-dynamic-import": async ({ fileUrl }) => {
     const namespace = await import(fileUrl)
     const namespaceResolved = {}
     await Promise.all([

package/src/{internal/node_launcher/createControllableNodeProcess.js → execute/runtimes/node/controlled_process.js}

@@ -1,46 +1,33 @@
 import { fork } from "node:child_process"
-import { urlToFileSystemPath, assertFilePresence } from "@jsenv/filesystem"
-import { createLogger, createDetailedMessage } from "@jsenv/logger"
+import { urlToFileSystemPath } from "@jsenv/filesystem"
+import { createDetailedMessage } from "@jsenv/logger"
 import {
   Abort,
   raceCallbacks,
-  createCallbackList,
   createCallbackListNotifiedOnce,
 } from "@jsenv/abort"
 import { uneval } from "@jsenv/uneval"
 
-import { nodeSupportsDynamicImport } from "@jsenv/core/src/internal/features/node_feature_detection/node_feature_detect_dynamic_import.js"
+import { memoize } from "@jsenv/utils/memoize/memoize.js"
 
-import { createChildProcessOptions } from "./createChildProcessOptions.js"
-import {
-  processOptionsFromExecArgv,
-  execArgvFromProcessOptions,
-} from "./processOptions.js"
+import { createChildExecOptions } from "./child_exec_options.js"
+import { ExecOptions } from "./exec_options.js"
 import { killProcessTree } from "./kill_process_tree.js"
 
 const NODE_CONTROLLABLE_FILE_URL = new URL(
-  "../node_runtime/nodeControllableFile.mjs",
+  "./controllable_file.mjs",
   import.meta.url,
 ).href
 
-// https://nodejs.org/api/process.html#process_signal_events
-const SIGINT_SIGNAL_NUMBER = 2
-const SIGABORT_SIGNAL_NUMBER = 6
-const SIGTERM_SIGNAL_NUMBER = 15
-const SIGINT_EXIT_CODE = 128 + SIGINT_SIGNAL_NUMBER
-const SIGABORT_EXIT_CODE = 128 + SIGABORT_SIGNAL_NUMBER
-const SIGTERM_EXIT_CODE = 128 + SIGTERM_SIGNAL_NUMBER
-// http://man7.org/linux/man-pages/man7/signal.7.html
-// https:// github.com/nodejs/node/blob/1d9511127c419ec116b3ddf5fc7a59e8f0f1c1e4/lib/internal/child_process.js#L472
-const GRACEFUL_STOP_SIGNAL = "SIGTERM"
-const STOP_SIGNAL = "SIGKILL"
-// it would be more correct if GRACEFUL_STOP_FAILED_SIGNAL was SIGHUP instead of SIGKILL.
-// but I'm not sure and it changes nothing so just use SIGKILL
-const GRACEFUL_STOP_FAILED_SIGNAL = "SIGKILL"
-
-export const createControllableNodeProcess = async ({
+export const createControlledProcess = async ({
   signal = new AbortController().signal,
-  logLevel,
+  logger,
+  logProcessCommand = false,
+
+  onStop,
+  onError,
+  onConsole,
+
   debugPort,
   debugMode,
   debugModeInheritBreak,
@@ -51,50 +38,47 @@ export const createControllableNodeProcess = async ({
   stdin = "pipe",
   stdout = "pipe",
   stderr = "pipe",
-  logProcessCommand = false,
 }) => {
-  const logger = createLogger({ logLevel })
-  const dynamicImportSupported = await nodeSupportsDynamicImport()
-  if (!dynamicImportSupported) {
-    throw new Error(`node does not support dynamic import`)
+  if (env !== undefined && typeof env !== "object") {
+    throw new TypeError(`env must be an object, got ${env}`)
+  }
+  const cleanupCallbackList = createCallbackListNotifiedOnce()
+  const cleanup = async (reason) => {
+    await cleanupCallbackList.notify({ reason })
   }
 
-  const childProcessOptions = await createChildProcessOptions({
+  const childExecOptions = await createChildExecOptions({
     signal,
     debugPort,
     debugMode,
     debugModeInheritBreak,
   })
-  const processOptions = {
-    ...childProcessOptions,
-    ...processOptionsFromExecArgv(commandLineOptions),
-  }
-  const execArgv = execArgvFromProcessOptions(processOptions)
-
-  if (env !== undefined && typeof env !== "object") {
-    throw new TypeError(`env must be an object, got ${env}`)
-  }
-
-  await assertFilePresence(NODE_CONTROLLABLE_FILE_URL)
+  const execArgv = ExecOptions.toExecArgv({
+    ...childExecOptions,
+    ...ExecOptions.fromExecArgv(commandLineOptions),
+  })
   const envForChildProcess = {
     ...(inheritProcessEnv ? process.env : {}),
     ...env,
   }
+  logger[logProcessCommand ? "info" : "debug"](
+    `${process.argv[0]} ${execArgv.join(" ")} ${urlToFileSystemPath(
+      NODE_CONTROLLABLE_FILE_URL,
+    )}`,
+  )
   const childProcess = fork(urlToFileSystemPath(NODE_CONTROLLABLE_FILE_URL), {
     execArgv,
     // silent: true
     stdio: ["pipe", "pipe", "pipe", "ipc"],
     env: envForChildProcess,
   })
-
   logger.debug(
-    createDetailedMessage(`fork child process pid ${childProcess.pid}`, {
+    createDetailedMessage(`child process forked (pid ${childProcess.pid})`, {
       "execArgv": execArgv.join(`\n`),
       "custom env": JSON.stringify(env, null, "  "),
     }),
   )
-
-  // if we passe stream, pipe them https://github.com/sindresorhus/execa/issues/81
+  // if we pass stream, pipe them https://github.com/sindresorhus/execa/issues/81
   if (typeof stdin === "object") {
     stdin.pipe(childProcess.stdin)
   }
@@ -104,30 +88,49 @@ export const createControllableNodeProcess = async ({
   if (typeof stderr === "object") {
     childProcess.stderr.pipe(stderr)
   }
-  if (logProcessCommand) {
-    console.log(
-      `${process.argv[0]} ${execArgv.join(" ")} ${urlToFileSystemPath(
-        NODE_CONTROLLABLE_FILE_URL,
-      )}`,
-    )
-  }
-
   const childProcessReadyPromise = new Promise((resolve) => {
     onceProcessMessage(childProcess, "ready", resolve)
   })
-
-  const outputCallbackList = createCallbackList()
   const removeOutputListener = installProcessOutputListener(
     childProcess,
     ({ type, text }) => {
-      outputCallbackList.notify({ type, text })
+      onConsole({ type, text })
     },
   )
-
-  const errorCallbackList = createCallbackList()
-
-  const stoppedCallbackList = createCallbackListNotifiedOnce()
-
+  const stop = memoize(async ({ gracefulStopAllocatedMs } = {}) => {
+    // all libraries are facing problem on windows when trying
+    // to kill a process spawning other processes.
+    // "killProcessTree" is theorically correct but sometimes keep process handing forever.
+    // Inside GitHub workflow the whole Virtual machine gets unresponsive and ends up being killed
+    // There is no satisfying solution to this problem so we stick to the basic
+    // childProcess.kill()
+    if (process.platform === "win32") {
+      childProcess.kill()
+      return
+    }
+    if (gracefulStopAllocatedMs) {
+      try {
+        await killProcessTree(childProcess.pid, {
+          signal: GRACEFUL_STOP_SIGNAL,
+          timeout: gracefulStopAllocatedMs,
+        })
+        return
+      } catch (e) {
+        if (e.code === "TIMEOUT") {
+          logger.debug(
+            `kill with SIGTERM because gracefulStop still pending after ${gracefulStopAllocatedMs}ms`,
+          )
+          await killProcessTree(childProcess.pid, {
+            signal: GRACEFUL_STOP_FAILED_SIGNAL,
+          })
+          return
+        }
+        throw e
+      }
+    }
+    await killProcessTree(childProcess.pid, { signal: STOP_SIGNAL })
+    return
+  })
   raceCallbacks(
     {
       // https://nodejs.org/api/child_process.html#child_process_event_disconnect
@@ -157,9 +160,9 @@ export const createControllableNodeProcess = async ({
           ) {
             return
           }
-          errorCallbackList.notify(error)
+          onError(error)
         },
-        exit: ({ code, signal }) => {
+        exit: async ({ code, signal }) => {
           // process.exit(1) in child process or process.exitCode = 1 + process.exit()
           // means there was an error even if we don't know exactly what.
           if (
@@ -169,112 +172,88 @@ export const createControllableNodeProcess = async ({
             code !== SIGTERM_EXIT_CODE &&
             code !== SIGABORT_EXIT_CODE
           ) {
-            errorCallbackList.notify(createExitWithFailureCodeError(code))
+            onError(createExitWithFailureCodeError(code))
           }
-          stoppedCallbackList.notify({ code, signal })
+          await cleanup("process exit")
+          onStop({ code, signal })
         },
       }
       raceEffects[winner.name](winner.data)
     },
   )
-
-  const stop = async ({ gracefulStopAllocatedMs } = {}) => {
-    if (stoppedCallbackList.notified) {
-      return {}
-    }
-
-    const createStoppedPromise = async () => {
-      if (stoppedCallbackList.notified) {
-        return
-      }
-      await new Promise((resolve) => stoppedCallbackList.add(resolve))
-    }
-
-    if (gracefulStopAllocatedMs) {
-      try {
-        await killProcessTree(childProcess.pid, {
-          signal: GRACEFUL_STOP_SIGNAL,
-          timeout: gracefulStopAllocatedMs,
-        })
-        await createStoppedPromise()
-        return { graceful: true }
-      } catch (e) {
-        if (e.code === "TIMEOUT") {
-          logger.debug(
-            `kill with SIGTERM because gracefulStop still pending after ${gracefulStopAllocatedMs}ms`,
-          )
-          await killProcessTree(childProcess.pid, {
-            signal: GRACEFUL_STOP_FAILED_SIGNAL,
-          })
-          await createStoppedPromise()
-          return { graceful: false }
-        }
-        throw e
-      }
-    }
-
-    await killProcessTree(childProcess.pid, { signal: STOP_SIGNAL })
-    await createStoppedPromise()
-    return { graceful: false }
-  }
-
-  const requestActionOnChildProcess = ({
+  const requestActionOnChildProcess = async ({
     signal,
     actionType,
     actionParams,
   }) => {
     const actionOperation = Abort.startOperation()
     actionOperation.addAbortSignal(signal)
-
-    return new Promise(async (resolve, reject) => {
-      actionOperation.throwIfAborted()
-      await childProcessReadyPromise
-
-      onceProcessMessage(childProcess, "action-result", ({ status, value }) => {
-        if (status === "action-completed") {
-          resolve(value)
-        } else {
-          reject(value)
-        }
-      })
-
-      logger.debug(
-        createDetailedMessage(`ask child process to perform an action`, {
-          actionType,
-          actionParams: JSON.stringify(actionParams, null, "  "),
-        }),
-      )
-
-      try {
+    try {
+      const result = await new Promise(async (resolve, reject) => {
         actionOperation.throwIfAborted()
-        await sendToProcess(childProcess, "action", {
-          actionType,
-          actionParams,
-        })
-      } catch (e) {
-        if (Abort.isAbortError(e) && actionOperation.signal.aborted) {
-          throw e
-        }
-        logger.error(
-          createDetailedMessage(`error while sending message to child`, {
-            ["error stack"]: e.stack,
+        await childProcessReadyPromise
+        onceProcessMessage(
+          childProcess,
+          "action-result",
+          ({ status, value }) => {
+            if (status === "action-completed") {
+              resolve(value)
+            } else {
+              reject(value)
+            }
+          },
+        )
+        logger.debug(
+          createDetailedMessage(`ask child process to perform an action`, {
+            actionType,
+            actionParams: JSON.stringify(actionParams, null, "  "),
           }),
         )
-        throw e
-      }
-    })
+        try {
+          actionOperation.throwIfAborted()
+          await sendToProcess(childProcess, "action", {
+            actionType,
+            actionParams,
+          })
+        } catch (e) {
+          if (Abort.isAbortError(e) && actionOperation.signal.aborted) {
+            throw e
+          }
+          logger.error(
+            createDetailedMessage(`error while sending message to child`, {
+              ["error stack"]: e.stack,
+            }),
+          )
+          throw e
+        }
+      })
+      return result
+    } finally {
+      await actionOperation.end()
+    }
   }
-
   return {
     execArgv,
-    stoppedCallbackList,
-    errorCallbackList,
-    outputCallbackList,
     stop,
     requestActionOnChildProcess,
   }
 }
 
+// https://nodejs.org/api/process.html#process_signal_events
+const SIGINT_SIGNAL_NUMBER = 2
+const SIGABORT_SIGNAL_NUMBER = 6
+const SIGTERM_SIGNAL_NUMBER = 15
+const SIGINT_EXIT_CODE = 128 + SIGINT_SIGNAL_NUMBER
+const SIGABORT_EXIT_CODE = 128 + SIGABORT_SIGNAL_NUMBER
+const SIGTERM_EXIT_CODE = 128 + SIGTERM_SIGNAL_NUMBER
+// http://man7.org/linux/man-pages/man7/signal.7.html
+// https:// github.com/nodejs/node/blob/1d9511127c419ec116b3ddf5fc7a59e8f0f1c1e4/lib/internal/child_process.js#L472
+const GRACEFUL_STOP_SIGNAL = "SIGTERM"
+const STOP_SIGNAL = "SIGKILL"
+// it would be more correct if GRACEFUL_STOP_FAILED_SIGNAL was SIGHUP instead of SIGKILL.
+// but I'm not sure and it changes nothing so just use SIGKILL
+const GRACEFUL_STOP_FAILED_SIGNAL = "SIGKILL"
+
 const sendToProcess = async (childProcess, type, data) => {
   const source = uneval(data, { functionAllowed: true })
   return new Promise((resolve, reject) => {
@@ -331,7 +310,6 @@ const onceProcessMessage = (childProcess, type, callback) => {
 
 const onceProcessEvent = (childProcess, type, callback) => {
   childProcess.once(type, callback)
-
   return () => {
     childProcess.removeListener(type, callback)
   }

package/src/execute/runtimes/node/exec_options.js

@@ -0,0 +1,44 @@
+export const ExecOptions = {
+  fromExecArgv: (execArgv) => {
+    const execOptions = {}
+    let i = 0
+    while (i < execArgv.length) {
+      const execArg = execArgv[i]
+      const option = execOptionFromExecArg(execArg)
+      execOptions[option.name] = option.value
+      i++
+    }
+    return execOptions
+  },
+  toExecArgv: (execOptions) => {
+    const execArgv = []
+    Object.keys(execOptions).forEach((optionName) => {
+      const optionValue = execOptions[optionName]
+      if (optionValue === "unset") {
+        return
+      }
+      if (optionValue === "") {
+        execArgv.push(optionName)
+        return
+      }
+      execArgv.push(`${optionName}=${optionValue}`)
+    })
+    return execArgv
+  },
+}
+
+const execOptionFromExecArg = (execArg) => {
+  const equalCharIndex = execArg.indexOf("=")
+  if (equalCharIndex === -1) {
+    return {
+      name: execArg,
+      value: "",
+    }
+  }
+  const name = execArg.slice(0, equalCharIndex)
+  const value = execArg.slice(equalCharIndex + 1)
+  return {
+    name,
+    value,
+  }
+}

package/src/{internal/node_launcher → execute/runtimes/node}/kill_process_tree.js

@@ -1,11 +1,13 @@
-import { require } from "../require.js"
+import { createRequire } from "node:module"
+
+const require = createRequire(import.meta.url)
 
 // see also https://github.com/sindresorhus/execa/issues/96
 export const killProcessTree = async (
   processId,
   { signal, timeout = 2000 },
 ) => {
-  var pidtree = require("pidtree")
+  const pidtree = require("pidtree")
 
   let descendantProcessIds
   try {