Add timeout (#147)

* Add runOptions.timeout

This commit adds new `runOptions.timeout` and `runOptions.killSignal`
options that allow a process to be killed after a specified number of
milliseconds have elapsed. See the [Node ChildProcess docs](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options).

This commit includes several additional changes that were necessary as
part of the implementation of `timeout`:

* Fix to `JavaCallerTester.java` that replaces an `==` string comparison
with a `args[0].equals("--sleep")`. This fixes the `sleep` command line
argument, which previously never triggered because the comparison
was always false.
* Recompile `JavaCallerTester.class` and `JavaCallerTester.jar`
* Fixed `should call JavaCallerTester.class detached` test. This began
failing after the call fix for `--sleep`. The test has been rewritten to
demonstrate the expected behavior for `detached`. Now, the test will
check that the Java process is initially still running and then check
the return status code once it exits.
* Update the NPM script `java:compile` to use `--release 8` instead of
`-source 8 -target 1.8`. This fixes an error that occurred when running
the previous script:

>warning: [options] bootstrap class path is not set in conjunction with -source 8
  not setting the bootstrap class path may lead to class files that cannot run on JDK 8
    --release 8 is recommended instead of -source 8 -target 1.8 because it sets the bootstrap class path automatically

See [this StackOverflow post](https://stackoverflow.com/a/61715683) for
more details.

Note that a warning is still generated:

>warning: [options] target value 8 is obsolete and will be removed in a future release
warning: [options] To suppress warnings about obsolete options, use -Xlint:-options.

Fixes #144

* Add to changelog

* Add timeout options to JavaCallerRunOptions type

* Remove null check for code when checking for timeout

This commit removes the check for `exitCode === null`, which will only
be the case on Windows. On Linux, the `exitCode` will be populated.

The [Node docs](https://nodejs.org/api/child_process.html#event-exit), say:

>The exit code if the child process exited on its own, or null if the child process terminated due to a signal.
>The 'exit' event is emitted after the child process ends. If the process exited, code is the final exit code of the process, otherwise null.

* Fix killSignal default in TypeScript docs

* Remove no-undef ESLint check for *.ts files

As recommended in the [TypeScript ESLint docs](https://typescript-eslint.io/troubleshooting/faqs/eslint#i-get-errors-from-the-no-undef-rule-about-global-variables-not-being-defined-even-though-there-are-no-typescript-errors),
the `no-undef` rule should not be used for `*.ts` files because it
gives false positives. This causes issues with using `NodeJS.Signals`
in `index.d.ts`.

* Add temporary logging

* Handle cross-platform timeout

* unify timeout codes

* Simplify timeout logic

This commit simplifies the timeout logic by no longer passing `timeout`
to `spawn`. Instead, the full timeout logic is handled by `run`, which
sets a timeout and determines whether the process was killed. Now that
there is no duplicate logic, `wasKilledByTimeout` can be removed
in favor of checking `killedByTimeout` directly.

* Remove unused variable

---------

Co-authored-by: Nicolas Vuillamy <nicolas.vuillamy@gmail.com>

Author: BrendanC23

.eslintrc.js

@@ -34,7 +34,8 @@ module.exports = {
       files: ["**/*.d.ts"],
       parser: "@typescript-eslint/parser",
       rules: {
-        "getter-return": "off"
+        "getter-return": "off",
+        "no-undef": "off"
       }
     }
   ],

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Add `timeout` and `killSignal` run options
+
 ## [4.3.3] 2025-02-03
 
 - Add types definition to make library compliant with typescript usage

README.md

@@ -65,13 +65,15 @@ Example: `["-Xms256m", "--someflagwithvalue myVal", "-c"]`
 
 | Parameter | Description | Default | Example |
 |-----------|-------------|---------|---------|
-| [detached](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | If set to true, node will node wait for the java command to be completed.<br/>In that case, `childJavaProcess` property will be returned, but `stdout` and `stderr` may be empty, except if an error is triggered at command execution | `false` | `true`
+| [detached](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | If set to true, node will not wait for the java command to be completed.<br/>In that case, `childJavaProcess` property will be returned, but `stdout` and `stderr` may be empty, except if an error is triggered at command execution | `false` | `true`
 | [stdoutEncoding](https://nodejs.org/api/stream.html#readablesetencodingencoding) | Adds control on spawn process stdout | `utf8` | `ucs2` |
 | waitForErrorMs | If detached is true, number of milliseconds to wait to detect an error before exiting JavaCaller run   | `500` | `2000` |
 | [cwd](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | You can override cwd of spawn called by JavaCaller runner | `process.cwd()` | `some/other/cwd/folder` |
 | javaArgs | List of arguments for JVM only, not the JAR or the class | `[]` | `['--add-opens=java.base/java.lang=ALL-UNNAMED']` |
 | [windowsVerbatimArguments](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | No quoting or escaping of arguments is done on Windows. Ignored on Unix. This is set to true automatically when shell is specified and is CMD. | `true` | `false` |
 | [windowless](https://docs.oracle.com/en/java/javase/17/docs/specs/man/java.html#:~:text=main()%20method.-,javaw,information%20if%20a%20launch%20fails.) | If windowless is true, JavaCaller calls javaw instead of java to not create any windows, useful when using detached on Windows. Ignored on Unix. | false | true
+| [timeout](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | In milliseconds the maximum amount of time the process is allowed to run. | `undefined` | `1000`
+| [killSignal](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | The signal value to be used when the spawned process will be killed by timeout or abort signal. | `SIGTERM` | `SIGINT`
 
 ## Examples
 

lib/index.d.ts

@@ -117,6 +117,20 @@ export interface JavaCallerRunOptions {
      * @default false
      */
     windowless?: boolean;
+
+    /**
+     * The number of milliseconds to wait before the Java process will time out. When this occurs,
+     * killSignal will ben
+     * @default undefined
+     */
+    timeout?: number;
+
+    /**
+     * If windowless is true, JavaCaller calls javaw instead of java to not create any windows,
+     * useful when using detached on Windows. Ignored on Unix.
+     * @default "SIGTERM"
+     */
+    killSignal?: number | NodeJS.Signals;
 }
 
 /**

lib/java-caller.js

@@ -69,12 +69,14 @@ class JavaCaller {
      * Runs java command of a JavaCaller instance
      * @param {string[]} [userArguments] - Java command line arguments
      * @param {object} [runOptions] - Run options
-     * @param {boolean} [runOptions.detached = false] - If set to true, node will node wait for the java command to be completed. In that case, childJavaProcess property will be returned, but stdout and stderr may be empty
+     * @param {boolean} [runOptions.detached = false] - If set to true, node will not wait for the java command to be completed. In that case, childJavaProcess property will be returned, but stdout and stderr may be empty
      * @param {string} [runOptions.stdoutEncoding = 'utf8'] - Adds control on spawn process stdout
      * @param {number} [runOptions.waitForErrorMs = 500] - If detached is true, number of milliseconds to wait to detect an error before exiting JavaCaller run
      * @param {string} [runOptions.cwd = .] - You can override cwd of spawn called by JavaCaller runner
      * @param {string} [runOptions.javaArgs = []] - You can override cwd of spawn called by JavaCaller runner
      * @param {string} [runOptions.windowsVerbatimArguments = true] - No quoting or escaping of arguments is done on Windows. Ignored on Unix. This is set to true automatically when shell is specified and is CMD.
+     * @param {number} [runOptions.timeout] - In milliseconds the maximum amount of time the process is allowed to run
+     * @param {NodeJS.Signals | number} [runOptions.killSignal = "SIGTERM"] - The signal value to be used when the spawned process will be killed by timeout or abort signal.
      * @return {Promise<{status:number, stdout:string, stderr:string, childJavaProcess:ChildProcess}>} - Command result (status, stdout, stderr, childJavaProcess)
      */
     async run(userArguments, runOptions = {}) {
@@ -84,6 +86,7 @@ class JavaCaller {
         runOptions.stdoutEncoding = typeof runOptions.stdoutEncoding === "undefined" ? "utf8" : runOptions.stdoutEncoding;
         runOptions.windowsVerbatimArguments = typeof runOptions.windowsVerbatimArguments === "undefined" ? true : runOptions.windowsVerbatimArguments;
         runOptions.windowless = typeof runOptions.windowless === "undefined" ? false : os.platform() !== "win32" ? false : runOptions.windowless;
+        runOptions.killSignal = typeof runOptions.killSignal === "undefined" ? "SIGTERM" : runOptions.killSignal;
         this.commandJavaArgs = (runOptions.javaArgs || []).concat(this.additionalJavaArgs);
 
         let javaExe = runOptions.windowless ? this.javaExecutableWindowless : this.javaExecutable;
@@ -97,10 +100,13 @@ class JavaCaller {
 
         const javaExeToUse = this.javaExecutableFromNodeJavaCaller ?? javaExe;
         const classPathStr = this.buildClasspathStr();
-        const javaArgs = this.buildArguments(classPathStr, (userArguments || []).concat(this.commandJavaArgs));
+        const javaArgs = this.buildArguments(classPathStr, (userArguments || []).concat(this.commandJavaArgs), runOptions.windowsVerbatimArguments);
         let stdout = "";
         let stderr = "";
         let child;
+        let timeoutId;
+        let killedByTimeout = false;
+
         const prom = new Promise((resolve) => {
             // Spawn java command line
             debug(`Java command: ${javaExeToUse} ${javaArgs.join(" ")}`);
@@ -117,6 +123,19 @@ class JavaCaller {
             }
             child = spawn(javaExeToUse, javaArgs, spawnOptions);
 
+            if (runOptions.timeout) {
+                timeoutId = setTimeout(() => {
+                    if (!child.killed) {
+                        try {
+                            child.kill(runOptions.killSignal);
+                            killedByTimeout = true;
+                        } catch (err) {
+                            stderr += `Failed to kill process after ${runOptions.timeout}ms: ${err.message}`;
+                        }
+                    }
+                }, runOptions.timeout);
+            }
+
             // Gather stdout and stderr if they must be returned
             if (spawnOptions.stdio === "pipe") {
                 child.stdout.setEncoding(`${runOptions.stdoutEncoding}`);
@@ -132,12 +151,28 @@ class JavaCaller {
             child.on("error", (data) => {
                 this.status = 666;
                 stderr += "Java spawn error: " + data;
+
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+
                 resolve();
             });
 
             // Catch status code
             child.on("close", (code) => {
-                this.status = code;
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+
+                if (killedByTimeout) {
+                    // Process was terminated because of the timeout
+                    this.status = 666;
+                    stderr += `Process timed out with ${runOptions.killSignal} after ${runOptions.timeout}ms.`;
+                } else {
+                    this.status = code;
+                }
+
                 resolve();
             });
 

package.json

@@ -9,7 +9,7 @@
   ],
   "scripts": {
     "lint:fix": "eslint **/*.js --fix && prettier --write \"./lib/**/*.{js,jsx,json}\" --tab-width 4 --print-width 150",
-    "java:compile": "javac -d test/java/dist -source 8 -target 1.8 test/java/src/com/nvuillam/javacaller/JavaCallerTester.java",
+    "java:compile": "javac -d test/java/dist --release 8 test/java/src/com/nvuillam/javacaller/JavaCallerTester.java",
     "java:jar": "cd test/java/dist && jar -cvfm ./../jar/JavaCallerTester.jar ./../jar/manifest/Manifest.txt com/nvuillam/javacaller/*.class && jar -cvfm ./../jar/JavaCallerTesterRunnable.jar ./../jar/manifest-runnable/Manifest.txt com/nvuillam/javacaller/*.class",
     "test": "mocha \"test/**/*.test.js\"",
     "test:coverage": "nyc npm run test",
@@ -78,4 +78,4 @@
     ],
     "all": true
   }
-}
+}

test/java-caller.test.js

@@ -32,9 +32,21 @@ describe("Call with classes", () => {
             classPath: 'test/java/dist',
             mainClass: 'com.nvuillam.javacaller.JavaCallerTester'
         });
+
+        // JavaCallerTester will sleep for 1000 ms
+        // After waitForErrorMs (500 ms), the promise will return
         const { status, stdout, stderr, childJavaProcess } = await java.run(['--sleep'], { detached: true });
-        childJavaProcess.kill('SIGINT');
-        checkStatus(0, status, stdout, stderr);
+
+        // Java process is still running
+        checkStatus(null, status, stdout, stderr);
+
+        return new Promise(resolve => {
+            // Java process has finished executing and the exit code can be read
+            childJavaProcess.on('exit', () => {
+                checkStatus(0, childJavaProcess.exitCode, stdout, stderr);
+                resolve();
+            });
+        });
     });
 
     it("should call JavaCallerTester.class using javaw", async () => {
@@ -187,4 +199,38 @@ describe("Call with classes", () => {
         checkStatus(0, status, stdout, stderr);
         checkStdOutIncludes(`JavaCallerTester is called !`, stdout, stderr);
     });
+
+    it("should terminate once timeout is reached", async () => {
+        const java = new JavaCaller({
+            classPath: 'test/java/dist',
+            mainClass: 'com.nvuillam.javacaller.JavaCallerTester'
+        });
+        const { status, stdout, stderr } = await java.run(["--sleep"], { timeout: 500 });
+
+        checkStatus(666, status, stdout, stderr);
+        checkStdErrIncludes(`timed out`, stdout, stderr);
+    });
+
+    it("should not terminate if process finished before timeout is reached", async () => {
+        const java = new JavaCaller({
+            classPath: 'test/java/dist',
+            mainClass: 'com.nvuillam.javacaller.JavaCallerTester'
+        });
+        const { status, stdout, stderr } = await java.run(["--sleep"], { timeout: 1500 });
+
+        checkStatus(0, status, stdout, stderr);
+        checkStdOutIncludes(`JavaCallerTester is called !`, stdout, stderr);
+    });
+
+    it("should terminate with custom killSignal when timeout is reached", async () => {
+        const java = new JavaCaller({
+            classPath: 'test/java/dist',
+            mainClass: 'com.nvuillam.javacaller.JavaCallerTester'
+        });
+        const { status, stdout, stderr } = await java.run(["--sleep"], { timeout: 500, killSignal: "SIGINT" });
+
+        checkStatus(666, status, stdout, stderr);
+        checkStdErrIncludes(`timed out`, stdout, stderr);
+        checkStdErrIncludes(`SIGINT`, stdout, stderr);
+    });
 });