feat: allow process to be started using instance_id

to be able to launch multiple instances of npm in the same node_modules
dir.

Refs: #2462

Author: simschla

lib/src/main/java/com/diffplug/spotless/npm/NodeModulesCachingNpmProcessFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 DiffPlug
+ * Copyright 2023-2025 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,6 +18,7 @@
 import java.io.File;
 import java.util.List;
 import java.util.Objects;
+import java.util.UUID;
 
 import javax.annotation.Nonnull;
 
@@ -65,8 +66,8 @@ public NpmProcess createNpmInstallProcess(NodeServerLayout nodeServerLayout, Npm
 	}
 
 	@Override
-	public NpmLongRunningProcess createNpmServeProcess(NodeServerLayout nodeServerLayout, NpmFormatterStepLocations formatterStepLocations) {
-		return StandardNpmProcessFactory.INSTANCE.createNpmServeProcess(nodeServerLayout, formatterStepLocations);
+	public NpmLongRunningProcess createNpmServeProcess(NodeServerLayout nodeServerLayout, NpmFormatterStepLocations formatterStepLocations, UUID nodeServerInstanceId) {
+		return StandardNpmProcessFactory.INSTANCE.createNpmServeProcess(nodeServerLayout, formatterStepLocations, nodeServerInstanceId);
 	}
 
 	private class CachingNmpInstall implements NpmProcess {

lib/src/main/java/com/diffplug/spotless/npm/NodeServeApp.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 DiffPlug
+ * Copyright 2023-2025 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,6 +15,8 @@
  */
 package com.diffplug.spotless.npm;
 
+import java.util.UUID;
+
 import javax.annotation.Nonnull;
 
 import org.slf4j.Logger;
@@ -32,9 +34,9 @@ public NodeServeApp(@Nonnull NodeServerLayout nodeServerLayout, @Nonnull NpmConf
 		super(nodeServerLayout, npmConfig, formatterStepLocations);
 	}
 
-	ProcessRunner.LongRunningProcess startNpmServeProcess() {
+	ProcessRunner.LongRunningProcess startNpmServeProcess(UUID nodeServerInstanceId) {
 		return timedLogger.withInfo("Starting npm based server in {} with {}.", this.nodeServerLayout.nodeModulesDir(), this.npmProcessFactory.describe())
-				.call(() -> npmProcessFactory.createNpmServeProcess(nodeServerLayout, formatterStepLocations).start());
+				.call(() -> npmProcessFactory.createNpmServeProcess(nodeServerLayout, formatterStepLocations, nodeServerInstanceId).start());
 	}
 
 }

lib/src/main/java/com/diffplug/spotless/npm/NpmFormatterStepStateBase.java

@@ -25,6 +25,7 @@
 import java.util.Iterator;
 import java.util.Map;
 import java.util.Map.Entry;
+import java.util.UUID;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 
@@ -112,12 +113,13 @@ protected ServerProcessInfo npmRunServer() throws ServerStartException, IOExcept
 			assertNodeServerDirReady();
 			LongRunningProcess server = null;
 			try {
-				// The npm process will output the randomly selected port of the http server process to 'server.port' file
+				final UUID nodeServerInstanceId = UUID.randomUUID();
+				// The npm process will output the randomly selected port of the http server process to 'server-<id>.port' file
 				// so in order to be safe, remove such a file if it exists before starting.
-				final File serverPortFile = new File(this.nodeServerLayout.nodeModulesDir(), "server.port");
+				final File serverPortFile = new File(this.nodeServerLayout.nodeModulesDir(), String.format("server-%s.port", nodeServerInstanceId));
 				NpmResourceHelper.deleteFileIfExists(serverPortFile);
 				// start the http server in node
-				server = nodeServeApp.startNpmServeProcess();
+				server = nodeServeApp.startNpmServeProcess(nodeServerInstanceId);
 
 				// await the readiness of the http server - wait for at most 60 seconds
 				try {

lib/src/main/java/com/diffplug/spotless/npm/NpmProcessFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 DiffPlug
+ * Copyright 2023-2025 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,6 +15,8 @@
  */
 package com.diffplug.spotless.npm;
 
+import java.util.UUID;
+
 public interface NpmProcessFactory {
 
 	enum OnlinePreferrence {
@@ -33,7 +35,7 @@ public String option() {
 
 	NpmProcess createNpmInstallProcess(NodeServerLayout nodeServerLayout, NpmFormatterStepLocations formatterStepLocations, OnlinePreferrence onlinePreferrence);
 
-	NpmLongRunningProcess createNpmServeProcess(NodeServerLayout nodeServerLayout, NpmFormatterStepLocations formatterStepLocations);
+	NpmLongRunningProcess createNpmServeProcess(NodeServerLayout nodeServerLayout, NpmFormatterStepLocations formatterStepLocations, UUID nodeServerInstanceId);
 
 	default String describe() {
 		return getClass().getSimpleName();

lib/src/main/java/com/diffplug/spotless/npm/StandardNpmProcessFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 DiffPlug
+ * Copyright 2023-2025 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,6 +19,7 @@
 import java.io.IOException;
 import java.util.List;
 import java.util.Map;
+import java.util.UUID;
 import java.util.concurrent.ExecutionException;
 
 import com.diffplug.spotless.ProcessRunner;
@@ -37,8 +38,8 @@ public NpmProcess createNpmInstallProcess(NodeServerLayout nodeServerLayout, Npm
 	}
 
 	@Override
-	public NpmLongRunningProcess createNpmServeProcess(NodeServerLayout nodeServerLayout, NpmFormatterStepLocations formatterStepLocations) {
-		return new NpmServe(nodeServerLayout.nodeModulesDir(), formatterStepLocations);
+	public NpmLongRunningProcess createNpmServeProcess(NodeServerLayout nodeServerLayout, NpmFormatterStepLocations formatterStepLocations, UUID nodeServerInstanceId) {
+		return new NpmServe(nodeServerLayout.nodeModulesDir(), formatterStepLocations, nodeServerInstanceId);
 	}
 
 	private static abstract class AbstractStandardNpmProcess {
@@ -119,16 +120,21 @@ public ProcessRunner.Result waitFor() {
 
 	private static class NpmServe extends AbstractStandardNpmProcess implements NpmLongRunningProcess {
 
-		public NpmServe(File workingDir, NpmFormatterStepLocations formatterStepLocations) {
+		private final UUID nodeServerInstanceId;
+
+		public NpmServe(File workingDir, NpmFormatterStepLocations formatterStepLocations, UUID nodeServerInstanceId) {
 			super(workingDir, formatterStepLocations);
+			this.nodeServerInstanceId = nodeServerInstanceId;
 		}
 
 		@Override
 		protected List<String> commandLine() {
 			return List.of(
 					npmExecutable(),
 					"start",
-					"--scripts-prepend-node-path=true");
+					"--scripts-prepend-node-path=true",
+					"--",
+					"--node-server-instance-id=" + nodeServerInstanceId);
 		}
 
 		@Override

lib/src/main/resources/com/diffplug/spotless/npm/common-serve.js

@@ -4,7 +4,7 @@ const GracefulShutdownManager = require("@moebius/http-graceful-shutdown").Grace
 const express = require("express");
 const app = express();
 
-app.use(express.json({ limit: "50mb" }));
+app.use(express.json({limit: "50mb"}));
 
 const fs = require("fs");
 
@@ -14,13 +14,33 @@ function debugLog() {
 	}
 }
 
+function getInstanceId() {
+	const args = process.argv.slice(2);
+
+	// Look for the --node-server-instance-id option
+	let instanceId;
+
+	args.forEach(arg => {
+		if (arg.startsWith('--node-server-instance-id=')) {
+			instanceId = arg.split('=')[1];
+		}
+	});
+
+	// throw if instanceId is not set
+	if (!instanceId) {
+		throw new Error("Missing --node-server-instance-id argument");
+	}
+	return instanceId;
+}
+
 var listener = app.listen(0, "127.0.0.1", () => {
-	debugLog("Server running on port " + listener.address().port);
-	fs.writeFile("server.port.tmp", "" + listener.address().port, function(err) {
+	const instanceId = getInstanceId();
+	debugLog("Server running on port " + listener.address().port + " for instance " + instanceId);
+	fs.writeFile("server.port.tmp", "" + listener.address().port, function (err) {
 		if (err) {
 			return console.log(err);
 		} else {
-			fs.rename("server.port.tmp", "server.port", function(err) {
+			fs.rename("server.port.tmp", `server-${instanceId}.port`, function (err) {
 				if (err) {
 					return console.log(err);
 				}
@@ -32,7 +52,7 @@ const shutdownManager = new GracefulShutdownManager(listener);
 
 app.post("/shutdown", (req, res) => {
 	res.status(200).send("Shutting down");
-	setTimeout(function() {
+	setTimeout(function () {
 		shutdownManager.terminate(() => debugLog("graceful shutdown finished."));
 	}, 200);
 });