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]