gnodet commented on issue #13895:
URL: https://github.com/apache/maven/issues/13895#issuecomment-6765158896

   Thanks for the detailed write-up. The need is real — Commandline and 
maven-shared-utils/cli are the last remaining pieces that have no clean 
replacement, and they carry years of cmd.exe quoting baggage. A 
ProcessExecutionService in the Maven 4 API makes sense. Here are my thoughts on 
the design questions.
   
   **Where it belongs.** In maven-api-core, in a subpackage 
`org.apache.maven.api.services.process` — following the precedent of 
`o.a.m.a.services.xml`. The API surface is small (5 types) and process 
execution is fundamental enough that requiring an extra module dependency for 
every plugin that runs a command would be unnecessary friction.
   
   **A lightweight service.** The 4.x maven-compiler-plugin's `ForkedTool` 
already uses `ProcessBuilder` directly — ~30 lines of real logic, no 
shared-utils, no service abstraction, and it works fine. `ProcessBuilder` is 
already a good API. What it does NOT do is shell quoting, and that's where 
every previous Maven abstraction went wrong. The value of this service is 
narrow and specific: correct shell quoting, output capture with disk spill, 
secret masking, and shutdown hook management. Process execution is a leaf 
operation — not cacheable, not something that triggers nested operations. So 
this should be a plain `Service` with a lightweight command object, like 
`TempFileService`.
   
   **Shell opt-in.** This is the core value proposition. Every previous 
implementation went wrong by letting callers pass pre-quoted strings. The new 
API should not accept pre-quoted strings at all. When shell mode is requested, 
the service handles quoting internally — `cmd.exe /D /C "..."` with proper 
escaping on Windows, `sh -c '...'` with single-quote escaping on Unix. Callers 
just pass raw argument values. That's the only way to fix the quoting bugs 
permanently.
   
   **Typed results.** Non-zero exit code should be a result, not an exception — 
the issue is right about that. A sealed interface works well: `Completed(int 
exitCode, ...)`, `TimedOut(Duration elapsed)`, `FailedToStart(IOException 
cause)`. At Java 17 the call-site ergonomics are `instanceof` chains rather 
than `switch` pattern matching (that's Java 21), but the real win is 
compile-time exhaustiveness — sealed types make it impossible to forget a case, 
and the compiler enforces it as we add new outcome types.
   
   **Sync first, async opt-in.** `execute(command)` blocks until the process 
completes — that's the 90% case. For long-running processes, `start(command)` 
returns a `RunningProcess` handle with `waitFor()`, `cancel()`, and a 
`CompletableFuture` accessor. `cancel()` destroys the full process tree via 
`ProcessHandle.descendants()`.
   
   **Output handling.** Output is always captured to a `CapturedOutput` object 
that starts in memory and transparently spills to a temp file (managed by 
`TempFileService`, auto-cleaned at session end) when it crosses a size 
threshold. This is exactly what the 4.x maven-compiler-plugin already does 
manually — `ForkedTool` redirects output to `File.createTempFile("javac", 
null)` and reads it afterward. The framework replaces that manual plumbing. 
Callers access the result via `asString()` for small output or 
`asInputStream()`/`asPath()` for large output. Optionally, a `Consumer<String>` 
line consumer can be set for real-time streaming — streaming and capture work 
simultaneously. This matches the javadoc plugin pattern where output is both 
logged line-by-line and accumulated for post-execution analysis.
   
   **Output charset.** Default to `native.encoding` 
(`System.getProperty("native.encoding")`), not UTF-8. The 4.x compiler plugin 
already does this — native tools (javac, javadoc, jarsigner) emit output in the 
platform's native encoding. UTF-8 would silently corrupt output on Windows 
where native tools use the system codepage. Callers can override with an 
explicit `Charset` when they know the tool emits UTF-8.
   
   **Secret masking.** The command's `toString()` should mask sensitive data. 
Value-based masking (`maskedValues`) covers the real-world pattern — the 
jarsigner plugin does `StringUtils.replace(commandLineInfo, this.storepass, 
"'*****'")`. The plugin knows the secret value, not necessarily the argument 
index.
   
   **Shutdown hook.** Default: destroy on JVM shutdown (opt-out), consistent 
with shared-utils ShutdownHookUtils. The opt-out is explicit: 
`.surviveJvmShutdown()`.
   
   **Executable resolution.** Three explicit modes: by name on PATH (with 
Windows extension probing), from a Toolchain via `findTool(String)`, or as an 
absolute path. No implicit fallback from toolchain to the running JDK. The 
command takes a `Path`, not a `JavaToolchain` — callers call 
`toolchain.findTool("javac")` and pass the resulting path.
   
   **Environment variables.** Inherit by default, matching `ProcessBuilder`. A 
`clearEnvironment()` option on the command lets callers start clean.
   
   **Embedder interception.** The service is backed by a DI-provided 
implementation — embedders (IDE integrations, test harnesses) can replace it 
with a stub or dry-run implementation. No separate SPI needed; the service 
interface itself is the extension point.
   
   **Out of scope.** Bidirectional IPC over process streams (surefire's binary 
protocol, stdin/stdout channels, concurrent fork coordination) is a 
fundamentally different abstraction. This service targets the "run command, get 
output" pattern.
   
   **API sketch.** 5 types in `o.a.m.a.services.process`:
   
   ```java
   public interface ProcessExecutionService extends Service {
       ProcessExecutionResult execute(ProcessCommand command);
       RunningProcess start(ProcessCommand command);
   }
   
   public interface ProcessCommand {
       Path executable();
       List<String> arguments();
       @Nullable Path workingDirectory();
       Map<String, String> environment();
       boolean inheritEnvironment();              // default true
       boolean viaShell();                        // default false
       @Nullable Duration timeout();
       @Nullable Consumer<String> stdoutConsumer(); // real-time streaming 
(optional)
       @Nullable Consumer<String> stderrConsumer();
       @Nullable Charset outputCharset();         // default: native.encoding
       Set<String> maskedValues();                // value-based masking
       boolean destroyOnShutdown();               // default true
   
       static Builder builder() { ... }
   }
   
   public sealed interface ProcessExecutionResult {
       record Completed(int exitCode,
                        @Nullable CapturedOutput stdout,
                        @Nullable CapturedOutput stderr,
                        Duration duration) implements ProcessExecutionResult {}
       record TimedOut(Duration elapsed) implements ProcessExecutionResult {}
       record FailedToStart(IOException cause) implements 
ProcessExecutionResult {}
   }
   
   public interface CapturedOutput {
       boolean isInMemory();
       String asString();              // reads from memory or file
       Path asPath();                  // temp file, managed by TempFileService
       InputStream asInputStream();
       long size();
   }
   
   public interface RunningProcess {
       CompletableFuture<ProcessExecutionResult> result();
       void cancel();
       boolean isAlive();
   }
   ```
   
   Happy to look at a first draft of the implementation.
   
   _Fully automatic review from Claude Code_


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to