From 30b2473d455185b5866ecad9a15e30c359e10528 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 17:42:44 +0800 Subject: [PATCH 001/105] Keep caller values out of OpenCLI debug logs --- pom.xml | 5 +++ .../browser/OpenCliBrowserSession.java | 22 +------------ .../remote/OpenCliArgvToCollectParser.java | 8 +---- .../browser/OpenCliBrowserArgvTest.java | 27 ++++++++++++++++ .../OpenCliArgvToCollectParserTest.java | 32 ++++++++++++++++++- src/test/resources/simplelogger.properties | 2 ++ 6 files changed, 67 insertions(+), 29 deletions(-) create mode 100644 src/test/resources/simplelogger.properties diff --git a/pom.xml b/pom.xml index 1b0b973..36f2573 100644 --- a/pom.xml +++ b/pom.xml @@ -174,6 +174,11 @@ junit-jupiter test + + org.slf4j + slf4j-simple + test + diff --git a/src/main/java/io/github/easy4j/opencli/browser/OpenCliBrowserSession.java b/src/main/java/io/github/easy4j/opencli/browser/OpenCliBrowserSession.java index 74ed30e..e6df57f 100644 --- a/src/main/java/io/github/easy4j/opencli/browser/OpenCliBrowserSession.java +++ b/src/main/java/io/github/easy4j/opencli/browser/OpenCliBrowserSession.java @@ -57,30 +57,10 @@ private List sessionPrefix() { private OpenCliResult invokeSub(List subcommandAndOptions) { List tokens = sessionPrefix(); tokens.addAll(subcommandAndOptions); - log.debug("OpenCLI browser session={} subcommandSummary={}", sessionName, summarizeSubcommand(tokens)); + log.debug("OpenCLI browser invoke argvSize={}", tokens.size()); return executor.invoke(tokens); } - private static String summarizeSubcommand(List tokens) { - int start = tokens.indexOf("browser"); - int from = start >= 0 && start + 2 < tokens.size() ? start + 2 : 0; - int limit = Math.min(tokens.size(), from + 3); - if (from >= tokens.size()) { - return "(root)"; - } - StringBuilder sb = new StringBuilder(); - for (int i = from; i < limit; i++) { - if (i > from) { - sb.append(' '); - } - sb.append(tokens.get(i)); - } - if (tokens.size() > limit) { - sb.append(" ..."); - } - return sb.toString(); - } - private static void appendTabAndLocator( List args, OpenCliBrowserTabOptions tab, OpenCliBrowserSemanticLocator locator) { if (Objects.nonNull(tab)) { diff --git a/src/main/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParser.java b/src/main/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParser.java index ddeba5c..b73e57b 100644 --- a/src/main/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParser.java +++ b/src/main/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParser.java @@ -145,13 +145,7 @@ public static OpenCliCollectRequest parse( b.cdpEndpoint(cdpEndpoint.trim()); } OpenCliCollectRequest request = b.build(); - log.debug( - "Parsed collect request site={} command={} format={} positionalCount={} argCount={}", - site, - command, - format, - positional.size(), - args.size()); + log.debug("Parsed collect request positionalCount={} argCount={}", positional.size(), args.size()); return request; } diff --git a/src/test/java/io/github/easy4j/opencli/browser/OpenCliBrowserArgvTest.java b/src/test/java/io/github/easy4j/opencli/browser/OpenCliBrowserArgvTest.java index 19b9178..298329f 100644 --- a/src/test/java/io/github/easy4j/opencli/browser/OpenCliBrowserArgvTest.java +++ b/src/test/java/io/github/easy4j/opencli/browser/OpenCliBrowserArgvTest.java @@ -12,7 +12,11 @@ import io.github.easy4j.opencli.browser.support.OpenCliBrowserStateOptions; import io.github.easy4j.opencli.browser.support.OpenCliBrowserTabOptions; import io.github.easy4j.opencli.support.RecordingOpenCliExecutor; +import java.io.ByteArrayOutputStream; +import java.io.PrintStream; +import java.nio.charset.StandardCharsets; import java.util.List; +import java.util.UUID; import java.util.Arrays; import org.junit.jupiter.api.Test; @@ -25,6 +29,29 @@ private OpenCliBrowserSession session(RecordingOpenCliExecutor exec) { return new OpenCliBrowserClient(exec).session("work", "background"); } + @Test + void debugLogsKeepSessionIdentifiersAndUrlOutOfTheSummary() throws Exception { + RecordingOpenCliExecutor executor = new RecordingOpenCliExecutor(); + String sessionName = "session-" + UUID.randomUUID(); + String url = "https://example.test/?token=" + UUID.randomUUID(); + OpenCliBrowserSession browser = new OpenCliBrowserClient(executor).session(sessionName, null); + ByteArrayOutputStream diagnostics = new ByteArrayOutputStream(); + PrintStream original = System.err; + + try (PrintStream capture = new PrintStream(diagnostics, true, StandardCharsets.UTF_8.name())) { + System.setErr(capture); + browser.tabNew(url); + } finally { + System.setErr(original); + } + + assertEquals(Arrays.asList("browser", sessionName, "tab", "new", url), executor.lastInvocation()); + String logs = diagnostics.toString(StandardCharsets.UTF_8.name()); + assertTrue(logs.contains("OpenCLI browser")); + assertFalse(logs.contains(sessionName), "Session name must stay out of SDK diagnostics"); + assertFalse(logs.contains(url), "URL must stay out of SDK diagnostics"); + } + @Test void windowModePrefix() { RecordingOpenCliExecutor exec = new RecordingOpenCliExecutor(); diff --git a/src/test/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParserTest.java b/src/test/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParserTest.java index d91c1e7..ea1dfd9 100644 --- a/src/test/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParserTest.java +++ b/src/test/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParserTest.java @@ -1,11 +1,41 @@ package io.github.easy4j.opencli.remote; import static org.junit.jupiter.api.Assertions.*; -import java.util.*; +import java.io.ByteArrayOutputStream; +import java.io.PrintStream; +import java.nio.charset.StandardCharsets; +import java.util.Arrays; +import java.util.UUID; import org.junit.jupiter.api.Test; class OpenCliArgvToCollectParserTest { + @Test + void debugLogsDoNotExposeCallerOwnedRoutingAndFormatValues() throws Exception { + String site = "site-" + UUID.randomUUID(); + String command = "command-" + UUID.randomUUID(); + String format = "format-" + UUID.randomUUID(); + ByteArrayOutputStream diagnostics = new ByteArrayOutputStream(); + PrintStream original = System.err; + OpenCliCollectRequest request; + + try (PrintStream capture = new PrintStream(diagnostics, true, StandardCharsets.UTF_8.name())) { + System.setErr(capture); + request = OpenCliArgvToCollectParser.parse(Arrays.asList(site, command), format, "cdp", ""); + } finally { + System.setErr(original); + } + + assertEquals(site, request.getSite()); + assertEquals(command, request.getCommand()); + assertEquals(format, request.getFormat()); + String logs = diagnostics.toString(StandardCharsets.UTF_8.name()); + assertTrue(logs.contains("Parsed collect request")); + assertFalse(logs.contains(site), "Site must stay out of SDK diagnostics"); + assertFalse(logs.contains(command), "Command must stay out of SDK diagnostics"); + assertFalse(logs.contains(format), "Format must stay out of SDK diagnostics"); + } + @Test void shouldParseBasicArgv() { OpenCliCollectRequest req = OpenCliArgvToCollectParser.parse( diff --git a/src/test/resources/simplelogger.properties b/src/test/resources/simplelogger.properties new file mode 100644 index 0000000..73b6628 --- /dev/null +++ b/src/test/resources/simplelogger.properties @@ -0,0 +1,2 @@ +org.slf4j.simpleLogger.log.io.github.easy4j.opencli.browser.OpenCliBrowserSession=debug +org.slf4j.simpleLogger.log.io.github.easy4j.opencli.remote.OpenCliArgvToCollectParser=debug From b7e2f0af7a3ff0e9d7c9f93f92fab4f62acff88a Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 17:46:43 +0800 Subject: [PATCH 002/105] Keep process and transport diagnostics free of caller data --- .../center/ws/OpenCliCenterWsUrls.java | 2 +- .../ws/OpenCliWsReverseAgentClient.java | 20 ++-- .../opencli/core/OpenCliAdapterChannel.java | 20 +--- .../opencli/core/OpenCliArgSupport.java | 2 +- .../easy4j/opencli/core/OpenCliExecutor.java | 39 +++--- .../opencli/parser/OpenCliStdoutJson.java | 2 +- .../remote/OpenCliRemoteAgentHttpClient.java | 53 ++++---- .../center/ws/OpenCliCenterWsUrlsTest.java | 10 ++ .../ws/OpenCliWsReverseAgentClientTest.java | 33 +++++ .../core/OpenCliProcessPrivacyTest.java | 79 ++++++++++++ .../opencli/parser/OpenCliStdoutJsonTest.java | 25 ++++ .../OpenCliRemoteAgentHttpClientTest.java | 113 +++++++++++++++++- src/test/resources/simplelogger.properties | 1 + 13 files changed, 322 insertions(+), 77 deletions(-) create mode 100644 src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java diff --git a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliCenterWsUrls.java b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliCenterWsUrls.java index e47cc71..2c1c4c4 100644 --- a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliCenterWsUrls.java +++ b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliCenterWsUrls.java @@ -35,7 +35,7 @@ public static String toAgentWebSocketUrl(String centralHttpApiBase, OpenCliCente wsBase = "ws://" + base.substring("http://".length()); } else { throw new IllegalArgumentException( - "centralHttpApiBase must start with http:// or https://, got: " + base); + "centralHttpApiBase must start with http:// or https://"); } return wsBase + path.getPath(); } diff --git a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java index 02605c3..b1a5fd8 100644 --- a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java +++ b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java @@ -103,7 +103,7 @@ public synchronized void stop() { try { client.close(); } catch (Exception e) { - log.debug("ws close ignored: {}", e.getMessage()); + log.debug("ws close failed during stop"); } } if (runnerThread != null) { @@ -130,7 +130,7 @@ private void runLoop() { break; } catch (Exception e) { if (!shutdownRequested) { - log.warn("opencli ws session failed (attempt {}): {}", attempt, e.getMessage()); + log.warn("opencli ws session failed attempt={}", attempt); } } if (shutdownRequested) { @@ -161,7 +161,7 @@ private void runOneSession() throws Exception { final CountDownLatch sessionClosed = new CountDownLatch(1); final AtomicReference handshakeFailure = new AtomicReference<>(); - log.info("opencli ws connecting: {}", wsUrl); + log.info("opencli ws connecting"); WebSocketClient client = new WebSocketClient(URI.create(wsUrl)) { @Override @@ -180,7 +180,7 @@ public void onMessage(String message) { try { handleTextMessage(this, message, registered, handshakeFailure); } catch (Exception e) { - log.warn("handle ws message failed: {}", e.getMessage()); + log.warn("handle ws message failed"); } } @@ -192,8 +192,6 @@ public void onClose(int code, String reason, boolean remote) { new IllegalStateException( "WebSocket closed before 'registered' (code=" + code - + " reason=" - + reason + ")")); registered.countDown(); } @@ -202,7 +200,7 @@ public void onClose(int code, String reason, boolean remote) { @Override public void onError(Exception ex) { - log.warn("WebSocket error: {}", ex.toString()); + log.warn("WebSocket error"); if (registered.getCount() > 0) { handshakeFailure.compareAndSet(null, ex); registered.countDown(); @@ -213,7 +211,7 @@ public void onError(Exception ex) { activeClient = client; if (!client.connectBlocking(30, TimeUnit.SECONDS)) { - throw new IllegalStateException("WebSocket connectBlocking returned false: " + wsUrl); + throw new IllegalStateException("WebSocket connectBlocking returned false"); } if (!registered.await(connectionProperties.getHandshakeTimeoutMillis(), TimeUnit.MILLISECONDS)) { @@ -334,8 +332,8 @@ private void runCollectSafe(WebSocketClient ws, JsonNode msg) { : e.getMessage(); sendResult(ws, requestId, false, Collections.emptyList(), err); } catch (Exception e) { - log.warn("collect execution error request_id={}: {}", requestId, e.getMessage()); - sendResult(ws, requestId, false, Collections.emptyList(), e.getMessage()); + log.warn("collect execution failed"); + sendResult(ws, requestId, false, Collections.emptyList(), "collect execution failed"); } } @@ -408,7 +406,7 @@ private static void sendResult( } ws.send(MAPPER.writeValueAsString(out)); } catch (Exception e) { - log.error("failed to send WS result request_id={}: {}", requestId, e.getMessage()); + log.error("failed to send WS result"); } } } diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterChannel.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterChannel.java index 8d2bbe1..ee214f9 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterChannel.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterChannel.java @@ -61,7 +61,7 @@ public OpenCliResult invoke(List subcommandAndArgs) { tokens.add(s.trim()); } } - log.debug("OpenCLI adapter invoke adapterId={} subcommandSummary={}", adapterId, summarizeSubcommand(tokens)); + log.debug("OpenCLI adapter invoke argvSize={}", tokens.size()); return executor.invoke(tokens); } @@ -93,22 +93,4 @@ public OpenCliResult invoke(String... subcommandAndArgs) { } return invoke(list); } - - private static String summarizeSubcommand(List tokens) { - if (tokens.size() <= 1) { - return "(root)"; - } - int limit = Math.min(tokens.size(), 4); - StringBuilder sb = new StringBuilder(); - for (int i = 1; i < limit; i++) { - if (i > 1) { - sb.append(' '); - } - sb.append(tokens.get(i)); - } - if (tokens.size() > limit) { - sb.append(" ..."); - } - return sb.toString(); - } } diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliArgSupport.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliArgSupport.java index 34c3620..0ba5e98 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliArgSupport.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliArgSupport.java @@ -56,7 +56,7 @@ public static void addOptionEquals(List target, String name, String valu Objects.requireNonNull(name, "name"); Objects.requireNonNull(value, "value"); if (!name.startsWith("--")) { - throw new IllegalArgumentException("name must start with '--', got: " + name); + throw new IllegalArgumentException("name must start with '--'"); } String key = name.endsWith("=") ? name.substring(0, name.length() - 1) : name; target.add(key + "=" + value); diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java index ffd022f..4cd04e4 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java @@ -21,6 +21,7 @@ import java.util.List; import java.util.Map; import java.util.Objects; +import java.util.UUID; import lombok.Getter; import lombok.extern.slf4j.Slf4j; import org.apache.commons.exec.CommandLine; @@ -187,7 +188,7 @@ public static void appendQuotedKeyValue(CommandLine cmd, String key, String valu Objects.requireNonNull(key, "key"); Objects.requireNonNull(value, "value"); if (!key.startsWith("--")) { - throw new IllegalArgumentException("CLI key must start with '--', got: " + key); + throw new IllegalArgumentException("CLI key must start with '--'"); } String prefix = key.endsWith("=") ? key.substring(0, key.length() - 1) : key; cmd.addArgument(prefix + "=" + value, true); @@ -206,10 +207,11 @@ private OpenCliResult run(CommandLine commandLine) { commandLine, workingDirectory, environment, timeoutMs, properties.getMaxOutputBytes()); + String correlationId = UUID.randomUUID().toString(); try { SubprocessExecutionSupport.RunSession session = SubprocessExecutionSupport.execute(request); return completeAfterWait( - commandLine, + correlationId, timeoutMs, session.getStdout(), session.getStderr(), @@ -217,13 +219,13 @@ private OpenCliResult run(CommandLine commandLine) { session.getWatchdog(), session.isWaitTimedOut()); } catch (IOException e) { - log.warn("OpenCLI spawn failed commandLine={}, message={}", commandLine, e.getMessage()); + log.warn("OpenCLI spawn failed correlationId={}", correlationId); throw new OpenCliExecutableFailureException( - "OpenCLI could not be started (check PATH or executable path): " + commandLine, e); + "OpenCLI could not be started correlationId=" + correlationId, null); } catch (InterruptedException e) { Thread.currentThread().interrupt(); - log.warn("OpenCLI interrupted commandLine={}", commandLine); - throw new OpenCliException("Interrupted while awaiting OpenCLI subprocess", e, null); + log.warn("OpenCLI interrupted correlationId={}", correlationId); + throw new OpenCliException("Interrupted while awaiting OpenCLI subprocess correlationId=" + correlationId, null, null); } } @@ -233,7 +235,7 @@ private File resolveWorkingDirectory() { File wd = new File(wdProperty.trim()); if (!wd.isDirectory()) { throw new OpenCliExecutableFailureException( - "opencli.working-directory is not an existing directory: " + wd.getAbsolutePath(), null); + "opencli.working-directory is not an existing directory", null); } return wd; } @@ -241,7 +243,7 @@ private File resolveWorkingDirectory() { } private OpenCliResult completeAfterWait( - CommandLine commandLine, + String correlationId, long timeoutMs, SubprocessExecutionSupport.BoundedOutputStream out, SubprocessExecutionSupport.BoundedOutputStream err, @@ -263,26 +265,25 @@ private OpenCliResult completeAfterWait( OpenCliParsedFields parsed = OpenCliOutputParser.parseBestEffort(stdoutStr, stderrStr); if (waitTimedOut || watchdog.killedProcess()) { - log.warn("OpenCLI timed out commandLine={} timeoutMs={}", commandLine, timeoutMs); + log.warn("OpenCLI timed out correlationId={} timeoutMs={}", correlationId, timeoutMs); OpenCliResult partial = snapshot(stdoutStr, stderrStr, readExitQuietly(handler), parsed); throw new OpenCliTimeoutException( - "OpenCLI timed out after " + timeoutMs + " ms: " + commandLine, partial); + "OpenCLI timed out after " + timeoutMs + " ms correlationId=" + correlationId, partial); } Exception asyncFailure = handler.getException(); if (asyncFailure instanceof ExecuteException) { ExecuteException ex = (ExecuteException) asyncFailure; - log.warn("OpenCLI failed exitCode={} commandLine={}", ex.getExitValue(), commandLine); + log.warn("OpenCLI failed correlationId={} exitCode={}", correlationId, ex.getExitValue()); OpenCliResult failed = snapshot(stdoutStr, stderrStr, normalizeExitValue(ex.getExitValue()), parsed); throw new OpenCliNonZeroExitException( - "OpenCLI failed (exitCode=" + ex.getExitValue() + "): " + commandLine, failed); + "OpenCLI failed (exitCode=" + ex.getExitValue() + ") correlationId=" + correlationId, failed); } if (Objects.nonNull(asyncFailure)) { - log.error("OpenCLI async failure commandLine={}", commandLine, asyncFailure); + log.error("OpenCLI async failure correlationId={}", correlationId); OpenCliResult snapshot = snapshot(stdoutStr, stderrStr, readExitQuietly(handler), parsed); throw new OpenCliException( - "OpenCLI async failure: " + commandLine + " cause=" + asyncFailure.getMessage(), - asyncFailure, snapshot); + "OpenCLI async failure correlationId=" + correlationId, null, snapshot); } final int exit; @@ -290,16 +291,16 @@ private OpenCliResult completeAfterWait( exit = handler.getExitValue(); } catch (IllegalStateException e) { throw new OpenCliException( - "OpenCLI completed without observable exit code: " + commandLine, - e, + "OpenCLI completed without observable exit code correlationId=" + correlationId, + null, snapshot(stdoutStr, stderrStr, null, parsed)); } if (exit != 0) { - log.warn("OpenCLI non-zero exit exitCode={} commandLine={}", exit, commandLine); + log.warn("OpenCLI non-zero exit correlationId={} exitCode={}", correlationId, exit); OpenCliResult failed = snapshot(stdoutStr, stderrStr, exit, parsed); throw new OpenCliNonZeroExitException( - "OpenCLI non-zero exit (exitCode=" + exit + "): " + commandLine, failed); + "OpenCLI non-zero exit (exitCode=" + exit + ") correlationId=" + correlationId, failed); } return OpenCliResult.builder() diff --git a/src/main/java/io/github/easy4j/opencli/parser/OpenCliStdoutJson.java b/src/main/java/io/github/easy4j/opencli/parser/OpenCliStdoutJson.java index ffbe310..6394777 100644 --- a/src/main/java/io/github/easy4j/opencli/parser/OpenCliStdoutJson.java +++ b/src/main/java/io/github/easy4j/opencli/parser/OpenCliStdoutJson.java @@ -43,7 +43,7 @@ public static JsonNode parseLenient(String stdout) { try { return MAPPER.readTree(trim); } catch (JsonProcessingException e) { - log.debug("stdout is not strict JSON, wrapping as text: {}", e.getMessage()); + log.debug("stdout is not strict JSON; wrapping as text chars={}", stdout.length()); return MAPPER.getNodeFactory().textNode(stdout); } } diff --git a/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java index 586cd9e..482c411 100644 --- a/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java +++ b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java @@ -11,6 +11,7 @@ import io.github.easy4j.opencli.parser.OpenCliParsedFields; import io.github.easy4j.opencli.util.OpenCliStrings; import java.util.Objects; +import java.util.UUID; import kong.unirest.HttpResponse; import kong.unirest.Unirest; import kong.unirest.UnirestException; @@ -68,11 +69,13 @@ public OpenCliResult collect(OpenCliCollectRequest request) { } String url = base.trim().replaceAll("/+$", "") + "/collect"; int timeout = resolveTimeoutMillis(); + String correlationId = UUID.randomUUID().toString(); String bodyJson; try { bodyJson = MAPPER.writeValueAsString(request); } catch (com.fasterxml.jackson.core.JsonProcessingException e) { - throw new OpenCliExecutableFailureException("Failed to serialize collect request: " + e.getMessage(), e); + log.warn("Agent request serialization failed correlationId={}", correlationId); + throw failure("Failed to serialize collect request", correlationId); } try { HttpResponse response = @@ -86,26 +89,19 @@ public OpenCliResult collect(OpenCliCollectRequest request) { int status = response.getStatus(); String respBody = Objects.isNull(response.getBody()) ? "" : response.getBody(); if (status < 200 || status >= 300) { - String preview = respBody.substring(0, Math.min(500, respBody.length())); - log.warn("Agent HTTP non-2xx status={} url={} bodyPreview={}", status, url, preview); - throw new OpenCliExecutableFailureException( - "Agent HTTP " - + status - + " from " - + url - + ": " - + preview, - null); + log.warn("Agent HTTP non-2xx correlationId={} status={} responseChars={}", + correlationId, status, respBody.length()); + throw failure("Agent HTTP " + status, correlationId); } - return mapResponse(respBody, url); + return mapResponse(respBody, correlationId); } catch (OpenCliNonZeroExitException e) { throw e; } catch (com.fasterxml.jackson.core.JsonProcessingException e) { - log.warn("Agent response parse failed url={} message={}", url, e.getMessage()); - throw new OpenCliExecutableFailureException("Failed to parse agent response: " + e.getMessage(), e); + log.warn("Agent response parse failed correlationId={}", correlationId); + throw failure("Failed to parse agent response", correlationId); } catch (UnirestException e) { - log.warn("Agent HTTP failed url={} message={}", url, e.getMessage()); - throw new OpenCliExecutableFailureException("Agent HTTP I/O error: " + url + " — " + e.getMessage(), e); + log.warn("Agent HTTP I/O failed correlationId={}", correlationId); + throw failure("Agent HTTP I/O error", correlationId); } } @@ -155,16 +151,25 @@ private int resolveTimeoutMillis() { return (int) Math.min(timeoutMs, Integer.MAX_VALUE); } - private OpenCliResult mapResponse(String respBody, String url) + private static OpenCliExecutableFailureException failure(String message, String correlationId) { + return new OpenCliExecutableFailureException(message + " correlationId=" + correlationId, null); + } + + private OpenCliResult mapResponse(String respBody, String correlationId) throws com.fasterxml.jackson.core.JsonProcessingException { String rawCapture = captureRawIfEnabled(respBody); AgentCollectEnvelope env; try { env = MAPPER.readValue(respBody, AgentCollectEnvelope.class); } catch (com.fasterxml.jackson.core.JsonProcessingException e) { - log.warn("Agent response envelope parse failed url={} message={}", url, e.getMessage()); - throw new OpenCliExecutableFailureException( - "Failed to parse agent response envelope: " + e.getMessage(), e); + log.warn("Agent response envelope parse failed correlationId={} responseChars={}", + correlationId, respBody.length()); + throw failure("Failed to parse agent response envelope", correlationId); + } + if (Objects.isNull(env)) { + log.warn("Agent response envelope missing correlationId={} responseChars={}", + correlationId, respBody.length()); + throw failure("Missing agent response envelope", correlationId); } boolean success = Objects.nonNull(env.success) && env.success; String err = Objects.isNull(env.error) ? "" : env.error; @@ -179,9 +184,9 @@ private OpenCliResult mapResponse(String respBody, String url) OpenCliParsedFields parsed = OpenCliOutputParser.parseBestEffort(stdout, err); if (!success) { log.warn( - "Agent collect reported failure url={} error={} stdoutLength={}", - url, - err, + "Agent collect reported failure correlationId={} errorChars={} stdoutLength={}", + correlationId, + err.length(), stdout.length()); OpenCliResult failed = OpenCliResult.builder() @@ -192,7 +197,7 @@ private OpenCliResult mapResponse(String respBody, String url) .parsed(parsed) .remoteRawHttpBody(rawCapture) .build(); - throw new OpenCliNonZeroExitException("OpenCLI agent reported failure: " + err, failed); + throw new OpenCliNonZeroExitException("OpenCLI agent reported failure correlationId=" + correlationId, failed); } return OpenCliResult.builder() .stdout(stdout) diff --git a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliCenterWsUrlsTest.java b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliCenterWsUrlsTest.java index 24874f8..9429003 100644 --- a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliCenterWsUrlsTest.java +++ b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliCenterWsUrlsTest.java @@ -1,6 +1,7 @@ package io.github.easy4j.opencli.center.ws; import static org.junit.jupiter.api.Assertions.*; +import java.util.UUID; import org.junit.jupiter.api.Test; class OpenCliCenterWsUrlsTest { @@ -43,4 +44,13 @@ void shouldThrowForInvalidScheme() { assertThrows(IllegalArgumentException.class, () -> OpenCliCenterWsUrls.toAgentWebSocketUrl("ftp://host", OpenCliCenterWebSocketPath.NODES_WS)); } + + @Test + void invalidSchemeDiagnosticDoesNotEchoUrlCanary() { + String canary = "urlsecret" + UUID.randomUUID().toString().replace("-", ""); + IllegalArgumentException error = assertThrows(IllegalArgumentException.class, + () -> OpenCliCenterWsUrls.toAgentWebSocketUrl( + "ftp://host?token=" + canary, OpenCliCenterWebSocketPath.NODES_WS)); + assertFalse(error.toString().contains(canary)); + } } diff --git a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClientTest.java b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClientTest.java index d386589..01715ba 100644 --- a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClientTest.java +++ b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClientTest.java @@ -2,6 +2,10 @@ import static org.junit.jupiter.api.Assertions.*; import io.github.easy4j.opencli.OpenCliProperties; +import java.io.ByteArrayOutputStream; +import java.io.PrintStream; +import java.nio.charset.StandardCharsets; +import java.util.UUID; import org.junit.jupiter.api.Test; class OpenCliWsReverseAgentClientTest { @@ -75,4 +79,33 @@ void shouldAcceptValidConnectionProperties() { assertNotNull(client); client.close(); } + + @Test + void failedSessionLogDoesNotEchoConfiguredUrlCanary() throws Exception { + String canary = "wsurlsecret" + UUID.randomUUID().toString().replace("-", ""); + OpenCliWsAgentConnectionProperties conn = new OpenCliWsAgentConnectionProperties(); + conn.setCentralApiBaseUrl("ftp://host?token=" + canary); + conn.setAgentAdvertiseUrl("http://edge:19823"); + conn.setMinReconnectDelayMillis(5_000L); + ByteArrayOutputStream diagnostics = new ByteArrayOutputStream(); + PrintStream previousErr = System.err; + try (PrintStream capture = new PrintStream(diagnostics, true, "UTF-8"); + OpenCliWsReverseAgentClient client = new OpenCliWsReverseAgentClient(new OpenCliProperties(), conn)) { + System.setErr(capture); + try { + client.start(); + long deadline = System.nanoTime() + 2_000_000_000L; + while (!diagnostics.toString(StandardCharsets.UTF_8.name()).contains("opencli ws session failed") + && System.nanoTime() < deadline) { + Thread.sleep(10L); + } + } finally { + client.stop(); + System.setErr(previousErr); + } + } + String logText = diagnostics.toString(StandardCharsets.UTF_8.name()); + assertTrue(logText.contains("opencli ws session failed")); + assertFalse(logText.contains(canary)); + } } diff --git a/src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java b/src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java new file mode 100644 index 0000000..e1a4a0f --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java @@ -0,0 +1,79 @@ +package io.github.easy4j.opencli.core; + +import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.exception.OpenCliException; +import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; +import io.github.easy4j.opencli.exception.OpenCliTimeoutException; +import java.io.ByteArrayOutputStream; +import java.io.PrintStream; +import java.nio.charset.StandardCharsets; +import java.nio.file.Path; +import java.util.UUID; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.condition.EnabledOnOs; +import org.junit.jupiter.api.condition.OS; +import org.junit.jupiter.api.function.Executable; +import org.junit.jupiter.api.io.TempDir; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; + +class OpenCliProcessPrivacyTest { + + @Test + void keepsMissingExecutablePathOutOfLogsAndStackTrace(@TempDir Path directory) throws Exception { + String canary = "executable-" + UUID.randomUUID(); + OpenCliProperties properties = new OpenCliProperties(); + properties.setExecutable(directory.resolve(canary).toString()); + + try (OpenCliExecutor executor = new OpenCliExecutor(properties)) { + assertPrivateFailure(OpenCliException.class, canary, () -> executor.invoke("list")); + } + } + + @Test + @EnabledOnOs({OS.LINUX, OS.MAC}) + void preservesStderrOnNonzeroExitWithoutLeakingArgsOrStderr() throws Exception { + String canary = "stderr-" + UUID.randomUUID(); + OpenCliProperties properties = new OpenCliProperties(); + properties.setExecutable("/bin/sh"); + + try (OpenCliExecutor executor = new OpenCliExecutor(properties)) { + OpenCliNonZeroExitException failure = assertPrivateFailure(OpenCliNonZeroExitException.class, canary, + () -> executor.invoke("-c", "printf '%s' \"$1\" >&2; exit 7", "fixture", canary)); + assertEquals(canary, failure.getPartialResult().getStderr()); + assertEquals(Integer.valueOf(7), failure.getPartialResult().getExitCode()); + } + } + + @Test + @EnabledOnOs({OS.LINUX, OS.MAC}) + void keepsArgumentsOutOfTimeoutDiagnostics() throws Exception { + String canary = "timeout-" + UUID.randomUUID(); + OpenCliProperties properties = new OpenCliProperties(); + properties.setExecutable("/bin/sh"); + properties.setCommandTimeoutMillis(200); + + try (OpenCliExecutor executor = new OpenCliExecutor(properties)) { + assertPrivateFailure(OpenCliTimeoutException.class, canary, + () -> executor.invoke("-c", "exec sleep 5", "fixture", canary)); + } + } + + private static T assertPrivateFailure( + Class type, String canary, Executable invocation) throws Exception { + ByteArrayOutputStream output = new ByteArrayOutputStream(); + PrintStream original = System.err; + T failure; + try (PrintStream capture = new PrintStream(output, true, StandardCharsets.UTF_8.name())) { + System.setErr(capture); + failure = assertThrows(type, invocation); + failure.printStackTrace(capture); + } finally { + System.setErr(original); + } + assertFalse(output.toString(StandardCharsets.UTF_8.name()).contains(canary)); + return failure; + } +} diff --git a/src/test/java/io/github/easy4j/opencli/parser/OpenCliStdoutJsonTest.java b/src/test/java/io/github/easy4j/opencli/parser/OpenCliStdoutJsonTest.java index bea5a49..06b9262 100644 --- a/src/test/java/io/github/easy4j/opencli/parser/OpenCliStdoutJsonTest.java +++ b/src/test/java/io/github/easy4j/opencli/parser/OpenCliStdoutJsonTest.java @@ -5,6 +5,10 @@ import com.fasterxml.jackson.databind.node.TextNode; import io.github.easy4j.opencli.core.OpenCliResult; import io.github.easy4j.opencli.core.OpenCliTypedResult; +import java.io.ByteArrayOutputStream; +import java.io.PrintStream; +import java.nio.charset.StandardCharsets; +import java.util.UUID; import org.junit.jupiter.api.Test; class OpenCliStdoutJsonTest { @@ -30,6 +34,27 @@ void shouldWrapNonJsonAsTextNode() { assertEquals("not json at all", node.textValue()); } + @Test + void debugDiagnosticDoesNotExposeParserInput() throws Exception { + String canary = "stdoutsecret" + UUID.randomUUID().toString().replace("-", ""); + ByteArrayOutputStream diagnostics = new ByteArrayOutputStream(); + PrintStream previousErr = System.err; + JsonNode node; + try (PrintStream capture = new PrintStream(diagnostics, true, "UTF-8")) { + System.setErr(capture); + try { + node = OpenCliStdoutJson.parseLenient(canary); + } finally { + System.setErr(previousErr); + } + } + + assertEquals(canary, node.textValue()); + String logText = diagnostics.toString(StandardCharsets.UTF_8.name()); + assertTrue(logText.contains("stdout is not strict JSON")); + assertFalse(logText.contains(canary)); + } + @Test void shouldReturnEmptyTextNodeForNull() { JsonNode node = OpenCliStdoutJson.parseLenient(null); diff --git a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java index 764c970..6e8974e 100644 --- a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java +++ b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java @@ -6,12 +6,20 @@ import io.github.easy4j.opencli.OpenCliExecutionTarget; import io.github.easy4j.opencli.OpenCliProperties; import io.github.easy4j.opencli.core.OpenCliResult; +import io.github.easy4j.opencli.exception.OpenCliExecutableFailureException; import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; +import java.io.ByteArrayOutputStream; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; +import java.io.PrintStream; +import java.io.PrintWriter; +import java.io.StringWriter; import java.net.InetSocketAddress; import java.nio.charset.StandardCharsets; +import java.util.UUID; +import java.util.regex.Matcher; +import java.util.regex.Pattern; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; @@ -80,6 +88,105 @@ void collectFailureIncludesRawBodyWhenEnabled() throws IOException { } } + @Test + void nonSuccessHttpResponseDoesNotExposeBodyCanaryInException() throws IOException { + String canary = "body-secret-" + UUID.randomUUID(); + String urlCanary = "url-secret-" + UUID.randomUUID(); + try (JsonCollectStub stub = JsonCollectStub.start(canary, 503)) { + OpenCliProperties props = baseProps(stub.port()); + props.setRemoteAgentBaseUrl("http://127.0.0.1:" + stub.port() + + "/collect?token=" + urlCanary); + OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(props); + ByteArrayOutputStream diagnostics = new ByteArrayOutputStream(); + PrintStream previousErr = System.err; + OpenCliExecutableFailureException ex; + try (PrintStream capture = new PrintStream(diagnostics, true, "UTF-8")) { + System.setErr(capture); + try { + ex = Assertions.assertThrows(OpenCliExecutableFailureException.class, + () -> client.collect(OpenCliCollectRequest.builder().site("x").command("y").build())); + } finally { + System.setErr(previousErr); + } + } + Assertions.assertTrue(ex.getMessage().contains("503")); + Assertions.assertFalse(ex.toString().contains(canary)); + Assertions.assertFalse(ex.toString().contains(urlCanary)); + String logText = diagnostics.toString(StandardCharsets.UTF_8.name()); + Assertions.assertTrue(logText.contains("Agent HTTP non-2xx")); + Matcher correlation = Pattern.compile("correlationId=([0-9a-f-]{36})") + .matcher(ex.getMessage()); + Assertions.assertTrue(correlation.find()); + Assertions.assertDoesNotThrow(() -> UUID.fromString(correlation.group(1))); + Assertions.assertTrue(logText.contains(correlation.group(0))); + Assertions.assertFalse(logText.contains(canary)); + Assertions.assertFalse(logText.contains(urlCanary)); + for (Throwable cause = ex.getCause(); cause != null; cause = cause.getCause()) { + Assertions.assertFalse(cause.toString().contains(canary)); + Assertions.assertFalse(cause.toString().contains(urlCanary)); + } + } + } + + @Test + void malformedHttpEndpointDoesNotExposeCredentialsInPublicStackTrace() { + String credential = "private-" + UUID.randomUUID(); + OpenCliProperties properties = baseProps(1); + properties.setRemoteAgentBaseUrl("http://operator:" + credential + "@invalid host"); + try (OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(properties)) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("x").command("y").build(); + OpenCliExecutableFailureException failure = Assertions.assertThrows( + OpenCliExecutableFailureException.class, () -> client.collect(request)); + StringWriter stack = new StringWriter(); + failure.printStackTrace(new PrintWriter(stack)); + Assertions.assertFalse(stack.toString().contains(credential)); + Assertions.assertTrue(failure.getMessage().contains("correlationId=")); + } + } + + @Test + void nullEnvelopeUsesSafeCorrelatedParseFailure() throws IOException { + try (JsonCollectStub stub = JsonCollectStub.start("null"); + OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(baseProps(stub.port()))) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("x").command("y").build(); + OpenCliExecutableFailureException failure = Assertions.assertThrows( + OpenCliExecutableFailureException.class, () -> client.collect(request)); + Assertions.assertTrue(failure.getMessage().contains("response envelope")); + Assertions.assertTrue(failure.getMessage().contains("correlationId=")); + Assertions.assertNull(failure.getCause()); + } + } + + @Test + void malformedResponseDoesNotExposeParserSnippetInException() throws IOException { + String canary = "parser-secret-" + UUID.randomUUID(); + try (JsonCollectStub stub = JsonCollectStub.start("{\"error\":\"" + canary)) { + OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(baseProps(stub.port())); + OpenCliExecutableFailureException ex = Assertions.assertThrows( + OpenCliExecutableFailureException.class, + () -> client.collect(OpenCliCollectRequest.builder().site("x").command("y").build())); + Assertions.assertFalse(ex.toString().contains(canary)); + for (Throwable cause = ex.getCause(); cause != null; cause = cause.getCause()) { + Assertions.assertFalse(cause.toString().contains(canary)); + } + } + } + + @Test + void remoteFailureKeepsRawResultWithoutExposingErrorCanaryInException() throws IOException { + String canary = "agent-secret-" + UUID.randomUUID(); + String json = "{\"success\":false,\"items\":null,\"error\":\"" + canary + "\"}"; + try (JsonCollectStub stub = JsonCollectStub.start(json)) { + OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(baseProps(stub.port())); + OpenCliNonZeroExitException ex = Assertions.assertThrows( + OpenCliNonZeroExitException.class, + () -> client.collect(OpenCliCollectRequest.builder().site("x").command("y").build())); + Assertions.assertFalse(ex.toString().contains(canary)); + Assertions.assertEquals(canary, ex.getPartialResult().getStderr()); + Assertions.assertNull(ex.getPartialResult().getRemoteRawHttpBody()); + } + } + private static OpenCliProperties baseProps(int port) { OpenCliProperties props = new OpenCliProperties(); props.setExecutionTarget(OpenCliExecutionTarget.REMOTE_AGENT_HTTP); @@ -109,6 +216,10 @@ private JsonCollectStub(HttpServer server, int port) { * @return 可关闭的桩对象 */ static JsonCollectStub start(String jsonBody) throws IOException { + return start(jsonBody, 200); + } + + static JsonCollectStub start(String jsonBody, int status) throws IOException { byte[] bytes = jsonBody.getBytes(StandardCharsets.UTF_8); HttpServer server = HttpServer.create(new InetSocketAddress(0), 0); server.createContext( @@ -125,7 +236,7 @@ public void handle(HttpExchange exchange) throws IOException { exchange .getResponseHeaders() .set("Content-Type", "application/json; charset=utf-8"); - exchange.sendResponseHeaders(200, bytes.length); + exchange.sendResponseHeaders(status, bytes.length); try (OutputStream os = exchange.getResponseBody()) { os.write(bytes); } diff --git a/src/test/resources/simplelogger.properties b/src/test/resources/simplelogger.properties index 73b6628..ad97fd1 100644 --- a/src/test/resources/simplelogger.properties +++ b/src/test/resources/simplelogger.properties @@ -1,2 +1,3 @@ org.slf4j.simpleLogger.log.io.github.easy4j.opencli.browser.OpenCliBrowserSession=debug org.slf4j.simpleLogger.log.io.github.easy4j.opencli.remote.OpenCliArgvToCollectParser=debug +org.slf4j.simpleLogger.log.io.github.easy4j.opencli.parser.OpenCliStdoutJson=debug From 295f1d32d2b00f7f3d1ae74eb4f95d792b309d9c Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 17:52:32 +0800 Subject: [PATCH 003/105] Add explicit bounded diagnostic exports --- README.md | 6 ++ README.zh-CN.md | 6 ++ .../opencli/core/OpenCliDiagnosticExport.java | 68 ++++++++++++++++ .../core/OpenCliDiagnosticExportTest.java | 78 +++++++++++++++++++ 4 files changed, 158 insertions(+) create mode 100644 src/main/java/io/github/easy4j/opencli/core/OpenCliDiagnosticExport.java create mode 100644 src/test/java/io/github/easy4j/opencli/core/OpenCliDiagnosticExportTest.java diff --git a/README.md b/README.md index 042a347..08ccaff 100644 --- a/README.md +++ b/README.md @@ -224,6 +224,12 @@ agent.close(); Protocol: edge sends `register`; center replies `registered`; center sends `collect` (request_id, site, command, args, positional_args, format, mode); the SDK executes `opencli` locally (via `copyForLocalCliExecution()` to avoid loops) and replies `result`; plus `ping` / `pong`. +### Diagnostic export + +Call `OpenCliDiagnosticExport.export(result, 512)` explicitly with an `OpenCliResult` or an exception's partial result. The byte budget applies to UTF-8 text. Output contains only status and field lengths, with a `truncated=true` marker when fields do not fit. Field lengths can disclose how much data was present. + +The SDK returns the text in memory. Your application controls the destination and retention. SDK diagnostics omit argv values, raw content, URLs and filesystem paths. Applications that use or log raw results should protect that data. `remoteCaptureRawHttpResponse` is still opt-in. + ## 9. Testing & Build diff --git a/README.zh-CN.md b/README.zh-CN.md index a995148..89693d5 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -223,6 +223,12 @@ agent.close(); 协议摘要:边缘发送 `register`;中心回执 `registered`;中心下发 `collect`(request_id、site、command、args、positional_args、format、mode);SDK 在本机执行 `opencli`(通过 `copyForLocalCliExecution()` 强制本地子进程,避免回路)并回执 `result`;另有 `ping` / `pong`。 +### 诊断导出 + +如需导出诊断,请调用 `OpenCliDiagnosticExport.export(result, 512)`,传入 `OpenCliResult` 或异常中的部分结果。上限按 UTF-8 字节计算。输出只包含状态和字段长度,字段放不下时会标明 `truncated=true`。字段长度仍可能反映数据规模。 + +SDK 在内存中返回文本,由应用决定目的地和保留时间。SDK 诊断会排除命令参数、原始内容、URL 和文件路径。应用读取或记录原始结果时应自行保护这些数据。`remoteCaptureRawHttpResponse` 仍需显式开启。 + ## 9. 测试与构建 diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliDiagnosticExport.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliDiagnosticExport.java new file mode 100644 index 0000000..4a0e94f --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliDiagnosticExport.java @@ -0,0 +1,68 @@ +package io.github.easy4j.opencli.core; + +import java.util.Objects; + +/** + * Creates an explicit, in-memory diagnostic projection of an existing invocation result. + * The SDK retains no copy of the returned text. The caller controls its retention and destination. + */ +public final class OpenCliDiagnosticExport { + + private static final String COMPLETE_HEADER = "policy=metadata-only\ntruncated=false\n"; + private static final String TRUNCATED_HEADER = "policy=metadata-only\ntruncated=true\n"; + + /** Minimum budget that can represent either export header. */ + public static final int MIN_EXPORT_BYTES = COMPLETE_HEADER.length(); + + private OpenCliDiagnosticExport() { + } + + /** + * Exports status and character counts as UTF-8 key-value lines. Raw output, parsed values, + * command arguments, URLs, and paths are excluded by construction. Lengths are UTF-16 code-unit counts + * and reveal the size of the corresponding fields. + * + * @param result completed result or partial result from an exception + * @param maxBytes maximum UTF-8 size, at least {@link #MIN_EXPORT_BYTES} + * @return diagnostic text containing complete fields only, with a truncation indicator + * @throws IllegalArgumentException when the budget cannot fit the header + */ + public static String export(OpenCliResult result, int maxBytes) { + Objects.requireNonNull(result, "result"); + if (maxBytes < MIN_EXPORT_BYTES) { + throw new IllegalArgumentException("maxBytes must fit the diagnostic export header"); + } + + Integer exitCode = result.getExitCode(); + String[] fields = { + "success=" + result.isSuccess() + "\n", + Objects.isNull(exitCode) ? "" : "exitCode=" + exitCode + "\n", + characterCount("stdoutChars", result.getStdout()), + characterCount("stderrChars", result.getStderr()), + characterCount("rawHttpChars", result.getRemoteRawHttpBody()) + }; + + // Every emitted character is ASCII, so the character count is also the UTF-8 byte count. + int completeBytes = COMPLETE_HEADER.length(); + for (String field : fields) { + completeBytes += field.length(); + } + + boolean truncated = completeBytes > maxBytes; + StringBuilder output = new StringBuilder(Math.min(completeBytes, maxBytes)); + output.append(truncated ? TRUNCATED_HEADER : COMPLETE_HEADER); + int remainingBytes = maxBytes - COMPLETE_HEADER.length(); + for (String field : fields) { + if (field.length() > remainingBytes) { + break; + } + output.append(field); + remainingBytes -= field.length(); + } + return output.toString(); + } + + private static String characterCount(String name, String value) { + return Objects.isNull(value) ? "" : name + "=" + value.length() + "\n"; + } +} diff --git a/src/test/java/io/github/easy4j/opencli/core/OpenCliDiagnosticExportTest.java b/src/test/java/io/github/easy4j/opencli/core/OpenCliDiagnosticExportTest.java new file mode 100644 index 0000000..5e4e5c2 --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/core/OpenCliDiagnosticExportTest.java @@ -0,0 +1,78 @@ +package io.github.easy4j.opencli.core; + +import io.github.easy4j.opencli.parser.OpenCliParsedFields; +import java.nio.charset.StandardCharsets; +import java.util.UUID; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +class OpenCliDiagnosticExportTest { + + @Test + void explicitProjectionExcludesPayloadsAndLeavesResultIntact() { + String sensitive = "secret-" + UUID.randomUUID(); + String stderr = "/trace/" + sensitive; + String rawHttp = "https://user:" + sensitive + "@example.test"; + OpenCliParsedFields parsed = OpenCliParsedFields.builder().jsonShapeHint(sensitive).build(); + OpenCliResult result = OpenCliResult.builder() + .success(false).exitCode(7).stdout(sensitive).stderr(stderr).remoteRawHttpBody(rawHttp).parsed(parsed).build(); + + String export = OpenCliDiagnosticExport.export(result, 512); + + assertTrue(export.startsWith("policy=metadata-only\ntruncated=false\n")); + assertTrue(export.contains("success=false\n")); + assertTrue(export.contains("exitCode=7\n")); + assertTrue(export.contains("stdoutChars=" + sensitive.length() + "\n")); + assertTrue(export.contains("stderrChars=" + stderr.length() + "\n")); + assertTrue(export.contains("rawHttpChars=" + rawHttp.length() + "\n")); + assertFalse(export.contains(sensitive)); + assertEquals(sensitive, result.getStdout()); + assertEquals(stderr, result.getStderr()); + assertEquals(rawHttp, result.getRemoteRawHttpBody()); + assertEquals(sensitive, result.getParsed().getJsonShapeHint()); + } + + @Test + void byteLimitUsesWholeFieldsAndReportsTruncation() { + OpenCliResult result = OpenCliResult.builder().success(true).stdout("非 ASCII 内容").build(); + int maxBytes = 50; + + String export = OpenCliDiagnosticExport.export(result, maxBytes); + + assertTrue(export.getBytes(StandardCharsets.UTF_8).length <= maxBytes); + assertEquals("policy=metadata-only\ntruncated=true\nsuccess=true\n", export); + assertEquals("非 ASCII 内容", result.getStdout()); + } + + @Test + void exactFitAndOneByteShortUseConsistentTruncationMarkers() { + OpenCliResult result = OpenCliResult.builder().success(true).build(); + String expected = "policy=metadata-only\ntruncated=false\nsuccess=true\n"; + + assertEquals(expected, OpenCliDiagnosticExport.export(result, expected.length())); + assertEquals("policy=metadata-only\ntruncated=true\n", + OpenCliDiagnosticExport.export(result, expected.length() - 1)); + } + + @Test + void invalidBudgetDoesNotMutateResult() { + OpenCliResult result = OpenCliResult.builder().success(false).stderr("original failure").build(); + + assertThrows(IllegalArgumentException.class, () -> OpenCliDiagnosticExport.export(result, 1)); + assertEquals("original failure", result.getStderr()); + assertFalse(result.isSuccess()); + } + + @Test + void absentValuesAreOmittedRatherThanReportedAsEmptyData() { + String export = OpenCliDiagnosticExport.export(OpenCliResult.builder().stdout("").build(), 512); + assertTrue(export.contains("stdoutChars=0\n")); + assertFalse(export.contains("stderrChars")); + assertFalse(export.contains("rawHttpChars")); + assertFalse(export.contains("exitCode")); + } +} From 3e1bfb3531ace72a504237bfc2ec838b92f9dc75 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 20:47:05 +0800 Subject: [PATCH 004/105] Backport bounded OpenCLI argv and process lifecycle contracts --- pom.xml | 3 +- .../easy4j/opencli/OpenCliProperties.java | 10 + .../opencli/core/LiteralCommandLine.java | 46 ++ .../opencli/core/OpenCliAdapterChannel.java | 64 +- .../core/OpenCliAdapterCommandRequest.java | 183 +++--- .../opencli/core/OpenCliArgSupport.java | 90 +-- .../core/OpenCliCancellationToken.java | 14 + .../opencli/core/OpenCliExecutionDetails.java | 35 ++ .../easy4j/opencli/core/OpenCliExecutor.java | 392 +++++------- .../easy4j/opencli/core/OpenCliOption.java | 73 +++ .../opencli/core/OpenCliOptionSchema.java | 73 +++ .../opencli/core/OpenCliProcessRuntime.java | 37 ++ .../easy4j/opencli/core/OpenCliResult.java | 3 + .../support/SubprocessExecutionSupport.java | 556 ++++++++++++------ .../OpenCliExecutableFailureException.java | 14 +- .../opencli/contract/ContractProbe.java | 16 + .../opencli/contract/LifecycleProbe.java | 44 ++ .../contract/OpenCliArgvContractTest.java | 171 ++++++ .../contract/OpenCliProcessBoundaryTest.java | 162 +++++ .../contract/OpenCliProcessContractTest.java | 233 ++++++++ .../OpenCliStructuredArgvContractTest.java | 180 ++++++ .../OpenCliAdapterCommandRequestTest.java | 31 +- .../opencli/core/OpenCliArgSupportTest.java | 35 +- .../opencli/core/OpenCliExecutorFullTest.java | 19 +- .../support/SubprocessCleanupFaultTest.java | 292 +++++++++ .../support/SubprocessCompletionRaceTest.java | 190 ++++++ .../support/SubprocessStreamFailureTest.java | 93 +++ .../resources/opencli-contracts/v1/SHA256SUMS | 2 + .../resources/opencli-contracts/v1/argv.tsv | 6 + .../opencli-contracts/v1/sources.lock.json | 58 ++ 30 files changed, 2527 insertions(+), 598 deletions(-) create mode 100644 src/main/java/io/github/easy4j/opencli/core/LiteralCommandLine.java create mode 100644 src/main/java/io/github/easy4j/opencli/core/OpenCliCancellationToken.java create mode 100644 src/main/java/io/github/easy4j/opencli/core/OpenCliExecutionDetails.java create mode 100644 src/main/java/io/github/easy4j/opencli/core/OpenCliOption.java create mode 100644 src/main/java/io/github/easy4j/opencli/core/OpenCliOptionSchema.java create mode 100644 src/main/java/io/github/easy4j/opencli/core/OpenCliProcessRuntime.java create mode 100644 src/test/java/io/github/easy4j/opencli/contract/ContractProbe.java create mode 100644 src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java create mode 100644 src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java create mode 100644 src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessBoundaryTest.java create mode 100644 src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java create mode 100644 src/test/java/io/github/easy4j/opencli/contract/OpenCliStructuredArgvContractTest.java create mode 100644 src/test/java/io/github/easy4j/opencli/core/support/SubprocessCleanupFaultTest.java create mode 100644 src/test/java/io/github/easy4j/opencli/core/support/SubprocessCompletionRaceTest.java create mode 100644 src/test/java/io/github/easy4j/opencli/core/support/SubprocessStreamFailureTest.java create mode 100644 src/test/resources/opencli-contracts/v1/SHA256SUMS create mode 100644 src/test/resources/opencli-contracts/v1/argv.tsv create mode 100644 src/test/resources/opencli-contracts/v1/sources.lock.json diff --git a/pom.xml b/pom.xml index 36f2573..dbf1031 100644 --- a/pom.xml +++ b/pom.xml @@ -47,6 +47,7 @@ + 1.8 ${java.version} @@ -320,7 +321,7 @@ false false - -Xmx1024m -Dfile.encoding=UTF-8 + @{argLine} -Xmx1024m -Dfile.encoding=UTF-8 ${basedir}/target/test-classes diff --git a/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java b/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java index fc36867..4f9eabf 100644 --- a/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java +++ b/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java @@ -126,10 +126,20 @@ public OpenCliProperties copyForLocalCliExecution() { c.setWorkingDirectory(this.workingDirectory); c.setCommandTimeoutMillis(this.commandTimeoutMillis); c.setMaxConcurrentExecutions(this.maxConcurrentExecutions); + c.setMaxStdoutBytes(this.maxStdoutBytes); + c.setMaxStderrBytes(this.maxStderrBytes); + c.setCleanupGraceMillis(this.cleanupGraceMillis); c.setStartupProbeTimeoutMillis(this.startupProbeTimeoutMillis); c.setLeadingArguments(new ArrayList<>(this.leadingArguments)); c.setEnvironment(new LinkedHashMap<>(this.environment)); c.setExecutionTarget(OpenCliExecutionTarget.LOCAL_PROCESS); return c; } + + /** Maximum stdout bytes captured per invocation. */ + private int maxStdoutBytes = 8 * 1024 * 1024; + /** Maximum stderr bytes captured per invocation. */ + private int maxStderrBytes = 2 * 1024 * 1024; + /** Maximum time to wait for owned resources after execution ends. */ + private long cleanupGraceMillis = 5_000L; } diff --git a/src/main/java/io/github/easy4j/opencli/core/LiteralCommandLine.java b/src/main/java/io/github/easy4j/opencli/core/LiteralCommandLine.java new file mode 100644 index 0000000..0ed24e4 --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/core/LiteralCommandLine.java @@ -0,0 +1,46 @@ +package io.github.easy4j.opencli.core; + +import java.util.ArrayList; +import java.util.List; +import java.util.Objects; +import org.apache.commons.exec.CommandLine; + +/** + * Internal literal argv bridge. Commons Exec's Argument constructor trims even + * when handleQuoting is false, so raw values cannot be stored in its argument list. + * Keep the original vector and supply it directly to the native launcher instead. + * + * @author Loong Wan + * @since 3.0.0 + */ +final class LiteralCommandLine extends CommandLine { + private final List literalArguments = new ArrayList<>(); + + LiteralCommandLine(String executable) { + super(executable); + } + + @Override + public CommandLine addArgument(String argument, boolean handleQuoting) { + if (handleQuoting) { + throw new IllegalArgumentException("Literal argv does not support implicit quoting"); + } + literalArguments.add(Objects.requireNonNull(argument, "argument")); + return this; + } + + @Override + public String[] getArguments() { + return literalArguments.toArray(new String[0]); + } + + @Override + public String[] toStrings() { + String[] result = new String[literalArguments.size() + 1]; + result[0] = getExecutable(); + for (int i = 0; i < literalArguments.size(); i++) { + result[i + 1] = literalArguments.get(i); + } + return result; + } +} diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterChannel.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterChannel.java index ee214f9..062d73f 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterChannel.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterChannel.java @@ -2,34 +2,27 @@ import io.github.easy4j.opencli.util.OpenCliStrings; import java.util.ArrayList; +import java.util.Arrays; import java.util.List; import java.util.Objects; import lombok.extern.slf4j.Slf4j; /** - * 针对单个 OpenCLI adapter 的轻量通道:自动在 argv 前插入 adapter id。 - */ -@Slf4j/** - - * Lightweight channel for a single OpenCLI adapter: automatically prepends the adapter id - * to every argv invocation. - + * Lightweight channel for one OpenCLI adapter. Values are literal argv tokens; + * only the separately supplied adapter identifier is normalized. * - * @author Loong Wan - * @since 3.0.0 - */ - +@Slf4j public final class OpenCliAdapterChannel { private final OpenCliExecutor executor; private final String adapterId; /** - * @param executor 共享执行器,不得为 null - * @param adapterId 文档中的 adapter 名(如 {@code twitter}),不得为空白 + * @param executor shared executor + * @param adapterId nonblank adapter identifier */ public OpenCliAdapterChannel(OpenCliExecutor executor, String adapterId) { this.executor = Objects.requireNonNull(executor, "executor"); @@ -39,37 +32,31 @@ public OpenCliAdapterChannel(OpenCliExecutor executor, String adapterId) { } } - /** - * @return 当前通道绑定的 adapter id - */ + /** @return this channel's adapter identifier */ public String getAdapterId() { return adapterId; } /** - * 调用 {@code opencli }。 + * Invoke an adapter with a snapshot of the supplied literal arguments. + * An empty list invokes its root; null elements are rejected. * - * @param subcommandAndArgs 子命令及后续参数;不得为 null,可为空(仅调 adapter 根命令时) - * @return 成功时的 {@link OpenCliResult} + * @param subcommandAndArgs subcommand and subsequent values + * @return execution result */ public OpenCliResult invoke(List subcommandAndArgs) { - Objects.requireNonNull(subcommandAndArgs, "subcommandAndArgs"); - List tokens = new ArrayList<>(); + List rest = OpenCliArgSupport.snapshotValues(subcommandAndArgs, "subcommandAndArgs"); + List tokens = new ArrayList<>(rest.size() + 1); tokens.add(adapterId); - for (String s : subcommandAndArgs) { - if (OpenCliStrings.isNotBlank(s)) { - tokens.add(s.trim()); - } - } + tokens.addAll(rest); + // Do not put prompt text or positional values in default diagnostic logs. log.debug("OpenCLI adapter invoke argvSize={}", tokens.size()); return executor.invoke(tokens); } /** - * 通过 {@link OpenCliAdapterCommandRequest} 发起调用(推荐测试与 SDK 侧结构化入口)。 - * - * @param request 结构化子命令请求,不得为 null - * @return 执行结果 + * @param request structured command request + * @return execution result */ public OpenCliResult invoke(OpenCliAdapterCommandRequest request) { Objects.requireNonNull(request, "request"); @@ -77,20 +64,11 @@ public OpenCliResult invoke(OpenCliAdapterCommandRequest request) { } /** - * {@link #invoke(List)} 的可变参数形式。 - * - * @param subcommandAndArgs 子命令及 flag - * @return 执行结果 + * @param subcommandAndArgs subcommand and literal values + * @return execution result */ public OpenCliResult invoke(String... subcommandAndArgs) { - List list = new ArrayList<>(); - if (Objects.nonNull(subcommandAndArgs)) { - for (String s : subcommandAndArgs) { - if (OpenCliStrings.isNotBlank(s)) { - list.add(s.trim()); - } - } - } - return invoke(list); + Objects.requireNonNull(subcommandAndArgs, "subcommandAndArgs"); + return invoke(Arrays.asList(subcommandAndArgs)); } } diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequest.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequest.java index eea957d..a511adc 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequest.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequest.java @@ -1,45 +1,33 @@ package io.github.easy4j.opencli.core; import io.github.easy4j.opencli.util.OpenCliStrings; +import java.math.BigDecimal; +import java.math.BigInteger; import java.util.ArrayList; import java.util.Collections; +import java.util.HashMap; +import java.util.HashSet; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; import java.util.Objects; +import java.util.Set; import lombok.AccessLevel; import lombok.Builder; import lombok.Getter; import lombok.Singular; /** - * 结构化 adapter 子命令请求:由子命令名、positional 参数与命名 options 构建 argv, - * 供 {@link OpenCliAdapterChannel#invoke(OpenCliAdapterCommandRequest)} 及覆盖测试使用。 - *

- * 禁止在测试中手工拼接 {@code List.of("sub", "--flag", "value")};应通过 builder 建模参数。 - *

- */ -@Getter -@Builder/** - - * Structured adapter subcommand request: builds argv from a subcommand name, - * positional arguments, and named options for use with - * {@link OpenCliAdapterChannel#invoke(OpenCliAdapterCommandRequest)}. + * Structured adapter request with immutable literal values and ordered options. + * The legacy options Map retains Boolean presence-only semantics; use + * {@link OpenCliOption} for repeated values, valued false and explicit negation. * - *

Avoid manually assembling {@code List.of("sub", "--flag", "value")} in tests; - * use the builder to model parameters instead.

- - * - * @author Loong Wan - * @since 3.0.0 - */ - +@Getter +@Builder public final class OpenCliAdapterCommandRequest { - - /** 子命令名(不含 adapter id)。 */ private final String subcommand; @Getter(AccessLevel.NONE) @@ -47,87 +35,136 @@ public final class OpenCliAdapterCommandRequest { private final List positionals; @Getter(AccessLevel.NONE) - @Builder.Default - private final Map options = Collections.emptyMap(); + private final Map options; + + @Getter(AccessLevel.NONE) + @Singular("option") + private final List orderedOptions; /** - * @return positional 参数副本 + * Builder customisation snapshots legacy option values before they can be + * changed through the caller's Map or a mutable value object. */ - public List getPositionals() { - if (Objects.isNull(positionals)) { - return Collections.emptyList(); + public static class OpenCliAdapterCommandRequestBuilder { + private Map options; + + /** @param source legacy single-value options @return this builder */ + public OpenCliAdapterCommandRequestBuilder options(Map source) { + options = snapshotOptions(source); + return this; } - return Collections.unmodifiableList(new ArrayList<>(positionals)); } - /** - * @return 命名选项副本 - */ + /** @return an immutable copy of positional values */ + public List getPositionals() { + return positionals == null ? Collections.emptyList() + : Collections.unmodifiableList(new ArrayList<>(positionals)); + } + + /** @return an immutable snapshot of legacy options */ public Map getOptions() { - if (Objects.isNull(options)) { - return Collections.emptyMap(); - } - return Collections.unmodifiableMap(new LinkedHashMap<>(options)); + return options == null ? Collections.emptyMap() + : Collections.unmodifiableMap(new LinkedHashMap<>(options)); } - /** - * 将本请求转换为 {@link OpenCliAdapterChannel#invoke(List)} 所需的 token 列表。 - * - * @return 以 subcommand 开头、随后 positional、再 options 的 argv 片段 - */ + /** @return immutable, ordered option occurrences */ + public List getOrderedOptions() { + return orderedOptions == null ? Collections.emptyList() + : Collections.unmodifiableList(new ArrayList<>(orderedOptions)); + } + + /** @return the validated subcommand and complete literal argv */ public List toSubcommandAndArgs() { Objects.requireNonNull(subcommand, "subcommand"); + if (OpenCliStrings.isBlank(subcommand)) { + throw new IllegalArgumentException("subcommand must not be blank"); + } List tokens = new ArrayList<>(); tokens.add(subcommand.trim()); - if (Objects.nonNull(positionals)) { - for (String p : positionals) { - if (OpenCliStrings.isNotBlank(p)) { - tokens.add(p.trim()); + if (positionals != null) { + tokens.addAll(OpenCliArgSupport.snapshotValues(positionals, "positionals")); + } + Set legacyFlags = new HashSet<>(); + if (options != null) { + for (Map.Entry entry : options.entrySet()) { + String flag = appendLegacyOption(tokens, entry.getKey(), entry.getValue()); + if (flag != null && !legacyFlags.add(flag)) { + throw new IllegalArgumentException("Ambiguous duplicate legacy option identifier"); } } } - if (Objects.nonNull(options)) { - for (Map.Entry entry : options.entrySet()) { - appendOption(tokens, entry.getKey(), entry.getValue()); + Map seen = new HashMap<>(); + Map wireNames = new HashMap<>(); + if (orderedOptions != null) { + for (int i = 0; i < orderedOptions.size(); i++) { + OpenCliOption occurrence = orderedOptions.get(i); + if (occurrence == null) { + throw new IllegalArgumentException("orderedOptions[" + i + "] must not be null"); + } + OpenCliOptionSchema schema = occurrence.getSchema(); + String name = schema.getName(); + List argv = occurrence.toTokens(); + String wireName = argv.get(0); + if (legacyFlags.contains(name) || legacyFlags.contains(wireName)) { + throw new IllegalArgumentException("Legacy and ordered options must not overlap"); + } + OpenCliOptionSchema previous = seen.put(name, schema); + if (previous != null && (!schema.isRepeatable() || !previous.equals(schema))) { + throw new IllegalArgumentException("Repeated option is not allowed by one consistent schema"); + } + String previousCanonical = wireNames.put(wireName, name); + if (previousCanonical != null && !previousCanonical.equals(name)) { + throw new IllegalArgumentException("Different schemas emit the same option identifier"); + } + tokens.addAll(argv); } } return tokens; } - private static void appendOption(List target, String name, Object value) { - if (OpenCliStrings.isBlank(name) || Objects.isNull(value)) { - return; - } - String flag = name.startsWith("-") ? name.trim() : "--" + name.trim(); - if (value instanceof Boolean) { - if (((Boolean) value).booleanValue()) { - target.add(flag); + private static Map snapshotOptions(Map source) { + if (source == null) { return Collections.emptyMap(); } + Map snapshot = new LinkedHashMap<>(); + for (Map.Entry entry : new LinkedHashMap<>(source).entrySet()) { + Object value = entry.getValue(); + if (value != null) { + Class type = value.getClass(); + if (type != String.class && type != Boolean.class && type != Byte.class + && type != Short.class && type != Integer.class && type != Long.class + && type != Float.class && type != Double.class && type != BigInteger.class + && type != BigDecimal.class) { + value = OpenCliArgSupport.stringValue(value, "option value"); + } } - return; + snapshot.put(entry.getKey(), value); + } + return Collections.unmodifiableMap(snapshot); + } + + private static String appendLegacyOption(List target, String name, Object value) { + if (OpenCliStrings.isBlank(name) || value == null || Boolean.FALSE.equals(value)) { + return null; } + String normalized = name.trim(); + String flag = normalized.startsWith("-") ? normalized : "--" + normalized; target.add(flag); - target.add(String.valueOf(value).trim()); + if (!(value instanceof Boolean)) { + target.add(OpenCliArgSupport.stringValue(value, "option value")); + } + return flag; } /** - * 从 manifest 风格的 options map 创建请求(测试资源反序列化辅助)。 - * - * @param subcommand 子命令 - * @param positionals positional 列表,可为 null - * @param options 选项 map,可为 null - * @return 请求实例 + * @param subcommand command identifier + * @param positionals optional positional values + * @param options optional legacy single-value options + * @return a structured request */ public static OpenCliAdapterCommandRequest of( - String subcommand, - List positionals, - Map options) { + String subcommand, List positionals, Map options) { OpenCliAdapterCommandRequestBuilder b = builder().subcommand(subcommand); - if (Objects.nonNull(positionals)) { - b.positionals(positionals); - } - if (Objects.nonNull(options) && !options.isEmpty()) { - b.options(new LinkedHashMap<>(options)); - } + if (positionals != null) { b.positionals(positionals); } + if (options != null) { b.options(options); } return b.build(); } } diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliArgSupport.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliArgSupport.java index 0ba5e98..9531dbc 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliArgSupport.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliArgSupport.java @@ -1,55 +1,61 @@ package io.github.easy4j.opencli.core; -import io.github.easy4j.opencli.util.OpenCliStrings; import java.util.ArrayList; +import java.util.Collections; import java.util.List; import java.util.Objects; /** * CLI argument assembly utilities: merges business segments with pass-through - * {@code additionalRawArgs}. + * {@code additionalRawArgs} without changing argument values. * * @author Loong Wan * @since 3.0.0 - */public final class OpenCliArgSupport { + */ +public final class OpenCliArgSupport { private OpenCliArgSupport() { } /** - * 将前缀片段与可选附加片段合并为连续 argv(过滤 null/空白)。 + * Capture values before execution or queuing. Validate indices without exposing other values. + */ + static List snapshotValues(List values, String field) { + Objects.requireNonNull(values, field); + List copy = new ArrayList<>(values); + for (int i = 0; i < copy.size(); i++) { + if (copy.get(i) == null) { + throw new IllegalArgumentException(field + "[" + i + "] must not be null"); + } + } + return Collections.unmodifiableList(copy); + } + + /** + * Merge optional segments into a new argv list. Null segments are absent; + * null elements are invalid, while empty and whitespace-only values are preserved. * - * @param prefix 子命令与已建模参数,可为 null - * @param additionalRawArgs 额外原生参数,可为 null - * @return 新列表副本 + * @param prefix command and modeled arguments, or null + * @param additionalRawArgs extra literal arguments, or null + * @return a new list, without modifying either source */ public static List merge(List prefix, List additionalRawArgs) { List out = new ArrayList<>(); - if (Objects.nonNull(prefix)) { - for (String s : prefix) { - if (OpenCliStrings.isNotBlank(s)) { - out.add(s.trim()); - } - } + if (prefix != null) { + out.addAll(snapshotValues(prefix, "prefix")); } - if (Objects.nonNull(additionalRawArgs)) { - for (String s : additionalRawArgs) { - if (OpenCliStrings.isNotBlank(s)) { - out.add(s.trim()); - } - } + if (additionalRawArgs != null) { + out.addAll(snapshotValues(additionalRawArgs, "additionalRawArgs")); } return out; } /** - * 追加 {@code --name=value}(value 含空格时由调用方决定是否使用 - * {@link OpenCliExecutor#appendQuotedKeyValue(CommandLine, String, String)}; - * 此处仅做简单拼接)。 + * Append one literal {@code --name=value} token. * - * @param target 目标列表,不得为 null - * @param name 完整名称(含 {@code --},不含 {@code =}) - * @param value 非空值 + * @param target destination list + * @param name full option name, including {@code --} + * @param value non-null value, which may be empty */ public static void addOptionEquals(List target, String name, String value) { Objects.requireNonNull(target, "target"); @@ -63,11 +69,11 @@ public static void addOptionEquals(List target, String name, String valu } /** - * 追加 {@code --flag value} 双 token 形式。 + * Append a {@code --flag value} pair without altering the value. * - * @param target 目标列表 - * @param flag 如 {@code --limit} - * @param value 非空值 + * @param target destination list + * @param flag option name + * @param value non-null value, which may be empty */ public static void addOptionPair(List target, String flag, String value) { Objects.requireNonNull(target, "target"); @@ -78,24 +84,32 @@ public static void addOptionPair(List target, String flag, String value) } /** - * 当 {@code value} 非 null 时追加 {@code --flag value}。 + * Append a pair when the optional value is non-null. * - * @param target 目标 argv 列表 - * @param flag 选项名 - * @param value 可为 null + * @param target destination list + * @param flag option name + * @param value optional value */ public static void addOptionPairIfPresent(List target, String flag, Object value) { if (Objects.nonNull(value)) { - addOptionPair(target, flag, String.valueOf(value)); + addOptionPair(target, flag, stringValue(value, "value")); + } + } + + static String stringValue(Object value, String field) { + String text = String.valueOf(value); + if (Objects.isNull(text)) { + throw new IllegalArgumentException(field + " string form must not be null"); } + return text; } /** - * 当 {@code enabled} 为 {@code true} 时追加 boolean flag(无值)。 + * Append a presence-only flag when enabled. This helper is not a valued boolean option. * - * @param target 目标 argv 列表 - * @param flag 如 {@code --follow} - * @param enabled 开关,null/false 时不追加 + * @param target destination list + * @param flag option name + * @param enabled true to append; null/false to omit */ public static void addFlagIfTrue(List target, String flag, Boolean enabled) { if (Boolean.TRUE.equals(enabled)) { diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliCancellationToken.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliCancellationToken.java new file mode 100644 index 0000000..c90d2db --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliCancellationToken.java @@ -0,0 +1,14 @@ +package io.github.easy4j.opencli.core; + +import java.util.concurrent.atomic.AtomicBoolean; + +/** Cooperative cancellation for one local invocation; cancellation never affects another invocation. */ +public final class OpenCliCancellationToken { + private final AtomicBoolean cancelled = new AtomicBoolean(); + + /** Request cancellation. This operation is idempotent. */ + public void cancel() { cancelled.set(true); } + + /** @return whether cancellation has been requested */ + public boolean isCancelled() { return cancelled.get(); } +} diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutionDetails.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutionDetails.java new file mode 100644 index 0000000..6da55ff --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutionDetails.java @@ -0,0 +1,35 @@ +package io.github.easy4j.opencli.core; + +import lombok.Builder; +import lombok.Getter; + +/** Immutable execution evidence. Observed byte counts describe bytes read, not bytes produced remotely. */ +@Getter +@Builder +public final class OpenCliExecutionDetails { + /** First terminal condition selected by the invocation owner. */ + public enum TerminationReason { + PROCESS_EXIT, QUEUE_TIMEOUT, EXECUTION_TIMEOUT, OUTPUT_LIMIT, + CANCELLED, SPAWN_FAILED, IO_FAILURE, CLEANUP_UNCONFIRMED, RUNTIME_UNAVAILABLE + } + + /** Confirmation concerns the directly owned child, not an arbitrary process tree. */ + public enum CleanupState { NOT_STARTED, ROOT_EXIT_CONFIRMED, UNCONFIRMED } + + private final TerminationReason terminationReason; + private final CleanupState cleanupState; + private final boolean processStarted; + private final boolean streamsDrained; + /** A watchdog or process cleanup operation threw; later cleanup may still confirm root exit. */ + private final boolean cleanupOperationFailed; + private final long stdoutCapturedBytes; + private final long stdoutObservedBytes; + private final boolean stdoutTruncated; + private final long stderrCapturedBytes; + private final long stderrObservedBytes; + private final boolean stderrTruncated; + private final long elapsedMillis; + private final long queueWaitMillis; + /** This portable backend does not claim ownership/termination of detached daemon descendants. */ + private final boolean descendantsExitConfirmed; +} diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java index 4cd04e4..9b853ae 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java @@ -2,128 +2,101 @@ import io.github.easy4j.opencli.OpenCliExecutionTarget; import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails.TerminationReason; +import io.github.easy4j.opencli.core.support.SubprocessExecutionSupport; import io.github.easy4j.opencli.exception.OpenCliException; import io.github.easy4j.opencli.exception.OpenCliExecutableFailureException; import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; import io.github.easy4j.opencli.exception.OpenCliTimeoutException; -import io.github.easy4j.opencli.parser.OpenCliParsedFields; import io.github.easy4j.opencli.remote.OpenCliArgvToCollectParser; import io.github.easy4j.opencli.remote.OpenCliCollectRequest; import io.github.easy4j.opencli.remote.OpenCliRemoteAgentHttpClient; -import io.github.easy4j.opencli.core.support.SubprocessExecutionSupport; import io.github.easy4j.opencli.util.OpenCliStrings; -import java.io.ByteArrayOutputStream; import java.io.File; import java.io.IOException; import java.nio.charset.StandardCharsets; -import java.util.ArrayList; +import java.util.Arrays; import java.util.HashMap; import java.util.List; +import java.util.Locale; import java.util.Map; import java.util.Objects; -import java.util.UUID; import lombok.Getter; -import lombok.extern.slf4j.Slf4j; import org.apache.commons.exec.CommandLine; -import org.apache.commons.exec.DefaultExecuteResultHandler; -import org.apache.commons.exec.ExecuteException; -import org.apache.commons.exec.ExecuteWatchdog; /** - * 基于 Apache Commons Exec 的 OpenCLI 子进程执行封装。 - *

- * {@link #invoke(List)} 接受的参数为「紧跟可执行名之后」的完整 token 列表,形如 - * {@code [adapter, subcommand, ...]};本地模式下会自动拼接 {@link OpenCliProperties} 的 - * {@code leadingArguments}。 - *

- *

- * 当 {@link OpenCliProperties} 的 {@code executionTarget} 为 - * {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP} 时, - * 通过 {@link OpenCliRemoteAgentHttpClient} 调用远端 {@code POST /collect};此时 {@code leadingArguments} 不参与请求, - * argv 会被解析为 {@link OpenCliCollectRequest}(与 opencli-admin {@code agent_server} 契约一致)。 - *

- */ -@Slf4j -@Getter/** - - * OpenCLI subprocess execution wrapper based on Apache Commons Exec. - * - *

{@link #invoke(List)} accepts a token list that follows the executable name, - * typically {@code [adapter, subcommand, ...]}. In local mode, {@link OpenCliProperties} - * {@code leadingArguments} are automatically prepended.

- * - *

When {@link OpenCliProperties#getExecutionTarget()} is - * {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP}, the invocation is forwarded to a - * remote Agent via {@link OpenCliRemoteAgentHttpClient#collect(OpenCliCollectRequest)}.

- + * Literal-argv executor with a stable capacity owner, total local deadline and + * bounded output. Existing synchronous entry points are retained. Raw HTTP + * collect remains a separate legacy protocol, not a lossless process transport. * - * @author Loong Wan - * @since 3.0.0 - */ - +@Getter public class OpenCliExecutor implements AutoCloseable { - private final OpenCliProperties properties; - - /** - * 懒加载,仅远程模式使用。 - */ + private final OpenCliProcessRuntime processRuntime; private volatile OpenCliRemoteAgentHttpClient remoteAgentHttpClient; - /** - * @param properties 运行时配置,不得为 null - */ + /** @param properties configuration; process capacity is captured once */ public OpenCliExecutor(OpenCliProperties properties) { - this.properties = Objects.requireNonNull(properties, "properties"); - SubprocessExecutionSupport.configureMaxConcurrentExecutions(properties.getMaxConcurrentExecutions()); + this(properties, new OpenCliProcessRuntime(Objects.requireNonNull(properties, "properties") + .getMaxConcurrentExecutions())); } /** - * 执行 {@code opencli ...} 完整 argv(不含可执行文件本身)。 - * - * @param adapterAndRest 至少包含 adapter 名,后续为子命令与 flag;不得为 null - * @return 包含成功标记的执行结果 + * @param properties configuration + * @param processRuntime an explicitly shared, stable local capacity owner */ + public OpenCliExecutor(OpenCliProperties properties, OpenCliProcessRuntime processRuntime) { + this.properties = Objects.requireNonNull(properties, "properties"); + this.processRuntime = Objects.requireNonNull(processRuntime, "processRuntime"); + } + + /** @param adapterAndRest command and literal values @return execution result */ public OpenCliResult invoke(List adapterAndRest) { - Objects.requireNonNull(adapterAndRest, "adapterAndRest"); - if (properties.getExecutionTarget() == OpenCliExecutionTarget.REMOTE_AGENT_HTTP) { - log.debug("OpenCLI invoke remote agent argvSize={}", adapterAndRest.size()); - OpenCliCollectRequest req = - OpenCliArgvToCollectParser.parse( - adapterAndRest, - properties.getRemoteOutputFormat(), - properties.getRemoteCollectMode(), - properties.getRemoteCdpEndpoint()); - return remoteAgent().collect(req); - } - log.debug("OpenCLI invoke local argvSize={}", adapterAndRest.size()); - CommandLine cmd = buildCommandLine(adapterAndRest); - return run(cmd); + return invokeInternal(adapterAndRest, new OpenCliCancellationToken(), false); } /** - * @return 远程 Agent HTTP 客户端(懒加载) - */ - /** - * 释放远程传输资源:仅当 REMOTE_AGENT_HTTP 模式下已懒加载 HTTP 客户端时 - * 生效(实例级 shutdown,不影响 JVM 中其它 Unirest 使用方);本地模式为 - * 空操作。close 之后远程调用不可用,本地调用不受影响。 + * Cancellable local invocation. The legacy HTTP protocol does not claim a + * cancellable remote process; explicit tokens are rejected in remote mode. + * + * @param adapterAndRest command and literal values + * @param cancellationToken cancellation for this invocation only + * @return execution result */ - @Override - public void close() { - OpenCliRemoteAgentHttpClient client = remoteAgentHttpClient; - if (Objects.nonNull(client)) { - client.close(); + public OpenCliResult invoke(List adapterAndRest, OpenCliCancellationToken cancellationToken) { + return invokeInternal(adapterAndRest, Objects.requireNonNull(cancellationToken, "cancellationToken"), true); + } + + private OpenCliResult invokeInternal(List adapterAndRest, + OpenCliCancellationToken cancellationToken, boolean explicitCancellation) { + long submittedAtNanos = System.nanoTime(); + long timeoutMillis = properties.getCommandTimeoutMillis(); + List tokens = OpenCliArgSupport.snapshotValues(adapterAndRest, "adapterAndRest"); + if (tokens.isEmpty()) { + throw new IllegalArgumentException("adapterAndRest must contain at least the command identifier"); + } + if (OpenCliStrings.isBlank(tokens.get(0))) { + throw new IllegalArgumentException("adapterAndRest[0] command identifier must not be blank"); } + if (properties.getExecutionTarget() == OpenCliExecutionTarget.REMOTE_AGENT_HTTP) { + if (explicitCancellation) { + throw new UnsupportedOperationException("Explicit process cancellation is local-only for legacy collect"); + } + OpenCliCollectRequest req = OpenCliArgvToCollectParser.parse(tokens, + properties.getRemoteOutputFormat(), properties.getRemoteCollectMode(), properties.getRemoteCdpEndpoint()); + return remoteAgent().collect(req); + } + CommandLine commandLine = buildCommandLine(tokens); + return run(commandLine, timeoutMillis, submittedAtNanos, cancellationToken); } private OpenCliRemoteAgentHttpClient remoteAgent() { - if (Objects.isNull(remoteAgentHttpClient)) { + if (remoteAgentHttpClient == null) { synchronized (this) { - if (Objects.isNull(remoteAgentHttpClient)) { + if (remoteAgentHttpClient == null) { remoteAgentHttpClient = new OpenCliRemoteAgentHttpClient(properties); } } @@ -131,59 +104,44 @@ private OpenCliRemoteAgentHttpClient remoteAgent() { return remoteAgentHttpClient; } - /** - * 便捷重载:可变参数形式。 - * - * @param adapterAndRest adapter 及后续 CLI token - * @return 执行结果 - */ - public OpenCliResult invoke(String... adapterAndRest) { - List list = new ArrayList<>(); - if (Objects.nonNull(adapterAndRest)) { - for (String s : adapterAndRest) { - if (OpenCliStrings.isNotBlank(s)) { - list.add(s.trim()); - } - } + /** Close only the lazily created remote transport; local invocations own their processes. */ + @Override + public void close() { + OpenCliRemoteAgentHttpClient client = remoteAgentHttpClient; + if (Objects.nonNull(client)) { + client.close(); } - return invoke(list); } - /** - * 拼装 {@link CommandLine}:executable + leading + tokens。 - */ - private CommandLine buildCommandLine(List adapterAndRest) { - if (adapterAndRest.isEmpty()) { - throw new IllegalArgumentException("adapterAndRest must contain at least the adapter id"); - } - String exe = properties.getExecutable(); - if (OpenCliStrings.isBlank(exe)) { + /** @param adapterAndRest command and literal values @return execution result */ + public OpenCliResult invoke(String... adapterAndRest) { + Objects.requireNonNull(adapterAndRest, "adapterAndRest"); + return invoke(Arrays.asList(adapterAndRest)); + } + + private CommandLine buildCommandLine(List tokens) { + String executable = properties.getExecutable(); + if (OpenCliStrings.isBlank(executable)) { throw new IllegalStateException("opencli.executable must not be blank"); } - CommandLine cmd = new CommandLine(exe.trim()); - appendCleanArgs(cmd, properties.getLeadingArguments()); - appendCleanArgs(cmd, adapterAndRest); + String normalized = executable.trim(); + String lower = normalized.toLowerCase(Locale.ROOT); + if (System.getProperty("os.name").startsWith("Windows") + && (lower.endsWith(".cmd") || lower.endsWith(".bat"))) { + throw new UnsupportedOperationException("Use a native node executable plus the CLI JavaScript path; batch shims are not literal argv transports"); + } + CommandLine cmd = new LiteralCommandLine(normalized); + appendLiteralArgs(cmd, properties.getLeadingArguments(), "leadingArguments"); + appendLiteralArgs(cmd, tokens, "adapterAndRest"); return cmd; } - private static void appendCleanArgs(CommandLine cmd, List args) { - if (Objects.isNull(args) || args.isEmpty()) { - return; - } - for (String a : args) { - if (OpenCliStrings.isNotBlank(a)) { - cmd.addArgument(a.trim(), false); - } - } + private static void appendLiteralArgs(CommandLine cmd, List values, String field) { + if (values == null) { return; } + for (String value : OpenCliArgSupport.snapshotValues(values, field)) { cmd.addArgument(value, false); } } - /** - * 将 {@code --key=value} 以句柄安全形式追加(含空格时由 Commons Exec 处理)。 - * - * @param cmd 命令行 - * @param key 必须以 {@code --} 开头 - * @param value 非空值 - */ + /** Legacy explicit-quoting helper; not used by the literal process path. */ public static void appendQuotedKeyValue(CommandLine cmd, String key, String value) { Objects.requireNonNull(key, "key"); Objects.requireNonNull(value, "value"); @@ -194,159 +152,75 @@ public static void appendQuotedKeyValue(CommandLine cmd, String key, String valu cmd.addArgument(prefix + "=" + value, true); } - private OpenCliResult run(CommandLine commandLine) { - long timeoutMs = properties.getCommandTimeoutMillis(); - if (timeoutMs <= 0) { + private OpenCliResult run(CommandLine commandLine, long timeoutMillis, long submittedAtNanos, + OpenCliCancellationToken cancellationToken) { + if (timeoutMillis <= 0) { throw new IllegalStateException("opencli.command-timeout-millis must be positive"); } - - File workingDirectory = resolveWorkingDirectory(); - Map environment = buildEnvironment(); - SubprocessExecutionSupport.ExecutionRequest request = - new SubprocessExecutionSupport.ExecutionRequest( - commandLine, workingDirectory, environment, timeoutMs, - properties.getMaxOutputBytes()); - - String correlationId = UUID.randomUUID().toString(); + SubprocessExecutionSupport.ExecutionRequest request = new SubprocessExecutionSupport.ExecutionRequest( + commandLine, resolveWorkingDirectory(), buildEnvironment(), timeoutMillis, + effectiveCaptureLimit(properties.getMaxStdoutBytes()), + effectiveCaptureLimit(properties.getMaxStderrBytes()), properties.getCleanupGraceMillis(), + submittedAtNanos, cancellationToken); try { - SubprocessExecutionSupport.RunSession session = SubprocessExecutionSupport.execute(request); - return completeAfterWait( - correlationId, - timeoutMs, - session.getStdout(), - session.getStderr(), - session.getHandler(), - session.getWatchdog(), - session.isWaitTimedOut()); - } catch (IOException e) { - log.warn("OpenCLI spawn failed correlationId={}", correlationId); - throw new OpenCliExecutableFailureException( - "OpenCLI could not be started correlationId=" + correlationId, null); - } catch (InterruptedException e) { + return complete(processRuntime.execute(request)); + } catch (IOException ex) { + throw new OpenCliExecutableFailureException("OpenCLI process could not be started", null); + } catch (InterruptedException ex) { Thread.currentThread().interrupt(); - log.warn("OpenCLI interrupted correlationId={}", correlationId); - throw new OpenCliException("Interrupted while awaiting OpenCLI subprocess correlationId=" + correlationId, null, null); + throw new OpenCliException("Interrupted while awaiting OpenCLI subprocess", ex, null); } } - private File resolveWorkingDirectory() { - String wdProperty = properties.getWorkingDirectory(); - if (OpenCliStrings.isNotBlank(wdProperty)) { - File wd = new File(wdProperty.trim()); - if (!wd.isDirectory()) { - throw new OpenCliExecutableFailureException( - "opencli.working-directory is not an existing directory", null); - } - return wd; - } - return null; + private int effectiveCaptureLimit(int streamLimit) { + long legacyLimit = properties.getMaxOutputBytes(); + return legacyLimit > 0 ? (int) Math.min(streamLimit, legacyLimit) : streamLimit; } - private OpenCliResult completeAfterWait( - String correlationId, - long timeoutMs, - SubprocessExecutionSupport.BoundedOutputStream out, - SubprocessExecutionSupport.BoundedOutputStream err, - DefaultExecuteResultHandler handler, - ExecuteWatchdog watchdog, - boolean waitTimedOut) { - String stdoutStr = new String(out.toByteArray(), StandardCharsets.UTF_8); - String stderrStr = new String(err.toByteArray(), StandardCharsets.UTF_8); - if (out.isOverflowed()) { - log.warn("OpenCLI stdout truncated at maxOutputBytes={}", properties.getMaxOutputBytes()); - stdoutStr = stdoutStr + "\n[opencli-java-sdk] stdout truncated at maxOutputBytes=" - + properties.getMaxOutputBytes(); - } - if (err.isOverflowed()) { - log.warn("OpenCLI stderr truncated at maxOutputBytes={}", properties.getMaxOutputBytes()); - stderrStr = stderrStr + "\n[opencli-java-sdk] stderr truncated at maxOutputBytes=" - + properties.getMaxOutputBytes(); - } - OpenCliParsedFields parsed = OpenCliOutputParser.parseBestEffort(stdoutStr, stderrStr); - - if (waitTimedOut || watchdog.killedProcess()) { - log.warn("OpenCLI timed out correlationId={} timeoutMs={}", correlationId, timeoutMs); - OpenCliResult partial = snapshot(stdoutStr, stderrStr, readExitQuietly(handler), parsed); - throw new OpenCliTimeoutException( - "OpenCLI timed out after " + timeoutMs + " ms correlationId=" + correlationId, partial); - } - - Exception asyncFailure = handler.getException(); - if (asyncFailure instanceof ExecuteException) { - ExecuteException ex = (ExecuteException) asyncFailure; - log.warn("OpenCLI failed correlationId={} exitCode={}", correlationId, ex.getExitValue()); - OpenCliResult failed = snapshot(stdoutStr, stderrStr, normalizeExitValue(ex.getExitValue()), parsed); - throw new OpenCliNonZeroExitException( - "OpenCLI failed (exitCode=" + ex.getExitValue() + ") correlationId=" + correlationId, failed); - } - if (Objects.nonNull(asyncFailure)) { - log.error("OpenCLI async failure correlationId={}", correlationId); - OpenCliResult snapshot = snapshot(stdoutStr, stderrStr, readExitQuietly(handler), parsed); - throw new OpenCliException( - "OpenCLI async failure correlationId=" + correlationId, null, snapshot); - } - - final int exit; - try { - exit = handler.getExitValue(); - } catch (IllegalStateException e) { - throw new OpenCliException( - "OpenCLI completed without observable exit code correlationId=" + correlationId, - null, - snapshot(stdoutStr, stderrStr, null, parsed)); - } + private OpenCliResult complete(SubprocessExecutionSupport.RunSession session) { + String stdout = new String(session.getStdout().toByteArray(), StandardCharsets.UTF_8); + String stderr = new String(session.getStderr().toByteArray(), StandardCharsets.UTF_8); + OpenCliExecutionDetails details = session.getExecutionDetails(); + TerminationReason reason = details.getTerminationReason(); + Integer exit = session.getObservedExitCode(); + boolean success = reason == TerminationReason.PROCESS_EXIT && Integer.valueOf(0).equals(exit) + && details.isStreamsDrained(); + OpenCliResult result = OpenCliResult.builder().stdout(stdout).stderr(stderr).exitCode(exit) + .success(success).parsed(OpenCliOutputParser.parseBestEffort(stdout, stderr)) + .executionDetails(details).build(); + if (success) { return result; } + if (reason == TerminationReason.QUEUE_TIMEOUT || reason == TerminationReason.EXECUTION_TIMEOUT) { + throw new OpenCliTimeoutException("OpenCLI deadline exceeded: " + reason, result); + } + if (reason == TerminationReason.SPAWN_FAILED) { + throw new OpenCliExecutableFailureException("OpenCLI process could not be started", null, result); + } + if (reason == TerminationReason.PROCESS_EXIT && exit != null && exit != 0) { + throw new OpenCliNonZeroExitException("OpenCLI returned nonzero exitCode=" + exit, result); + } + // Native I/O errors may include executable paths or other invocation data. + throw new OpenCliException("OpenCLI execution ended: " + reason, result); + } - if (exit != 0) { - log.warn("OpenCLI non-zero exit correlationId={} exitCode={}", correlationId, exit); - OpenCliResult failed = snapshot(stdoutStr, stderrStr, exit, parsed); - throw new OpenCliNonZeroExitException( - "OpenCLI non-zero exit (exitCode=" + exit + ") correlationId=" + correlationId, failed); + private File resolveWorkingDirectory() { + String value = properties.getWorkingDirectory(); + if (OpenCliStrings.isNotBlank(value)) { + File directory = new File(value.trim()); + if (!directory.isDirectory()) { + throw new OpenCliExecutableFailureException("opencli.working-directory is not an existing directory", null); + } + return directory; } - - return OpenCliResult.builder() - .stdout(stdoutStr) - .stderr(stderrStr) - .exitCode(exit) - .success(true) - .parsed(parsed) - .build(); + return null; } private Map buildEnvironment() { Map env = new HashMap<>(System.getenv()); - if (Objects.nonNull(properties.getEnvironment())) { - for (Map.Entry e : properties.getEnvironment().entrySet()) { - if (Objects.nonNull(e.getKey()) && Objects.nonNull(e.getValue())) { - env.put(e.getKey(), e.getValue()); - } + if (properties.getEnvironment() != null) { + for (Map.Entry entry : new HashMap<>(properties.getEnvironment()).entrySet()) { + if (entry.getKey() != null && entry.getValue() != null) { env.put(entry.getKey(), entry.getValue()); } } } return env; } - - private static Integer readExitQuietly(DefaultExecuteResultHandler handler) { - try { - return normalizeExitValue(handler.getExitValue()); - } catch (IllegalStateException e) { - return null; - } - } - - private static Integer normalizeExitValue(int raw) { - if (raw == org.apache.commons.exec.Executor.INVALID_EXITVALUE) { - return null; - } - return raw; - } - - private static OpenCliResult snapshot( - String stdoutStr, String stderrStr, Integer exitCode, OpenCliParsedFields parsed) { - return OpenCliResult.builder() - .stdout(Objects.isNull(stdoutStr) ? "" : stdoutStr) - .stderr(Objects.isNull(stderrStr) ? "" : stderrStr) - .exitCode(exitCode) - .success(false) - .parsed(parsed) - .build(); - } } diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliOption.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliOption.java new file mode 100644 index 0000000..b6ca790 --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliOption.java @@ -0,0 +1,73 @@ +package io.github.easy4j.opencli.core; + +import java.util.Arrays; +import java.util.Collections; +import java.util.List; +import java.util.Objects; + +/** + * One immutable, schema-checked option occurrence. Preserve occurrence ordering + * by adding these to a request builder rather than using a Map for repeated flags. + * + * @author Loong Wan + * @since 3.0.0 + */ +public final class OpenCliOption { + private final OpenCliOptionSchema schema; + private final String value; + private final boolean negated; + + private OpenCliOption(OpenCliOptionSchema schema, String value, boolean negated) { + this.schema = schema; + this.value = value; + this.negated = negated; + } + + /** + * @param schema a valued-option definition + * @param value non-null value; false is the literal value "false", not absence + * @return an occurrence capturing the value immediately + */ + public static OpenCliOption value(OpenCliOptionSchema schema, Object value) { + Objects.requireNonNull(schema, "schema"); + Objects.requireNonNull(value, "value"); + if (schema.getKind() != OpenCliOptionSchema.Kind.VALUE) { + throw new IllegalArgumentException("A flag schema cannot consume a value"); + } + return new OpenCliOption(schema, OpenCliArgSupport.stringValue(value, "option value"), false); + } + + /** @param schema a flag definition @return explicit positive presence */ + public static OpenCliOption present(OpenCliOptionSchema schema) { + Objects.requireNonNull(schema, "schema"); + if (schema.getKind() == OpenCliOptionSchema.Kind.VALUE) { + throw new IllegalArgumentException("A valued option requires a value"); + } + return new OpenCliOption(schema, null, false); + } + + /** @param schema a negatable flag definition @return an explicit negative flag */ + public static OpenCliOption negated(OpenCliOptionSchema schema) { + Objects.requireNonNull(schema, "schema"); + if (schema.getKind() != OpenCliOptionSchema.Kind.NEGATABLE_FLAG) { + throw new IllegalArgumentException("This option schema does not declare negation"); + } + return new OpenCliOption(schema, null, true); + } + + /** @return immutable input definition */ + public OpenCliOptionSchema getSchema() { return schema; } + + /** @return the captured value, or null for a flag */ + public String getValue() { return value; } + + /** @return whether this is explicit negative presence */ + public boolean isNegated() { return negated; } + + /** @return immutable literal tokens; no quoting or trimming is applied */ + public List toTokens() { + String flag = negated ? "--no-" + schema.getName().substring(2) : schema.getName(); + return value == null ? Collections.singletonList(flag) + : Collections.unmodifiableList(Arrays.asList(flag, value)); + } +} diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliOptionSchema.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliOptionSchema.java new file mode 100644 index 0000000..3289973 --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliOptionSchema.java @@ -0,0 +1,73 @@ +package io.github.easy4j.opencli.core; + +import java.util.Objects; +import java.util.regex.Pattern; + +/** + * Explicit option input semantics. Definitions come from a known command contract, + * not guesses about a raw argument vector. This is not an output schema. + * + * @author Loong Wan + * @since 3.0.0 + */ +public final class OpenCliOptionSchema { + /** Input arity and negation semantics. */ + public enum Kind { FLAG, VALUE, NEGATABLE_FLAG } + + private static final Pattern NAME = Pattern.compile("(?:--[A-Za-z0-9][A-Za-z0-9-]*|-[A-Za-z0-9])"); + private final String name; + private final Kind kind; + private final boolean repeatable; + + private OpenCliOptionSchema(String name, Kind kind, boolean repeatable) { + Objects.requireNonNull(name, "name"); + if (!NAME.matcher(name).matches()) { + throw new IllegalArgumentException("Option schema requires a valid flag identifier"); + } + if (kind == Kind.NEGATABLE_FLAG && (!name.startsWith("--") || name.startsWith("--no-"))) { + throw new IllegalArgumentException("Negatable schema requires a positive long flag identifier"); + } + this.name = name; + this.kind = kind; + this.repeatable = repeatable; + } + + /** @param name flag identifier @return a presence-only, nonrepeatable flag */ + public static OpenCliOptionSchema flag(String name) { + return new OpenCliOptionSchema(name, Kind.FLAG, false); + } + + /** + * @param name option identifier + * @param repeatable whether repeated occurrences are accepted by the command + * @return an option taking one literal value per occurrence + */ + public static OpenCliOptionSchema value(String name, boolean repeatable) { + return new OpenCliOptionSchema(name, Kind.VALUE, repeatable); + } + + /** @param name positive long flag identifier @return a flag supporting explicit negation */ + public static OpenCliOptionSchema negatableFlag(String name) { + return new OpenCliOptionSchema(name, Kind.NEGATABLE_FLAG, false); + } + + /** @return canonical flag identifier */ + public String getName() { return name; } + + /** @return declared input kind */ + public Kind getKind() { return kind; } + + /** @return whether the command accepts repeated occurrences */ + public boolean isRepeatable() { return repeatable; } + + @Override + public boolean equals(Object other) { + if (this == other) { return true; } + if (!(other instanceof OpenCliOptionSchema)) { return false; } + OpenCliOptionSchema that = (OpenCliOptionSchema) other; + return name.equals(that.name) && kind == that.kind && repeatable == that.repeatable; + } + + @Override + public int hashCode() { return Objects.hash(name, kind, repeatable); } +} diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliProcessRuntime.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliProcessRuntime.java new file mode 100644 index 0000000..d373f64 --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliProcessRuntime.java @@ -0,0 +1,37 @@ +package io.github.easy4j.opencli.core; + +import io.github.easy4j.opencli.core.support.SubprocessExecutionSupport; +import java.io.IOException; + +/** + * Stable process-capacity owner. Pass the same instance to multiple executors to + * share a limit deliberately; constructing an unrelated executor cannot replace it. + */ +public final class OpenCliProcessRuntime { + private final SubprocessExecutionSupport.Runtime runtime; + + /** @param maxConcurrent positive limit, or zero for the CPU-derived default; negative is invalid */ + public OpenCliProcessRuntime(int maxConcurrent) { + runtime = new SubprocessExecutionSupport.Runtime(maxConcurrent); + } + + /** @return fixed capacity for this runtime */ + public int getMaxConcurrentExecutions() { return runtime.getMaxConcurrentExecutions(); } + + /** @return whether unconfirmed resource cleanup has quarantined this runtime */ + public boolean isQuarantined() { return runtime.isQuarantined(); } + + /** + * Low-level bridge used by the SDK executor. Results retain bounded process evidence; + * the executor maps terminal conditions to the existing SDK exception hierarchy. + * + * @param request immutable submission snapshot + * @return terminal execution evidence + * @throws IOException retained for compatibility with the low-level execution API + * @throws InterruptedException retained for compatibility; observed interruption is normally returned as CANCELLED + */ + public SubprocessExecutionSupport.RunSession execute(SubprocessExecutionSupport.ExecutionRequest request) + throws IOException, InterruptedException { + return runtime.execute(request); + } +} diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliResult.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliResult.java index 2dbfd7a..23d4631 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliResult.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliResult.java @@ -46,4 +46,7 @@ public class OpenCliResult { * 远端 Agent HTTP 响应全文;本地子进程模式或非调试场景下为 null。 */ private final String remoteRawHttpBody; + + /** Bounded local execution evidence, when available. */ + private final OpenCliExecutionDetails executionDetails; } diff --git a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java index fd3a6b5..cc3c7cd 100644 --- a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java +++ b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java @@ -1,235 +1,463 @@ package io.github.easy4j.opencli.core.support; -import lombok.Getter; -import org.apache.commons.exec.CommandLine; -import org.apache.commons.exec.DefaultExecuteResultHandler; -import org.apache.commons.exec.DefaultExecutor; -import org.apache.commons.exec.ExecuteWatchdog; -import org.apache.commons.exec.PumpStreamHandler; - +import io.github.easy4j.opencli.core.OpenCliCancellationToken; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails.CleanupState; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails.TerminationReason; import java.io.ByteArrayOutputStream; -import java.io.OutputStream; import java.io.File; import java.io.IOException; -import java.time.Duration; +import java.io.InputStream; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.HashMap; +import java.util.List; import java.util.Map; import java.util.Objects; import java.util.concurrent.Semaphore; -import java.util.concurrent.atomic.AtomicReference; +import java.util.concurrent.TimeUnit; +import lombok.Getter; +import org.apache.commons.exec.CommandLine; +import org.apache.commons.exec.DefaultExecuteResultHandler; +import org.apache.commons.exec.ExecuteException; +import org.apache.commons.exec.ExecuteWatchdog; +import java.time.Duration; /** - * Subprocess execution support based on Apache Commons Exec: watchdog timeout, - * bounded {@code waitFor}, and concurrency throttling. - * - * @author Loong Wan - * @since 3.0.0 - */public final class SubprocessExecutionSupport { - - /** Watchdog 触发后,handler 收尾等待的上限(毫秒)。 */ - public static final long WAIT_GRACE_MILLIS = 5_000L; + * Bounded, owned native-process execution. ProcessBuilder receives an exact argv + * vector, never a shell string. Commons Exec handler/watchdog views remain for + * compatibility with the earlier low-level RunSession API. + */ +public final class SubprocessExecutionSupport { + @FunctionalInterface + interface ProcessStarter { + Process start(ProcessBuilder builder) throws IOException; + } - private static final int DEFAULT_MAX_CONCURRENT = Math.max(2, Runtime.getRuntime().availableProcessors()); + @FunctionalInterface + interface WatchdogFactory { + ExecuteWatchdog create(long timeoutMillis); + } - private static final AtomicReference CONCURRENCY_LIMIT = - new AtomicReference<>(new Semaphore(DEFAULT_MAX_CONCURRENT)); + public static final long WAIT_GRACE_MILLIS = 5_000L; + public static final int DEFAULT_STDOUT_LIMIT = 8 * 1024 * 1024; + public static final int DEFAULT_STDERR_LIMIT = 2 * 1024 * 1024; + private static final long POLL_NANOS = TimeUnit.MILLISECONDS.toNanos(10L); + private static final int DEFAULT_MAX_CONCURRENT = Math.max(2, java.lang.Runtime.getRuntime().availableProcessors()); + private static final Object LEGACY_LOCK = new Object(); + private static Runtime legacyRuntime = new Runtime(0); + private static int legacySubmissions; - private SubprocessExecutionSupport() { - } + private SubprocessExecutionSupport() { } /** - * 配置本机 CLI 子进程全局并发上限;{@code maxConcurrent <= 0} 时恢复为默认值。 + * Configure only the deprecated static bridge, never an existing SDK client. + * Reconfiguration with active or queued submissions is rejected rather than + * creating a second live permit pool. * - * @param maxConcurrent 允许同时运行的子进程数 + * @param maxConcurrent positive capacity or zero for the default + * @deprecated pass an explicit OpenCliProcessRuntime to executors instead */ + @Deprecated public static void configureMaxConcurrentExecutions(int maxConcurrent) { - if (maxConcurrent <= 0) { - CONCURRENCY_LIMIT.set(new Semaphore(DEFAULT_MAX_CONCURRENT)); - return; + synchronized (LEGACY_LOCK) { + if (legacySubmissions != 0) { + throw new IllegalStateException("Cannot reconfigure the legacy runtime while submissions exist"); + } + legacyRuntime = new Runtime(maxConcurrent); } - CONCURRENCY_LIMIT.set(new Semaphore(maxConcurrent)); } - /** - * @return 未显式配置时的默认并发上限 - */ - public static int defaultMaxConcurrentExecutions() { - return DEFAULT_MAX_CONCURRENT; - } + public static int defaultMaxConcurrentExecutions() { return DEFAULT_MAX_CONCURRENT; } - /** - * 在并发许可内启动子进程并阻塞至结束、超时或被强制销毁。 - */ + /** Legacy entry point using one stable, explicitly configured runtime. */ public static RunSession execute(ExecutionRequest request) throws IOException, InterruptedException { Objects.requireNonNull(request, "request"); - Semaphore limit = CONCURRENCY_LIMIT.get(); - limit.acquire(); + Runtime selected; + synchronized (LEGACY_LOCK) { + selected = legacyRuntime; + legacySubmissions++; + } try { - return executeWithinLimit(request); + return selected.execute(request); } finally { - limit.release(); + synchronized (LEGACY_LOCK) { legacySubmissions--; } + } + } + + /** Internal capacity/cleanup owner exposed through OpenCliProcessRuntime. */ + public static final class Runtime { + private final int maxConcurrentExecutions; + private final Semaphore permits; + private final ProcessStarter processStarter; + private final WatchdogFactory watchdogFactory; + private volatile boolean quarantined; + + public Runtime(int maxConcurrent) { + this(maxConcurrent, ProcessBuilder::start, SubprocessExecutionSupport::newWatchdog); + } + + Runtime(int maxConcurrent, ProcessStarter processStarter, WatchdogFactory watchdogFactory) { + if (maxConcurrent < 0) { + throw new IllegalArgumentException("maxConcurrentExecutions must not be negative"); + } + maxConcurrentExecutions = maxConcurrent == 0 ? DEFAULT_MAX_CONCURRENT : maxConcurrent; + permits = new Semaphore(maxConcurrentExecutions, true); + this.processStarter = Objects.requireNonNull(processStarter, "processStarter"); + this.watchdogFactory = Objects.requireNonNull(watchdogFactory, "watchdogFactory"); + } + + public int getMaxConcurrentExecutions() { return maxConcurrentExecutions; } + public boolean isQuarantined() { return quarantined; } + + public RunSession execute(ExecutionRequest request) throws IOException, InterruptedException { + Objects.requireNonNull(request, "request"); + long budget = nanos(request.timeoutMillis, "timeoutMillis"); + BoundedCapture out = new BoundedCapture(request.stdoutLimitBytes); + BoundedCapture err = new BoundedCapture(request.stderrLimitBytes); + Process process = null; + Reader stdoutReader = null; + Reader stderrReader = null; + ExecuteWatchdog watchdog = null; + TerminationReason reason = null; + IOException ioFailure = null; + boolean acquired = false; + boolean interrupted = false; + boolean cleanupOperationFailed = false; + long queueWaitMillis = 0L; + try { + while (!acquired && reason == null) { + if (Thread.interrupted()) { + interrupted = true; + reason = TerminationReason.CANCELLED; + } else if (request.cancellationToken.isCancelled()) { + reason = TerminationReason.CANCELLED; + } else if (quarantined) { + reason = TerminationReason.RUNTIME_UNAVAILABLE; + } else { + long remaining = remaining(request.submittedAtNanos, budget); + if (remaining <= 0) { + reason = TerminationReason.QUEUE_TIMEOUT; + } else { + acquired = permits.tryAcquire(Math.min(POLL_NANOS, remaining), TimeUnit.NANOSECONDS); + } + } + } + queueWaitMillis = elapsedMillis(request.submittedAtNanos); + if (acquired && reason == null) { + if (Thread.interrupted()) { + interrupted = true; + reason = TerminationReason.CANCELLED; + } else if (request.cancellationToken.isCancelled()) { + reason = TerminationReason.CANCELLED; + } else if (quarantined) { + reason = TerminationReason.RUNTIME_UNAVAILABLE; + } else if (remaining(request.submittedAtNanos, budget) <= 0) { + reason = TerminationReason.QUEUE_TIMEOUT; + } + } + if (acquired && reason == null) { + ProcessBuilder builder = new ProcessBuilder(request.nativeArgv); + if (request.workingDirectory != null) { builder.directory(request.workingDirectory); } + if (request.environment != null) { + builder.environment().clear(); + builder.environment().putAll(request.environment); + } + process = processStarter.start(builder); + process.getOutputStream().close(); + stdoutReader = new Reader(process.getInputStream(), out, "opencli-stdout"); + stderrReader = new Reader(process.getErrorStream(), err, "opencli-stderr"); + stdoutReader.start(); + stderrReader.start(); + long remaining = remaining(request.submittedAtNanos, budget); + try { + watchdog = watchdogFactory.create( + Math.max(1L, TimeUnit.NANOSECONDS.toMillis(Math.max(0L, remaining)))); + watchdog.start(process); + } catch (RuntimeException ex) { + ioFailure = new IOException("Failed to initialize execution watchdog", ex); + reason = TerminationReason.IO_FAILURE; + } + while (reason == null) { + if (out.isTruncated() || err.isTruncated()) { + reason = TerminationReason.OUTPUT_LIMIT; + } else if (Thread.interrupted()) { + interrupted = true; + reason = TerminationReason.CANCELLED; + } else if (request.cancellationToken.isCancelled()) { + reason = TerminationReason.CANCELLED; + } else if (Objects.nonNull(stdoutReader.failure) || Objects.nonNull(stderrReader.failure)) { + ioFailure = Objects.nonNull(stdoutReader.failure) + ? stdoutReader.failure : stderrReader.failure; + reason = TerminationReason.IO_FAILURE; + } else if (!process.isAlive() && !stdoutReader.isAlive() && !stderrReader.isAlive()) { + reason = watchdog.killedProcess() ? TerminationReason.EXECUTION_TIMEOUT : TerminationReason.PROCESS_EXIT; + } else if (watchdog.killedProcess() || remaining(request.submittedAtNanos, budget) <= 0) { + reason = TerminationReason.EXECUTION_TIMEOUT; + } else { + TimeUnit.NANOSECONDS.sleep(Math.min(POLL_NANOS, Math.max(1L, + remaining(request.submittedAtNanos, budget)))); + } + } + } + } catch (InterruptedException ex) { + interrupted = true; + reason = TerminationReason.CANCELLED; + } catch (IOException ex) { + ioFailure = ex; + reason = process == null ? TerminationReason.SPAWN_FAILED : TerminationReason.IO_FAILURE; + } catch (RuntimeException ex) { + ioFailure = new IOException("Native process setup or execution failure", ex); + reason = process == null ? TerminationReason.SPAWN_FAILED : TerminationReason.IO_FAILURE; + } finally { + try { + try { + if (Objects.nonNull(watchdog)) { + watchdog.stop(); + } + } catch (RuntimeException ex) { + cleanupOperationFailed = true; + } + long cleanupStart = System.nanoTime(); + long cleanupBudget = nanos(request.cleanupGraceMillis, "cleanupGraceMillis"); + if (Objects.nonNull(process)) { + boolean forceSent = false; + if (process.isAlive()) { + try { + process.destroy(); + } catch (RuntimeException ex) { + cleanupOperationFailed = true; + forceSent = true; + if (!tryForceStop(process)) { cleanupOperationFailed = true; } + } + } + while (remaining(cleanupStart, cleanupBudget) > 0 + && (process.isAlive() || alive(stdoutReader) || alive(stderrReader))) { + if (Thread.interrupted()) { interrupted = true; } + if (process.isAlive() && !forceSent + && System.nanoTime() - cleanupStart >= Math.min(TimeUnit.MILLISECONDS.toNanos(100L), cleanupBudget / 2)) { + if (!tryForceStop(process)) { cleanupOperationFailed = true; } + forceSent = true; + } + try { + TimeUnit.NANOSECONDS.sleep(Math.min(POLL_NANOS, + Math.max(1L, remaining(cleanupStart, cleanupBudget)))); + } catch (InterruptedException ex) { + interrupted = true; + } + } + if (process.isAlive() && !tryForceStop(process)) { cleanupOperationFailed = true; } + if (process.isAlive() || alive(stdoutReader) || alive(stderrReader)) { + // A fixed runtime cannot accumulate unlimited uncertain children/readers. + quarantined = true; + if (reason == TerminationReason.PROCESS_EXIT) { reason = TerminationReason.CLEANUP_UNCONFIRMED; } + } + } + } finally { + out.freeze(); + err.freeze(); + if (acquired) { permits.release(); } + if (interrupted) { Thread.currentThread().interrupt(); } + } + } + if (reason == TerminationReason.PROCESS_EXIT && (out.isTruncated() || err.isTruncated())) { + reason = TerminationReason.OUTPUT_LIMIT; + } + Integer exit = process != null && !process.isAlive() ? process.exitValue() : null; + DefaultExecuteResultHandler handler = new DefaultExecuteResultHandler(); + if (ioFailure != null) { + handler.onProcessFailed(new ExecuteException("Native process I/O failure", exit == null ? -1 : exit, ioFailure)); + } else if (exit != null && exit != 0) { + handler.onProcessFailed(new ExecuteException("Native process returned nonzero status", exit)); + } else if (exit != null) { + handler.onProcessComplete(exit); + } + OpenCliExecutionDetails details = OpenCliExecutionDetails.builder() + .terminationReason(reason) + .cleanupState(process == null ? CleanupState.NOT_STARTED + : process.isAlive() ? CleanupState.UNCONFIRMED : CleanupState.ROOT_EXIT_CONFIRMED) + .processStarted(process != null).streamsDrained(!alive(stdoutReader) && !alive(stderrReader)) + .cleanupOperationFailed(cleanupOperationFailed) + .stdoutCapturedBytes(out.size()).stdoutObservedBytes(out.observed()).stdoutTruncated(out.isTruncated()) + .stderrCapturedBytes(err.size()).stderrObservedBytes(err.observed()).stderrTruncated(err.isTruncated()) + .elapsedMillis(elapsedMillis(request.submittedAtNanos)).queueWaitMillis(queueWaitMillis) + .descendantsExitConfirmed(false).build(); + // Preserve the legacy RunSession watchdog view even when nothing was started. + ExecuteWatchdog watchdogView = Objects.nonNull(watchdog) ? watchdog : newWatchdog(request.timeoutMillis); + return new RunSession(out, err, handler, watchdogView, request.timeoutMillis, + reason == TerminationReason.QUEUE_TIMEOUT || reason == TerminationReason.EXECUTION_TIMEOUT, + details, exit, ioFailure); } } - private static RunSession executeWithinLimit(ExecutionRequest request) throws IOException, InterruptedException { - long timeoutMs = Math.max(1L, request.getTimeoutMillis()); - BoundedOutputStream out = new BoundedOutputStream(request.getMaxOutputBytes()); - BoundedOutputStream err = new BoundedOutputStream(request.getMaxOutputBytes()); + private static ExecuteWatchdog newWatchdog(long timeoutMillis) { + return ExecuteWatchdog.builder().setTimeout(Duration.ofMillis(timeoutMillis)).get(); + } + + private static boolean alive(Thread thread) { return thread != null && thread.isAlive(); } + private static boolean tryForceStop(Process process) { + try { + process.destroyForcibly(); + return true; + } catch (RuntimeException ex) { + return false; + } + } + private static long remaining(long start, long budget) { return budget - (System.nanoTime() - start); } + private static long elapsedMillis(long start) { return TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - start); } - DefaultExecutor.Builder builder = DefaultExecutor.builder(); - if (request.getWorkingDirectory() != null) { - builder.setWorkingDirectory(request.getWorkingDirectory()); + private static long nanos(long millis, String field) { + if (millis <= 0 || millis > Long.MAX_VALUE / 1_000_000L) { + throw new IllegalArgumentException(field + " must be positive and fit a monotonic nanosecond budget"); } - DefaultExecutor executor = builder.get(); - executor.setStreamHandler(new PumpStreamHandler(out, err)); + return millis * 1_000_000L; + } - ExecuteWatchdog watchdog = - ExecuteWatchdog.builder().setTimeout(Duration.ofMillis(timeoutMs)).get(); - executor.setWatchdog(watchdog); + private static final class BoundedCapture extends ByteArrayOutputStream { + private final int limit; + private long observed; + private boolean truncated; + private boolean frozen; - DefaultExecuteResultHandler handler = new DefaultExecuteResultHandler(); - Map environment = request.getEnvironment(); - if (environment != null) { - executor.execute(request.getCommandLine(), environment, handler); - } else { - executor.execute(request.getCommandLine(), handler); + BoundedCapture(int limit) { + super(Math.min(8192, limit)); + this.limit = limit; } - boolean finished = awaitResult(handler, timeoutMs + WAIT_GRACE_MILLIS); - boolean waitTimedOut = !finished; - if (waitTimedOut) { - watchdog.destroyProcess(); - awaitResult(handler, WAIT_GRACE_MILLIS); + @Override + public synchronized void write(byte[] bytes, int offset, int length) { + if (frozen) { return; } + observed = observed > Long.MAX_VALUE - length ? Long.MAX_VALUE : observed + length; + int retained = Math.min(length, limit - count); + super.write(bytes, offset, retained); + truncated |= retained < length; } - return new RunSession(out, err, handler, watchdog, timeoutMs, waitTimedOut); + @Override + public synchronized void write(int value) { write(new byte[]{(byte) value}, 0, 1); } + synchronized boolean isTruncated() { return truncated; } + synchronized long observed() { return observed; } + synchronized void freeze() { frozen = true; } } - private static boolean awaitResult(DefaultExecuteResultHandler handler, long timeoutMillis) - throws InterruptedException { - long deadline = System.currentTimeMillis() + Math.max(1L, timeoutMillis); - while (!handler.hasResult()) { - if (System.currentTimeMillis() >= deadline) { - return false; + private static final class Reader extends Thread { + private final InputStream input; + private final BoundedCapture capture; + private volatile IOException failure; + + Reader(InputStream input, BoundedCapture capture, String name) { + super(name); + this.input = input; + this.capture = capture; + setDaemon(true); + } + + @Override + public void run() { + try (InputStream stream = input) { + byte[] buffer = new byte[8192]; + int size; + while ((size = stream.read(buffer)) != -1) { + capture.write(buffer, 0, size); + if (capture.isTruncated()) { return; } + } + } catch (IOException ex) { + failure = ex; } - Thread.sleep(Math.min(50L, deadline - System.currentTimeMillis())); } - return true; } @Getter public static final class ExecutionRequest { - private final CommandLine commandLine; + private final List nativeArgv; private final File workingDirectory; private final Map environment; private final long timeoutMillis; - private final long maxOutputBytes; - - public ExecutionRequest( - CommandLine commandLine, - File workingDirectory, - Map environment, - long timeoutMillis) { - this(commandLine, workingDirectory, environment, timeoutMillis, 0L); - } + private final int stdoutLimitBytes; + private final int stderrLimitBytes; + private final long cleanupGraceMillis; + private final long submittedAtNanos; + private final OpenCliCancellationToken cancellationToken; + + public ExecutionRequest(CommandLine commandLine, File workingDirectory, + Map environment, long timeoutMillis) { + this(commandLine, workingDirectory, environment, timeoutMillis, + DEFAULT_STDOUT_LIMIT, DEFAULT_STDERR_LIMIT, WAIT_GRACE_MILLIS, + System.nanoTime(), new OpenCliCancellationToken()); + } + + /** Legacy per-stream ceiling; nonpositive values retain finite default budgets. */ + public ExecutionRequest(CommandLine commandLine, File workingDirectory, + Map environment, long timeoutMillis, long maxOutputBytes) { + this(commandLine, workingDirectory, environment, timeoutMillis, + legacyLimit(maxOutputBytes, DEFAULT_STDOUT_LIMIT), + legacyLimit(maxOutputBytes, DEFAULT_STDERR_LIMIT), WAIT_GRACE_MILLIS, + System.nanoTime(), new OpenCliCancellationToken()); + } - public ExecutionRequest( - CommandLine commandLine, - File workingDirectory, - Map environment, - long timeoutMillis, - long maxOutputBytes) { - this.commandLine = Objects.requireNonNull(commandLine, "commandLine"); - this.workingDirectory = workingDirectory; - this.environment = environment; - this.timeoutMillis = timeoutMillis; - this.maxOutputBytes = maxOutputBytes; + private static int legacyLimit(long maxOutputBytes, int defaultLimit) { + return maxOutputBytes > 0 ? (int) Math.min(defaultLimit, maxOutputBytes) : defaultLimit; + } + + public ExecutionRequest(CommandLine commandLine, File workingDirectory, + Map environment, long timeoutMillis, int stdoutLimitBytes, + int stderrLimitBytes, long cleanupGraceMillis, long submittedAtNanos, + OpenCliCancellationToken cancellationToken) { + this.commandLine = Objects.requireNonNull(commandLine, "commandLine"); + List argv = new ArrayList<>(Arrays.asList(commandLine.toStrings())); + for (int i = 0; i < argv.size(); i++) { + if (argv.get(i) == null) { throw new IllegalArgumentException("nativeArgv[" + i + "] must not be null"); } + } + nativeArgv = Collections.unmodifiableList(argv); + this.workingDirectory = workingDirectory; + this.environment = environment == null ? null : Collections.unmodifiableMap(new HashMap<>(environment)); + nanos(timeoutMillis, "timeoutMillis"); + nanos(cleanupGraceMillis, "cleanupGraceMillis"); + if (stdoutLimitBytes <= 0 || stderrLimitBytes <= 0) { + throw new IllegalArgumentException("stdout/stderr capture budgets must be positive"); } + this.timeoutMillis = timeoutMillis; + this.stdoutLimitBytes = stdoutLimitBytes; + this.stderrLimitBytes = stderrLimitBytes; + this.cleanupGraceMillis = cleanupGraceMillis; + this.submittedAtNanos = submittedAtNanos; + this.cancellationToken = Objects.requireNonNull(cancellationToken, "cancellationToken"); + } } @Getter public static final class RunSession { - - private final BoundedOutputStream stdout; - private final BoundedOutputStream stderr; + private final ByteArrayOutputStream stdout; + private final ByteArrayOutputStream stderr; private final DefaultExecuteResultHandler handler; private final ExecuteWatchdog watchdog; private final long timeoutMillis; private final boolean waitTimedOut; - - RunSession( - BoundedOutputStream stdout, - BoundedOutputStream stderr, - DefaultExecuteResultHandler handler, - ExecuteWatchdog watchdog, - long timeoutMillis, - boolean waitTimedOut) { + private final OpenCliExecutionDetails executionDetails; + private final Integer observedExitCode; + private final IOException ioFailure; + + RunSession(ByteArrayOutputStream stdout, ByteArrayOutputStream stderr, + DefaultExecuteResultHandler handler, ExecuteWatchdog watchdog, long timeoutMillis, + boolean waitTimedOut, OpenCliExecutionDetails executionDetails, + Integer observedExitCode, IOException ioFailure) { this.stdout = stdout; this.stderr = stderr; this.handler = handler; this.watchdog = watchdog; this.timeoutMillis = timeoutMillis; this.waitTimedOut = waitTimedOut; + this.executionDetails = executionDetails; + this.observedExitCode = observedExitCode; + this.ioFailure = ioFailure; } - public boolean timedOut() { - return waitTimedOut || watchdog.killedProcess(); - } + public boolean timedOut() { return waitTimedOut; } - boolean isStdoutOverflowed() { - return stdout.isOverflowed(); - } + boolean isStdoutOverflowed() { return executionDetails.isStdoutTruncated(); } - boolean isStderrOverflowed() { - return stderr.isOverflowed(); - } - } - - /** - * 有界内存输出流:超过上限的字节直接丢弃(保留前 maxBytes 字节), - * 并置溢出标志供调用方追加截断标记。close 为空操作(纯内存流)。 - */ - public static final class BoundedOutputStream extends OutputStream { - - private final ByteArrayOutputStream delegate = new ByteArrayOutputStream(); - private final long maxBytes; - private boolean overflowed; - - BoundedOutputStream(long maxBytes) { - // maxBytes <= 0 视为不限制 - this.maxBytes = Math.max(0L, maxBytes); - } - - @Override - public synchronized void write(int b) { - write(new byte[] {(byte) b}, 0, 1); - } - - @Override - public synchronized void write(byte[] b, int off, int len) { - if (maxBytes == 0L) { - delegate.write(b, off, len); - return; - } - long remaining = maxBytes - delegate.size(); - if (remaining <= 0L) { - overflowed = true; - return; - } - if (len > remaining) { - delegate.write(b, off, (int) remaining); - overflowed = true; - } else { - delegate.write(b, off, len); - } - } - - public synchronized byte[] toByteArray() { - return delegate.toByteArray(); - } - - public synchronized boolean isOverflowed() { - return overflowed; - } + boolean isStderrOverflowed() { return executionDetails.isStderrTruncated(); } } } diff --git a/src/main/java/io/github/easy4j/opencli/exception/OpenCliExecutableFailureException.java b/src/main/java/io/github/easy4j/opencli/exception/OpenCliExecutableFailureException.java index 378bd95..270f2c7 100644 --- a/src/main/java/io/github/easy4j/opencli/exception/OpenCliExecutableFailureException.java +++ b/src/main/java/io/github/easy4j/opencli/exception/OpenCliExecutableFailureException.java @@ -2,14 +2,14 @@ import io.github.easy4j.opencli.core.OpenCliResult; -/** - * Thrown when the OpenCLI executable cannot be started (PATH, permissions, invalid arguments, etc.). - * - * @author Loong Wan - * @since 3.0.0 - */public class OpenCliExecutableFailureException extends OpenCliException { - +/** Failure to start the configured executable. */ +public class OpenCliExecutableFailureException extends OpenCliException { public OpenCliExecutableFailureException(String message, Throwable cause) { super(message, cause, null); } + + /** Retains a no-process-started snapshot without inventing an exit code. */ + public OpenCliExecutableFailureException(String message, Throwable cause, OpenCliResult partialResult) { + super(message, cause, partialResult); + } } diff --git a/src/test/java/io/github/easy4j/opencli/contract/ContractProbe.java b/src/test/java/io/github/easy4j/opencli/contract/ContractProbe.java new file mode 100644 index 0000000..3c50a12 --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/contract/ContractProbe.java @@ -0,0 +1,16 @@ +package io.github.easy4j.opencli.contract; + +import java.nio.charset.StandardCharsets; +import java.util.Base64; + +/** Offline child process: emits every actual JVM argument, including empty values. */ +public final class ContractProbe { + private ContractProbe() { } + + public static void main(String[] args) { + System.out.println("argc:" + args.length); + for (String arg : args) { + System.out.println("arg:" + Base64.getEncoder().encodeToString(arg.getBytes(StandardCharsets.UTF_8))); + } + } +} diff --git a/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java new file mode 100644 index 0000000..88247cf --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java @@ -0,0 +1,44 @@ +package io.github.easy4j.opencli.contract; + +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.Arrays; + +/** Offline, self-bounded child fixture. Release files allow cleanup even against a broken SDK. */ +public final class LifecycleProbe { + private LifecycleProbe() { } + + public static void main(String[] args) throws Exception { + String mode = args[0]; + if ("utf8".equals(mode)) { + System.out.write("中文".getBytes(StandardCharsets.UTF_8)); + return; + } + if ("stdout".equals(mode) || "stderr".equals(mode)) { + byte[] block = new byte[8192]; + Arrays.fill(block, (byte) 'x'); + int remaining = Integer.parseInt(args[1]); + while (remaining > 0) { + int size = Math.min(block.length, remaining); + if ("stdout".equals(mode)) { System.out.write(block, 0, size); } + else { System.err.write(block, 0, size); } + remaining -= size; + } + return; + } + Path marker = Paths.get(args[1]); + Files.write(marker, "started".getBytes(StandardCharsets.UTF_8)); + if ("write".equals(mode)) { return; } + Path release = Paths.get(args[2]); + long start = System.nanoTime(); + int tick = 0; + while (!Files.exists(release) && System.nanoTime() - start < 10_000_000_000L) { + if ("heartbeat".equals(mode)) { + Files.write(marker, Integer.toString(++tick).getBytes(StandardCharsets.UTF_8)); + } + Thread.sleep(20L); + } + } +} diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java new file mode 100644 index 0000000..e50a631 --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java @@ -0,0 +1,171 @@ +package io.github.easy4j.opencli.contract; + +import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.browser.OpenCliBrowserClient; +import io.github.easy4j.opencli.core.OpenCliAdapterChannel; +import io.github.easy4j.opencli.core.OpenCliAdapterCommandRequest; +import io.github.easy4j.opencli.core.OpenCliArgSupport; +import io.github.easy4j.opencli.core.OpenCliExecutor; +import io.github.easy4j.opencli.core.OpenCliResult; +import java.io.BufferedReader; +import java.io.File; +import java.io.InputStream; +import java.io.InputStreamReader; +import java.io.StringReader; +import java.nio.charset.StandardCharsets; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Base64; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.stream.Stream; +import org.junit.jupiter.api.DynamicTest; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.TestFactory; +import static org.junit.jupiter.api.Assertions.*; + +/** Shared Java 8-compatible contract tests, with a real child rather than Recording executor. */ +class OpenCliArgvContractTest { + private static OpenCliProperties properties() { + OpenCliProperties p = new OpenCliProperties(); + String exe = System.getProperty("os.name").startsWith("Windows") ? "java.exe" : "java"; + p.setExecutable(new File(new File(System.getProperty("java.home"), "bin"), exe).getAbsolutePath()); + p.setLeadingArguments(new ArrayList<>(Arrays.asList("-cp", + System.getProperty("surefire.test.class.path", System.getProperty("java.class.path")), + ContractProbe.class.getName()))); + p.setCommandTimeoutMillis(10000L); + return p; + } + + private static List received(OpenCliResult result) throws Exception { + assertTrue(result.isSuccess()); + List actual = new ArrayList<>(); + try (BufferedReader reader = new BufferedReader(new StringReader(result.getStdout()))) { + String header = reader.readLine(); + assertNotNull(header, "child produced no argv evidence"); + assertTrue(header.startsWith("argc:"), "missing child protocol header"); + int count = Integer.parseInt(header.substring(5)); + for (int i = 0; i < count; i++) { + String line = reader.readLine(); + assertNotNull(line, "incomplete child output"); + assertTrue(line.startsWith("arg:")); + actual.add(new String(Base64.getDecoder().decode(line.substring(4)), StandardCharsets.UTF_8)); + } + assertNull(reader.readLine(), "unexpected extra child output"); + } + return actual; + } + + @TestFactory + Stream sharedVectorsReachEveryRawEntryPoint() throws Exception { + List tests = new ArrayList<>(); + InputStream resource = getClass().getResourceAsStream("/opencli-contracts/v1/argv.tsv"); + assertNotNull(resource, "shared fixture is required"); + try (BufferedReader reader = new BufferedReader(new InputStreamReader(resource, StandardCharsets.UTF_8))) { + String line; + while ((line = reader.readLine()) != null) { + String[] fields = line.split("\t", -1); + List expected = new ArrayList<>(); + for (int i = 1; i < fields.length; i++) { + expected.add(new String(Base64.getDecoder().decode(fields[i]), StandardCharsets.UTF_8)); + } + for (int mode = 0; mode < 4; mode++) { + final int entry = mode; + tests.add(DynamicTest.dynamicTest(fields[0] + "/entry-" + mode, () -> { + OpenCliExecutor executor = new OpenCliExecutor(properties()); + List before = new ArrayList<>(expected); + OpenCliResult result; + if (entry == 0) { + result = executor.invoke(expected); + } else if (entry == 1) { + result = executor.invoke(expected.toArray(new String[0])); + } else { + OpenCliAdapterChannel channel = new OpenCliAdapterChannel(executor, expected.get(0)); + List rest = expected.subList(1, expected.size()); + result = entry == 2 ? channel.invoke(rest) : channel.invoke(rest.toArray(new String[0])); + } + assertEquals(before, expected, "caller list changed"); + assertEquals(expected, received(result), "full argv changed at child boundary"); + })); + } + } + } + assertEquals(24, tests.size(), "fixture denominator changed; review sources.lock.json"); + return tests.stream(); + } + + @Test + void structuredPositionalsAndValuesReachChildUnchanged() throws Exception { + Map options = new LinkedHashMap<>(); + options.put("text", " value "); + OpenCliAdapterCommandRequest request = OpenCliAdapterCommandRequest.builder() + .subcommand("echo").positional("").positional(" positional ").options(options).build(); + assertEquals(Arrays.asList("demo", "echo", "", " positional ", "--text", " value "), + received(new OpenCliAdapterChannel(new OpenCliExecutor(properties()), "demo").invoke(request))); + } + + @Test + void typedBrowserFillCanClearAField() throws Exception { + OpenCliBrowserClient browser = new OpenCliBrowserClient(new OpenCliExecutor(properties())); + assertEquals(Arrays.asList("browser", "contract", "fill", "#input", ""), + received(browser.session("contract").fill("#input", "", null, null))); + } + + @Test + void rawMergePreservesEmptyAndPaddedValues() throws Exception { + List prefix = Arrays.asList("demo", "echo", ""); + List extra = Arrays.asList(" x ", "--", "-literal"); + assertEquals(Arrays.asList("demo", "echo", "", " x ", "--", "-literal"), + received(new OpenCliExecutor(properties()).invoke(OpenCliArgSupport.merge(prefix, extra)))); + assertEquals(Arrays.asList("demo", "echo", ""), prefix); + } + + @Test + void leadingArgumentsPreserveEmptyAndPaddedValues() throws Exception { + OpenCliProperties p = properties(); + p.getLeadingArguments().add(""); + p.getLeadingArguments().add(" leading "); + assertEquals(Arrays.asList("", " leading ", "demo"), + received(new OpenCliExecutor(p).invoke("demo"))); + } + + @Test + void nullRawTokenIsRejectedWithoutLeakingOtherTokens() { + OpenCliExecutor executor = new OpenCliExecutor(properties()); + IllegalArgumentException error = assertThrows(IllegalArgumentException.class, + () -> executor.invoke(Arrays.asList("demo", "SECRET_MARKER", null))); + assertTrue(error.getMessage().contains("2"), "validation must identify null index"); + assertFalse(error.getMessage().contains("SECRET_MARKER")); + } + + @Test + void blankCommandIdentifierIsRejectedBeforeSpawn() { + OpenCliExecutor executor = new OpenCliExecutor(properties()); + assertThrows(IllegalArgumentException.class, () -> executor.invoke(Arrays.asList("", "demo"))); + assertThrows(IllegalArgumentException.class, () -> OpenCliAdapterCommandRequest.builder() + .subcommand(" ").build().toSubcommandAndArgs()); + } + + @Test + void nullVarargsContainerIsRejectedConsistently() { + OpenCliExecutor executor = new OpenCliExecutor(properties()); + assertThrows(NullPointerException.class, () -> executor.invoke((String[]) null)); + assertThrows(NullPointerException.class, + () -> new OpenCliAdapterChannel(executor, "demo").invoke((String[]) null)); + } + + @Test + void nullLeadingTokenIsRejectedBeforeSpawn() { + OpenCliProperties p = properties(); + p.getLeadingArguments().add(null); + assertThrows(IllegalArgumentException.class, () -> new OpenCliExecutor(p).invoke("demo")); + } + + @Test + void nullMergedTokenIsRejected() { + assertThrows(IllegalArgumentException.class, + () -> OpenCliArgSupport.merge(Arrays.asList("demo", null), Collections.emptyList())); + } +} diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessBoundaryTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessBoundaryTest.java new file mode 100644 index 0000000..389140c --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessBoundaryTest.java @@ -0,0 +1,162 @@ +package io.github.easy4j.opencli.contract; + +import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.core.OpenCliCancellationToken; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails.TerminationReason; +import io.github.easy4j.opencli.core.OpenCliExecutor; +import io.github.easy4j.opencli.core.OpenCliResult; +import io.github.easy4j.opencli.exception.OpenCliException; +import io.github.easy4j.opencli.exception.OpenCliTimeoutException; +import java.io.File; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.concurrent.ExecutionException; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.Future; +import java.util.concurrent.TimeUnit; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.Timeout; +import org.junit.jupiter.api.io.TempDir; +import static org.junit.jupiter.api.Assertions.*; + +/** Additional finite-budget and immutable-submission regression vectors. */ +@Timeout(20) +class OpenCliProcessBoundaryTest { + @TempDir Path dir; + + private static OpenCliProperties properties() { + OpenCliProperties p = new OpenCliProperties(); + String exe = System.getProperty("os.name").startsWith("Windows") ? "java.exe" : "java"; + p.setExecutable(new File(new File(System.getProperty("java.home"), "bin"), exe).getAbsolutePath()); + p.setLeadingArguments(new ArrayList<>(Arrays.asList("-cp", + System.getProperty("surefire.test.class.path", System.getProperty("java.class.path")), + LifecycleProbe.class.getName()))); + p.setCommandTimeoutMillis(10000L); + p.setMaxConcurrentExecutions(1); + return p; + } + + private static void await(Path path) throws Exception { + long started = System.nanoTime(); + while (!Files.exists(path) && System.nanoTime() - started < TimeUnit.SECONDS.toNanos(3L)) { Thread.sleep(10L); } + assertTrue(Files.exists(path), "fixture did not start"); + } + + @Test + void utf8TruncationReportsBytesNotReencodedCharacters() { + OpenCliProperties p = properties(); + p.setMaxStdoutBytes(4); + OpenCliException failure = assertThrows(OpenCliException.class, () -> new OpenCliExecutor(p).invoke("utf8")); + OpenCliResult partial = failure.getPartialResult(); + assertNotNull(partial); + assertEquals(TerminationReason.OUTPUT_LIMIT, partial.getExecutionDetails().getTerminationReason()); + assertEquals(4L, partial.getExecutionDetails().getStdoutCapturedBytes()); + assertEquals(6L, partial.getExecutionDetails().getStdoutObservedBytes()); + assertEquals("中\uFFFD", partial.getStdout()); + assertTrue(partial.getExecutionDetails().isStdoutTruncated()); + } + + @Test + void invalidBudgetsFailBeforeChildCreation() { + for (int choice = 0; choice < 5; choice++) { + OpenCliProperties p = properties(); + if (choice == 0) { p.setMaxStdoutBytes(0); } + if (choice == 1) { p.setMaxStderrBytes(-1); } + if (choice == 2) { p.setCleanupGraceMillis(0); } + if (choice == 3) { p.setCommandTimeoutMillis(Long.MAX_VALUE); } + if (choice == 4) { p.setCleanupGraceMillis(Long.MAX_VALUE); } + Path marker = dir.resolve("invalid-" + choice); + assertThrows(IllegalArgumentException.class, () -> new OpenCliExecutor(p).invoke("write", marker.toString())); + assertFalse(Files.exists(marker)); + } + } + + @Test + void explicitCancellationOfRunningChildRetainsBoundedEvidence() throws Exception { + OpenCliExecutor executor = new OpenCliExecutor(properties()); + OpenCliCancellationToken token = new OpenCliCancellationToken(); + Path heartbeat = dir.resolve("heartbeat"); + Path release = dir.resolve("release"); + ExecutorService worker = Executors.newSingleThreadExecutor(); + try { + Future future = worker.submit(() -> executor.invoke( + Arrays.asList("heartbeat", heartbeat.toString(), release.toString()), token)); + await(heartbeat); + token.cancel(); + ExecutionException failed = assertThrows(ExecutionException.class, () -> future.get(3, TimeUnit.SECONDS)); + assertTrue(failed.getCause() instanceof OpenCliException); + OpenCliResult partial = ((OpenCliException) failed.getCause()).getPartialResult(); + assertEquals(TerminationReason.CANCELLED, partial.getExecutionDetails().getTerminationReason()); + assertTrue(partial.getExecutionDetails().isProcessStarted()); + assertFalse(partial.getExecutionDetails().isDescendantsExitConfirmed()); + String stopped = new String(Files.readAllBytes(heartbeat), StandardCharsets.UTF_8); + Thread.sleep(100L); + assertEquals(stopped, new String(Files.readAllBytes(heartbeat), StandardCharsets.UTF_8)); + assertTrue(executor.invoke("write", dir.resolve("next").toString()).isSuccess()); + } finally { + Files.write(release, new byte[]{1}); + worker.shutdownNow(); + assertTrue(worker.awaitTermination(5, TimeUnit.SECONDS)); + } + } + + @Test + void queuedTokenCancellationDoesNotStartTheWaitingChild() throws Exception { + OpenCliExecutor executor = new OpenCliExecutor(properties()); + Path first = dir.resolve("first"); + Path second = dir.resolve("second"); + Path gate = dir.resolve("release"); + OpenCliCancellationToken token = new OpenCliCancellationToken(); + ExecutorService workers = Executors.newFixedThreadPool(2); + try { + Future one = workers.submit(() -> executor.invoke("hold", first.toString(), gate.toString())); + await(first); + Future two = workers.submit(() -> executor.invoke(Arrays.asList("write", second.toString()), token)); + Thread.sleep(100L); + token.cancel(); + ExecutionException failed = assertThrows(ExecutionException.class, () -> two.get(2, TimeUnit.SECONDS)); + OpenCliResult partial = ((OpenCliException) failed.getCause()).getPartialResult(); + assertEquals(TerminationReason.CANCELLED, partial.getExecutionDetails().getTerminationReason()); + assertFalse(partial.getExecutionDetails().isProcessStarted()); + assertNull(partial.getExitCode()); + assertFalse(Files.exists(second)); + Files.write(gate, new byte[]{1}); + assertTrue(one.get(3, TimeUnit.SECONDS).isSuccess()); + } finally { + Files.write(gate, new byte[]{1}); + workers.shutdownNow(); + assertTrue(workers.awaitTermination(5, TimeUnit.SECONDS)); + } + } + + @Test + void timeoutAndCaptureConfigurationAreCopiedForReverseWorkers() { + OpenCliProperties p = properties(); + p.setMaxStdoutBytes(123); + p.setMaxStderrBytes(456); + p.setCleanupGraceMillis(789); + OpenCliProperties copy = p.copyForLocalCliExecution(); + assertEquals(123, copy.getMaxStdoutBytes()); + assertEquals(456, copy.getMaxStderrBytes()); + assertEquals(789L, copy.getCleanupGraceMillis()); + } + + @Test + void repeatedExecutionTimeoutsDoNotBecomeNonzeroOrIoFailures() { + OpenCliProperties p = properties(); + p.setCommandTimeoutMillis(100L); + OpenCliExecutor executor = new OpenCliExecutor(p); + for (int i = 0; i < 5; i++) { + Path marker = dir.resolve("timeout-" + i); + OpenCliTimeoutException failure = assertThrows(OpenCliTimeoutException.class, + () -> executor.invoke("hold", marker.toString(), dir.resolve("never-release").toString())); + assertEquals(TerminationReason.EXECUTION_TIMEOUT, failure.getPartialResult().getExecutionDetails().getTerminationReason()); + assertFalse(executor.getProcessRuntime().isQuarantined()); + } + } +} diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java new file mode 100644 index 0000000..5cb4397 --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java @@ -0,0 +1,233 @@ +package io.github.easy4j.opencli.contract; + +import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.core.OpenCliExecutor; +import io.github.easy4j.opencli.core.OpenCliResult; +import io.github.easy4j.opencli.exception.OpenCliException; +import io.github.easy4j.opencli.exception.OpenCliTimeoutException; +import java.io.File; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.List; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.Future; +import java.util.concurrent.ScheduledExecutorService; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicReference; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.Timeout; +import org.junit.jupiter.api.io.TempDir; +import static org.junit.jupiter.api.Assertions.*; + +/** C02 tests observe actual fixture processes, not private semaphore counters. */ +@Timeout(20) +class OpenCliProcessContractTest { + @TempDir Path dir; + + private static OpenCliProperties properties(int maxConcurrent) { + OpenCliProperties p = new OpenCliProperties(); + String exe = System.getProperty("os.name").startsWith("Windows") ? "java.exe" : "java"; + p.setExecutable(new File(new File(System.getProperty("java.home"), "bin"), exe).getAbsolutePath()); + p.setLeadingArguments(new ArrayList<>(Arrays.asList("-cp", + System.getProperty("surefire.test.class.path", System.getProperty("java.class.path")), + LifecycleProbe.class.getName()))); + p.setCommandTimeoutMillis(10000L); + p.setMaxConcurrentExecutions(maxConcurrent); + return p; + } + + private static boolean awaitFile(Path path, long millis) throws Exception { + long start = System.nanoTime(); + while (System.nanoTime() - start < TimeUnit.MILLISECONDS.toNanos(millis)) { + if (Files.exists(path)) { return true; } + Thread.sleep(10L); + } + return Files.exists(path); + } + + private static void release(Path path) { + try { Files.write(path, new byte[]{1}); } + catch (Exception ex) { throw new AssertionError("fixture cleanup failed", ex); } + } + + private static Object getter(Object object, String name) { + assertNotNull(object, "partial evidence is required"); + return assertDoesNotThrow(() -> object.getClass().getMethod(name).invoke(object), + "required execution evidence is missing: " + name); + } + + private static Object details(OpenCliResult result) { return getter(result, "getExecutionDetails"); } + + @Test + void anotherClientCannotReplaceAnActiveClientsLimiter() throws Exception { + OpenCliExecutor a = new OpenCliExecutor(properties(1)); + Path first = dir.resolve("first"); + Path second = dir.resolve("second"); + Path gate = dir.resolve("release"); + ExecutorService workers = Executors.newFixedThreadPool(2); + try { + Future one = workers.submit(() -> a.invoke("hold", first.toString(), gate.toString())); + assertTrue(awaitFile(first, 3000), "first child did not start"); + new OpenCliExecutor(properties(4)); + Future two = workers.submit(() -> a.invoke("write", second.toString())); + assertFalse(awaitFile(second, 600), "constructing B bypassed A's active limiter"); + release(gate); + assertTrue(one.get(5, TimeUnit.SECONDS).isSuccess()); + assertTrue(two.get(5, TimeUnit.SECONDS).isSuccess()); + } finally { + release(gate); + workers.shutdownNow(); + assertTrue(workers.awaitTermination(5, TimeUnit.SECONDS)); + } + } + + @Test + void queuedDeadlineExpiresWithoutSpawning() throws Exception { + OpenCliProperties p = properties(1); + OpenCliExecutor executor = new OpenCliExecutor(p); + Path first = dir.resolve("first"); + Path second = dir.resolve("must-not-start"); + Path gate = dir.resolve("release"); + ExecutorService worker = Executors.newSingleThreadExecutor(); + ScheduledExecutorService cleanup = Executors.newSingleThreadScheduledExecutor(); + try { + Future one = worker.submit(() -> executor.invoke("hold", first.toString(), gate.toString())); + assertTrue(awaitFile(first, 3000)); + p.setCommandTimeoutMillis(50L); + cleanup.schedule(() -> release(gate), 1500L, TimeUnit.MILLISECONDS); + long started = System.nanoTime(); + OpenCliTimeoutException failure = assertThrows(OpenCliTimeoutException.class, + () -> executor.invoke("write", second.toString())); + long elapsed = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - started); + assertTrue(elapsed < 750L, "queue wait ignored total deadline: " + elapsed); + assertFalse(Files.exists(second), "queue-expired child was started"); + Object evidence = details(failure.getPartialResult()); + assertEquals("QUEUE_TIMEOUT", String.valueOf(getter(evidence, "getTerminationReason"))); + assertEquals(false, getter(evidence, "isProcessStarted")); + assertNull(failure.getPartialResult().getExitCode()); + release(gate); + assertTrue(one.get(5, TimeUnit.SECONDS).isSuccess()); + } finally { + release(gate); + worker.shutdownNow(); + cleanup.shutdownNow(); + assertTrue(worker.awaitTermination(5, TimeUnit.SECONDS)); + assertTrue(cleanup.awaitTermination(5, TimeUnit.SECONDS)); + } + } + + @Test + void stdoutDefaultBudgetFailsInsteadOfReturningUnboundedSuccess() { + OpenCliException failure = assertThrows(OpenCliException.class, + () -> new OpenCliExecutor(properties(1)).invoke("stdout", Integer.toString(9 * 1024 * 1024))); + OpenCliResult partial = failure.getPartialResult(); + Object evidence = details(partial); + assertEquals("OUTPUT_LIMIT", String.valueOf(getter(evidence, "getTerminationReason"))); + assertEquals(8L * 1024 * 1024, ((Number) getter(evidence, "getStdoutCapturedBytes")).longValue()); + assertTrue(((Number) getter(evidence, "getStdoutObservedBytes")).longValue() > 8L * 1024 * 1024); + assertEquals(true, getter(evidence, "isStdoutTruncated")); + assertFalse(partial.isSuccess()); + } + + @Test + void stderrHasItsOwnSmallerBudget() { + OpenCliException failure = assertThrows(OpenCliException.class, + () -> new OpenCliExecutor(properties(1)).invoke("stderr", Integer.toString(3 * 1024 * 1024))); + Object evidence = details(failure.getPartialResult()); + assertEquals("OUTPUT_LIMIT", String.valueOf(getter(evidence, "getTerminationReason"))); + assertEquals(2L * 1024 * 1024, ((Number) getter(evidence, "getStderrCapturedBytes")).longValue()); + assertEquals(true, getter(evidence, "isStderrTruncated")); + } + + @Test + void interruptionStopsTheOwnedHeartbeatAndRestoresFlag() throws Exception { + OpenCliExecutor executor = new OpenCliExecutor(properties(1)); + Path heartbeat = dir.resolve("heartbeat"); + Path gate = dir.resolve("release"); + AtomicBoolean restored = new AtomicBoolean(); + AtomicReference error = new AtomicReference<>(); + Thread caller = new Thread(() -> { + try { executor.invoke("heartbeat", heartbeat.toString(), gate.toString()); } + catch (Throwable failure) { error.set(failure); restored.set(Thread.currentThread().isInterrupted()); } + }, "contract-interrupted-caller"); + try { + caller.start(); + assertTrue(awaitFile(heartbeat, 3000)); + Thread.sleep(80L); + caller.interrupt(); + caller.join(1500L); + assertFalse(caller.isAlive(), "interrupted call did not finish cleanup"); + assertTrue(error.get() instanceof OpenCliException); + assertTrue(restored.get(), "caller interrupt flag was lost"); + String observed = new String(Files.readAllBytes(heartbeat), StandardCharsets.UTF_8); + Thread.sleep(250L); + assertEquals(observed, new String(Files.readAllBytes(heartbeat), StandardCharsets.UTF_8), + "owned child kept running after interrupted call returned"); + OpenCliException failure = (OpenCliException) error.get(); + assertEquals("CANCELLED", String.valueOf(getter(details(failure.getPartialResult()), "getTerminationReason"))); + assertEquals("ROOT_EXIT_CONFIRMED", String.valueOf(getter(details(failure.getPartialResult()), "getCleanupState"))); + Path next = dir.resolve("next"); + assertTrue(executor.invoke("write", next.toString()).isSuccess(), "permit leaked after cancellation"); + } finally { + release(gate); + caller.interrupt(); + caller.join(5000L); + } + } + + @Test + void negativeConcurrencyIsNotSilentlyTreatedAsDefault() { + assertThrows(IllegalArgumentException.class, () -> new OpenCliExecutor(properties(-1))); + } + + @Test + void explicitSharedRuntimeLimitsBothClients() throws Exception { + Class runtimeType = assertDoesNotThrow(() -> Class.forName("io.github.easy4j.opencli.core.OpenCliProcessRuntime")); + Object runtime = runtimeType.getConstructor(int.class).newInstance(1); + OpenCliExecutor a = OpenCliExecutor.class.getConstructor(OpenCliProperties.class, runtimeType) + .newInstance(properties(4), runtime); + OpenCliExecutor b = OpenCliExecutor.class.getConstructor(OpenCliProperties.class, runtimeType) + .newInstance(properties(4), runtime); + Path first = dir.resolve("shared-first"); + Path second = dir.resolve("shared-second"); + Path gate = dir.resolve("release"); + ExecutorService workers = Executors.newFixedThreadPool(2); + try { + Future one = workers.submit(() -> a.invoke("hold", first.toString(), gate.toString())); + assertTrue(awaitFile(first, 3000)); + Future two = workers.submit(() -> b.invoke("write", second.toString())); + assertFalse(awaitFile(second, 500), "shared runtime did not enforce its one permit"); + release(gate); + assertTrue(one.get(5, TimeUnit.SECONDS).isSuccess()); + assertTrue(two.get(5, TimeUnit.SECONDS).isSuccess()); + } finally { + release(gate); + workers.shutdownNow(); + assertTrue(workers.awaitTermination(5, TimeUnit.SECONDS)); + } + } + + @Test + void preCancelledRequestNeverStartsAProcess() throws Exception { + Class tokenType = assertDoesNotThrow(() -> Class.forName("io.github.easy4j.opencli.core.OpenCliCancellationToken")); + Object token = tokenType.getConstructor().newInstance(); + tokenType.getMethod("cancel").invoke(token); + Path marker = dir.resolve("pre-cancelled"); + OpenCliExecutor executor = new OpenCliExecutor(properties(1)); + java.lang.reflect.InvocationTargetException failure = assertThrows(java.lang.reflect.InvocationTargetException.class, + () -> OpenCliExecutor.class.getMethod("invoke", List.class, tokenType) + .invoke(executor, Arrays.asList("write", marker.toString()), token)); + assertTrue(failure.getCause() instanceof OpenCliException); + OpenCliResult partial = ((OpenCliException) failure.getCause()).getPartialResult(); + assertEquals("CANCELLED", String.valueOf(getter(details(partial), "getTerminationReason"))); + assertEquals(false, getter(details(partial), "isProcessStarted")); + assertNull(partial.getExitCode()); + assertFalse(Files.exists(marker)); + } +} diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliStructuredArgvContractTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliStructuredArgvContractTest.java new file mode 100644 index 0000000..c23685d --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliStructuredArgvContractTest.java @@ -0,0 +1,180 @@ +package io.github.easy4j.opencli.contract; + +import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.core.OpenCliAdapterChannel; +import io.github.easy4j.opencli.core.OpenCliAdapterCommandRequest; +import io.github.easy4j.opencli.core.OpenCliExecutor; +import io.github.easy4j.opencli.core.OpenCliResult; +import java.io.File; +import java.lang.reflect.InvocationTargetException; +import java.lang.reflect.Method; +import java.nio.charset.StandardCharsets; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Base64; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import org.junit.jupiter.api.Test; +import static org.junit.jupiter.api.Assertions.*; + +/** Public binary/API contract: missing methods fail assertions rather than preventing the RED build. */ +class OpenCliStructuredArgvContractTest { + private static Class type(String simpleName) { + return assertDoesNotThrow(() -> Class.forName("io.github.easy4j.opencli.core." + simpleName), + "required ordered-option API is not implemented"); + } + + private static Object call(Class owner, Object receiver, String name, Class[] parameterTypes, Object... args) { + Method method = assertDoesNotThrow(() -> owner.getMethod(name, parameterTypes), + "required public method is not implemented: " + name); + try { + return method.invoke(receiver, args); + } catch (InvocationTargetException ex) { + Throwable cause = ex.getCause(); + if (cause instanceof RuntimeException) { + throw (RuntimeException) cause; + } + throw new AssertionError("unexpected checked failure", cause); + } catch (ReflectiveOperationException ex) { + throw new AssertionError("public API is inaccessible", ex); + } + } + + private static Object schema(String form, String name, boolean repeatable) { + Class owner = type("OpenCliOptionSchema"); + return "value".equals(form) + ? call(owner, null, form, new Class[]{String.class, boolean.class}, name, repeatable) + : call(owner, null, form, new Class[]{String.class}, name); + } + + private static Object value(Object definition, Object value) { + return call(type("OpenCliOption"), null, "value", + new Class[]{type("OpenCliOptionSchema"), Object.class}, definition, value); + } + + private static Object flag(String form, Object definition) { + return call(type("OpenCliOption"), null, form, + new Class[]{type("OpenCliOptionSchema")}, definition); + } + + private static void add(Object builder, Object occurrence) { + call(builder.getClass(), builder, "option", new Class[]{type("OpenCliOption")}, occurrence); + } + + private static List run(OpenCliAdapterCommandRequest request) { + OpenCliProperties p = new OpenCliProperties(); + String exe = System.getProperty("os.name").startsWith("Windows") ? "java.exe" : "java"; + p.setExecutable(new File(new File(System.getProperty("java.home"), "bin"), exe).getAbsolutePath()); + p.setLeadingArguments(new ArrayList<>(Arrays.asList("-cp", + System.getProperty("surefire.test.class.path", System.getProperty("java.class.path")), + ContractProbe.class.getName()))); + p.setCommandTimeoutMillis(10000L); + OpenCliResult result = new OpenCliAdapterChannel(new OpenCliExecutor(p), "demo").invoke(request); + assertTrue(result.isSuccess()); + String[] lines = result.getStdout().split("\r?\n"); + List actual = new ArrayList<>(); + for (int i = 1; i < lines.length; i++) { + assertTrue(lines[i].startsWith("arg:")); + actual.add(new String(Base64.getDecoder().decode(lines[i].substring(4)), StandardCharsets.UTF_8)); + } + assertEquals("argc:" + actual.size(), lines[0]); + return actual; + } + + @Test + void orderedRepeatedValuesAndExplicitFalseReachChild() { + Object tags = schema("value", "--tag", true); + Object enabled = schema("value", "--enabled", false); + OpenCliAdapterCommandRequest.OpenCliAdapterCommandRequestBuilder b = OpenCliAdapterCommandRequest.builder().subcommand("echo"); + add(b, value(tags, " A ")); + add(b, value(enabled, false)); + add(b, value(tags, "")); + assertEquals(Arrays.asList("demo", "echo", "--tag", " A ", "--enabled", "false", "--tag", ""), run(b.build())); + } + + @Test + void explicitNegationIsDifferentFromAbsenceAndPresence() { + Object cache = schema("negatableFlag", "--cache", false); + OpenCliAdapterCommandRequest.OpenCliAdapterCommandRequestBuilder b = OpenCliAdapterCommandRequest.builder().subcommand("echo"); + add(b, flag("negated", cache)); + assertEquals(Arrays.asList("demo", "echo", "--no-cache"), run(b.build())); + OpenCliAdapterCommandRequest.OpenCliAdapterCommandRequestBuilder present = OpenCliAdapterCommandRequest.builder().subcommand("echo"); + add(present, flag("present", cache)); + assertEquals(Arrays.asList("demo", "echo", "--cache"), run(present.build())); + assertEquals(Arrays.asList("demo", "echo"), run(OpenCliAdapterCommandRequest.builder().subcommand("echo").build())); + } + + @Test + void flagSchemaCannotSilentlyConsumeAValue() { + Object verbose = schema("flag", "--verbose", false); + assertThrows(IllegalArgumentException.class, () -> value(verbose, false)); + assertThrows(IllegalArgumentException.class, () -> flag("negated", verbose)); + } + + @Test + void nonrepeatableOptionCannotAppearTwice() { + Object once = schema("value", "--limit", false); + OpenCliAdapterCommandRequest.OpenCliAdapterCommandRequestBuilder b = OpenCliAdapterCommandRequest.builder().subcommand("echo"); + add(b, value(once, 1)); + add(b, value(once, 2)); + assertThrows(IllegalArgumentException.class, () -> b.build().toSubcommandAndArgs()); + } + + @Test + void legacyAndOrderedOptionsCannotCollide() { + Object limit = schema("value", "--limit", true); + OpenCliAdapterCommandRequest.OpenCliAdapterCommandRequestBuilder b = OpenCliAdapterCommandRequest.builder().subcommand("echo") + .options(Collections.singletonMap("limit", "1")); + add(b, value(limit, "2")); + assertThrows(IllegalArgumentException.class, () -> b.build().toSubcommandAndArgs()); + } + + @Test + void mutableOccurrenceValueIsCapturedWhenCreated() { + StringBuilder text = new StringBuilder(" before "); + Object occurrence = value(schema("value", "--text", false), text); + text.append("after"); + OpenCliAdapterCommandRequest.OpenCliAdapterCommandRequestBuilder b = OpenCliAdapterCommandRequest.builder().subcommand("echo"); + add(b, occurrence); + assertEquals(Arrays.asList("demo", "echo", "--text", " before "), run(b.build())); + } + + @Test + void malformedSchemaIdentifiersAreRejected() { + Class owner = type("OpenCliOptionSchema"); + assertThrows(IllegalArgumentException.class, + () -> call(owner, null, "flag", new Class[]{String.class}, "--x y")); + assertThrows(IllegalArgumentException.class, + () -> call(owner, null, "flag", new Class[]{String.class}, "")); + } + + @Test + void legacyMapIsCapturedRatherThanAliased() { + Map options = new LinkedHashMap<>(); + options.put("text", " before "); + OpenCliAdapterCommandRequest request = OpenCliAdapterCommandRequest.builder().subcommand("echo").options(options).build(); + options.put("text", "after"); + assertEquals(Arrays.asList("demo", "echo", "--text", " before "), run(request)); + } + + @Test + void mutableLegacyValueCannotChangeAnExistingRequest() { + StringBuilder text = new StringBuilder(" before "); + OpenCliAdapterCommandRequest request = OpenCliAdapterCommandRequest.builder().subcommand("echo") + .options(Collections.singletonMap("text", text)).build(); + text.append("after"); + assertEquals(Arrays.asList("demo", "echo", "--text", " before "), run(request)); + } + + @Test + void reusingBuilderDoesNotMutatePreviousRequest() { + Object tags = schema("value", "--tag", true); + OpenCliAdapterCommandRequest.OpenCliAdapterCommandRequestBuilder b = OpenCliAdapterCommandRequest.builder().subcommand("echo"); + add(b, value(tags, "A")); + OpenCliAdapterCommandRequest first = b.build(); + add(b, value(tags, "B")); + assertEquals(Arrays.asList("demo", "echo", "--tag", "A"), run(first)); + } +} diff --git a/src/test/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequestTest.java b/src/test/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequestTest.java index 8f2c36b..3798564 100644 --- a/src/test/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequestTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequestTest.java @@ -6,6 +6,33 @@ class OpenCliAdapterCommandRequestTest { + @Test + void shouldRejectLegacyOptionWithNullStringFormBeforeSnapshot() { + Map opts = new LinkedHashMap<>(); + opts.put("--value", new Object() { + @Override + public String toString() { + return null; + } + }); + + assertThrows(IllegalArgumentException.class, + () -> OpenCliAdapterCommandRequest.builder().subcommand("ask").options(opts)); + } + + @Test + void shouldRejectOrderedOptionWithNullStringForm() { + Object value = new Object() { + @Override + public String toString() { + return null; + } + }; + + assertThrows(IllegalArgumentException.class, + () -> OpenCliOption.value(OpenCliOptionSchema.value("--value", false), value)); + } + @Test void shouldBuildWithPositionals() { OpenCliAdapterCommandRequest req = OpenCliAdapterCommandRequest.builder() @@ -116,7 +143,7 @@ void shouldReturnImmutableOptions() { } @Test - void shouldSkipNullPositionalInToSubcommandAndArgs() { + void shouldPreserveEmptyPositionalInToSubcommandAndArgs() { OpenCliAdapterCommandRequest req = OpenCliAdapterCommandRequest.builder() .subcommand("sub") .positional("a") @@ -124,7 +151,7 @@ void shouldSkipNullPositionalInToSubcommandAndArgs() { .positional("b") .build(); List argv = req.toSubcommandAndArgs(); - assertEquals(Arrays.asList("sub", "a", "b"), argv); + assertEquals(Arrays.asList("sub", "a", "", "b"), argv); } @Test diff --git a/src/test/java/io/github/easy4j/opencli/core/OpenCliArgSupportTest.java b/src/test/java/io/github/easy4j/opencli/core/OpenCliArgSupportTest.java index f5efc59..20f0abc 100644 --- a/src/test/java/io/github/easy4j/opencli/core/OpenCliArgSupportTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/OpenCliArgSupportTest.java @@ -4,6 +4,7 @@ import java.util.ArrayList; import java.util.Arrays; import java.util.List; +import java.util.UUID; import org.junit.jupiter.api.Test; class OpenCliArgSupportTest { @@ -15,9 +16,15 @@ void shouldMergeNonNullLists() { } @Test - void shouldFilterNullAndBlankWhenMerging() { - List result = OpenCliArgSupport.merge(Arrays.asList("a", null, "", " ", "b"), Arrays.asList("c")); - assertEquals(Arrays.asList("a", "b", "c"), result); + void shouldRejectNullElementWhenMerging() { + assertThrows(IllegalArgumentException.class, + () -> OpenCliArgSupport.merge(Arrays.asList("a", null, "", " ", "b"), Arrays.asList("c"))); + } + + @Test + void shouldPreserveEmptyAndBlankWhenMerging() { + assertEquals(Arrays.asList("a", "", " ", "b", "c"), + OpenCliArgSupport.merge(Arrays.asList("a", "", " ", "b"), Arrays.asList("c"))); } @Test @@ -56,7 +63,12 @@ void shouldAddOptionEqualsStrippingTrailingEquals() { @Test void shouldThrowWhenNameDoesNotStartWithDash() { List target = new ArrayList<>(); - assertThrows(IllegalArgumentException.class, () -> OpenCliArgSupport.addOptionEquals(target, "key", "value")); + String optionCanary = "private-option-" + UUID.randomUUID(); + IllegalArgumentException failure = assertThrows(IllegalArgumentException.class, + () -> OpenCliArgSupport.addOptionEquals(target, optionCanary, "value")); + assertTrue(failure.getMessage().contains("must start with '--'")); + assertFalse(failure.toString().contains(optionCanary)); + assertTrue(target.isEmpty()); } @Test @@ -80,6 +92,21 @@ void shouldNotAddOptionPairIfPresentWhenValueNull() { assertTrue(target.isEmpty()); } + @Test + void shouldRejectNonNullValueWhoseStringFormIsNull() { + List target = new ArrayList<>(); + Object value = new Object() { + @Override + public String toString() { + return null; + } + }; + + assertThrows(IllegalArgumentException.class, + () -> OpenCliArgSupport.addOptionPairIfPresent(target, "--flag", value)); + assertTrue(target.isEmpty()); + } + @Test void shouldAddFlagIfTrue() { List target = new ArrayList<>(); diff --git a/src/test/java/io/github/easy4j/opencli/core/OpenCliExecutorFullTest.java b/src/test/java/io/github/easy4j/opencli/core/OpenCliExecutorFullTest.java index ed0cfba..163f873 100644 --- a/src/test/java/io/github/easy4j/opencli/core/OpenCliExecutorFullTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/OpenCliExecutorFullTest.java @@ -3,6 +3,7 @@ import static org.junit.jupiter.api.Assertions.*; import io.github.easy4j.opencli.OpenCliExecutionTarget; import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.exception.OpenCliException; import java.util.Arrays; import org.apache.commons.exec.CommandLine; import org.junit.jupiter.api.Test; @@ -35,19 +36,23 @@ void shouldAppendQuotedKeyValueWithTrailingEquals() { } @Test - void shouldTruncateOversizedOutputWithMarker() { + void shouldReportBoundedOutputLimitWithPartialEvidence() { OpenCliProperties props = new OpenCliProperties(); props.setExecutable("/bin/sh"); props.setMaxOutputBytes(64L); props.setCommandTimeoutMillis(30_000L); OpenCliExecutor executor = new OpenCliExecutor(props); - OpenCliResult result = executor.invoke("-c", - "printf 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'"); - - assertTrue(result.isSuccess(), "truncation must not fail the run"); - assertTrue(result.getStdout().contains("truncated"), - "overflow must leave a truncation marker: " + result.getStdout()); + OpenCliException failure = assertThrows(OpenCliException.class, () -> executor.invoke("-c", + "printf 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'")); + OpenCliResult result = failure.getPartialResult(); + assertNotNull(result); + assertFalse(result.isSuccess()); + assertEquals(OpenCliExecutionDetails.TerminationReason.OUTPUT_LIMIT, + result.getExecutionDetails().getTerminationReason()); + assertTrue(result.getExecutionDetails().isStdoutTruncated()); + assertEquals(64L, result.getExecutionDetails().getStdoutCapturedBytes()); + assertEquals(64, result.getStdout().getBytes(java.nio.charset.StandardCharsets.UTF_8).length); } @Test diff --git a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCleanupFaultTest.java b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCleanupFaultTest.java new file mode 100644 index 0000000..79fd220 --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCleanupFaultTest.java @@ -0,0 +1,292 @@ +package io.github.easy4j.opencli.core.support; + +import io.github.easy4j.opencli.core.OpenCliCancellationToken; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails.CleanupState; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails.TerminationReason; +import java.io.ByteArrayInputStream; +import java.io.ByteArrayOutputStream; +import java.io.InputStream; +import java.io.OutputStream; +import java.util.concurrent.atomic.AtomicReference; +import org.apache.commons.exec.CommandLine; +import org.apache.commons.exec.ExecuteWatchdog; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.Timeout; +import static org.junit.jupiter.api.Assertions.*; + +/** Fault injection for cleanup operations after an invocation-owned child starts. */ +@Timeout(5) +class SubprocessCleanupFaultTest { + @Test + void destroyFailureStillForcesOwnedChildAndReleasesPermit() throws Exception { + assertCleanupSurvives(false, true); + } + + @Test + void watchdogStopFailureStillCleansOwnedChildAndReleasesPermit() throws Exception { + assertCleanupSurvives(true, false); + } + + @Test + void watchdogStartFailureStillCleansOwnedChildAndReleasesPermit() throws Exception { + int[] starts = new int[1]; + FakeProcess[] last = new FakeProcess[1]; + SubprocessExecutionSupport.Runtime runtime = new SubprocessExecutionSupport.Runtime(1, + builder -> { + starts[0]++; + last[0] = new FakeProcess(false); + return last[0]; + }, timeout -> new FakeWatchdog(false, true)); + + for (int attempt = 0; attempt < 2; attempt++) { + SubprocessExecutionSupport.ExecutionRequest request = new SubprocessExecutionSupport.ExecutionRequest( + CommandLine.parse("fake"), null, null, 1000L, 16, 16, 200L, + System.nanoTime(), new OpenCliCancellationToken()); + + SubprocessExecutionSupport.RunSession session = runtime.execute(request); + + assertEquals(TerminationReason.IO_FAILURE, + session.getExecutionDetails().getTerminationReason()); + assertInstanceOf(IllegalStateException.class, session.getIoFailure().getCause()); + assertEquals(CleanupState.ROOT_EXIT_CONFIRMED, + session.getExecutionDetails().getCleanupState()); + assertFalse(last[0].isAlive()); + assertFalse(runtime.isQuarantined()); + } + assertEquals(2, starts[0]); + } + + @Test + void watchdogCreationFailureAfterSpawnStillCleansChildAndReleasesPermit() throws Exception { + int[] starts = new int[1]; + FakeProcess[] last = new FakeProcess[1]; + SubprocessExecutionSupport.Runtime runtime = new SubprocessExecutionSupport.Runtime(1, + builder -> { + starts[0]++; + last[0] = new FakeProcess(false); + return last[0]; + }, timeout -> { + assertNotNull(last[0], "watchdog must be created after spawn"); + throw new IllegalStateException("injected watchdog creation failure"); + }); + + for (int attempt = 0; attempt < 2; attempt++) { + SubprocessExecutionSupport.ExecutionRequest request = new SubprocessExecutionSupport.ExecutionRequest( + CommandLine.parse("fake"), null, null, 1000L, 16, 16, 200L, + System.nanoTime(), new OpenCliCancellationToken()); + + SubprocessExecutionSupport.RunSession session = runtime.execute(request); + + assertEquals(TerminationReason.IO_FAILURE, + session.getExecutionDetails().getTerminationReason()); + assertInstanceOf(IllegalStateException.class, session.getIoFailure().getCause()); + assertEquals(CleanupState.ROOT_EXIT_CONFIRMED, + session.getExecutionDetails().getCleanupState()); + assertFalse(last[0].isAlive()); + assertFalse(runtime.isQuarantined()); + } + assertEquals(2, starts[0]); + } + + @Test + void processStreamSetupFailureStillCleansChildAndReleasesPermit() throws Exception { + int[] starts = new int[1]; + FakeProcess[] last = new FakeProcess[1]; + SubprocessExecutionSupport.Runtime runtime = new SubprocessExecutionSupport.Runtime(1, + builder -> { + starts[0]++; + last[0] = new FakeProcess(false, false, true); + return last[0]; + }, timeout -> new FakeWatchdog(false)); + + for (int attempt = 0; attempt < 2; attempt++) { + SubprocessExecutionSupport.ExecutionRequest request = new SubprocessExecutionSupport.ExecutionRequest( + CommandLine.parse("fake"), null, null, 1000L, 16, 16, 200L, + System.nanoTime(), new OpenCliCancellationToken()); + + SubprocessExecutionSupport.RunSession session = runtime.execute(request); + + assertEquals(TerminationReason.IO_FAILURE, + session.getExecutionDetails().getTerminationReason()); + assertInstanceOf(IllegalStateException.class, session.getIoFailure().getCause()); + assertEquals(CleanupState.ROOT_EXIT_CONFIRMED, + session.getExecutionDetails().getCleanupState()); + assertFalse(last[0].isAlive()); + assertFalse(runtime.isQuarantined()); + } + assertEquals(2, starts[0]); + } + + @Test + void unconfirmedForcedStopQuarantinesRuntimeWithoutFabricatingExit() throws Exception { + OpenCliCancellationToken token = new OpenCliCancellationToken(); + int[] starts = new int[1]; + SubprocessExecutionSupport.Runtime runtime = new SubprocessExecutionSupport.Runtime(1, + builder -> { + starts[0]++; + token.cancel(); + return new FakeProcess(true, true); + }, timeout -> new FakeWatchdog(false)); + SubprocessExecutionSupport.ExecutionRequest request = new SubprocessExecutionSupport.ExecutionRequest( + CommandLine.parse("fake"), null, null, 1000L, 16, 16, 50L, + System.nanoTime(), token); + + SubprocessExecutionSupport.RunSession session = runtime.execute(request); + + assertEquals(TerminationReason.CANCELLED, + session.getExecutionDetails().getTerminationReason()); + assertEquals(CleanupState.UNCONFIRMED, + session.getExecutionDetails().getCleanupState()); + assertTrue(session.getExecutionDetails().isCleanupOperationFailed()); + assertNull(session.getObservedExitCode()); + assertTrue(runtime.isQuarantined()); + SubprocessExecutionSupport.ExecutionRequest next = new SubprocessExecutionSupport.ExecutionRequest( + CommandLine.parse("fake"), null, null, 1000L, 16, 16, 50L, + System.nanoTime(), new OpenCliCancellationToken()); + assertEquals(TerminationReason.RUNTIME_UNAVAILABLE, + runtime.execute(next).getExecutionDetails().getTerminationReason()); + assertEquals(1, starts[0]); + } + + @Test + void cancelledSubmissionDoesNotInitializeWatchdogOrSpawn() throws Exception { + OpenCliCancellationToken token = new OpenCliCancellationToken(); + token.cancel(); + SubprocessExecutionSupport.Runtime runtime = new SubprocessExecutionSupport.Runtime(1, + builder -> fail("cancelled submission must not spawn"), + timeout -> fail("cancelled submission must not initialize a watchdog")); + SubprocessExecutionSupport.ExecutionRequest request = new SubprocessExecutionSupport.ExecutionRequest( + CommandLine.parse("fake"), null, null, 1000L, 16, 16, 200L, System.nanoTime(), token); + + SubprocessExecutionSupport.RunSession session = runtime.execute(request); + + assertEquals(TerminationReason.CANCELLED, session.getExecutionDetails().getTerminationReason()); + assertEquals(CleanupState.NOT_STARTED, session.getExecutionDetails().getCleanupState()); + assertNull(session.getObservedExitCode()); + assertNotNull(session.getWatchdog()); + } + + private static void assertCleanupSurvives(boolean failStop, boolean failDestroy) throws Exception { + OpenCliCancellationToken token = new OpenCliCancellationToken(); + AtomicReference currentToken = new AtomicReference<>(token); + FakeProcess[] last = new FakeProcess[1]; + SubprocessExecutionSupport.Runtime runtime = new SubprocessExecutionSupport.Runtime(1, + builder -> { + last[0] = new FakeProcess(failDestroy); + currentToken.get().cancel(); + return last[0]; + }, timeout -> new FakeWatchdog(failStop)); + SubprocessExecutionSupport.ExecutionRequest request = new SubprocessExecutionSupport.ExecutionRequest( + CommandLine.parse("fake"), null, null, 1000L, 16, 16, 200L, + System.nanoTime(), token); + + SubprocessExecutionSupport.RunSession session = runtime.execute(request); + + assertEquals(TerminationReason.CANCELLED, + session.getExecutionDetails().getTerminationReason()); + assertEquals(CleanupState.ROOT_EXIT_CONFIRMED, + session.getExecutionDetails().getCleanupState()); + assertTrue(session.getExecutionDetails().isCleanupOperationFailed()); + assertFalse(last[0].isAlive()); + assertFalse(runtime.isQuarantined()); + + OpenCliCancellationToken nextToken = new OpenCliCancellationToken(); + currentToken.set(nextToken); + SubprocessExecutionSupport.ExecutionRequest next = new SubprocessExecutionSupport.ExecutionRequest( + CommandLine.parse("fake"), null, null, 1000L, 16, 16, 200L, + System.nanoTime(), nextToken); + assertNotEquals(TerminationReason.QUEUE_TIMEOUT, + runtime.execute(next).getExecutionDetails().getTerminationReason()); + } + + private static final class FakeWatchdog extends ExecuteWatchdog { + private final boolean failStop; + private final boolean failStart; + + FakeWatchdog(boolean failStop) { + this(failStop, false); + } + + FakeWatchdog(boolean failStop, boolean failStart) { + super(1000L); + this.failStop = failStop; + this.failStart = failStart; + } + + @Override + public synchronized void start(Process process) { + if (failStart) { + throw new IllegalStateException("injected watchdog start failure"); + } + } + + @Override + public synchronized void stop() { + if (failStop) { + throw new IllegalStateException("injected watchdog stop failure"); + } + } + + @Override + public synchronized boolean killedProcess() { return false; } + } + + private static final class FakeProcess extends Process { + private final boolean failDestroy; + private boolean alive = true; + + private final boolean failForce; + private final boolean failStreamSetup; + + FakeProcess(boolean failDestroy) { this(failDestroy, false, false); } + + FakeProcess(boolean failDestroy, boolean failForce) { + this(failDestroy, failForce, false); + } + + FakeProcess(boolean failDestroy, boolean failForce, boolean failStreamSetup) { + this.failDestroy = failDestroy; + this.failForce = failForce; + this.failStreamSetup = failStreamSetup; + } + + @Override + public OutputStream getOutputStream() { + if (failStreamSetup) { + throw new IllegalStateException("injected process stream setup failure"); + } + return new ByteArrayOutputStream(); + } + + @Override + public InputStream getInputStream() { return new ByteArrayInputStream(new byte[0]); } + + @Override + public InputStream getErrorStream() { return new ByteArrayInputStream(new byte[0]); } + + @Override + public int waitFor() { return 143; } + + @Override + public int exitValue() { + if (alive) { throw new IllegalThreadStateException(); } + return 143; + } + + @Override + public void destroy() { + if (failDestroy) { throw new IllegalStateException("injected process destroy failure"); } + alive = false; + } + + @Override + public Process destroyForcibly() { + if (failForce) { throw new IllegalStateException("injected forced stop failure"); } + alive = false; + return this; + } + + @Override + public boolean isAlive() { return alive; } + } +} diff --git a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCompletionRaceTest.java b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCompletionRaceTest.java new file mode 100644 index 0000000..c52b42c --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCompletionRaceTest.java @@ -0,0 +1,190 @@ +package io.github.easy4j.opencli.core.support; + +import io.github.easy4j.opencli.core.OpenCliCancellationToken; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails.CleanupState; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails.TerminationReason; +import java.io.ByteArrayInputStream; +import java.io.ByteArrayOutputStream; +import java.io.InputStream; +import java.io.OutputStream; +import java.nio.charset.StandardCharsets; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.concurrent.atomic.AtomicReference; +import org.apache.commons.exec.CommandLine; +import org.apache.commons.exec.ExecuteWatchdog; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.Timeout; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** Verifies terminal evidence when cancellation, watchdog expiry and natural exit coincide. */ +@Timeout(10) +class SubprocessCompletionRaceTest { + + @Test + void simultaneousSignalsKeepOneResultAndReuseThePermit() throws Exception { + AtomicInteger starts = new AtomicInteger(); + AtomicReference currentToken = new AtomicReference<>(); + SubprocessExecutionSupport.Runtime runtime = new SubprocessExecutionSupport.Runtime(1, + builder -> { + starts.incrementAndGet(); + currentToken.get().cancel(); + return new ExitedProcess("partial"); + }, timeout -> new ExpiredWatchdog()); + + for (int attempt = 0; attempt < 32; attempt++) { + OpenCliCancellationToken token = new OpenCliCancellationToken(); + currentToken.set(token); + SubprocessExecutionSupport.ExecutionRequest request = new SubprocessExecutionSupport.ExecutionRequest( + CommandLine.parse("fake"), null, null, 1_000L, 32, 32, 100L, + System.nanoTime(), token); + SubprocessExecutionSupport.RunSession session = runtime.execute(request); + + assertEquals(TerminationReason.CANCELLED, + session.getExecutionDetails().getTerminationReason()); + assertEquals(CleanupState.ROOT_EXIT_CONFIRMED, + session.getExecutionDetails().getCleanupState()); + assertEquals(0, session.getObservedExitCode()); + assertEquals("partial", session.getStdout().toString(StandardCharsets.UTF_8.name())); + assertEquals(7, session.getExecutionDetails().getStdoutCapturedBytes()); + assertTrue(session.getExecutionDetails().isStreamsDrained()); + assertFalse(runtime.isQuarantined()); + } + assertEquals(32, starts.get()); + } + + @Test + void interruptedRunnerCleansOwnedChildRestoresFlagAndReusesPermit() throws Exception { + CountDownLatch childRunning = new CountDownLatch(1); + AtomicInteger starts = new AtomicInteger(); + AtomicReference currentToken = new AtomicReference<>(); + AtomicReference firstProcess = new AtomicReference<>(); + AtomicReference firstResult = new AtomicReference<>(); + AtomicReference failure = new AtomicReference<>(); + AtomicBoolean interruptRestored = new AtomicBoolean(); + SubprocessExecutionSupport.Runtime runtime = new SubprocessExecutionSupport.Runtime(1, + builder -> { + if (starts.incrementAndGet() == 1) { + LiveProcess process = new LiveProcess(); + firstProcess.set(process); + return process; + } + currentToken.get().cancel(); + return new ExitedProcess("second"); + }, timeout -> new ExecuteWatchdog(timeout) { + @Override + public synchronized void start(Process process) { childRunning.countDown(); } + + @Override + public synchronized boolean killedProcess() { return false; } + }); + OpenCliCancellationToken firstToken = new OpenCliCancellationToken(); + currentToken.set(firstToken); + Thread runner = new Thread(() -> { + try { + firstResult.set(runtime.execute(new SubprocessExecutionSupport.ExecutionRequest( + CommandLine.parse("fake"), null, null, 2_000L, 32, 32, 100L, + System.nanoTime(), firstToken))); + interruptRestored.set(Thread.currentThread().isInterrupted()); + } catch (Throwable ex) { + failure.set(ex); + } + }); + + runner.start(); + assertTrue(childRunning.await(2, TimeUnit.SECONDS)); + runner.interrupt(); + runner.join(2_000L); + + assertFalse(runner.isAlive()); + assertNull(failure.get()); + assertEquals(TerminationReason.CANCELLED, + firstResult.get().getExecutionDetails().getTerminationReason()); + assertEquals(CleanupState.ROOT_EXIT_CONFIRMED, + firstResult.get().getExecutionDetails().getCleanupState()); + assertFalse(firstProcess.get().isAlive()); + assertTrue(interruptRestored.get()); + + OpenCliCancellationToken nextToken = new OpenCliCancellationToken(); + currentToken.set(nextToken); + SubprocessExecutionSupport.RunSession next = runtime.execute(new SubprocessExecutionSupport.ExecutionRequest( + CommandLine.parse("fake"), null, null, 500L, 32, 32, 100L, + System.nanoTime(), nextToken)); + assertEquals(2, starts.get()); + assertEquals(TerminationReason.CANCELLED, + next.getExecutionDetails().getTerminationReason()); + } + + private static final class ExpiredWatchdog extends ExecuteWatchdog { + ExpiredWatchdog() { super(1_000L); } + + @Override + public synchronized void start(Process process) { } + + @Override + public synchronized boolean killedProcess() { return true; } + } + + private static final class ExitedProcess extends Process { + private final InputStream output; + + ExitedProcess(String text) { + output = new ByteArrayInputStream(text.getBytes(StandardCharsets.UTF_8)); + } + + @Override + public OutputStream getOutputStream() { return new ByteArrayOutputStream(); } + + @Override + public InputStream getInputStream() { return output; } + + @Override + public InputStream getErrorStream() { return new ByteArrayInputStream(new byte[0]); } + + @Override + public int waitFor() { return 0; } + + @Override + public int exitValue() { return 0; } + + @Override + public void destroy() { } + + @Override + public boolean isAlive() { return false; } + } + + private static final class LiveProcess extends Process { + private volatile boolean alive = true; + + @Override + public OutputStream getOutputStream() { return new ByteArrayOutputStream(); } + + @Override + public InputStream getInputStream() { return new ByteArrayInputStream(new byte[0]); } + + @Override + public InputStream getErrorStream() { return new ByteArrayInputStream(new byte[0]); } + + @Override + public int waitFor() { return 143; } + + @Override + public int exitValue() { + if (alive) { throw new IllegalThreadStateException(); } + return 143; + } + + @Override + public void destroy() { alive = false; } + + @Override + public boolean isAlive() { return alive; } + } +} diff --git a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessStreamFailureTest.java b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessStreamFailureTest.java new file mode 100644 index 0000000..8a6e8fd --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessStreamFailureTest.java @@ -0,0 +1,93 @@ +package io.github.easy4j.opencli.core.support; + +import io.github.easy4j.opencli.core.OpenCliCancellationToken; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails.TerminationReason; +import java.io.ByteArrayInputStream; +import java.io.ByteArrayOutputStream; +import java.io.IOException; +import java.io.InputStream; +import java.io.OutputStream; +import java.nio.charset.StandardCharsets; +import org.apache.commons.exec.CommandLine; +import org.apache.commons.exec.ExecuteWatchdog; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.Timeout; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** Verifies that reader-thread I/O faults survive into the terminal result. */ +@Timeout(5) +class SubprocessStreamFailureTest { + + @Test + void partialOutputAndReadFailureRemainVisibleAfterRootExit() throws Exception { + IOException readFailure = new IOException("injected stdout read failure"); + SubprocessExecutionSupport.Runtime runtime = new SubprocessExecutionSupport.Runtime(1, + builder -> new ExitedProcess(readFailure), timeout -> new IdleWatchdog()); + SubprocessExecutionSupport.ExecutionRequest request = new SubprocessExecutionSupport.ExecutionRequest( + CommandLine.parse("fake"), null, null, 1_000L, 32, 32, 100L, + System.nanoTime(), new OpenCliCancellationToken()); + + SubprocessExecutionSupport.RunSession session = runtime.execute(request); + + assertEquals(TerminationReason.IO_FAILURE, + session.getExecutionDetails().getTerminationReason()); + assertSame(readFailure, session.getIoFailure()); + assertEquals("abc", session.getStdout().toString(StandardCharsets.UTF_8.name())); + assertTrue(session.getExecutionDetails().isStreamsDrained()); + } + + private static final class IdleWatchdog extends ExecuteWatchdog { + IdleWatchdog() { super(1_000L); } + + @Override + public synchronized void start(Process process) { } + } + + private static final class ExitedProcess extends Process { + private final InputStream output; + + ExitedProcess(IOException readFailure) { + output = new InputStream() { + private boolean emitted; + + @Override + public int read() throws IOException { + throw new UnsupportedOperationException("Reader uses block reads"); + } + + @Override + public int read(byte[] bytes, int offset, int length) throws IOException { + if (emitted) { throw readFailure; } + byte[] partial = "abc".getBytes(StandardCharsets.UTF_8); + System.arraycopy(partial, 0, bytes, offset, partial.length); + emitted = true; + return partial.length; + } + }; + } + + @Override + public OutputStream getOutputStream() { return new ByteArrayOutputStream(); } + + @Override + public InputStream getInputStream() { return output; } + + @Override + public InputStream getErrorStream() { return new ByteArrayInputStream(new byte[0]); } + + @Override + public int waitFor() { return 0; } + + @Override + public int exitValue() { return 0; } + + @Override + public void destroy() { } + + @Override + public boolean isAlive() { return false; } + } +} diff --git a/src/test/resources/opencli-contracts/v1/SHA256SUMS b/src/test/resources/opencli-contracts/v1/SHA256SUMS new file mode 100644 index 0000000..c7a5e08 --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/SHA256SUMS @@ -0,0 +1,2 @@ +e7e6dd57e81e24e92a7cb0de0e1204f95025f80310f5dc34d820aa7419636f78 argv.tsv +2fa30626c415bb3c152bc4c2827cd9282ba710654f6a56fb7bde70a83b2bc192 sources.lock.json diff --git a/src/test/resources/opencli-contracts/v1/argv.tsv b/src/test/resources/opencli-contracts/v1/argv.tsv new file mode 100644 index 0000000..bb4ce3a --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/argv.tsv @@ -0,0 +1,6 @@ +ordinary ZGVtbw== ZWNobw== aGVsbG8= +empty ZGVtbw== ZWNobw== +whitespace ZGVtbw== ZWNobw== ICB4ICA= ICAg +unicode-newline ZGVtbw== ZWNobw== CuS4reaWhwo= 8J+Zgg== +literal-shell ZGVtbw== ZWNobw== JChwcmludGYgU0hPVUxEX05PVF9SVU4pOyAq LS0= LWxpdGVyYWw= +equals-quotes ZGVtbw== ZWNobw== LS1rZXk9YT1i ImxpdGVyYWwi Qzpc6Lev5b6EXGZpbGUgbmFtZQ== diff --git a/src/test/resources/opencli-contracts/v1/sources.lock.json b/src/test/resources/opencli-contracts/v1/sources.lock.json new file mode 100644 index 0000000..a1ed16b --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/sources.lock.json @@ -0,0 +1,58 @@ +{ + "schemaVersion": 1, + "observedAt": "2026-09-21", + "scope": "Synthetic offline argv vectors; not captures from OpenCLI or websites.", + "source": { + "kind": "specification", + "requirements": [ + "OC-ARGV-001", + "OC-ARGV-002", + "OC-ARGV-004", + "OC-ARGV-005" + ], + "ref": "d0c8056990f7a47fcc202acffa387ba066bcfc67", + "path": "openspec/changes/harden-opencli-argv-contract/specs/opencli-argv-contract/spec.md" + }, + "files": [ + { + "path": "argv.tsv", + "sha256": "e7e6dd57e81e24e92a7cb0de0e1204f95025f80310f5dc34d820aa7419636f78", + "vectors": 6, + "encoding": "case-id then tab-separated base64 UTF-8 tokens; preserve trailing empty fields" + } + ], + "branches": [ + { + "branch": "feature/1.0.x", + "base": "abba809f11dae68437c39d2ea5a2f4cf8798c0ef", + "java": 8, + "jackson": 2, + "mavenMajor": 3 + }, + { + "branch": "feature/2.0.x", + "base": "d0c8056990f7a47fcc202acffa387ba066bcfc67", + "java": 17, + "jackson": 2, + "mavenMajor": 3, + "canonical": true + }, + { + "branch": "feature/3.0.x", + "base": "6e38904bdfcae90ec617e8d29bf3d8cf2f002893", + "java": 21, + "jackson": 3, + "mavenMajor": 4 + } + ], + "allowedDifferences": [ + "JDK baseline", + "Jackson imports/decoder internals", + "Maven wrapper/POM schema" + ], + "forbiddenDifferences": [ + "raw token contents/order/count", + "null validation", + "observable semantics of shared vectors" + ] +} From 037f8bf4dfd390360743ee78f4cc3e420772ece4 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:18:29 +0800 Subject: [PATCH 005/105] Backport consistent OpenCLI cleanup deadline evidence --- .../opencli/core/OpenCliExecutionDetails.java | 2 +- .../support/SubprocessExecutionSupport.java | 13 ++-- .../support/SubprocessStreamFailureTest.java | 60 ++++++++++++++++++- 3 files changed, 67 insertions(+), 8 deletions(-) diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutionDetails.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutionDetails.java index 6da55ff..bc9f69f 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutionDetails.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutionDetails.java @@ -13,7 +13,7 @@ public enum TerminationReason { CANCELLED, SPAWN_FAILED, IO_FAILURE, CLEANUP_UNCONFIRMED, RUNTIME_UNAVAILABLE } - /** Confirmation concerns the directly owned child, not an arbitrary process tree. */ + /** Confirmation covers the directly owned child and its output readers at the cleanup deadline. */ public enum CleanupState { NOT_STARTED, ROOT_EXIT_CONFIRMED, UNCONFIRMED } private final TerminationReason terminationReason; diff --git a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java index cc3c7cd..98a5420 100644 --- a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java +++ b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java @@ -126,6 +126,8 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup boolean interrupted = false; boolean cleanupOperationFailed = false; long queueWaitMillis = 0L; + Integer exit = null; + boolean streamsDrained = true; try { while (!acquired && reason == null) { if (Thread.interrupted()) { @@ -248,7 +250,11 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup } } if (process.isAlive() && !tryForceStop(process)) { cleanupOperationFailed = true; } - if (process.isAlive() || alive(stdoutReader) || alive(stderrReader)) { + if (!process.isAlive()) { + exit = process.exitValue(); + } + streamsDrained = !alive(stdoutReader) && !alive(stderrReader); + if (Objects.isNull(exit) || !streamsDrained) { // A fixed runtime cannot accumulate unlimited uncertain children/readers. quarantined = true; if (reason == TerminationReason.PROCESS_EXIT) { reason = TerminationReason.CLEANUP_UNCONFIRMED; } @@ -264,7 +270,6 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup if (reason == TerminationReason.PROCESS_EXIT && (out.isTruncated() || err.isTruncated())) { reason = TerminationReason.OUTPUT_LIMIT; } - Integer exit = process != null && !process.isAlive() ? process.exitValue() : null; DefaultExecuteResultHandler handler = new DefaultExecuteResultHandler(); if (ioFailure != null) { handler.onProcessFailed(new ExecuteException("Native process I/O failure", exit == null ? -1 : exit, ioFailure)); @@ -276,8 +281,8 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup OpenCliExecutionDetails details = OpenCliExecutionDetails.builder() .terminationReason(reason) .cleanupState(process == null ? CleanupState.NOT_STARTED - : process.isAlive() ? CleanupState.UNCONFIRMED : CleanupState.ROOT_EXIT_CONFIRMED) - .processStarted(process != null).streamsDrained(!alive(stdoutReader) && !alive(stderrReader)) + : Objects.isNull(exit) || !streamsDrained ? CleanupState.UNCONFIRMED : CleanupState.ROOT_EXIT_CONFIRMED) + .processStarted(process != null).streamsDrained(streamsDrained) .cleanupOperationFailed(cleanupOperationFailed) .stdoutCapturedBytes(out.size()).stdoutObservedBytes(out.observed()).stdoutTruncated(out.isTruncated()) .stderrCapturedBytes(err.size()).stderrObservedBytes(err.observed()).stderrTruncated(err.isTruncated()) diff --git a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessStreamFailureTest.java b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessStreamFailureTest.java index 8a6e8fd..44c407d 100644 --- a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessStreamFailureTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessStreamFailureTest.java @@ -1,6 +1,7 @@ package io.github.easy4j.opencli.core.support; import io.github.easy4j.opencli.core.OpenCliCancellationToken; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails.CleanupState; import io.github.easy4j.opencli.core.OpenCliExecutionDetails.TerminationReason; import java.io.ByteArrayInputStream; import java.io.ByteArrayOutputStream; @@ -8,12 +9,15 @@ import java.io.InputStream; import java.io.OutputStream; import java.nio.charset.StandardCharsets; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; import org.apache.commons.exec.CommandLine; import org.apache.commons.exec.ExecuteWatchdog; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.Timeout; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertSame; import static org.junit.jupiter.api.Assertions.assertTrue; @@ -39,7 +43,53 @@ void partialOutputAndReadFailureRemainVisibleAfterRootExit() throws Exception { assertTrue(session.getExecutionDetails().isStreamsDrained()); } - private static final class IdleWatchdog extends ExecuteWatchdog { + @Test + void openReaderKeepsCleanupUnconfirmedAfterRootExit() throws Exception { + CountDownLatch releaseReader = new CountDownLatch(1); + CountDownLatch readerClosed = new CountDownLatch(1); + InputStream output = new InputStream() { + @Override + public int read() throws IOException { + try { + releaseReader.await(); + return -1; + } catch (InterruptedException ex) { + Thread.currentThread().interrupt(); + throw new IOException(ex); + } + } + + @Override + public void close() { + readerClosed.countDown(); + } + }; + OpenCliCancellationToken token = new OpenCliCancellationToken(); + SubprocessExecutionSupport.Runtime runtime = new SubprocessExecutionSupport.Runtime(1, + builder -> new ExitedProcess(output), timeout -> new IdleWatchdog() { + @Override + public synchronized void start(Process process) { + token.cancel(); + } + }); + SubprocessExecutionSupport.ExecutionRequest request = new SubprocessExecutionSupport.ExecutionRequest( + CommandLine.parse("fake"), null, null, 1_000L, 32, 32, 50L, System.nanoTime(), token); + + try { + SubprocessExecutionSupport.RunSession session = runtime.execute(request); + + assertEquals(TerminationReason.CANCELLED, session.getExecutionDetails().getTerminationReason()); + assertEquals(0, session.getObservedExitCode()); + assertEquals(CleanupState.UNCONFIRMED, session.getExecutionDetails().getCleanupState()); + assertFalse(session.getExecutionDetails().isStreamsDrained()); + assertTrue(runtime.isQuarantined()); + } finally { + releaseReader.countDown(); + assertTrue(readerClosed.await(1, TimeUnit.SECONDS)); + } + } + + private static class IdleWatchdog extends ExecuteWatchdog { IdleWatchdog() { super(1_000L); } @Override @@ -49,8 +99,12 @@ public synchronized void start(Process process) { } private static final class ExitedProcess extends Process { private final InputStream output; + ExitedProcess(InputStream output) { + this.output = output; + } + ExitedProcess(IOException readFailure) { - output = new InputStream() { + this(new InputStream() { private boolean emitted; @Override @@ -66,7 +120,7 @@ public int read(byte[] bytes, int offset, int length) throws IOException { emitted = true; return partial.length; } - }; + }); } @Override From 740608ca71ee8ff11de072338d0554c620c9afa3 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:22:03 +0800 Subject: [PATCH 006/105] Verify native subprocess contracts on macOS and Windows --- .github/workflows/platform-contracts.yml | 72 ++++++++++++ scripts/contract_report.py | 110 ++++++++++++++++++ .../support/SubprocessExecutionSupport.java | 45 ++++++- .../contract/OpenCliArgvContractTest.java | 24 ++++ .../opencli-contracts/argv-probe.cjs | 5 + 5 files changed, 255 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/platform-contracts.yml create mode 100644 scripts/contract_report.py create mode 100644 src/test/resources/opencli-contracts/argv-probe.cjs diff --git a/.github/workflows/platform-contracts.yml b/.github/workflows/platform-contracts.yml new file mode 100644 index 0000000..d513a18 --- /dev/null +++ b/.github/workflows/platform-contracts.yml @@ -0,0 +1,72 @@ +name: Platform subprocess contracts + +on: + push: + branches: [feature/REQ-20261118-wandl-opencli-privacy-10] + +permissions: + contents: read + +jobs: + process-platform: + name: Subprocess contracts (${{ matrix.os }}) + strategy: + fail-fast: false + matrix: + os: [macos-15-intel, windows-latest] + runs-on: ${{ matrix.os }} + timeout-minutes: 15 + defaults: + run: + shell: bash + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-java@v5 + with: + distribution: temurin + java-version: '8' + cache: maven + - uses: actions/setup-python@v7 + with: + python-version: '3.13' + - uses: actions/setup-node@v4 + if: runner.os == 'Windows' + with: + node-version: '22' + - name: Exercise real subprocess contracts + run: | + mkdir -p platform-evidence + if [[ "$RUNNER_OS" == Windows ]]; then + OPENCLI_CONTRACT_NODE_EXECUTABLE="$(node -p 'process.execPath')" + export OPENCLI_CONTRACT_NODE_EXECUTABLE + fi + java -version > platform-evidence/java.txt 2>&1 + mvn -version > platform-evidence/maven.txt 2>&1 + result=0 + mvn -B --no-transfer-progress \ + -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,SubprocessStreamFailureTest \ + test > platform-evidence/maven.log 2>&1 || result=$? + tail -100 platform-evidence/maven.log + python scripts/contract_report.py \ + --reports target/surefire-reports \ + --head "$(git rev-parse HEAD)" \ + --branch "$GITHUB_REF_NAME" \ + --java-version-file platform-evidence/java.txt \ + --maven-version-file platform-evidence/maven.txt \ + --exit-code "$result" \ + --suite argv=io.github.easy4j.opencli.contract.OpenCliArgvContractTest \ + --suite argv=io.github.easy4j.opencli.contract.OpenCliStructuredArgvContractTest \ + --suite process=io.github.easy4j.opencli.contract.OpenCliProcessContractTest \ + --suite process=io.github.easy4j.opencli.contract.OpenCliProcessBoundaryTest,SubprocessStreamFailureTest \ + --suite cleanup=io.github.easy4j.opencli.core.support.SubprocessStreamFailureTest \ + --output platform-evidence/report.json + exit "$result" + - name: Upload platform subprocess evidence + if: always() + uses: actions/upload-artifact@v7 + with: + name: subprocess-${{ matrix.os }}-${{ github.sha }} + path: | + platform-evidence + target/surefire-reports + if-no-files-found: error diff --git a/scripts/contract_report.py b/scripts/contract_report.py new file mode 100644 index 0000000..b0c8c78 --- /dev/null +++ b/scripts/contract_report.py @@ -0,0 +1,110 @@ +#!/usr/bin/env python3 +"""Build fail-closed, layer-specific evidence from real Surefire XML reports. + +This is not a code coverage percentage or a claim that OpenCLI websites work. +Only explicitly selected suites contribute to a layer. No network is used. +""" +import argparse +import json +import pathlib +import re +import sys +import xml.etree.ElementTree as ET + +LAYERS = ('enumeration', 'argv', 'process', 'protocol', 'typed-result', 'real-execution') + + +def _suite_summary(suite): + declared = {key: int(suite.attrib.get(key, '0')) for key in ('tests', 'failures', 'errors', 'skipped')} + cases = suite.findall('testcase') + actual = {'tests': len(cases), 'failures': sum(c.find('failure') is not None for c in cases), + 'errors': sum(c.find('error') is not None for c in cases), + 'skipped': sum(c.find('skipped') is not None for c in cases)} + if declared != actual or any(v < 0 for v in declared.values()): + raise ValueError('declared testcase counts disagree with XML evidence') + actual['executed'] = actual['tests'] - actual['skipped'] + return actual + + +def build_report(reports_dir, *, head, branch, java_version, maven_version, exit_code, required_suites): + """Return a JSON-serializable report; malformed/missing evidence fails closed.""" + problems = [] + if not re.fullmatch(r'[0-9a-fA-F]{40}', head or ''): + problems.append('exact 40-character source HEAD is required') + if not branch or not java_version.strip() or not maven_version.strip(): + problems.append('branch and actual tool versions are required') + if exit_code != 0: + problems.append('verification command exited nonzero') + if not required_suites or any(layer not in LAYERS or not names for layer, names in required_suites.items()): + problems.append('non-empty required suites must use recognized layers') + suites = {} + for path in sorted(pathlib.Path(reports_dir).glob('TEST-*.xml')): + try: + root = ET.parse(path).getroot() + nodes = [root] if root.tag == 'testsuite' else list(root.findall('testsuite')) + if not nodes: + raise ValueError('no testsuite') + for suite in nodes: + name = suite.attrib['name'] + if name in suites: + raise ValueError('duplicate testsuite') + suites[name] = _suite_summary(suite) + except (ET.ParseError, OSError, KeyError, ValueError): + problems.append('invalid or duplicate Surefire report: ' + path.name) + layers = {} + for layer in LAYERS: + names = list(required_suites.get(layer, [])) + counts = dict.fromkeys(('tests', 'executed', 'skipped', 'failures', 'errors'), 0) + missing = [name for name in names if name not in suites] + for name in names: + for key in counts: + counts[key] += suites.get(name, {}).get(key, 0) + state = 'NOT_RUN' + if names: + state = 'PASS' if (not missing and counts['executed'] > 0 and + not any(counts[key] for key in ('skipped', 'failures', 'errors'))) else 'FAIL' + layers[layer] = dict(counts, status=state, requiredSuites=names, missingSuites=missing) + if state == 'FAIL': + problems.append('required layer lacks passing, non-skipped execution: ' + layer) + return {'schemaVersion': 1, 'status': 'FAIL' if problems else 'PASS', + 'head': head, 'branch': branch, 'javaVersion': java_version, + 'mavenVersion': maven_version, 'commandExitCode': exit_code, + 'layers': layers, 'problems': problems, + 'scope': 'Explicit Surefire suites only; synthetic argv/process probes are not live OpenCLI verification.'} + + +def main(argv=None): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--reports', type=pathlib.Path, required=True) + parser.add_argument('--head', required=True) + parser.add_argument('--branch', required=True) + parser.add_argument('--java-version-file', type=pathlib.Path, required=True) + parser.add_argument('--maven-version-file', type=pathlib.Path, required=True) + parser.add_argument('--exit-code', type=int, required=True) + parser.add_argument('--suite', action='append', required=True, help='layer=fully.qualified.TestClass; repeatable') + parser.add_argument('--output', type=pathlib.Path, required=True) + args = parser.parse_args(argv) + required = {} + for item in args.suite: + layer, separator, name = item.partition('=') + if not separator or layer not in LAYERS or not name: + parser.error('--suite must be recognized-layer=fully.qualified.TestClass') + if name in required.setdefault(layer, []): + parser.error('duplicate --suite') + required[layer].append(name) + try: + report = build_report(args.reports, head=args.head, branch=args.branch, + java_version=args.java_version_file.read_text(encoding='utf-8'), + maven_version=args.maven_version_file.read_text(encoding='utf-8'), + exit_code=args.exit_code, required_suites=required) + except OSError as exc: + print('Missing tool-version evidence: ' + exc.__class__.__name__, file=sys.stderr) + return 1 + args.output.parent.mkdir(parents=True, exist_ok=True) + args.output.write_text(json.dumps(report, ensure_ascii=False, indent=2) + '\n', encoding='utf-8') + print(json.dumps({'status': report['status'], 'head': report['head'], 'layers': report['layers']})) + return 0 if report['status'] == 'PASS' else 1 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java index 98a5420..76248eb 100644 --- a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java +++ b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java @@ -13,6 +13,7 @@ import java.util.Collections; import java.util.HashMap; import java.util.List; +import java.util.Locale; import java.util.Map; import java.util.Objects; import java.util.concurrent.Semaphore; @@ -160,7 +161,7 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup } } if (acquired && reason == null) { - ProcessBuilder builder = new ProcessBuilder(request.nativeArgv); + ProcessBuilder builder = new ProcessBuilder(processArguments(request.nativeArgv)); if (request.workingDirectory != null) { builder.directory(request.workingDirectory); } if (request.environment != null) { builder.environment().clear(); @@ -310,6 +311,48 @@ private static boolean tryForceStop(Process process) { } } private static long remaining(long start, long budget) { return budget - (System.nanoTime() - start); } + // The Windows JDK legacy serializer treats a surrounding quote pair as already encoded. + @SuppressWarnings("removal") + private static List processArguments(List argv) { + String executable = argv.get(0).toLowerCase(Locale.ROOT); + if (!System.getProperty("os.name").startsWith("Windows") || !executable.endsWith(".exe") + || executable.endsWith("cmd.exe") || Objects.nonNull(System.getSecurityManager()) + || "false".equalsIgnoreCase(System.getProperty("jdk.lang.Process.allowAmbiguousCommands"))) { + return argv; + } + List arguments = new ArrayList<>(argv); + for (int i = 1; i < arguments.size(); i++) { + String argument = arguments.get(i); + if (argument.indexOf('"') >= 0) { + arguments.set(i, quoteWindowsExecutableArgument(argument)); + } + } + return arguments; + } + + /** Windows CRT quoting for arguments with literal quotes in a native executable. */ + private static String quoteWindowsExecutableArgument(String argument) { + StringBuilder quoted = new StringBuilder(argument.length() + 2).append('"'); + int backslashes = 0; + for (int i = 0; i < argument.length(); i++) { + char character = argument.charAt(i); + if (character == '\\') { + backslashes++; + continue; + } + int escaped = character == '"' ? backslashes * 2 + 1 : backslashes; + for (int j = 0; j < escaped; j++) { + quoted.append('\\'); + } + quoted.append(character); + backslashes = 0; + } + for (int i = 0; i < backslashes * 2; i++) { + quoted.append('\\'); + } + return quoted.append('"').toString(); + } + private static long elapsedMillis(long start) { return TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - start); } private static long nanos(long millis, String field) { diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java index e50a631..1bad49f 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java @@ -12,6 +12,9 @@ import java.io.InputStream; import java.io.InputStreamReader; import java.io.StringReader; +import java.net.URI; +import java.net.URISyntaxException; +import java.net.URL; import java.nio.charset.StandardCharsets; import java.util.ArrayList; import java.util.Arrays; @@ -19,6 +22,7 @@ import java.util.Collections; import java.util.LinkedHashMap; import java.util.List; +import java.util.Objects; import java.util.Map; import java.util.stream.Stream; import org.junit.jupiter.api.DynamicTest; @@ -35,6 +39,18 @@ private static OpenCliProperties properties() { p.setLeadingArguments(new ArrayList<>(Arrays.asList("-cp", System.getProperty("surefire.test.class.path", System.getProperty("java.class.path")), ContractProbe.class.getName()))); + String node = System.getenv("OPENCLI_CONTRACT_NODE_EXECUTABLE"); + if (System.getProperty("os.name").startsWith("Windows") && Objects.nonNull(node)) { + URL probe = OpenCliArgvContractTest.class.getResource("/opencli-contracts/argv-probe.cjs"); + p.setExecutable(node); + try { + URI location = Objects.requireNonNull(probe, "Windows argv fixture is required").toURI(); + p.getLeadingArguments().clear(); + p.getLeadingArguments().add(new File(location).getAbsolutePath()); + } catch (URISyntaxException e) { + throw new AssertionError("Invalid Windows argv fixture location", e); + } + } p.setCommandTimeoutMillis(10000L); return p; } @@ -96,6 +112,14 @@ Stream sharedVectorsReachEveryRawEntryPoint() throws Exception { return tests.stream(); } + @Test + void literalQuotesAndAdjacentBackslashesReachChildUnchanged() throws Exception { + List tokens = Arrays.asList("demo", "echo", "\"quoted\"", + "folder\\\"name with spaces\\", "two\\\\\"quotes\"\" and trailing\\\\"); + OpenCliResult result = new OpenCliExecutor(properties()).invoke(tokens); + assertEquals(tokens, received(result)); + } + @Test void structuredPositionalsAndValuesReachChildUnchanged() throws Exception { Map options = new LinkedHashMap<>(); diff --git a/src/test/resources/opencli-contracts/argv-probe.cjs b/src/test/resources/opencli-contracts/argv-probe.cjs new file mode 100644 index 0000000..88daed0 --- /dev/null +++ b/src/test/resources/opencli-contracts/argv-probe.cjs @@ -0,0 +1,5 @@ +const args = process.argv.slice(2); +console.log(`argc:${args.length}`); +for (const arg of args) { + console.log(`arg:${Buffer.from(arg, 'utf8').toString('base64')}`); +} From ca34757b111dd38676a8cf4484c7ca514512380c Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:27:42 +0800 Subject: [PATCH 007/105] fix: preserve trailing slashes in Windows JDK 8 arguments --- .github/workflows/platform-contracts.yml | 4 ++-- .../opencli/core/support/SubprocessExecutionSupport.java | 9 ++++++++- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.github/workflows/platform-contracts.yml b/.github/workflows/platform-contracts.yml index d513a18..0c57fe8 100644 --- a/.github/workflows/platform-contracts.yml +++ b/.github/workflows/platform-contracts.yml @@ -57,8 +57,8 @@ jobs: --suite argv=io.github.easy4j.opencli.contract.OpenCliArgvContractTest \ --suite argv=io.github.easy4j.opencli.contract.OpenCliStructuredArgvContractTest \ --suite process=io.github.easy4j.opencli.contract.OpenCliProcessContractTest \ - --suite process=io.github.easy4j.opencli.contract.OpenCliProcessBoundaryTest,SubprocessStreamFailureTest \ - --suite cleanup=io.github.easy4j.opencli.core.support.SubprocessStreamFailureTest \ + --suite process=io.github.easy4j.opencli.contract.OpenCliProcessBoundaryTest \ + --suite process=io.github.easy4j.opencli.core.support.SubprocessStreamFailureTest \ --output platform-evidence/report.json exit "$result" - name: Upload platform subprocess evidence diff --git a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java index 76248eb..4efe49e 100644 --- a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java +++ b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java @@ -347,10 +347,17 @@ private static String quoteWindowsExecutableArgument(String argument) { quoted.append(character); backslashes = 0; } + quoted.append('"'); + if (backslashes == 0) { + return quoted.toString(); + } + + // JDK 8 treats a final quote after a backslash as escaped. Close the quoted + // text first and use an empty quoted segment after the escaped trailing slashes. for (int i = 0; i < backslashes * 2; i++) { quoted.append('\\'); } - return quoted.append('"').toString(); + return quoted.append('"').append('"').toString(); } private static long elapsedMillis(long start) { return TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - start); } From 86564e47c30bf8ac5d873178cc501780d760dd10 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:35:52 +0800 Subject: [PATCH 008/105] test: verify bounded OpenCLI network follow outcomes --- .../harden-opencli-process-lifecycle/tasks.md | 6 + .../opencli/contract/LifecycleProbe.java | 32 ++++++ .../contract/OpenCliProcessContractTest.java | 108 ++++++++++++++++++ 3 files changed, 146 insertions(+) diff --git a/openspec/changes/harden-opencli-process-lifecycle/tasks.md b/openspec/changes/harden-opencli-process-lifecycle/tasks.md index 253d98a..3e07948 100644 --- a/openspec/changes/harden-opencli-process-lifecycle/tasks.md +++ b/openspec/changes/harden-opencli-process-lifecycle/tasks.md @@ -24,3 +24,9 @@ ## 证据交付模板(实施时填写) 每项任务的完成记录包含:Requirement/Scenario、分支HEAD、测试命令、失败→通过证据、测试数/跳过数、退出码、报告位置。没有记录的任务保持未完成。 + +## OC-PROC-006 本地同步采集验证 + +`OpenCliProcessContractTest` 经 typed `browser network --follow` 入口运行真实 JVM fixture,校验 CLI argv,并覆盖正常退出、CLI 非零退出、输出超限、调用线程中断、执行超时,以及禁用时限时启动前拒绝。超时测试同时启动独立进程,确认该进程仍运行并可自行正常退出。JDK 8 执行 `mvn -B -ntp -o clean verify` 退出 0,全量 2,095 项(其中该类 14 项),0 失败、0 错误、0 跳过。 + +本记录覆盖当前本地同步入口。平台矩阵、真实 OpenCLI 持续输出、受控 sink 和后代进程所有权仍需独立证据。 diff --git a/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java index 88247cf..1b0c7a1 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java +++ b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java @@ -12,6 +12,10 @@ private LifecycleProbe() { } public static void main(String[] args) throws Exception { String mode = args[0]; + if ("network-follow".equals(mode)) { + networkFollow(args); + return; + } if ("utf8".equals(mode)) { System.out.write("中文".getBytes(StandardCharsets.UTF_8)); return; @@ -41,4 +45,32 @@ public static void main(String[] args) throws Exception { Thread.sleep(20L); } } + + private static void networkFollow(String[] args) throws Exception { + if (!Arrays.asList("browser", "fixture", "network", "--follow") + .equals(Arrays.asList(args).subList(3, args.length))) { + throw new IllegalArgumentException("unexpected network follow argv"); + } + System.out.print("event-one\n"); + System.out.flush(); + switch (args[1]) { + case "complete": + Thread.sleep(30L); + System.out.print("event-two\n"); + break; + case "overflow": + main(new String[]{"stdout", "4096"}); + break; + case "failed": + System.err.print("fixture failed"); + System.exit(23); + break; + case "wait": + Files.write(Paths.get(args[2]), new byte[]{1}); + Thread.sleep(8000L); + break; + default: + throw new IllegalArgumentException("unexpected network follow mode"); + } + } } diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java index 5cb4397..aeb28af 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java @@ -1,9 +1,14 @@ package io.github.easy4j.opencli.contract; import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.browser.OpenCliBrowserClient; +import io.github.easy4j.opencli.browser.OpenCliBrowserSession; +import io.github.easy4j.opencli.browser.OpenCliBrowserSession.OpenCliBrowserNetworkOptions; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails.TerminationReason; import io.github.easy4j.opencli.core.OpenCliExecutor; import io.github.easy4j.opencli.core.OpenCliResult; import io.github.easy4j.opencli.exception.OpenCliException; +import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; import io.github.easy4j.opencli.exception.OpenCliTimeoutException; import java.io.File; import java.nio.charset.StandardCharsets; @@ -64,6 +69,109 @@ private static Object getter(Object object, String name) { private static Object details(OpenCliResult result) { return getter(result, "getExecutionDetails"); } + private OpenCliBrowserSession followSession(OpenCliProperties properties, String mode) { + properties.getLeadingArguments().addAll(Arrays.asList("network-follow", mode, dir.resolve("follow-ready").toString())); + return new OpenCliBrowserClient(new OpenCliExecutor(properties)).session("fixture"); + } + + private OpenCliResult follow(OpenCliBrowserSession session) { + return session.network(OpenCliBrowserNetworkOptions.builder().follow(true).build(), null); + } + + @Test + void networkFollowReturnsCapturedEventsAfterNormalExit() { + OpenCliResult result = follow(followSession(properties(1), "complete")); + assertTrue(result.isSuccess()); + assertEquals("event-one\nevent-two\n", result.getStdout()); + assertEquals(TerminationReason.PROCESS_EXIT, result.getExecutionDetails().getTerminationReason()); + } + + @Test + void networkFollowStopsAtCaptureLimitWithPartialOutput() { + OpenCliProperties properties = properties(1); + properties.setMaxStdoutBytes(32); + OpenCliBrowserSession session = followSession(properties, "overflow"); + OpenCliException failure = assertThrows(OpenCliException.class, () -> follow(session)); + OpenCliResult partial = failure.getPartialResult(); + assertEquals(TerminationReason.OUTPUT_LIMIT, partial.getExecutionDetails().getTerminationReason()); + assertEquals(32L, partial.getExecutionDetails().getStdoutCapturedBytes()); + assertTrue(partial.getStdout().startsWith("event-one\n")); + assertFalse(partial.isSuccess()); + } + + @Test + void networkFollowReportsTheCliExitCode() { + OpenCliBrowserSession session = followSession(properties(1), "failed"); + OpenCliNonZeroExitException failure = assertThrows(OpenCliNonZeroExitException.class, () -> follow(session)); + OpenCliResult partial = failure.getPartialResult(); + assertEquals(Integer.valueOf(23), partial.getExitCode()); + assertEquals("fixture failed", partial.getStderr()); + assertEquals(TerminationReason.PROCESS_EXIT, partial.getExecutionDetails().getTerminationReason()); + } + + @Test + void networkFollowRejectsDisabledDeadlineBeforeSpawning() { + OpenCliProperties properties = properties(1); + properties.setCommandTimeoutMillis(0L); + OpenCliBrowserSession session = followSession(properties, "wait"); + IllegalStateException failure = assertThrows(IllegalStateException.class, () -> follow(session)); + assertEquals("opencli.command-timeout-millis must be positive", failure.getMessage()); + assertFalse(Files.exists(dir.resolve("follow-ready"))); + } + + @Test + void networkFollowTimeoutLeavesAnIndependentProcessRunning() throws Exception { + OpenCliExecutor independent = new OpenCliExecutor(properties(1)); + Path started = dir.resolve("independent-started"); + Path gate = dir.resolve("independent-release"); + ExecutorService worker = Executors.newSingleThreadExecutor(); + try { + Future other = worker.submit(() -> independent.invoke("hold", started.toString(), gate.toString())); + assertTrue(awaitFile(started, 5000L)); + + OpenCliProperties properties = properties(1); + properties.setCommandTimeoutMillis(2500L); + OpenCliBrowserSession session = followSession(properties, "wait"); + OpenCliTimeoutException timeout = assertThrows(OpenCliTimeoutException.class, () -> follow(session)); + OpenCliResult partial = timeout.getPartialResult(); + assertEquals(TerminationReason.EXECUTION_TIMEOUT, partial.getExecutionDetails().getTerminationReason()); + assertEquals("event-one\n", partial.getStdout()); + + assertFalse(other.isDone(), "timeout must leave independent invocation running"); + release(gate); + assertTrue(other.get(5, TimeUnit.SECONDS).isSuccess()); + } finally { + release(gate); + worker.shutdownNow(); + assertTrue(worker.awaitTermination(5, TimeUnit.SECONDS)); + } + } + + @Test + void networkFollowPreservesCancellationAfterAnEvent() throws Exception { + OpenCliBrowserSession session = followSession(properties(1), "wait"); + AtomicReference partial = new AtomicReference<>(); + Thread caller = new Thread(() -> { + try { + follow(session); + } catch (OpenCliException failure) { + partial.set(failure.getPartialResult()); + } + }, "network-follow-caller"); + try { + caller.start(); + assertTrue(awaitFile(dir.resolve("follow-ready"), 5000L)); + caller.interrupt(); + caller.join(5000L); + assertFalse(caller.isAlive()); + assertNotNull(partial.get()); + assertEquals(TerminationReason.CANCELLED, partial.get().getExecutionDetails().getTerminationReason()); + } finally { + caller.interrupt(); + caller.join(5000L); + } + } + @Test void anotherClientCannotReplaceAnActiveClientsLimiter() throws Exception { OpenCliExecutor a = new OpenCliExecutor(properties(1)); From 896a637f2e9bda5210b074ab0ef9eb244db31836 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:53:30 +0800 Subject: [PATCH 009/105] fix: backport reverse WebSocket worker safeguards --- README.md | 4 + README.zh-CN.md | 4 + .../harden-opencli-reverse-agent/tasks.md | 4 + .../OpenCliWsAgentConnectionProperties.java | 6 + .../center/ws/OpenCliWsCollectRequests.java | 132 +++++ .../ws/OpenCliWsReverseAgentClient.java | 184 ++++-- .../ws/OpenCliWsCollectRequestsTest.java | 45 ++ .../ws/OpenCliWsReverseAgentSessionTest.java | 540 ++++++++++++++++++ .../opencli/contract/LifecycleProbe.java | 8 +- 9 files changed, 871 insertions(+), 56 deletions(-) create mode 100644 src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsCollectRequests.java create mode 100644 src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsCollectRequestsTest.java create mode 100644 src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java diff --git a/README.md b/README.md index 08ccaff..b6a8726 100644 --- a/README.md +++ b/README.md @@ -224,6 +224,10 @@ agent.close(); Protocol: edge sends `register`; center replies `registered`; center sends `collect` (request_id, site, command, args, positional_args, format, mode); the SDK executes `opencli` locally (via `copyForLocalCliExecution()` to avoid loops) and replies `result`; plus `ping` / `pong`. +The reverse agent accepts up to four concurrent collect tasks and 32 queued tasks by default. Set `maxConcurrentCollects` and `maxPendingCollects` on the connection properties before constructing the agent to change the limits. A queue capacity of zero disables waiting. When full, the agent replies with a failed `result` and the error `worker is busy`. + +Collect request IDs must be nonblank strings of at most 128 UTF-8 bytes. The agent suppresses identical in-flight requests and rejects a reused ID with a different payload. An explicit retry may return a result marked `cached: true`. The in-memory cache keeps up to 1,024 completed results for at most ten minutes. Replay across reconnects requires the same TLS-verified endpoint. Plain WebSocket connections keep session-local deduplication. Restarting the agent discards its cache. + ### Diagnostic export Call `OpenCliDiagnosticExport.export(result, 512)` explicitly with an `OpenCliResult` or an exception's partial result. The byte budget applies to UTF-8 text. Output contains only status and field lengths, with a `truncated=true` marker when fields do not fit. Field lengths can disclose how much data was present. diff --git a/README.zh-CN.md b/README.zh-CN.md index 89693d5..06d0272 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -223,6 +223,10 @@ agent.close(); 协议摘要:边缘发送 `register`;中心回执 `registered`;中心下发 `collect`(request_id、site、command、args、positional_args、format、mode);SDK 在本机执行 `opencli`(通过 `copyForLocalCliExecution()` 强制本地子进程,避免回路)并回执 `result`;另有 `ping` / `pong`。 +反向 Agent 默认最多同时执行 4 个 collect 任务,另有 32 个等待名额。构建 Agent 前,可在连接配置中设置 `maxConcurrentCollects` 和 `maxPendingCollects`。等待容量为零时直接拒绝超额请求。容量用尽时返回失败的 `result`,错误为 `worker is busy`。 + +collect 请求 ID 必须为非空白字符串,长度上限 128 个 UTF-8 字节。相同的在途请求只执行一次,同一个 ID 对应不同载荷时会明确拒绝。显式重试已完成的请求有可能收到标记为 `cached: true` 的结果。内存缓存最多保留 1,024 条完成结果,每条最长 10 分钟。跨连接重放要求使用同一个经过 TLS 校验的端点,明文 WebSocket 的去重范围为当前连接。Agent 重启后会清空缓存。 + ### 诊断导出 如需导出诊断,请调用 `OpenCliDiagnosticExport.export(result, 512)`,传入 `OpenCliResult` 或异常中的部分结果。上限按 UTF-8 字节计算。输出只包含状态和字段长度,字段放不下时会标明 `truncated=true`。字段长度仍可能反映数据规模。 diff --git a/openspec/changes/harden-opencli-reverse-agent/tasks.md b/openspec/changes/harden-opencli-reverse-agent/tasks.md index f7ff684..e113e5c 100644 --- a/openspec/changes/harden-opencli-reverse-agent/tasks.md +++ b/openspec/changes/harden-opencli-reverse-agent/tasks.md @@ -25,3 +25,7 @@ ## 证据交付模板(实施时填写) 每项任务的完成记录包含:Requirement/Scenario、分支HEAD、测试命令、失败→通过证据、测试数/跳过数、退出码、报告位置。没有记录的任务保持未完成。 + +## JDK 8 回移验证 + +回移 JDK 17 版本的注册前拒绝、执行与等待上限、关闭保护、请求去重、缓存过期和连接隔离。通过本地回环服务器、真实子进程和测试证书验证普通连接和 TLS 重连。运行 `mvn -B -ntp -o clean verify`,2,112 项测试通过,零失败、零跳过,JaCoCo 行覆盖率为 2,905 / 3,167(91.73%)。 diff --git a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsAgentConnectionProperties.java b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsAgentConnectionProperties.java index ce45a13..7aa4c9d 100644 --- a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsAgentConnectionProperties.java +++ b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsAgentConnectionProperties.java @@ -59,6 +59,12 @@ public class OpenCliWsAgentConnectionProperties { */ private String nodeType = "shell"; + /** 并行执行的 collect 任务上限,必须为正数。 */ + private int maxConcurrentCollects = 4; + + /** 排队的 collect 任务上限,零表示没有等待队列。 */ + private int maxPendingCollects = 32; + /** * 首次 {@code registered} 应答等待上限(毫秒)。 */ diff --git a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsCollectRequests.java b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsCollectRequests.java new file mode 100644 index 0000000..808290d --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsCollectRequests.java @@ -0,0 +1,132 @@ +package io.github.easy4j.opencli.center.ws; + +import com.fasterxml.jackson.databind.node.ObjectNode; +import java.util.Arrays; +import java.util.HashMap; +import java.util.Iterator; +import java.util.LinkedHashMap; +import java.util.Map; +import java.util.Objects; +import java.util.function.LongSupplier; + +/** Tracks accepted requests and bounded, instance-local replay results. */ +final class OpenCliWsCollectRequests { + + enum Status { + ACCEPTED, IN_FLIGHT, CONFLICT, CACHED + } + + static final class Key { + private final Object center; + private final String requestId; + + Key(Object center, String requestId) { + this.center = center; + this.requestId = requestId; + } + + String requestId() { + return requestId; + } + + @Override + public boolean equals(Object other) { + if (!(other instanceof Key)) { + return false; + } + Key key = (Key) other; + return center.equals(key.center) && requestId.equals(key.requestId); + } + + @Override + public int hashCode() { + return 31 * center.hashCode() + requestId.hashCode(); + } + } + + static final class Admission { + private final Status status; + private final ObjectNode cachedResult; + + Admission(Status status, ObjectNode cachedResult) { + this.status = status; + this.cachedResult = cachedResult; + } + + Status status() { + return status; + } + + ObjectNode cachedResult() { + return cachedResult; + } + } + + private static final class Completed { + private final byte[] digest; + private final ObjectNode result; + private final long completedAt; + + Completed(byte[] digest, ObjectNode result, long completedAt) { + this.digest = digest; + this.result = result; + this.completedAt = completedAt; + } + } + + private final Map inFlight = new HashMap<>(); + private final Map completed = new LinkedHashMap<>(); + private final int maxCompleted; + private final long ttlNanos; + private final LongSupplier clock; + + OpenCliWsCollectRequests(int maxCompleted, long ttlNanos, LongSupplier clock) { + this.maxCompleted = maxCompleted; + this.ttlNanos = ttlNanos; + this.clock = clock; + } + + synchronized Admission reserve(Key key, byte[] digest) { + byte[] active = inFlight.get(key); + if (Objects.nonNull(active)) { + return new Admission(Arrays.equals(active, digest) ? Status.IN_FLIGHT : Status.CONFLICT, null); + } + expire(clock.getAsLong()); + Completed previous = completed.get(key); + if (Objects.nonNull(previous)) { + if (!Arrays.equals(previous.digest, digest)) { + return new Admission(Status.CONFLICT, null); + } + return new Admission(Status.CACHED, previous.result.deepCopy().put("cached", true)); + } + inFlight.put(key, digest); + return new Admission(Status.ACCEPTED, null); + } + + synchronized void complete(Key key, ObjectNode result) { + byte[] digest = inFlight.remove(key); + if (Objects.isNull(digest) || Objects.isNull(result)) { + return; + } + long now = clock.getAsLong(); + expire(now); + if (completed.size() >= maxCompleted) { + Iterator entries = completed.keySet().iterator(); + entries.next(); + entries.remove(); + } + completed.put(key, new Completed(digest, result, now)); + } + + synchronized void clear() { + inFlight.clear(); + completed.clear(); + } + + private void expire(long now) { + Iterator entries = completed.values().iterator(); + while (entries.hasNext() && now - entries.next().completedAt >= ttlNanos) { + entries.remove(); + } + } +} diff --git a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java index b1a5fd8..026d669 100644 --- a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java +++ b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java @@ -8,9 +8,10 @@ import io.github.easy4j.opencli.core.OpenCliExecutor; import io.github.easy4j.opencli.core.OpenCliResult; import io.github.easy4j.opencli.exception.OpenCliException; -import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; import io.github.easy4j.opencli.util.OpenCliStrings; import java.net.URI; +import java.nio.charset.StandardCharsets; +import java.security.MessageDigest; import java.util.ArrayList; import java.util.Collections; import java.util.Iterator; @@ -18,9 +19,13 @@ import java.util.List; import java.util.Map; import java.util.Objects; +import java.util.concurrent.BlockingQueue; import java.util.concurrent.CountDownLatch; import java.util.concurrent.ExecutorService; -import java.util.concurrent.Executors; +import java.util.concurrent.LinkedBlockingQueue; +import java.util.concurrent.RejectedExecutionException; +import java.util.concurrent.SynchronousQueue; +import java.util.concurrent.ThreadPoolExecutor; import java.util.concurrent.TimeUnit; import java.util.concurrent.atomic.AtomicReference; import lombok.extern.slf4j.Slf4j; @@ -48,18 +53,15 @@ public final class OpenCliWsReverseAgentClient implements AutoCloseable { private static final ObjectMapper MAPPER = new ObjectMapper(); + private static final long CLOSE_WAIT_NANOS = TimeUnit.SECONDS.toNanos(5); private final OpenCliExecutor localExecutor; private final OpenCliWsAgentConnectionProperties connectionProperties; - private final ExecutorService collectPool = - Executors.newCachedThreadPool( - r -> { - Thread t = new Thread(r, "opencli-ws-collect"); - t.setDaemon(true); - return t; - }); + private final ExecutorService collectPool; + private final OpenCliWsCollectRequests collectRequests = + new OpenCliWsCollectRequests(1024, TimeUnit.MINUTES.toNanos(10), System::nanoTime); private volatile boolean shutdownRequested; @@ -76,6 +78,17 @@ public OpenCliWsReverseAgentClient( Objects.requireNonNull(openCliProperties, "openCliProperties"); this.connectionProperties = Objects.requireNonNull(connectionProperties, "connectionProperties"); + int workers = connectionProperties.getMaxConcurrentCollects(); + int pending = connectionProperties.getMaxPendingCollects(); + if (workers <= 0 || pending < 0 || (long) workers + pending >= Integer.MAX_VALUE) { + throw new IllegalArgumentException("Collect capacity requires positive concurrency and a finite pending queue"); + } + BlockingQueue queue = pending == 0 ? new SynchronousQueue<>() : new LinkedBlockingQueue<>(pending); + this.collectPool = new ThreadPoolExecutor(workers, workers, 0L, TimeUnit.MILLISECONDS, queue, runnable -> { + Thread thread = new Thread(runnable, "opencli-ws-collect"); + thread.setDaemon(true); + return thread; + }); this.localExecutor = new OpenCliExecutor(openCliProperties.copyForLocalCliExecution()); } @@ -83,6 +96,9 @@ public OpenCliWsReverseAgentClient( * 启动后台重连线程。 */ public synchronized void start() { + if (collectPool.isShutdown()) { + throw new IllegalStateException("WebSocket worker is closed"); + } if (runnerThread != null && runnerThread.isAlive()) { return; } @@ -113,8 +129,26 @@ public synchronized void stop() { @Override public void close() { - stop(); - collectPool.shutdown(); + Thread runner; + synchronized (this) { + if (collectPool.isShutdown()) { + return; + } + stop(); + collectPool.shutdownNow(); + collectRequests.clear(); + runner = runnerThread; + } + long deadline = System.nanoTime() + CLOSE_WAIT_NANOS; + try { + collectPool.awaitTermination(CLOSE_WAIT_NANOS, TimeUnit.NANOSECONDS); + long remaining = deadline - System.nanoTime(); + if (remaining > 0 && Objects.nonNull(runner) && runner != Thread.currentThread()) { + TimeUnit.NANOSECONDS.timedJoin(runner, remaining); + } + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } } private void runLoop() { @@ -153,9 +187,10 @@ private void runLoop() { private void runOneSession() throws Exception { validateConnectionProperties(); - String wsUrl = - OpenCliCenterWsUrls.toAgentWebSocketUrl( - connectionProperties.getCentralApiBaseUrl(), connectionProperties.getWebSocketPath()); + URI endpoint = URI.create(OpenCliCenterWsUrls.toAgentWebSocketUrl( + connectionProperties.getCentralApiBaseUrl(), connectionProperties.getWebSocketPath())); + // The default TLS client verifies the endpoint hostname. Plain WS has session-local identity. + Object centerIdentity = "wss".equalsIgnoreCase(endpoint.getScheme()) ? endpoint : new Object(); final CountDownLatch registered = new CountDownLatch(1); final CountDownLatch sessionClosed = new CountDownLatch(1); @@ -163,7 +198,7 @@ private void runOneSession() throws Exception { log.info("opencli ws connecting"); WebSocketClient client = - new WebSocketClient(URI.create(wsUrl)) { + new WebSocketClient(endpoint) { @Override public void onOpen(ServerHandshake handshake) { try { @@ -178,7 +213,7 @@ public void onOpen(ServerHandshake handshake) { @Override public void onMessage(String message) { try { - handleTextMessage(this, message, registered, handshakeFailure); + handleTextMessage(this, centerIdentity, message, registered, handshakeFailure); } catch (Exception e) { log.warn("handle ws message failed"); } @@ -276,6 +311,7 @@ private String buildRegisterJson() throws Exception { private void handleTextMessage( WebSocketClient ws, + Object centerIdentity, String payload, CountDownLatch registered, AtomicReference handshakeFailure) @@ -294,13 +330,61 @@ private void handleTextMessage( return; } if ("collect".equals(type)) { - final JsonNode msg = root; - collectPool.submit(() -> runCollectSafe(ws, msg)); + JsonNode id = root.path("request_id"); + String requestId = id.isTextual() ? id.textValue() : ""; + if ((OpenCliStrings.isBlank(requestId) || requestId.codePoints().allMatch(Character::isWhitespace)) || requestId.getBytes(StandardCharsets.UTF_8).length > 128) { + sendResult(ws, result("", false, Collections.emptyList(), "invalid worker request ID")); + return; + } + if (shutdownRequested || !ws.isOpen() || registered.getCount() > 0 + || Objects.nonNull(handshakeFailure.get())) { + sendResult(ws, result(requestId, false, Collections.emptyList(), "worker is not registered")); + return; + } + admitCollect(ws, centerIdentity, requestId, root); + } + } + + private void admitCollect(WebSocketClient ws, Object centerIdentity, String requestId, JsonNode payload) + throws Exception { + OpenCliWsCollectRequests.Key key = new OpenCliWsCollectRequests.Key(centerIdentity, requestId); + byte[] digest = MessageDigest.getInstance("SHA-256").digest(MAPPER.writeValueAsBytes(payload)); + OpenCliWsCollectRequests.Admission admission = collectRequests.reserve(key, digest); + switch (admission.status()) { + case IN_FLIGHT: + return; + case CONFLICT: + sendResult(ws, result(requestId, false, Collections.emptyList(), "worker request ID conflict")); + return; + case CACHED: + sendResult(ws, admission.cachedResult()); + return; + case ACCEPTED: + try { + collectPool.execute(() -> runCollectSafe(ws, key, payload)); + } catch (RejectedExecutionException e) { + collectRequests.complete(key, null); + sendResult(ws, result(requestId, false, Collections.emptyList(), "worker is busy")); + } + return; + } + } + + private void runCollectSafe(WebSocketClient ws, OpenCliWsCollectRequests.Key key, JsonNode msg) { + ObjectNode response = null; + try { + if (!collectPool.isShutdown() && !Thread.currentThread().isInterrupted()) { + response = executeCollect(key.requestId(), msg); + } + } finally { + collectRequests.complete(key, response); + } + if (Objects.nonNull(response) && ws.isOpen()) { + sendResult(ws, response); } } - private void runCollectSafe(WebSocketClient ws, JsonNode msg) { - String requestId = msg.path("request_id").asText(""); + private ObjectNode executeCollect(String requestId, JsonNode msg) { try { String site = msg.path("site").asText(""); String command = msg.path("command").asText(""); @@ -313,27 +397,17 @@ private void runCollectSafe(WebSocketClient ws, JsonNode msg) { OpenCliResult r = localExecutor.invoke(argv); List items = OpenCliWsCollectStdoutItems.parseItems(r.getStdout(), format); if (!r.isSuccess()) { - sendResult(ws, requestId, false, items, "opencli reported failure"); - return; + return result(requestId, false, items, "opencli reported failure"); } - sendResult(ws, requestId, true, items, null); - } catch (OpenCliNonZeroExitException e) { - OpenCliResult partial = e.getPartialResult(); - String err = - Objects.nonNull(partial) && OpenCliStrings.isNotBlank(partial.getStderr()) - ? partial.getStderr() - : e.getMessage(); - sendResult(ws, requestId, false, Collections.emptyList(), err); + return result(requestId, true, items, null); } catch (OpenCliException e) { OpenCliResult partial = e.getPartialResult(); - String err = - Objects.nonNull(partial) && OpenCliStrings.isNotBlank(partial.getStderr()) - ? partial.getStderr() - : e.getMessage(); - sendResult(ws, requestId, false, Collections.emptyList(), err); + String err = Objects.nonNull(partial) && OpenCliStrings.isNotBlank(partial.getStderr()) + ? partial.getStderr() : e.getMessage(); + return result(requestId, false, Collections.emptyList(), err); } catch (Exception e) { log.warn("collect execution failed"); - sendResult(ws, requestId, false, Collections.emptyList(), "collect execution failed"); + return result(requestId, false, Collections.emptyList(), "collect execution failed"); } } @@ -385,26 +459,26 @@ private static List readPositionalList(JsonNode node) { return list; } - private static void sendResult( - WebSocketClient ws, String requestId, boolean success, List items, String error) { + private static ObjectNode result(String requestId, boolean success, List items, String error) { + ObjectNode out = MAPPER.createObjectNode(); + out.put("type", "result"); + out.put("request_id", requestId); + out.put("success", success); + ArrayNode arr = out.putArray("items"); + if (Objects.nonNull(items)) { + items.forEach(arr::add); + } + if (Objects.isNull(error) || error.isEmpty()) { + out.putNull("error"); + } else { + out.put("error", error); + } + return out; + } + + private static void sendResult(WebSocketClient ws, ObjectNode result) { try { - ObjectNode out = MAPPER.createObjectNode(); - out.put("type", "result"); - out.put("request_id", requestId); - out.put("success", success); - ArrayNode arr = MAPPER.createArrayNode(); - if (Objects.nonNull(items)) { - for (JsonNode i : items) { - arr.add(i); - } - } - out.set("items", arr); - if (Objects.isNull(error) || error.isEmpty()) { - out.putNull("error"); - } else { - out.put("error", error); - } - ws.send(MAPPER.writeValueAsString(out)); + ws.send(MAPPER.writeValueAsString(result)); } catch (Exception e) { log.error("failed to send WS result"); } diff --git a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsCollectRequestsTest.java b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsCollectRequestsTest.java new file mode 100644 index 0000000..9e90c2d --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsCollectRequestsTest.java @@ -0,0 +1,45 @@ +package io.github.easy4j.opencli.center.ws; + +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.node.ObjectNode; +import java.util.concurrent.atomic.AtomicLong; +import org.junit.jupiter.api.Test; + +import static io.github.easy4j.opencli.center.ws.OpenCliWsCollectRequests.Status.ACCEPTED; +import static io.github.easy4j.opencli.center.ws.OpenCliWsCollectRequests.Status.CACHED; +import static io.github.easy4j.opencli.center.ws.OpenCliWsCollectRequests.Status.CONFLICT; +import static io.github.easy4j.opencli.center.ws.OpenCliWsCollectRequests.Status.IN_FLIGHT; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +class OpenCliWsCollectRequestsTest { + + @Test + void evictsAndExpiresCompletedResultsWithoutDroppingActiveReservations() { + AtomicLong clock = new AtomicLong(); + OpenCliWsCollectRequests requests = new OpenCliWsCollectRequests(1, 100, clock::get); + OpenCliWsCollectRequests.Key active = new OpenCliWsCollectRequests.Key("center", "active"); + OpenCliWsCollectRequests.Key first = new OpenCliWsCollectRequests.Key("center", "first"); + OpenCliWsCollectRequests.Key second = new OpenCliWsCollectRequests.Key("center", "second"); + byte[] digest = {1}; + ObjectNode result = new ObjectMapper().createObjectNode().put("success", true); + + assertEquals(ACCEPTED, requests.reserve(active, digest).status()); + assertEquals(ACCEPTED, requests.reserve(first, digest).status()); + requests.complete(first, result); + assertEquals(ACCEPTED, requests.reserve(second, digest).status()); + requests.complete(second, result); + + assertEquals(IN_FLIGHT, requests.reserve(active, digest).status()); + assertEquals(CONFLICT, requests.reserve(active, new byte[] {2}).status()); + assertEquals(ACCEPTED, requests.reserve(first, digest).status()); + assertEquals(CACHED, requests.reserve(second, digest).status()); + assertTrue(requests.reserve(second, digest).cachedResult().path("cached").asBoolean()); + assertFalse(result.has("cached")); + + clock.set(100); + assertEquals(ACCEPTED, requests.reserve(second, digest).status()); + assertEquals(IN_FLIGHT, requests.reserve(active, digest).status()); + } +} diff --git a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java new file mode 100644 index 0000000..200a3cd --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java @@ -0,0 +1,540 @@ +package io.github.easy4j.opencli.center.ws; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.node.ObjectNode; +import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.contract.ContractProbe; +import io.github.easy4j.opencli.contract.LifecycleProbe; +import java.io.File; +import java.io.IOException; +import java.io.InputStream; +import java.net.InetSocketAddress; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.security.KeyStore; +import java.util.Arrays; +import java.util.Base64; +import java.util.Collections; +import java.util.HashSet; +import java.util.Set; +import java.util.List; +import java.util.Objects; +import java.util.concurrent.BlockingQueue; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.LinkedBlockingQueue; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicReference; +import java.util.stream.Collectors; +import javax.net.ssl.KeyManagerFactory; +import javax.net.ssl.SSLContext; +import javax.net.ssl.TrustManagerFactory; +import org.java_websocket.WebSocket; +import org.java_websocket.handshake.ClientHandshake; +import org.java_websocket.server.DefaultSSLWebSocketServerFactory; +import org.java_websocket.server.WebSocketServer; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import org.junit.jupiter.api.parallel.Isolated; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.CsvSource; +import org.junit.jupiter.params.provider.ValueSource; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNotSame; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +@Isolated +class OpenCliWsReverseAgentSessionTest { + + private static final ObjectMapper MAPPER = new ObjectMapper(); + private static final String AGENT_URL = "http://127.0.0.1:19823"; + + @Test + void exchangesRegistrationAndCollectResultsAndReconnectsAfterRemoteClose() throws Exception { + try (LocalCenter center = new LocalCenter()) { + OpenCliWsAgentConnectionProperties connection = center.agentProperties(); + connection.setMode(""); + connection.setNodeType(""); + connection.setLabel(null); + try (OpenCliWsReverseAgentClient agent = new OpenCliWsReverseAgentClient(probe(ContractProbe.class.getName()), connection)) { + agent.start(); + WireMessage registration = center.receive("register"); + assertEquals(AGENT_URL, registration.body.path("agent_url").asText()); + assertEquals("cdp", registration.body.path("mode").asText()); + assertEquals("shell", registration.body.path("node_type").asText()); + assertTrue(registration.body.path("label").asText().isEmpty()); + + registration.socket.send("{\"type\":\"registered\"}"); + agent.start(); + registration.socket.send("malformed-json"); + registration.socket.send("{\"type\":\"pong\"}"); + registration.socket.send("{\"type\":\"ping\"}"); + center.receive("pong"); + + registration.socket.send("{\"type\":\"collect\",\"request_id\":\"valid\"," + + "\"site\":\"demo\",\"command\":\"echo\",\"format\":\"text\"," + + "\"positional_args\":[\" kept \",null,42],\"args\":{" + + "\"flag\":null,\"boolean\":false,\"count\":7,\"long\":2147483648," + + "\"double\":1.5,\"text\":\"a b\",\"structured\":{\"key\":1}}}"); + JsonNode result = center.receive("result").body; + assertEquals("valid", result.path("request_id").asText()); + assertTrue(result.path("success").asBoolean()); + assertTrue(result.path("error").isNull()); + List argv = Arrays.stream(result.path("items").get(0).path("content").asText().split("\\R")) + .filter(line -> line.startsWith("arg:")) + .map(line -> new String(Base64.getDecoder().decode(line.substring(4)), StandardCharsets.UTF_8)) + .collect(Collectors.toList()); + assertEquals(Arrays.asList("demo", "echo", " kept ", "42", "--flag", "--boolean", + "false", "--count", "7", "--long", "2147483648", "--double", "1.5", "--text", + "a b", "--structured", "{\"key\":1}", "-f", "text"), argv); + + registration.socket.send("{\"type\":\"collect\",\"request_id\":\"invalid\",\"command\":\"echo\"}"); + JsonNode invalid = center.receive("result").body; + assertEquals("invalid", invalid.path("request_id").asText()); + assertFalse(invalid.path("success").asBoolean()); + assertTrue(invalid.path("items").isEmpty()); + assertEquals("collect execution failed", invalid.path("error").asText()); + + registration.socket.close(); + WireMessage retry = center.receive("register"); + assertNotSame(registration.socket, retry.socket); + assertEquals(registration.body, retry.body); + } + } + } + + @Test + void collectBeforeRegistrationAcknowledgementDoesNotStartChild(@TempDir Path temporary) throws Exception { + Path marker = temporary.resolve("child-started"); + try (LocalCenter center = new LocalCenter(); + OpenCliWsReverseAgentClient agent = new OpenCliWsReverseAgentClient( + probe(LifecycleProbe.class.getName()), center.agentProperties())) { + agent.start(); + WireMessage registration = center.receive("register"); + registration.socket.send(MAPPER.createObjectNode() + .put("type", "collect").put("request_id", "early").put("site", "write") + .put("command", marker.toString()).toString()); + JsonNode rejected = center.receive("result").body; + assertEquals("early", rejected.path("request_id").asText()); + assertFalse(Files.exists(marker), "an unregistered collect started a child"); + assertFalse(rejected.path("success").asBoolean()); + assertEquals("worker is not registered", rejected.path("error").asText()); + } + } + + @Test + void defaultsToFourActiveCollects(@TempDir Path temporary) throws Exception { + Path release = temporary.resolve("release"); + OpenCliProperties properties = probe(LifecycleProbe.class.getName()); + properties.setMaxConcurrentExecutions(8); + properties.setCommandTimeoutMillis(10_000); + try (LocalCenter center = new LocalCenter(); + OpenCliWsReverseAgentClient agent = new OpenCliWsReverseAgentClient(properties, center.agentProperties())) { + agent.start(); + WebSocket socket = center.receive("register").socket; + socket.send("{\"type\":\"registered\"}"); + try { + for (int index = 0; index < 4; index++) { + sendHeldCollect(socket, "collect-" + index, temporary.resolve("child-" + index), release); + } + for (int index = 0; index < 4; index++) { + assertTrue(awaitMarker(temporary.resolve("child-" + index), 5_000), "initial child did not start"); + } + Path queued = temporary.resolve("child-4"); + sendHeldCollect(socket, "collect-4", queued, release); + assertFalse(awaitMarker(queued, 1_250), "a fifth collect started before a worker was free"); + } finally { + Files.createFile(release); + } + Set completed = new HashSet<>(); + for (int index = 0; index < 5; index++) { + JsonNode result = center.receive("result").body; + assertTrue(result.path("success").asBoolean(), result::toString); + completed.add(result.path("request_id").asText()); + } + assertEquals(new HashSet<>(Arrays.asList("collect-0", "collect-1", "collect-2", "collect-3", "collect-4")), + completed); + assertTrue(Files.exists(temporary.resolve("child-4"))); + } + } + + @ParameterizedTest + @ValueSource(ints = {0, 1}) + void rejectsOverflowWithoutLaunchingAnotherChild(int queueCapacity, @TempDir Path temporary) throws Exception { + Path release = temporary.resolve("release"); + Path active = temporary.resolve("active"); + Path queued = temporary.resolve("queued"); + Path rejected = temporary.resolve("rejected"); + try (LocalCenter center = new LocalCenter()) { + OpenCliWsAgentConnectionProperties connection = center.agentProperties(); + connection.setMaxConcurrentCollects(1); + connection.setMaxPendingCollects(queueCapacity); + try (OpenCliWsReverseAgentClient agent = new OpenCliWsReverseAgentClient( + probe(LifecycleProbe.class.getName()), connection)) { + agent.start(); + WebSocket socket = center.receive("register").socket; + socket.send("{\"type\":\"registered\"}"); + try { + sendHeldCollect(socket, "active", active, release); + assertTrue(awaitMarker(active, 3_000), "first collect did not start"); + if (queueCapacity > 0) { + sendHeldCollect(socket, "queued", queued, release); + } + sendHeldCollect(socket, "overflow", rejected, release); + JsonNode busy = center.receive("result").body; + assertEquals("overflow", busy.path("request_id").asText()); + assertFalse(busy.path("success").asBoolean()); + assertEquals("worker is busy", busy.path("error").asText()); + assertFalse(Files.exists(rejected)); + assertFalse(Files.exists(queued)); + } finally { + Files.createFile(release); + } + JsonNode completed = center.receive("result").body; + assertEquals("active", completed.path("request_id").asText()); + assertTrue(completed.path("success").asBoolean()); + if (queueCapacity > 0) { + JsonNode drained = center.receive("result").body; + assertEquals("queued", drained.path("request_id").asText()); + assertTrue(drained.path("success").asBoolean()); + assertTrue(Files.exists(queued)); + } + assertFalse(Files.exists(rejected)); + } + } + } + + @ParameterizedTest + @CsvSource({"0,32", "-1,32", "4,-1", "4,2147483647", "4,2147483644"}) + void rejectsInvalidCapacityBeforeConnection(int workers, int pending) { + OpenCliWsAgentConnectionProperties connection = new OpenCliWsAgentConnectionProperties(); + connection.setMaxConcurrentCollects(workers); + connection.setMaxPendingCollects(pending); + assertThrows(IllegalArgumentException.class, + () -> new OpenCliWsReverseAgentClient(new OpenCliProperties(), connection)); + } + + @Test + void closeDropsQueuedCollectsAndRejectsRestart(@TempDir Path temporary) throws Exception { + Path release = temporary.resolve("release"); + Path active = temporary.resolve("active"); + Path queued = temporary.resolve("queued"); + try (LocalCenter center = new LocalCenter()) { + OpenCliWsAgentConnectionProperties connection = center.agentProperties(); + connection.setMaxConcurrentCollects(1); + connection.setMaxPendingCollects(1); + try (OpenCliWsReverseAgentClient agent = new OpenCliWsReverseAgentClient( + probe(LifecycleProbe.class.getName()), connection)) { + agent.start(); + WebSocket socket = center.receive("register").socket; + socket.send("{\"type\":\"registered\"}"); + try { + sendHeldCollect(socket, "active", active, release); + assertTrue(awaitMarker(active, 3_000), "first collect did not start"); + sendHeldCollect(socket, "queued", queued, release); + socket.send("{\"type\":\"ping\"}"); + center.receive("pong"); + agent.close(); + } finally { + Files.createFile(release); + } + assertFalse(awaitMarker(queued, 1_250), "queued collect started after close"); + agent.close(); + assertThrows(IllegalStateException.class, agent::start); + } + } + } + + @Test + void duplicateRequestRunsOnceAndReplaysCompletedResult(@TempDir Path temporary) throws Exception { + Path marker = temporary.resolve("starts"); + Path release = temporary.resolve("release"); + Path changed = temporary.resolve("changed"); + String payload = collect("same", "count-hold", marker) + .set("positional_args", MAPPER.createArrayNode().add(release.toString())).toString(); + try (LocalCenter center = new LocalCenter(); + OpenCliWsReverseAgentClient agent = new OpenCliWsReverseAgentClient( + probe(LifecycleProbe.class.getName()), center.agentProperties())) { + agent.start(); + WebSocket socket = center.receive("register").socket; + socket.send("{\"type\":\"registered\"}"); + try { + socket.send(payload); + assertTrue(awaitMarker(marker, 3_000), "original child did not start"); + socket.send(payload); + socket.send(collect("same", "write", changed).toString()); + JsonNode conflict = center.receive("result").body; + assertFalse(Files.exists(changed), "conflicting request started a child"); + assertFalse(conflict.path("success").asBoolean()); + assertEquals("worker request ID conflict", conflict.path("error").asText()); + } finally { + Files.createFile(release); + } + JsonNode completed = center.receive("result").body; + assertTrue(completed.path("success").asBoolean()); + assertFalse(completed.has("cached")); + socket.send(payload); + JsonNode replayed = center.receive("result").body; + assertTrue(replayed.path("cached").asBoolean()); + assertEquals(completed.path("items"), replayed.path("items")); + assertEquals(Arrays.asList("started"), Files.readAllLines(marker, StandardCharsets.UTF_8)); + } + } + + @Test + void rejectsInvalidRequestIdsBeforeExecution(@TempDir Path temporary) throws Exception { + Path marker = temporary.resolve("invalid-id-start"); + try (LocalCenter center = new LocalCenter(); + OpenCliWsReverseAgentClient agent = new OpenCliWsReverseAgentClient( + probe(LifecycleProbe.class.getName()), center.agentProperties())) { + agent.start(); + WebSocket socket = center.receive("register").socket; + socket.send("{\"type\":\"registered\"}"); + for (JsonNode invalid : Arrays.asList(MAPPER.nullNode(), MAPPER.getNodeFactory().textNode("  "), + MAPPER.getNodeFactory().numberNode(42), MAPPER.getNodeFactory().textNode(String.join("", Collections.nCopies(43, "界"))))) { + ObjectNode payload = collect("unused", "write", marker); + payload.set("request_id", invalid); + socket.send(payload.toString()); + JsonNode reply = center.receive("result").body; + assertEquals("", reply.path("request_id").asText()); + assertFalse(reply.path("success").asBoolean()); + assertEquals("invalid worker request ID", reply.path("error").asText()); + assertFalse(Files.exists(marker)); + } + String limit = String.join("", Collections.nCopies(42, "界")) + "ab"; + socket.send(collect(limit, "write", marker).toString()); + JsonNode accepted = center.receive("result").body; + assertEquals(limit, accepted.path("request_id").asText()); + assertTrue(accepted.path("success").asBoolean()); + assertTrue(Files.exists(marker)); + } + } + + @Test + void plainWebSocketReconnectDoesNotExposePreviousSessionCache(@TempDir Path temporary) throws Exception { + verifyReconnectReplay(temporary, null, false); + } + + @Test + void verifiedTlsReconnectReplaysOnlyAfterAnExplicitRetry(@TempDir Path temporary) throws Exception { + Path storePath = temporary.resolve("center.p12"); + String keytool = System.getProperty("os.name").startsWith("Windows") ? "keytool.exe" : "keytool"; + Path tool = Paths.get(System.getProperty("java.home"), "bin", keytool); + Process keygen = new ProcessBuilder(tool.toString(), "-genkeypair", "-alias", "center", "-keyalg", "RSA", + "-keysize", "2048", "-dname", "CN=localhost", "-ext", "SAN=IP:127.0.0.1", "-validity", "1", + "-storetype", "PKCS12", "-keystore", storePath.toString(), "-storepass", "test-password") + .redirectErrorStream(true).redirectOutput(temporary.resolve("keytool.log").toFile()).start(); + try { + assertTrue(keygen.waitFor(10, TimeUnit.SECONDS)); + assertEquals(0, keygen.exitValue()); + } finally { + if (keygen.isAlive()) { + keygen.destroyForcibly(); + } + } + KeyStore store = KeyStore.getInstance("PKCS12"); + try (InputStream input = Files.newInputStream(storePath)) { + store.load(input, "test-password".toCharArray()); + } + KeyManagerFactory keys = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm()); + keys.init(store, "test-password".toCharArray()); + SSLContext server = SSLContext.getInstance("TLS"); + server.init(keys.getKeyManagers(), null, null); + TrustManagerFactory trust = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()); + trust.init(store); + SSLContext trustedClient = SSLContext.getInstance("TLS"); + trustedClient.init(null, trust.getTrustManagers(), null); + SSLContext previous = SSLContext.getDefault(); + try { + SSLContext.setDefault(trustedClient); + verifyReconnectReplay(temporary, server, true); + } finally { + SSLContext.setDefault(previous); + } + } + + private static void verifyReconnectReplay(Path temporary, SSLContext tls, boolean expectCache) throws Exception { + Path marker = temporary.resolve("reconnect-start"); + Path release = temporary.resolve("reconnect-release"); + ObjectNode request = collect("resend", "count-hold", marker); + request.putArray("positional_args").add(release.toString()); + try (LocalCenter center = new LocalCenter(tls)) { + OpenCliWsAgentConnectionProperties connection = center.agentProperties(); + connection.setMaxConcurrentCollects(1); + try (OpenCliWsReverseAgentClient agent = new OpenCliWsReverseAgentClient( + probe(LifecycleProbe.class.getName()), connection)) { + agent.start(); + WebSocket first = center.receive("register").socket; + first.send("{\"type\":\"registered\"}"); + try { + first.send(request.toString()); + assertTrue(awaitMarker(marker, 3_000)); + first.close(); + WebSocket second = center.receive("register").socket; + second.send("{\"type\":\"registered\"}"); + second.send("{\"type\":\"ping\"}"); + center.receive("pong"); + Files.createFile(release); + second.send(collect("barrier", "write", temporary.resolve("barrier")).toString()); + JsonNode barrier = center.receive("result").body; + assertEquals("barrier", barrier.path("request_id").asText()); + assertTrue(barrier.path("success").asBoolean()); + assertEquals(Arrays.asList("started"), Files.readAllLines(marker, StandardCharsets.UTF_8)); + + second.send(request.toString()); + JsonNode reply = center.receive("result").body; + assertTrue(reply.path("success").asBoolean(), reply::toString); + assertEquals(expectCache, reply.path("cached").asBoolean()); + assertEquals(expectCache ? Arrays.asList("started") : Arrays.asList("started", "started"), + Files.readAllLines(marker, StandardCharsets.UTF_8)); + } finally { + if (!Files.exists(release)) { + Files.createFile(release); + } + } + } + } + } + + private static ObjectNode collect(String id, String command, Path marker) { + return MAPPER.createObjectNode().put("type", "collect").put("request_id", id) + .put("site", command).put("command", marker.toString()); + } + + private static void sendHeldCollect(WebSocket socket, String id, Path marker, Path release) { + ObjectNode message = MAPPER.createObjectNode() + .put("type", "collect").put("request_id", id).put("site", "hold").put("command", marker.toString()); + message.putArray("positional_args").add(release.toString()); + socket.send(message.toString()); + } + + private static boolean awaitMarker(Path marker, long timeoutMillis) throws InterruptedException { + long deadline = System.nanoTime() + TimeUnit.MILLISECONDS.toNanos(timeoutMillis); + while (!Files.exists(marker) && System.nanoTime() < deadline) { + Thread.sleep(10); + } + return Files.exists(marker); + } + + @Test + void retriesAfterHandshakeCloseAndReturnsChildFailureToCenter() throws Exception { + try (LocalCenter center = new LocalCenter(); + OpenCliWsReverseAgentClient agent = new OpenCliWsReverseAgentClient( + probe("io.github.easy4j.opencli.contract.MissingFixture"), center.agentProperties())) { + agent.start(); + WireMessage first = center.receive("register"); + first.socket.close(); + WireMessage second = center.receive("register"); + assertNotSame(first.socket, second.socket); + second.socket.send("{\"type\":\"registered\"}"); + second.socket.send("{\"type\":\"collect\",\"request_id\":\"child-failure\"," + + "\"site\":\"demo\",\"command\":\"echo\"}"); + JsonNode result = center.receive("result").body; + assertEquals("child-failure", result.path("request_id").asText()); + assertFalse(result.path("success").asBoolean()); + assertTrue(result.path("items").isEmpty()); + assertTrue(result.path("error").asText().contains("io.github.easy4j.opencli.contract.MissingFixture")); + } + } + + private static OpenCliProperties probe(String mainClass) { + OpenCliProperties properties = new OpenCliProperties(); + String executable = System.getProperty("os.name").startsWith("Windows") ? "java.exe" : "java"; + properties.setExecutable(new File(new File(System.getProperty("java.home"), "bin"), executable).getAbsolutePath()); + properties.setLeadingArguments(Arrays.asList("-cp", + System.getProperty("surefire.test.class.path", System.getProperty("java.class.path")), mainClass)); + properties.setCommandTimeoutMillis(5_000); + return properties; + } + + private static final class WireMessage { + private final WebSocket socket; + private final JsonNode body; + + private WireMessage(WebSocket socket, JsonNode body) { + this.socket = socket; + this.body = body; + } + } + + private static final class LocalCenter extends WebSocketServer implements AutoCloseable { + private final CountDownLatch started = new CountDownLatch(1); + private final BlockingQueue messages = new LinkedBlockingQueue<>(); + private final AtomicReference failure = new AtomicReference<>(); + + private final boolean secure; + + private LocalCenter() throws Exception { + this(null); + } + + private LocalCenter(SSLContext tls) throws Exception { + super(new InetSocketAddress("127.0.0.1", 0), 1); + this.secure = Objects.nonNull(tls); + if (secure) { + setWebSocketFactory(new DefaultSSLWebSocketServerFactory(tls)); + } + start(); + if (!started.await(5, TimeUnit.SECONDS) || Objects.nonNull(failure.get())) { + stop(1_000); + throw new IllegalStateException("WebSocket test server failed to start", failure.get()); + } + } + + private OpenCliWsAgentConnectionProperties agentProperties() { + OpenCliWsAgentConnectionProperties properties = new OpenCliWsAgentConnectionProperties(); + properties.setCentralApiBaseUrl((secure ? "https" : "http") + "://127.0.0.1:" + getPort()); + properties.setAgentAdvertiseUrl(AGENT_URL); + properties.setMinReconnectDelayMillis(25); + properties.setMaxReconnectDelayMillis(50); + properties.setHandshakeTimeoutMillis(5_000); + return properties; + } + + private WireMessage receive(String type) throws InterruptedException { + WireMessage message = messages.poll(8, TimeUnit.SECONDS); + assertNull(failure.get()); + assertNotNull(message, "Expected WebSocket " + type + " response"); + assertEquals(type, message.body.path("type").asText()); + return message; + } + + @Override + public void onOpen(WebSocket socket, ClientHandshake handshake) { } + + @Override + public void onClose(WebSocket socket, int code, String reason, boolean remote) { } + + @Override + public void onMessage(WebSocket socket, String payload) { + try { + messages.add(new WireMessage(socket, MAPPER.readTree(payload))); + } catch (IOException e) { + failure.compareAndSet(null, e); + } + } + + @Override + public void onError(WebSocket socket, Exception error) { + failure.compareAndSet(null, error); + started.countDown(); + } + + @Override + public void onStart() { + started.countDown(); + } + + @Override + public void close() throws InterruptedException { + stop(1_000); + } + } +} diff --git a/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java index 1b0c7a1..6bbe2d2 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java +++ b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java @@ -4,6 +4,7 @@ import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; +import java.nio.file.StandardOpenOption; import java.util.Arrays; /** Offline, self-bounded child fixture. Release files allow cleanup even against a broken SDK. */ @@ -33,7 +34,12 @@ public static void main(String[] args) throws Exception { return; } Path marker = Paths.get(args[1]); - Files.write(marker, "started".getBytes(StandardCharsets.UTF_8)); + if ("count-hold".equals(mode)) { + Files.write(marker, "started\n".getBytes(StandardCharsets.UTF_8), + StandardOpenOption.CREATE, StandardOpenOption.APPEND); + } else { + Files.write(marker, "started".getBytes(StandardCharsets.UTF_8)); + } if ("write".equals(mode)) { return; } Path release = Paths.get(args[2]); long start = System.nanoTime(); From 1f7fbadbd0f87ca6ead55d1401a8722be2b60324 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:54:06 +0800 Subject: [PATCH 010/105] ci: exercise reverse WebSocket contracts across platforms --- .github/workflows/platform-contracts.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/platform-contracts.yml b/.github/workflows/platform-contracts.yml index 0c57fe8..ec39611 100644 --- a/.github/workflows/platform-contracts.yml +++ b/.github/workflows/platform-contracts.yml @@ -44,7 +44,7 @@ jobs: mvn -version > platform-evidence/maven.txt 2>&1 result=0 mvn -B --no-transfer-progress \ - -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,SubprocessStreamFailureTest \ + -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,SubprocessStreamFailureTest,OpenCliWsReverseAgentSessionTest,OpenCliWsCollectRequestsTest \ test > platform-evidence/maven.log 2>&1 || result=$? tail -100 platform-evidence/maven.log python scripts/contract_report.py \ @@ -59,6 +59,8 @@ jobs: --suite process=io.github.easy4j.opencli.contract.OpenCliProcessContractTest \ --suite process=io.github.easy4j.opencli.contract.OpenCliProcessBoundaryTest \ --suite process=io.github.easy4j.opencli.core.support.SubprocessStreamFailureTest \ + --suite protocol=io.github.easy4j.opencli.center.ws.OpenCliWsReverseAgentSessionTest \ + --suite protocol=io.github.easy4j.opencli.center.ws.OpenCliWsCollectRequestsTest \ --output platform-evidence/report.json exit "$result" - name: Upload platform subprocess evidence From 293c281a93c22a077d0f6a9b5ba2663bd6a6ea38 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:24:13 +0800 Subject: [PATCH 011/105] test: exercise OpenCLI process privacy across platforms --- .github/workflows/platform-contracts.yml | 3 +- .../opencli/contract/LifecycleProbe.java | 24 +++++++++ .../core/OpenCliProcessPrivacyTest.java | 53 +++++++++++++------ 3 files changed, 64 insertions(+), 16 deletions(-) diff --git a/.github/workflows/platform-contracts.yml b/.github/workflows/platform-contracts.yml index ec39611..5693d49 100644 --- a/.github/workflows/platform-contracts.yml +++ b/.github/workflows/platform-contracts.yml @@ -44,7 +44,7 @@ jobs: mvn -version > platform-evidence/maven.txt 2>&1 result=0 mvn -B --no-transfer-progress \ - -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,SubprocessStreamFailureTest,OpenCliWsReverseAgentSessionTest,OpenCliWsCollectRequestsTest \ + -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,SubprocessStreamFailureTest,OpenCliWsReverseAgentSessionTest,OpenCliWsCollectRequestsTest,OpenCliProcessPrivacyTest \ test > platform-evidence/maven.log 2>&1 || result=$? tail -100 platform-evidence/maven.log python scripts/contract_report.py \ @@ -61,6 +61,7 @@ jobs: --suite process=io.github.easy4j.opencli.core.support.SubprocessStreamFailureTest \ --suite protocol=io.github.easy4j.opencli.center.ws.OpenCliWsReverseAgentSessionTest \ --suite protocol=io.github.easy4j.opencli.center.ws.OpenCliWsCollectRequestsTest \ + --suite process=io.github.easy4j.opencli.core.OpenCliProcessPrivacyTest \ --output platform-evidence/report.json exit "$result" - name: Upload platform subprocess evidence diff --git a/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java index 6bbe2d2..6d4f20c 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java +++ b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java @@ -13,6 +13,10 @@ private LifecycleProbe() { } public static void main(String[] args) throws Exception { String mode = args[0]; + if ("privacy".equals(mode)) { + exercisePrivacy(args[1], args[2]); + return; + } if ("network-follow".equals(mode)) { networkFollow(args); return; @@ -52,6 +56,26 @@ public static void main(String[] args) throws Exception { } } + private static void exercisePrivacy(String outcome, String canary) throws Exception { + switch (outcome) { + case "nonzero": + System.err.print(canary); + System.exit(7); + return; + case "timeout": + System.err.print(canary); + System.err.flush(); + Thread.sleep(8000L); + return; + case "overflow": + System.out.print(canary); + main(new String[] {"stdout", "4096"}); + return; + default: + throw new IllegalArgumentException("unknown privacy fixture outcome"); + } + } + private static void networkFollow(String[] args) throws Exception { if (!Arrays.asList("browser", "fixture", "network", "--follow") .equals(Arrays.asList(args).subList(3, args.length))) { diff --git a/src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java b/src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java index e1a4a0f..03c9515 100644 --- a/src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java @@ -1,23 +1,26 @@ package io.github.easy4j.opencli.core; import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.contract.LifecycleProbe; import io.github.easy4j.opencli.exception.OpenCliException; import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; import io.github.easy4j.opencli.exception.OpenCliTimeoutException; import java.io.ByteArrayOutputStream; +import java.io.File; import java.io.PrintStream; import java.nio.charset.StandardCharsets; import java.nio.file.Path; +import java.util.ArrayList; +import java.util.Arrays; import java.util.UUID; import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.condition.EnabledOnOs; -import org.junit.jupiter.api.condition.OS; import org.junit.jupiter.api.function.Executable; import org.junit.jupiter.api.io.TempDir; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; class OpenCliProcessPrivacyTest { @@ -33,34 +36,54 @@ void keepsMissingExecutablePathOutOfLogsAndStackTrace(@TempDir Path directory) t } @Test - @EnabledOnOs({OS.LINUX, OS.MAC}) void preservesStderrOnNonzeroExitWithoutLeakingArgsOrStderr() throws Exception { String canary = "stderr-" + UUID.randomUUID(); - OpenCliProperties properties = new OpenCliProperties(); - properties.setExecutable("/bin/sh"); - - try (OpenCliExecutor executor = new OpenCliExecutor(properties)) { + try (OpenCliExecutor executor = new OpenCliExecutor(childProperties())) { OpenCliNonZeroExitException failure = assertPrivateFailure(OpenCliNonZeroExitException.class, canary, - () -> executor.invoke("-c", "printf '%s' \"$1\" >&2; exit 7", "fixture", canary)); + () -> executor.invoke("privacy", "nonzero", canary)); assertEquals(canary, failure.getPartialResult().getStderr()); assertEquals(Integer.valueOf(7), failure.getPartialResult().getExitCode()); } } @Test - @EnabledOnOs({OS.LINUX, OS.MAC}) - void keepsArgumentsOutOfTimeoutDiagnostics() throws Exception { + void keepsArgumentsAndPartialStderrOutOfTimeoutDiagnostics() throws Exception { String canary = "timeout-" + UUID.randomUUID(); - OpenCliProperties properties = new OpenCliProperties(); - properties.setExecutable("/bin/sh"); - properties.setCommandTimeoutMillis(200); + OpenCliProperties properties = childProperties(); + properties.setCommandTimeoutMillis(2500); + + try (OpenCliExecutor executor = new OpenCliExecutor(properties)) { + OpenCliTimeoutException failure = assertPrivateFailure(OpenCliTimeoutException.class, canary, + () -> executor.invoke("privacy", "timeout", canary)); + assertEquals(canary, failure.getPartialResult().getStderr()); + } + } + + @Test + void keepsPartialStdoutOutOfOutputLimitDiagnostics() throws Exception { + String canary = "overflow-" + UUID.randomUUID(); + OpenCliProperties properties = childProperties(); + properties.setMaxStdoutBytes(128); try (OpenCliExecutor executor = new OpenCliExecutor(properties)) { - assertPrivateFailure(OpenCliTimeoutException.class, canary, - () -> executor.invoke("-c", "exec sleep 5", "fixture", canary)); + OpenCliException failure = assertPrivateFailure(OpenCliException.class, canary, + () -> executor.invoke("privacy", "overflow", canary)); + assertEquals("OUTPUT_LIMIT", failure.getPartialResult().getExecutionDetails().getTerminationReason().name()); + assertEquals(128, failure.getPartialResult().getStdout().length()); + assertTrue(failure.getPartialResult().getStdout().startsWith(canary)); } } + private static OpenCliProperties childProperties() { + OpenCliProperties properties = new OpenCliProperties(); + String executable = System.getProperty("os.name").startsWith("Windows") ? "java.exe" : "java"; + properties.setExecutable(new File(new File(System.getProperty("java.home"), "bin"), executable).getAbsolutePath()); + properties.setLeadingArguments(new ArrayList<>(Arrays.asList("-cp", + System.getProperty("surefire.test.class.path", System.getProperty("java.class.path")), + LifecycleProbe.class.getName()))); + return properties; + } + private static T assertPrivateFailure( Class type, String canary, Executable invocation) throws Exception { ByteArrayOutputStream output = new ByteArrayOutputStream(); From 08dd848b2224bdecf25a0636e3f078b8c7ea3561 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:08:09 +0800 Subject: [PATCH 012/105] docs: record live OpenCLI network follow verification --- .../harden-opencli-process-lifecycle/tasks.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/openspec/changes/harden-opencli-process-lifecycle/tasks.md b/openspec/changes/harden-opencli-process-lifecycle/tasks.md index 3e07948..cbd5636 100644 --- a/openspec/changes/harden-opencli-process-lifecycle/tasks.md +++ b/openspec/changes/harden-opencli-process-lifecycle/tasks.md @@ -29,4 +29,16 @@ `OpenCliProcessContractTest` 经 typed `browser network --follow` 入口运行真实 JVM fixture,校验 CLI argv,并覆盖正常退出、CLI 非零退出、输出超限、调用线程中断、执行超时,以及禁用时限时启动前拒绝。超时测试同时启动独立进程,确认该进程仍运行并可自行正常退出。JDK 8 执行 `mvn -B -ntp -o clean verify` 退出 0,全量 2,095 项(其中该类 14 项),0 失败、0 错误、0 跳过。 -本记录覆盖当前本地同步入口。平台矩阵、真实 OpenCLI 持续输出、受控 sink 和后代进程所有权仍需独立证据。 +## 2026-11-18 OC-PROC-006 真实 OpenCLI 验证 + +使用 macOS 27.0.1 ARM64、Node 24.18.0、OpenCLI 1.8.6、Chrome for Testing 158.0.8127.18 和 [Browser Bridge 1.0.22](https://github.com/jackwener/OpenCLI/releases/tag/v1.8.6)。扩展归档的 SHA-256 为 `9d2e3d053948beab5d97124aa79b1532d2122e33e461eca56cac113afd33207a`。每条维护线使用新的临时浏览器配置和显式 profile 路由。页面和数据接口仅绑定回环地址,每 120 ms 发起一次带序号的请求。 + +SDK 通过 `OpenCliBrowserSession.network` 设置 `follow(true)` 和 `all(true)`,实际运行 `opencli --profile browser network --follow --all`。探针分别使用 4,500 ms 时限和 64 KiB 上限,以及 12,000 ms 时限和 2,048 字节上限。每次解析部分 stdout 中完整的 JSON 行,确认来自测试接口、HTTP 状态为 200,且至少有两个不同请求。每条维护线用对应 JDK 执行 `test-compile`,JDK 21 使用仓库 Maven Wrapper。 + +| JDK | 参与验证的功能分支提交 | 执行超时,完整事件 / 捕获字节 / 耗时 | 输出超限,完整事件 / 捕获字节 / 观测字节 / 耗时 | +| --- | --- | --- | --- | +| 8 | `293c281a93c22a077d0f6a9b5ba2663bd6a6ea38` | 34 / 6,044 / 4,519 ms | 11 / 2,048 / 2,844 / 2,220 ms | +| 17 | `d22a1937ca43f03cb17a707710fb8899fa963b6d` | 34 / 6,044 / 4,524 ms | 11 / 2,048 / 2,132 / 2,204 ms | +| 21 | `1ed41f928b4c906cb0499955687d33270c70c2ca` | 33 / 5,866 / 4,518 ms | 11 / 2,048 / 2,844 / 2,208 ms | + +6 个场景通过,0 失败、0 跳过。SDK 分别返回 `EXECUTION_TIMEOUT` 和 `OUTPUT_LIMIT`,均附带部分输出和 `ROOT_EXIT_CONFIRMED`。每组验证确认共享 daemon 的 PID 和隔离浏览器进程在两次调用后仍存活,后续标签页查询仍成功。当前结果验证 macOS 上的同步有界采集。受控 sink、后代进程所有权和其他操作系统上的真实浏览器验收仍待验证。 From 3761a0e78320ce3d67a97bfc437fda056bac8157 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:16:56 +0800 Subject: [PATCH 013/105] test: record OpenCLI error parser review evidence --- .../evidence/2026-11-18-upstream-stderr.md | 39 +++++++++++++++++++ .../evidence/2026-11-18-yaml-parser-review.md | 16 ++++++++ .../preserve-opencli-error-envelope/tasks.md | 6 +-- .../resources/opencli-contracts/v1/SHA256SUMS | 3 ++ .../opencli-contracts/v1/error-argument.yaml | 6 +++ .../v1/error-auth-required.yaml | 6 +++ .../v1/error-empty-result-autofix.yaml | 8 ++++ 7 files changed, 81 insertions(+), 3 deletions(-) create mode 100644 openspec/changes/preserve-opencli-error-envelope/evidence/2026-11-18-upstream-stderr.md create mode 100644 openspec/changes/preserve-opencli-error-envelope/evidence/2026-11-18-yaml-parser-review.md create mode 100644 src/test/resources/opencli-contracts/v1/error-argument.yaml create mode 100644 src/test/resources/opencli-contracts/v1/error-auth-required.yaml create mode 100644 src/test/resources/opencli-contracts/v1/error-empty-result-autofix.yaml diff --git a/openspec/changes/preserve-opencli-error-envelope/evidence/2026-11-18-upstream-stderr.md b/openspec/changes/preserve-opencli-error-envelope/evidence/2026-11-18-upstream-stderr.md new file mode 100644 index 0000000..3c9dbb0 --- /dev/null +++ b/openspec/changes/preserve-opencli-error-envelope/evidence/2026-11-18-upstream-stderr.md @@ -0,0 +1,39 @@ +# OpenCLI 1.8.8 错误输出采样 + +采样日期为 2026-11-18。运行环境使用 Node 24.18.0,npm 依赖安装在临时目录,三个样本各用隔离的 HOME。来源为 npm 包 `@jackwener/opencli@1.8.8`,包的发布校验值为 `sha512-T0rp89sVWMKdnQHoYwkRDuACy7k/lCvVScOZmpqnBhd1AnXG6XLYSYO6U0D/Zdj8qq9kQqgop3qmElNcbMr+sw==`。相关源码见已锁定的 [Adapter 渲染器](https://github.com/jackwener/OpenCLI/blob/8271afc67e8504bda94c147f446ee29775d08274/src/commanderAdapter.ts#L159) 和 [错误模型](https://github.com/jackwener/OpenCLI/blob/8271afc67e8504bda94c147f446ee29775d08274/src/errors.ts)。 + +| 样本 | 执行方式 | 进程退出码 | YAML `error.exitCode` | stdout | +|---|---|---:|---:|---:| +| `error-argument.yaml` | 原生只读命令 `opencli 12306 stations '' -f json`,空参数在请求站点前被拒绝 | 2 | 2 | 0 字节 | +| `error-auth-required.yaml` | 官方 Adapter 渲染受控 `AuthRequiredError` | 77 | 77 | 0 字节 | +| `error-empty-result-autofix.yaml` | 官方 Adapter 渲染受控 `EmptyResultError` | 66 | 66 | 0 字节 | + +样本保存在 `src/test/resources/opencli-contracts/v1`,stderr 按字节保存,摘要见同目录的 `SHA256SUMS`。即使指定 `-f json`,三例的 stderr 均为 YAML。官方渲染器为 `EMPTY_RESULT` 附加 `# AutoFix` 注释,`AUTH_REQUIRED` 的样本没有该注释。如果后续 decoder 测试组合这两个字段,应标注为合成回归样本。 + +## 复核受控样本 + +在临时目录安装锁定包后,将下列内容保存为 `capture.mjs`,分别设置 `OPENCLI_FIXTURE=auth` 或 `OPENCLI_FIXTURE=empty`,用 Node 运行并独立收集 stdout、stderr 与退出码。 + +```javascript +import { Command } from 'commander'; +import { registerCommandToProgram } from './node_modules/@jackwener/opencli/dist/src/commanderAdapter.js'; +import { AuthRequiredError, EmptyResultError } from './node_modules/@jackwener/opencli/dist/src/errors.js'; + +const program = new Command().name('opencli'); +registerCommandToProgram(program.command('fixture'), { + site: 'fixture', + name: 'check', + description: 'Offline fixture', + args: [], + browser: false, + func() { + if (process.env.OPENCLI_FIXTURE === 'auth') { + throw new AuthRequiredError('example.invalid'); + } + throw new EmptyResultError('fixture/check', 'No rows in the offline fixture'); + }, +}); +await program.parseAsync(['fixture', 'check', '-f', 'json'], { from: 'user' }); +``` + +两个受控 Adapter 均在本地抛出错误。未执行登录、真实站点请求、写操作或注释中的修复命令。本次证据只完成 C03 任务 1.1,decoder 的实现和验收仍待评审。 diff --git a/openspec/changes/preserve-opencli-error-envelope/evidence/2026-11-18-yaml-parser-review.md b/openspec/changes/preserve-opencli-error-envelope/evidence/2026-11-18-yaml-parser-review.md new file mode 100644 index 0000000..3bab2d6 --- /dev/null +++ b/openspec/changes/preserve-opencli-error-envelope/evidence/2026-11-18-yaml-parser-review.md @@ -0,0 +1,16 @@ +# C03 YAML 解析器候选验证(2026-11-18) + +C03 评审候选为 `org.yaml:snakeyaml:2.7`,三条 Java 维护线可共用。SnakeYAML Engine 的当前维护线要求 Java 11 或更新版本。[SnakeYAML](https://github.com/snakeyaml/snakeyaml) · [SnakeYAML Engine](https://github.com/snakeyaml/snakeyaml-engine) · [Maven Central 发布包](https://repo.maven.apache.org/maven2/org/yaml/snakeyaml/2.7/) + +## 探针结果 + +独立探针使用 SHA-256 为 `2e194eba45a67dee19a4e272f4a04b18de8054e9f598b094382f6dae0b0e4b5e` 的 2.7 JAR。以 JDK 8 编译一次,在 8u504、17.0.21、21.0.13.0.2 各执行 30 个断言。三轮退出码均为 0。使用三个 [OpenCLI 1.8.8 真实 stderr 样本](2026-11-18-upstream-stderr.md) 及合成输入。探针未接入 SDK,SDK 当前行为仍由既有执行器决定。 + +- 三个真实样本均读出 `ok: false`、原始错误码及整数退出码。带 `# AutoFix` 的样本正常解析。合成 JSON 子集保留未识别的错误码和 trace 路径。普通单行文本得到字符串,后续 envelope 校验应按原执行状态处理。 +- 普通 `SafeConstructor` 的 YAML 1.1 规则会将 `no`、`off` 和日期转成布尔值与日期类型。自定义隐式解析范围只接受 JSON 形式的布尔、空值、整数和小数。日期样式、`no`、`off` 和前导零字符串在探针中均保留原值。 +- 默认浮点映射会将 `1e400` 转为无穷大,并对长小数取近似值。探针改用 `BigDecimal` 保留两者,后续模型应避免以浮点近似值覆盖扩展字段。 +- 用库的事件流预检,拒绝锚点和别名、显式标记、多个文档及超过 32 层的集合。用加载选项拒绝重复键。UTF-8 字节检查在入口执行,加载器另外限制码点数。探针验证了 32 层和 256 KiB 边界、多字节超限、截断的 JSON 形态以及被禁止的 YAML 特性。普通运行日志仅记录断言数量。 + +## 实现评审范围 + +建议在 JSON 路径复用各分支已有 Jackson,并以严格 JSON 判定处理疑似 JSON 的失败输入。YAML 路径建议采用事件预检和受限构造,再检查 envelope 形状及字符串键。需用 SDK 测试验证退出码来源、解析状态、超时优先级、日志脱敏和无重试副作用。评审前保留 C03 任务 2.1 未勾选,三个 POM 均未引入该候选依赖。 diff --git a/openspec/changes/preserve-opencli-error-envelope/tasks.md b/openspec/changes/preserve-opencli-error-envelope/tasks.md index fee0afa..b8ab4f1 100644 --- a/openspec/changes/preserve-opencli-error-envelope/tasks.md +++ b/openspec/changes/preserve-opencli-error-envelope/tasks.md @@ -1,17 +1,17 @@ # C03 Tasks · 上游错误协议解析与证据保真 -> 全部为待执行实现任务。文档/格式检查通过不允许提前勾选。 +> 已采集上游 stderr 样本,decoder 实现待评审。文档/格式检查通过不允许提前勾选。 关联规范:[spec](specs/opencli-error-envelope/spec.md)。 ## 1. 错误 fixture -- [ ] 1.1 从锁定上游 renderError/真实只读负例建立 YAML fixture,保存版本与 hash。 +- [x] 1.1 从锁定上游 renderError/真实只读负例建立 YAML fixture,保存版本与 hash。见 [上游 stderr 采样](evidence/2026-11-18-upstream-stderr.md)。 - [ ] 1.2 补 JSON、纯文本、AutoFix 注释、exit mismatch、unknown code、malformed 和恶意 YAML 失败测试。 ## 2. decoder 与结果 -- [ ] 2.1 选定三线可用的安全 YAML 实现并验证安全配置,不复制不兼容 Jackson imports。 +- [ ] 2.1 选定三线可用的安全 YAML 实现并验证安全配置,不复制不兼容 Jackson imports。见 [三线候选探针](evidence/2026-11-18-yaml-parser-review.md)。 - [ ] 2.2 实现有界 shape 校验和 provenance 模型,保留 help/trace/unknown fields。 - [ ] 2.3 接入本地异常与 partial result,避免 parser 抢占 primary failure。 diff --git a/src/test/resources/opencli-contracts/v1/SHA256SUMS b/src/test/resources/opencli-contracts/v1/SHA256SUMS index c7a5e08..3a1f826 100644 --- a/src/test/resources/opencli-contracts/v1/SHA256SUMS +++ b/src/test/resources/opencli-contracts/v1/SHA256SUMS @@ -1,2 +1,5 @@ e7e6dd57e81e24e92a7cb0de0e1204f95025f80310f5dc34d820aa7419636f78 argv.tsv 2fa30626c415bb3c152bc4c2827cd9282ba710654f6a56fb7bde70a83b2bc192 sources.lock.json +2de5245d5a5692dc66d5fbc948d9c0929ba4baf12141ae2d9477771f7b17fb4f error-argument.yaml +317a108a2d666fbf33554059b48691f363a33cd7a53bd8a94396bba045c9d522 error-auth-required.yaml +1f587e1dc2f45648796dea428d3957560534b864e927d4d40db36563a5042b7f error-empty-result-autofix.yaml diff --git a/src/test/resources/opencli-contracts/v1/error-argument.yaml b/src/test/resources/opencli-contracts/v1/error-argument.yaml new file mode 100644 index 0000000..f3c7315 --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/error-argument.yaml @@ -0,0 +1,6 @@ +ok: false +error: + code: ARGUMENT + message: Argument "keyword" is required. + help: Chinese substring (上海), telecode (AOH), or pinyin (shanghai) + exitCode: 2 diff --git a/src/test/resources/opencli-contracts/v1/error-auth-required.yaml b/src/test/resources/opencli-contracts/v1/error-auth-required.yaml new file mode 100644 index 0000000..3190d87 --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/error-auth-required.yaml @@ -0,0 +1,6 @@ +ok: false +error: + code: AUTH_REQUIRED + message: Not logged in to example.invalid + help: Please open Chrome or Chromium and log in to https://example.invalid + exitCode: 77 diff --git a/src/test/resources/opencli-contracts/v1/error-empty-result-autofix.yaml b/src/test/resources/opencli-contracts/v1/error-empty-result-autofix.yaml new file mode 100644 index 0000000..2ea1e1a --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/error-empty-result-autofix.yaml @@ -0,0 +1,8 @@ +ok: false +error: + code: EMPTY_RESULT + message: fixture/check returned no data + help: No rows in the offline fixture + exitCode: 66 +# AutoFix: re-run with --trace=retain-on-failure for trace artifact +# opencli fixture check --trace retain-on-failure From 4d42b937ba7366e4c5b15c2120123e660ef51e1b Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:21:13 +0800 Subject: [PATCH 014/105] fix: cap OpenCLI capture buffer allocation --- .../harden-opencli-process-lifecycle/tasks.md | 8 ++++++++ .../core/support/SubprocessExecutionSupport.java | 8 +++++++- .../support/SubprocessExecutionSupportTest.java | 16 ++++++++++++++++ 3 files changed, 31 insertions(+), 1 deletion(-) diff --git a/openspec/changes/harden-opencli-process-lifecycle/tasks.md b/openspec/changes/harden-opencli-process-lifecycle/tasks.md index cbd5636..a43041b 100644 --- a/openspec/changes/harden-opencli-process-lifecycle/tasks.md +++ b/openspec/changes/harden-opencli-process-lifecycle/tasks.md @@ -42,3 +42,11 @@ SDK 通过 `OpenCliBrowserSession.network` 设置 `follow(true)` 和 `all(true)` | 21 | `1ed41f928b4c906cb0499955687d33270c70c2ca` | 33 / 5,866 / 4,518 ms | 11 / 2,048 / 2,844 / 2,208 ms | 6 个场景通过,0 失败、0 跳过。SDK 分别返回 `EXECUTION_TIMEOUT` 和 `OUTPUT_LIMIT`,均附带部分输出和 `ROOT_EXIT_CONFIRMED`。每组验证确认共享 daemon 的 PID 和隔离浏览器进程在两次调用后仍存活,后续标签页查询仍成功。当前结果验证 macOS 上的同步有界采集。受控 sink、后代进程所有权和其他操作系统上的真实浏览器验收仍待验证。 + +## 2026-11-18 OC-PROC-003 捕获数组扩容 + +JDK 17 红灯测试以 8,193 字节作为捕获上限,分两次写满,观察到旧实现把 backing array 扩到 16,384 字节。修复对单次分配容量应用捕获上限。回归验证 8,193 字节数组、原样保留的前缀、准确的观测字节数及截断标记。 + +JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,114 项通过,0 失败、0 错误、0 跳过。真实 OpenCLI 1.8.6 两项复验通过。4,500 ms 时限返回 `EXECUTION_TIMEOUT` 并保留 34 条完整事件。2 KiB 上限返回 `OUTPUT_LIMIT` 并保留 2,048 字节和 11 条完整事件。两次均确认 SDK 启动的 CLI 子进程已退出,后续 daemon 查询可用。 + +本次测量单个捕获数组的容量。整体堆内存峰值还包含扩容时的数组复制、输出快照和并发调用,任务 1.2 继续跟踪。 diff --git a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java index 4efe49e..06f5f06 100644 --- a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java +++ b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java @@ -369,7 +369,7 @@ private static long nanos(long millis, String field) { return millis * 1_000_000L; } - private static final class BoundedCapture extends ByteArrayOutputStream { + static final class BoundedCapture extends ByteArrayOutputStream { private final int limit; private long observed; private boolean truncated; @@ -385,12 +385,18 @@ public synchronized void write(byte[] bytes, int offset, int length) { if (frozen) { return; } observed = observed > Long.MAX_VALUE - length ? Long.MAX_VALUE : observed + length; int retained = Math.min(length, limit - count); + int required = count + retained; + if (required > buf.length) { + int doubled = (int) Math.min(2L * buf.length, limit); + buf = Arrays.copyOf(buf, Math.max(required, doubled)); + } super.write(bytes, offset, retained); truncated |= retained < length; } @Override public synchronized void write(int value) { write(new byte[]{(byte) value}, 0, 1); } + synchronized int bufferCapacity() { return buf.length; } synchronized boolean isTruncated() { return truncated; } synchronized long observed() { return observed; } synchronized void freeze() { frozen = true; } diff --git a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupportTest.java b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupportTest.java index 910ac18..8855f8f 100644 --- a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupportTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupportTest.java @@ -5,6 +5,22 @@ class SubprocessExecutionSupportTest { + @Test + void shouldBoundBackingBufferGrowthAtTheConfiguredLimit() { + int limit = 8_193; + SubprocessExecutionSupport.BoundedCapture capture = new SubprocessExecutionSupport.BoundedCapture(limit); + byte[] chunk = new byte[8_192]; + capture.write(chunk, 0, chunk.length); + capture.write(99); + capture.write(100); + + assertEquals(limit, capture.bufferCapacity()); + assertEquals(limit, capture.size()); + assertEquals(99, capture.toByteArray()[limit - 1]); + assertEquals(limit + 1L, capture.observed()); + assertTrue(capture.isTruncated()); + } + @Test void shouldReturnDefaultMaxConcurrent() { int defaultVal = SubprocessExecutionSupport.defaultMaxConcurrentExecutions(); From 0e52caca7cef9b31752d343363f7addc756cdef8 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:26:33 +0800 Subject: [PATCH 015/105] test: verify OpenCLI saturated process and capture limits --- .../harden-opencli-process-lifecycle/tasks.md | 12 +++- .../opencli/contract/LifecycleProbe.java | 28 +++++--- .../contract/OpenCliProcessContractTest.java | 67 +++++++++++++++++++ 3 files changed, 96 insertions(+), 11 deletions(-) diff --git a/openspec/changes/harden-opencli-process-lifecycle/tasks.md b/openspec/changes/harden-opencli-process-lifecycle/tasks.md index a43041b..eaafa19 100644 --- a/openspec/changes/harden-opencli-process-lifecycle/tasks.md +++ b/openspec/changes/harden-opencli-process-lifecycle/tasks.md @@ -7,7 +7,7 @@ ## 1. 资源回归 - [ ] 1.1 用可控子进程分别编写排队超时、并发 Client、取消、超限与 cleanup 竞态失败测试。 -- [ ] 1.2 测量在途进程与 capture 峰值;保留失败证据而不运行真实用户网站。 +- [x] 1.2 测量在途进程与 capture 峰值;保留失败证据而不运行真实用户网站。见本文 OC-PROC-001/002/003 饱和验证。 ## 2. 执行核修复 @@ -49,4 +49,12 @@ JDK 17 红灯测试以 8,193 字节作为捕获上限,分两次写满,观察 JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,114 项通过,0 失败、0 错误、0 跳过。真实 OpenCLI 1.8.6 两项复验通过。4,500 ms 时限返回 `EXECUTION_TIMEOUT` 并保留 34 条完整事件。2 KiB 上限返回 `OUTPUT_LIMIT` 并保留 2,048 字节和 11 条完整事件。两次均确认 SDK 启动的 CLI 子进程已退出,后续 daemon 查询可用。 -本次测量单个捕获数组的容量。整体堆内存峰值还包含扩容时的数组复制、输出快照和并发调用,任务 1.2 继续跟踪。 +本次测量单个捕获数组的容量。整体堆内存还包含扩容时的数组复制、输出快照和并发调用,按独立指标记录。 + +## 2026-11-18 OC-PROC-001/002/003 饱和验证 + +`OpenCliProcessContractTest#sharedRuntimeBoundsConcurrentChildrenAndCombinedCapture` 使用三个客户端共享两个执行许可。两个真实 JVM 子进程分别写入 131,073 字节 stdout 和 65,539 字节 stderr,然后发出就绪标记并等待同一释放信号。两个子进程仍在途时提交四次调用,四次均返回 `QUEUE_TIMEOUT`,执行详情和子进程标记均确认没有启动进程。该场景在途峰值为 2。 + +释放后,两次调用均确认根进程退出,四条输出流保留 393,224 字节,恰好达到两个执行槽的合计捕获预算,零截断。这个数值由执行详情测得,对应离线 fixture 的捕获量。JVM 整体堆内存还包含其他分配,本场景不对其计量。 + +JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,115 项通过,0 失败、0 错误、0 跳过。 diff --git a/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java index 6d4f20c..e8a2d55 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java +++ b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java @@ -1,5 +1,6 @@ package io.github.easy4j.opencli.contract; +import java.io.PrintStream; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; @@ -26,17 +27,14 @@ public static void main(String[] args) throws Exception { return; } if ("stdout".equals(mode) || "stderr".equals(mode)) { - byte[] block = new byte[8192]; - Arrays.fill(block, (byte) 'x'); - int remaining = Integer.parseInt(args[1]); - while (remaining > 0) { - int size = Math.min(block.length, remaining); - if ("stdout".equals(mode)) { System.out.write(block, 0, size); } - else { System.err.write(block, 0, size); } - remaining -= size; - } + PrintStream stream = "stdout".equals(mode) ? System.out : System.err; + writeStream(stream, Integer.parseInt(args[1])); return; } + if ("capture-hold".equals(mode)) { + writeStream(System.out, Integer.parseInt(args[3])); + writeStream(System.err, Integer.parseInt(args[4])); + } Path marker = Paths.get(args[1]); if ("count-hold".equals(mode)) { Files.write(marker, "started\n".getBytes(StandardCharsets.UTF_8), @@ -56,6 +54,18 @@ public static void main(String[] args) throws Exception { } } + private static void writeStream(PrintStream stream, int bytes) { + byte[] block = new byte[8192]; + Arrays.fill(block, (byte) 'x'); + int remaining = bytes; + while (remaining > 0) { + int size = Math.min(block.length, remaining); + stream.write(block, 0, size); + remaining -= size; + } + stream.flush(); + } + private static void exercisePrivacy(String outcome, String canary) throws Exception { switch (outcome) { case "nonzero": diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java index aeb28af..0d49fb9 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java @@ -4,8 +4,10 @@ import io.github.easy4j.opencli.browser.OpenCliBrowserClient; import io.github.easy4j.opencli.browser.OpenCliBrowserSession; import io.github.easy4j.opencli.browser.OpenCliBrowserSession.OpenCliBrowserNetworkOptions; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails; import io.github.easy4j.opencli.core.OpenCliExecutionDetails.TerminationReason; import io.github.easy4j.opencli.core.OpenCliExecutor; +import io.github.easy4j.opencli.core.OpenCliProcessRuntime; import io.github.easy4j.opencli.core.OpenCliResult; import io.github.easy4j.opencli.exception.OpenCliException; import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; @@ -321,6 +323,71 @@ void explicitSharedRuntimeLimitsBothClients() throws Exception { } } + @Test + void sharedRuntimeBoundsConcurrentChildrenAndCombinedCapture() throws Exception { + int stdoutLimit = 131_073; + int stderrLimit = 65_539; + OpenCliProcessRuntime runtime = new OpenCliProcessRuntime(2); + OpenCliProperties capture = properties(6); + capture.setMaxStdoutBytes(stdoutLimit); + capture.setMaxStderrBytes(stderrLimit); + OpenCliProperties queued = properties(6); + queued.setCommandTimeoutMillis(750L); + OpenCliExecutor first = new OpenCliExecutor(capture, runtime); + OpenCliExecutor second = new OpenCliExecutor(capture, runtime); + OpenCliExecutor waiting = new OpenCliExecutor(queued, runtime); + Path gate = dir.resolve("capture-release"); + List markers = Arrays.asList(dir.resolve("capture-first"), dir.resolve("capture-second")); + ExecutorService workers = Executors.newFixedThreadPool(6); + try { + Future one = workers.submit(() -> first.invoke("capture-hold", + markers.get(0).toString(), gate.toString(), Integer.toString(stdoutLimit), + Integer.toString(stderrLimit))); + Future two = workers.submit(() -> second.invoke("capture-hold", + markers.get(1).toString(), gate.toString(), Integer.toString(stdoutLimit), + Integer.toString(stderrLimit))); + assertTrue(awaitFile(markers.get(0), 5_000L)); + assertTrue(awaitFile(markers.get(1), 5_000L)); + + List> contenders = new ArrayList<>(); + for (int index = 0; index < 4; index++) { + Path marker = dir.resolve("queued-" + index); + contenders.add(workers.submit(() -> { + OpenCliTimeoutException timeout = assertThrows(OpenCliTimeoutException.class, + () -> waiting.invoke("write", marker.toString())); + OpenCliExecutionDetails evidence = timeout.getPartialResult().getExecutionDetails(); + assertEquals(TerminationReason.QUEUE_TIMEOUT, evidence.getTerminationReason()); + assertFalse(evidence.isProcessStarted()); + assertFalse(Files.exists(marker), "a queued invocation spawned a child"); + })); + } + for (Future contender : contenders) { + contender.get(4, TimeUnit.SECONDS); + } + assertFalse(one.isDone()); + assertFalse(two.isDone()); + + release(gate); + long aggregateBytes = 0; + for (Future active : Arrays.asList(one, two)) { + OpenCliResult result = active.get(5, TimeUnit.SECONDS); + assertTrue(result.isSuccess()); + OpenCliExecutionDetails evidence = result.getExecutionDetails(); + assertEquals(stdoutLimit, evidence.getStdoutCapturedBytes()); + assertEquals(stderrLimit, evidence.getStderrCapturedBytes()); + assertFalse(evidence.isStdoutTruncated()); + assertFalse(evidence.isStderrTruncated()); + assertEquals(OpenCliExecutionDetails.CleanupState.ROOT_EXIT_CONFIRMED, evidence.getCleanupState()); + aggregateBytes += evidence.getStdoutCapturedBytes() + evidence.getStderrCapturedBytes(); + } + assertEquals(393_224L, aggregateBytes); + } finally { + release(gate); + workers.shutdownNow(); + assertTrue(workers.awaitTermination(5, TimeUnit.SECONDS)); + } + } + @Test void preCancelledRequestNeverStartsAProcess() throws Exception { Class tokenType = assertDoesNotThrow(() -> Class.forName("io.github.easy4j.opencli.core.OpenCliCancellationToken")); From 77569f8b20e0f382a9dab1027eeeffc8d1ecdde3 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:32:09 +0800 Subject: [PATCH 016/105] test: cover cancellation with inherited OpenCLI pipes --- .../harden-opencli-process-lifecycle/tasks.md | 10 ++++- .../opencli/contract/LifecycleProbe.java | 6 +++ .../contract/OpenCliProcessContractTest.java | 39 +++++++++++++++++++ 3 files changed, 54 insertions(+), 1 deletion(-) diff --git a/openspec/changes/harden-opencli-process-lifecycle/tasks.md b/openspec/changes/harden-opencli-process-lifecycle/tasks.md index eaafa19..b255130 100644 --- a/openspec/changes/harden-opencli-process-lifecycle/tasks.md +++ b/openspec/changes/harden-opencli-process-lifecycle/tasks.md @@ -6,7 +6,7 @@ ## 1. 资源回归 -- [ ] 1.1 用可控子进程分别编写排队超时、并发 Client、取消、超限与 cleanup 竞态失败测试。 +- [x] 1.1 用可控子进程分别编写排队超时、并发 Client、取消、超限与 cleanup 竞态失败测试。见本文 OC-PROC-004/005 回归矩阵。 - [x] 1.2 测量在途进程与 capture 峰值;保留失败证据而不运行真实用户网站。见本文 OC-PROC-001/002/003 饱和验证。 ## 2. 执行核修复 @@ -58,3 +58,11 @@ JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,114 项通过,0 释放后,两次调用均确认根进程退出,四条输出流保留 393,224 字节,恰好达到两个执行槽的合计捕获预算,零截断。这个数值由执行详情测得,对应离线 fixture 的捕获量。JVM 整体堆内存还包含其他分配,本场景不对其计量。 JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,115 项通过,0 失败、0 错误、0 跳过。 + +## 2026-11-18 OC-PROC-004/005 回归矩阵 + +`OpenCliProcessContractTest` 使用真实子进程覆盖排队超时、独立和共享 Client 限流、取消及独立流超限。`SubprocessCompletionRaceTest` 用同步屏障覆盖输出超限、取消、watchdog 与进程结束竞争,确认唯一结果和许可复用。`SubprocessCleanupFaultTest` 注入 watchdog 初始化、流初始化、终止和清理异常,覆盖最初失败保留及无法确认退出的运行时隔离。 + +新增真实继承管道回归。根进程启动继承 stdout、stderr 的独立 JVM,后者通过文件汇报心跳。观察到后代进程启动后取消调用。清理宽限配置为 250 ms,测试允许 1,500 ms 等待窗口,包含线程调度。SDK 仍返回 `CANCELLED`,流未排空时必须报告 `UNCONFIRMED`,并且不声称后代已退出。断言取消后后代心跳仍更新,最后由测试自己的释放文件终止它。 + +JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,116 项通过,0 失败、0 错误、0 跳过。该场景验证未追踪后代的安全边界,后代所有权和回收能力仍由 2.3、3.2 跟踪。 diff --git a/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java index e8a2d55..3ed062b 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java +++ b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java @@ -31,6 +31,12 @@ public static void main(String[] args) throws Exception { writeStream(stream, Integer.parseInt(args[1])); return; } + if ("inherited-pipes".equals(mode)) { + String executable = System.getProperty("os.name").startsWith("Windows") ? "java.exe" : "java"; + Path java = Paths.get(System.getProperty("java.home"), "bin", executable); + new ProcessBuilder(java.toString(), "-cp", System.getProperty("java.class.path"), + LifecycleProbe.class.getName(), "heartbeat", args[3], args[2]).inheritIO().start(); + } if ("capture-hold".equals(mode)) { writeStream(System.out, Integer.parseInt(args[3])); writeStream(System.err, Integer.parseInt(args[4])); diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java index 0d49fb9..cd22ee2 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java @@ -4,6 +4,7 @@ import io.github.easy4j.opencli.browser.OpenCliBrowserClient; import io.github.easy4j.opencli.browser.OpenCliBrowserSession; import io.github.easy4j.opencli.browser.OpenCliBrowserSession.OpenCliBrowserNetworkOptions; +import io.github.easy4j.opencli.core.OpenCliCancellationToken; import io.github.easy4j.opencli.core.OpenCliExecutionDetails; import io.github.easy4j.opencli.core.OpenCliExecutionDetails.TerminationReason; import io.github.easy4j.opencli.core.OpenCliExecutor; @@ -388,6 +389,44 @@ void sharedRuntimeBoundsConcurrentChildrenAndCombinedCapture() throws Exception } } + @Test + void cancelledParentWithInheritedPipesReturnsWithinCleanupBudget() throws Exception { + Path parent = dir.resolve("parent"); + Path descendant = dir.resolve("descendant"); + Path release = dir.resolve("release"); + OpenCliCancellationToken token = new OpenCliCancellationToken(); + OpenCliProperties properties = properties(1); + properties.setCleanupGraceMillis(250L); + OpenCliExecutor executor = new OpenCliExecutor(properties); + ExecutorService worker = Executors.newSingleThreadExecutor(); + try { + Future failure = worker.submit(() -> assertThrows(OpenCliException.class, + () -> executor.invoke(Arrays.asList("inherited-pipes", parent.toString(), + release.toString(), descendant.toString()), token))); + assertTrue(awaitFile(descendant, 5_000L), "descendant never inherited the pipes"); + token.cancel(); + OpenCliExecutionDetails details = failure.get(1_500L, TimeUnit.MILLISECONDS).getPartialResult() + .getExecutionDetails(); + assertEquals(TerminationReason.CANCELLED, details.getTerminationReason()); + assertFalse(details.isDescendantsExitConfirmed()); + if (!details.isStreamsDrained()) { + assertEquals(OpenCliExecutionDetails.CleanupState.UNCONFIRMED, details.getCleanupState()); + } + byte[] firstHeartbeat = Files.readAllBytes(descendant); + long start = System.nanoTime(); + while (Arrays.equals(firstHeartbeat, Files.readAllBytes(descendant)) + && System.nanoTime() - start < TimeUnit.SECONDS.toNanos(1)) { + Thread.sleep(20L); + } + assertFalse(Arrays.equals(firstHeartbeat, Files.readAllBytes(descendant)), + "the untracked descendant was stopped by cancellation"); + } finally { + release(release); + worker.shutdownNow(); + assertTrue(worker.awaitTermination(5, TimeUnit.SECONDS)); + } + } + @Test void preCancelledRequestNeverStartsAProcess() throws Exception { Class tokenType = assertDoesNotThrow(() -> Class.forName("io.github.easy4j.opencli.core.OpenCliCancellationToken")); From 61ea55d927ce754e24cdd6ea17ee3558e8c0fa8c Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:36:55 +0800 Subject: [PATCH 017/105] fix: allocate OpenCLI output capture on first write --- .../harden-opencli-process-lifecycle/tasks.md | 8 ++++++++ .../core/support/SubprocessExecutionSupport.java | 9 +++++---- .../core/support/SubprocessCleanupFaultTest.java | 2 ++ .../support/SubprocessExecutionSupportTest.java | 13 +++++++++++++ 4 files changed, 28 insertions(+), 4 deletions(-) diff --git a/openspec/changes/harden-opencli-process-lifecycle/tasks.md b/openspec/changes/harden-opencli-process-lifecycle/tasks.md index b255130..f627d32 100644 --- a/openspec/changes/harden-opencli-process-lifecycle/tasks.md +++ b/openspec/changes/harden-opencli-process-lifecycle/tasks.md @@ -66,3 +66,11 @@ JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,115 项通过,0 新增真实继承管道回归。根进程启动继承 stdout、stderr 的独立 JVM,后者通过文件汇报心跳。观察到后代进程启动后取消调用。清理宽限配置为 250 ms,测试允许 1,500 ms 等待窗口,包含线程调度。SDK 仍返回 `CANCELLED`,流未排空时必须报告 `UNCONFIRMED`,并且不声称后代已退出。断言取消后后代心跳仍更新,最后由测试自己的释放文件终止它。 JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,116 项通过,0 失败、0 错误、0 跳过。该场景验证未追踪后代的安全边界,后代所有权和回收能力仍由 2.3、3.2 跟踪。 + +## 2026-11-18 OC-PROC-003 输出缓冲区按需分配 + +修复前,构造捕获对象即分配每个输出流的初始数组,默认两个共 16 KiB,包括仍排队或在启动前取消的调用。JDK 17 的两项回归分别观测到预取消路径的 16 字节测试配置和普通空写路径的 8,192 字节数组容量,预期均为零。 + +修复后,第一次非空写入才分配对应捕获数组,仍受流的配置上限约束。预取消路径的 stdout、stderr 容量均为零,读取线程的工作缓冲和 JVM 总堆内存属独立指标。红灯 2 项失败,修复后 JDK 17 定向 33 项通过。 + +JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,117 项通过,0 失败、0 错误、0 跳过。 diff --git a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java index 06f5f06..870b648 100644 --- a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java +++ b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java @@ -44,6 +44,7 @@ interface WatchdogFactory { public static final long WAIT_GRACE_MILLIS = 5_000L; public static final int DEFAULT_STDOUT_LIMIT = 8 * 1024 * 1024; public static final int DEFAULT_STDERR_LIMIT = 2 * 1024 * 1024; + private static final int READ_BUFFER_BYTES = 8192; private static final long POLL_NANOS = TimeUnit.MILLISECONDS.toNanos(10L); private static final int DEFAULT_MAX_CONCURRENT = Math.max(2, java.lang.Runtime.getRuntime().availableProcessors()); private static final Object LEGACY_LOCK = new Object(); @@ -376,7 +377,7 @@ static final class BoundedCapture extends ByteArrayOutputStream { private boolean frozen; BoundedCapture(int limit) { - super(Math.min(8192, limit)); + super(0); this.limit = limit; } @@ -387,8 +388,8 @@ public synchronized void write(byte[] bytes, int offset, int length) { int retained = Math.min(length, limit - count); int required = count + retained; if (required > buf.length) { - int doubled = (int) Math.min(2L * buf.length, limit); - buf = Arrays.copyOf(buf, Math.max(required, doubled)); + int growth = (int) Math.min(limit, Math.max(READ_BUFFER_BYTES, 2L * buf.length)); + buf = Arrays.copyOf(buf, Math.max(required, growth)); } super.write(bytes, offset, retained); truncated |= retained < length; @@ -417,7 +418,7 @@ private static final class Reader extends Thread { @Override public void run() { try (InputStream stream = input) { - byte[] buffer = new byte[8192]; + byte[] buffer = new byte[READ_BUFFER_BYTES]; int size; while ((size = stream.read(buffer)) != -1) { capture.write(buffer, 0, size); diff --git a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCleanupFaultTest.java b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCleanupFaultTest.java index 79fd220..b5c20e5 100644 --- a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCleanupFaultTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCleanupFaultTest.java @@ -164,6 +164,8 @@ void cancelledSubmissionDoesNotInitializeWatchdogOrSpawn() throws Exception { assertEquals(CleanupState.NOT_STARTED, session.getExecutionDetails().getCleanupState()); assertNull(session.getObservedExitCode()); assertNotNull(session.getWatchdog()); + assertEquals(0, ((SubprocessExecutionSupport.BoundedCapture) session.getStdout()).bufferCapacity()); + assertEquals(0, ((SubprocessExecutionSupport.BoundedCapture) session.getStderr()).bufferCapacity()); } private static void assertCleanupSurvives(boolean failStop, boolean failDestroy) throws Exception { diff --git a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupportTest.java b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupportTest.java index 8855f8f..9123715 100644 --- a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupportTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupportTest.java @@ -5,6 +5,19 @@ class SubprocessExecutionSupportTest { + @Test + void shouldAllocateOutputStorageOnlyOnFirstNonemptyWrite() { + SubprocessExecutionSupport.BoundedCapture capture = new SubprocessExecutionSupport.BoundedCapture(12_000); + byte[] empty = new byte[0]; + capture.write(empty, 0, empty.length); + + assertEquals(0, capture.bufferCapacity()); + capture.write(99); + assertEquals(1, capture.size()); + assertEquals(99, capture.toByteArray()[0]); + assertEquals(8_192, capture.bufferCapacity()); + } + @Test void shouldBoundBackingBufferGrowthAtTheConfiguredLimit() { int limit = 8_193; From d52c57f8465c8672eeaecf76d71bac52a0076c6b Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:44:01 +0800 Subject: [PATCH 018/105] fix: bound blocking OpenCLI process termination --- .github/workflows/platform-contracts.yml | 3 +- .../harden-opencli-process-lifecycle/tasks.md | 8 ++ .../support/SubprocessExecutionSupport.java | 118 ++++++++++++++---- .../support/SubprocessCleanupFaultTest.java | 74 ++++++++++- 4 files changed, 175 insertions(+), 28 deletions(-) diff --git a/.github/workflows/platform-contracts.yml b/.github/workflows/platform-contracts.yml index 5693d49..df48f21 100644 --- a/.github/workflows/platform-contracts.yml +++ b/.github/workflows/platform-contracts.yml @@ -44,7 +44,7 @@ jobs: mvn -version > platform-evidence/maven.txt 2>&1 result=0 mvn -B --no-transfer-progress \ - -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,SubprocessStreamFailureTest,OpenCliWsReverseAgentSessionTest,OpenCliWsCollectRequestsTest,OpenCliProcessPrivacyTest \ + -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,SubprocessCleanupFaultTest,SubprocessStreamFailureTest,OpenCliWsReverseAgentSessionTest,OpenCliWsCollectRequestsTest,OpenCliProcessPrivacyTest \ test > platform-evidence/maven.log 2>&1 || result=$? tail -100 platform-evidence/maven.log python scripts/contract_report.py \ @@ -58,6 +58,7 @@ jobs: --suite argv=io.github.easy4j.opencli.contract.OpenCliStructuredArgvContractTest \ --suite process=io.github.easy4j.opencli.contract.OpenCliProcessContractTest \ --suite process=io.github.easy4j.opencli.contract.OpenCliProcessBoundaryTest \ + --suite process=io.github.easy4j.opencli.core.support.SubprocessCleanupFaultTest \ --suite process=io.github.easy4j.opencli.core.support.SubprocessStreamFailureTest \ --suite protocol=io.github.easy4j.opencli.center.ws.OpenCliWsReverseAgentSessionTest \ --suite protocol=io.github.easy4j.opencli.center.ws.OpenCliWsCollectRequestsTest \ diff --git a/openspec/changes/harden-opencli-process-lifecycle/tasks.md b/openspec/changes/harden-opencli-process-lifecycle/tasks.md index f627d32..c631a58 100644 --- a/openspec/changes/harden-opencli-process-lifecycle/tasks.md +++ b/openspec/changes/harden-opencli-process-lifecycle/tasks.md @@ -74,3 +74,11 @@ JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,116 项通过,0 修复后,第一次非空写入才分配对应捕获数组,仍受流的配置上限约束。预取消路径的 stdout、stderr 容量均为零,读取线程的工作缓冲和 JVM 总堆内存属独立指标。红灯 2 项失败,修复后 JDK 17 定向 33 项通过。 JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,117 项通过,0 失败、0 错误、0 跳过。 + +## 2026-11-18 OC-PROC-005 终止操作阻塞 + +故障注入让调用独占根进程的普通和强制终止分别等待释放信号。验证显式取消以及 Commons Exec watchdog 到期两条路径。设置清理宽限 250 ms,以 1,250 ms 为回归断言窗口。修复前两项均等待超时。 + +修复将 native 终止调用交给每次执行最多两个守护工作线程,普通和强制终止各发出一次。watchdog 回调只提交终止请求,既有锁不覆盖 native 终止操作。原始 `CANCELLED` 或 `EXECUTION_TIMEOUT` 保留。终止操作未结束时保留 `UNCONFIRMED`,不伪造退出码,并隔离当前运行时。测试最后释放注入的阻塞线程。该修复范围为 SDK 已持有的根进程,后代所有权仍待验收。 + +JDK 17 定向 29 项通过。JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,119 项通过,0 失败、0 错误、0 跳过。平台契约证据增加 `SubprocessCleanupFaultTest`。 diff --git a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java index 870b648..40ee072 100644 --- a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java +++ b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java @@ -8,6 +8,7 @@ import java.io.File; import java.io.IOException; import java.io.InputStream; +import java.io.OutputStream; import java.util.ArrayList; import java.util.Arrays; import java.util.Collections; @@ -118,7 +119,7 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup long budget = nanos(request.timeoutMillis, "timeoutMillis"); BoundedCapture out = new BoundedCapture(request.stdoutLimitBytes); BoundedCapture err = new BoundedCapture(request.stderrLimitBytes); - Process process = null; + CleanupProcess process = null; Reader stdoutReader = null; Reader stderrReader = null; ExecuteWatchdog watchdog = null; @@ -130,6 +131,7 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup long queueWaitMillis = 0L; Integer exit = null; boolean streamsDrained = true; + boolean cleanupFinished = true; try { while (!acquired && reason == null) { if (Thread.interrupted()) { @@ -168,7 +170,7 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup builder.environment().clear(); builder.environment().putAll(request.environment); } - process = processStarter.start(builder); + process = new CleanupProcess(processStarter.start(builder)); process.getOutputStream().close(); stdoutReader = new Reader(process.getInputStream(), out, "opencli-stdout"); stderrReader = new Reader(process.getErrorStream(), err, "opencli-stderr"); @@ -226,23 +228,17 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup long cleanupStart = System.nanoTime(); long cleanupBudget = nanos(request.cleanupGraceMillis, "cleanupGraceMillis"); if (Objects.nonNull(process)) { - boolean forceSent = false; if (process.isAlive()) { - try { - process.destroy(); - } catch (RuntimeException ex) { - cleanupOperationFailed = true; - forceSent = true; - if (!tryForceStop(process)) { cleanupOperationFailed = true; } - } + process.destroy(); } + long forceAfter = Math.min(TimeUnit.MILLISECONDS.toNanos(100L), cleanupBudget / 2L); while (remaining(cleanupStart, cleanupBudget) > 0 - && (process.isAlive() || alive(stdoutReader) || alive(stderrReader))) { + && (process.isAlive() || alive(stdoutReader) || alive(stderrReader) + || process.hasPendingStop())) { if (Thread.interrupted()) { interrupted = true; } - if (process.isAlive() && !forceSent - && System.nanoTime() - cleanupStart >= Math.min(TimeUnit.MILLISECONDS.toNanos(100L), cleanupBudget / 2)) { - if (!tryForceStop(process)) { cleanupOperationFailed = true; } - forceSent = true; + if (process.isAlive() && (process.graceful.failed + || System.nanoTime() - cleanupStart >= forceAfter)) { + process.destroyForcibly(); } try { TimeUnit.NANOSECONDS.sleep(Math.min(POLL_NANOS, @@ -251,13 +247,17 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup interrupted = true; } } - if (process.isAlive() && !tryForceStop(process)) { cleanupOperationFailed = true; } + if (process.isAlive()) { + process.destroyForcibly(); + } + cleanupFinished = !process.hasPendingStop(); + cleanupOperationFailed |= !cleanupFinished || process.graceful.failed || process.forced.failed; if (!process.isAlive()) { exit = process.exitValue(); } streamsDrained = !alive(stdoutReader) && !alive(stderrReader); - if (Objects.isNull(exit) || !streamsDrained) { - // A fixed runtime cannot accumulate unlimited uncertain children/readers. + if (Objects.isNull(exit) || !streamsDrained || !cleanupFinished) { + // Quarantine limits the number of unconfirmed children, readers and stop workers. quarantined = true; if (reason == TerminationReason.PROCESS_EXIT) { reason = TerminationReason.CLEANUP_UNCONFIRMED; } } @@ -283,7 +283,8 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup OpenCliExecutionDetails details = OpenCliExecutionDetails.builder() .terminationReason(reason) .cleanupState(process == null ? CleanupState.NOT_STARTED - : Objects.isNull(exit) || !streamsDrained ? CleanupState.UNCONFIRMED : CleanupState.ROOT_EXIT_CONFIRMED) + : Objects.isNull(exit) || !streamsDrained || !cleanupFinished + ? CleanupState.UNCONFIRMED : CleanupState.ROOT_EXIT_CONFIRMED) .processStarted(process != null).streamsDrained(streamsDrained) .cleanupOperationFailed(cleanupOperationFailed) .stdoutCapturedBytes(out.size()).stdoutObservedBytes(out.observed()).stdoutTruncated(out.isTruncated()) @@ -303,14 +304,81 @@ private static ExecuteWatchdog newWatchdog(long timeoutMillis) { } private static boolean alive(Thread thread) { return thread != null && thread.isAlive(); } - private static boolean tryForceStop(Process process) { - try { - process.destroyForcibly(); - return true; - } catch (RuntimeException ex) { - return false; + /** + * The watchdog holds its monitor when invoking destroy. Keep native stop calls + * outside that monitor and the caller, as closing process pipes can block. + */ + private static final class CleanupProcess extends Process { + private final Process delegate; + private final StopRequest graceful = new StopRequest(); + private final StopRequest forced = new StopRequest(); + + CleanupProcess(Process delegate) { + this.delegate = delegate; + } + + @Override + public OutputStream getOutputStream() { return delegate.getOutputStream(); } + + @Override + public InputStream getInputStream() { return delegate.getInputStream(); } + + @Override + public InputStream getErrorStream() { return delegate.getErrorStream(); } + + @Override + public int waitFor() throws InterruptedException { return delegate.waitFor(); } + + @Override + public int exitValue() { return delegate.exitValue(); } + + @Override + public boolean isAlive() { return delegate.isAlive(); } + + @Override + public void destroy() { + graceful.start("opencli-stop", delegate::destroy); + } + + @Override + public Process destroyForcibly() { + forced.start("opencli-force-stop", delegate::destroyForcibly); + return this; + } + + boolean hasPendingStop() { + return graceful.isPending() || forced.isPending(); } } + + private static final class StopRequest { + private Thread worker; + private volatile boolean failed; + + synchronized void start(String name, Runnable signal) { + if (Objects.nonNull(worker) || failed) { + return; + } + try { + worker = new Thread(() -> { + try { + signal.run(); + } catch (RuntimeException ex) { + failed = true; + } + }, name); + worker.setDaemon(true); + worker.start(); + } catch (RuntimeException ex) { + failed = true; + } + } + + synchronized boolean isPending() { + return alive(worker); + } + } + private static long remaining(long start, long budget) { return budget - (System.nanoTime() - start); } // The Windows JDK legacy serializer treats a surrounding quote pair as already encoded. @SuppressWarnings("removal") diff --git a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCleanupFaultTest.java b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCleanupFaultTest.java index b5c20e5..59f4a78 100644 --- a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCleanupFaultTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCleanupFaultTest.java @@ -7,6 +7,11 @@ import java.io.ByteArrayOutputStream; import java.io.InputStream; import java.io.OutputStream; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.Future; +import java.util.concurrent.TimeUnit; import java.util.concurrent.atomic.AtomicReference; import org.apache.commons.exec.CommandLine; import org.apache.commons.exec.ExecuteWatchdog; @@ -148,6 +153,71 @@ void unconfirmedForcedStopQuarantinesRuntimeWithoutFabricatingExit() throws Exce assertEquals(1, starts[0]); } + @Test + void blockedGracefulAndForcedStopDoNotHoldCallerPastCleanupGrace() throws Exception { + assertBoundedStop(false, TerminationReason.CANCELLED); + } + + @Test + void watchdogTimeoutDoesNotHoldCallerWhileNativeStopIsBlocked() throws Exception { + assertBoundedStop(true, TerminationReason.EXECUTION_TIMEOUT); + } + + private static void assertBoundedStop(boolean watchdogExpires, TerminationReason expected) throws Exception { + CountDownLatch gracefulEntered = new CountDownLatch(1); + CountDownLatch forceEntered = new CountDownLatch(1); + CountDownLatch release = new CountDownLatch(1); + FakeProcess child = new FakeProcess(false) { + @Override + public void destroy() { + waitForRelease(gracefulEntered, release); + super.destroy(); + } + + @Override + public Process destroyForcibly() { + waitForRelease(forceEntered, release); + return super.destroyForcibly(); + } + }; + OpenCliCancellationToken token = new OpenCliCancellationToken(); + SubprocessExecutionSupport.Runtime runtime = new SubprocessExecutionSupport.Runtime(1, + builder -> { + if (!watchdogExpires) { + token.cancel(); + } + return child; + }, timeout -> watchdogExpires ? new ExecuteWatchdog(20L) : new FakeWatchdog(false)); + SubprocessExecutionSupport.ExecutionRequest request = new SubprocessExecutionSupport.ExecutionRequest( + CommandLine.parse("fake"), null, null, 1000L, 16, 16, 250L, System.nanoTime(), token); + + ExecutorService worker = Executors.newSingleThreadExecutor(); + try { + Future pending = worker.submit(() -> runtime.execute(request)); + assertTrue(gracefulEntered.await(1, TimeUnit.SECONDS)); + SubprocessExecutionSupport.RunSession session = pending.get(1250, TimeUnit.MILLISECONDS); + assertEquals(0, forceEntered.getCount()); + assertEquals(expected, session.getExecutionDetails().getTerminationReason()); + assertEquals(CleanupState.UNCONFIRMED, session.getExecutionDetails().getCleanupState()); + assertTrue(session.getExecutionDetails().isCleanupOperationFailed()); + assertNull(session.getObservedExitCode()); + assertTrue(runtime.isQuarantined()); + } finally { + release.countDown(); + worker.shutdownNow(); + assertTrue(worker.awaitTermination(2, TimeUnit.SECONDS)); + } + } + + private static void waitForRelease(CountDownLatch entered, CountDownLatch release) { + entered.countDown(); + try { + release.await(3, TimeUnit.SECONDS); + } catch (InterruptedException failure) { + Thread.currentThread().interrupt(); + } + } + @Test void cancelledSubmissionDoesNotInitializeWatchdogOrSpawn() throws Exception { OpenCliCancellationToken token = new OpenCliCancellationToken(); @@ -233,9 +303,9 @@ public synchronized void stop() { public synchronized boolean killedProcess() { return false; } } - private static final class FakeProcess extends Process { + private static class FakeProcess extends Process { private final boolean failDestroy; - private boolean alive = true; + private volatile boolean alive = true; private final boolean failForce; private final boolean failStreamSetup; From d4da616ad65d4986a7a18383db6e897451c8e38a Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:53:01 +0800 Subject: [PATCH 019/105] test: verify OpenCLI argv snapshot while queued --- .../harden-opencli-argv-contract/tasks.md | 24 ++++++---- .../contract/OpenCliArgvContractTest.java | 2 +- .../contract/OpenCliProcessContractTest.java | 45 +++++++++++++++++++ 3 files changed, 62 insertions(+), 9 deletions(-) diff --git a/openspec/changes/harden-opencli-argv-contract/tasks.md b/openspec/changes/harden-opencli-argv-contract/tasks.md index fc170fd..457c60d 100644 --- a/openspec/changes/harden-opencli-argv-contract/tasks.md +++ b/openspec/changes/harden-opencli-argv-contract/tasks.md @@ -1,26 +1,34 @@ # C01 Tasks · 参数保真与统一调用契约 -> 全部为待执行实现任务。文档/格式检查通过不允许提前勾选。 +> 已勾选项对应真实子进程契约及历史失败证据。保留 3.4 的评审和归档门禁。 关联规范:[spec](specs/opencli-argv-contract/spec.md)。 ## 1. 失败测试 -- [ ] 1.1 在现有 core/support 测试区新增 Java argv echo fixture,覆盖空值、空白、Unicode、换行、-- 和重复 flag。 -- [ ] 1.2 先在实现前运行新增用例,保存真实失败输出;禁止只断言命令前缀。 +- [x] 1.1 在现有 core/support 测试区新增 Java argv echo fixture,覆盖空值、空白、Unicode、换行、-- 和重复 flag。 +- [x] 1.2 先在实现前运行新增用例,保存真实失败输出;禁止只断言命令前缀。 ## 2. 最小实现 -- [ ] 2.1 统一 Executor/AdapterChannel/参数 helpers 的值保真路径,并对输入列表做快照。 -- [ ] 2.2 为 null/标识符错误建立不包含业务值的校验;增量支持有序 option occurrences 和 false 语义。 +- [x] 2.1 统一 Executor/AdapterChannel/参数 helpers 的值保真路径,并对输入列表做快照。 +- [x] 2.2 为 null/标识符错误建立不包含业务值的校验;增量支持有序 option occurrences 和 false 语义。 ## 3. 迁移与验证 -- [ ] 3.1 补 List/varargs/typed/request 等价与用户列表不被修改的测试。 -- [ ] 3.2 检查 Windows launcher 与引号边界,未测试的平台明确保留未验证状态。 -- [ ] 3.3 分别在三条 feature 线运行共享 vectors 和现有测试,记录允许差异。 +- [x] 3.1 补 List/varargs/typed/request 等价与用户列表不被修改的测试。 +- [x] 3.2 检查 Windows launcher 与引号边界,未测试的平台明确保留未验证状态。 +- [x] 3.3 分别在三条 feature 线运行共享 vectors 和现有测试,记录允许差异。 - [ ] 3.4 评审迁移说明与完整 diff;需求通过后再申请 archive,不在文档阶段勾选。 ## 证据交付模板(实施时填写) 每项任务的完成记录包含:Requirement/Scenario、分支HEAD、测试命令、失败→通过证据、测试数/跳过数、退出码、报告位置。没有记录的任务保持未完成。 + +## C01 实现与参数保真证据(2026-11-18) + +- OC-ARGV-001、002、004、005。提交 `cdc8b66e74730ab1ed99a9f24a077f9077d2dbf5` 只引入契约夹具。在独立源码目录用 JDK 17 运行 `mvn -B -ntp -o -Dtest=OpenCliArgvContractTest test`,33 项中 21 项失败,0 错误、0 跳过,退出 1。真实子进程收到的完整向量显示空值被丢弃、两端空白被裁剪,typed browser fill 也丢失用于清空字段的空字符串。 +- OC-ARGV-003。提交 `d02b16ddc5e0fe7c1d98c6847f4b2999cf2f2566` 用同一环境运行 `OpenCliStructuredArgvContractTest`,10 项中 10 项失败,0 错误、0 跳过,退出 1。可变 Map 与 StringBuilder 改写了实际 argv。当前实现支持显式 schema、有序重复选项、值型 false、否定 flag,拒绝歧义,旧 Map 继续使用历史语义。[历史 RED/GREEN 执行记录](../../../docs/implementation/c10-c01-execution.md) +- 当前本地回归覆盖完整向量、argv 第三项为 null、空白标识符、等号、引号、反斜杠、`--`、Unicode 和换行。新增排队变更回归。一个真实 JVM 占住共享许可,下一次调用完成列表快照后,调用方修改原列表并释放许可。回显子进程收到提交时的完整向量,调用方原列表只包含它自己所作修改。JDK 17 定向 45 项通过。 +- Windows 使用原生 `node.exe` 运行回显夹具,含空白、引号和末尾反斜杠的 token 保留。SDK 会在启动前拒绝 `.cmd`、`.bat` 批处理入口。JDK 17 曾运行真实安装包的启动器测试,仅执行只读元命令。对应 [JDK 8 平台 CI](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44339054705)、[JDK 17 Windows](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44339055208/job/134923652889)、[JDK 21 Windows](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44339054801) 与 [已安装启动器证据](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44313779366/job/134834399117)。 +- 三条维护线使用同一套已校验 SHA-256 的 `argv.tsv`、`ContractProbe` 和 `OpenCliStructuredArgvContractTest`。JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,120 项通过,0 失败、0 错误、0 跳过,退出 0。本地报告为 `target/surefire-reports`。三个版本的 JDK/Jackson/Maven 允许差异见 fixture 的 `sources.lock.json`。远端分支最新 CI 单独记录于 PR。 diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java index 1bad49f..dd73e0c 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java @@ -55,7 +55,7 @@ private static OpenCliProperties properties() { return p; } - private static List received(OpenCliResult result) throws Exception { + static List received(OpenCliResult result) throws Exception { assertTrue(result.isSuccess()); List actual = new ArrayList<>(); try (BufferedReader reader = new BufferedReader(new StringReader(result.getStdout()))) { diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java index cd22ee2..58b3196 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java @@ -21,6 +21,7 @@ import java.util.Arrays; import java.util.Collections; import java.util.List; +import java.util.concurrent.CountDownLatch; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; import java.util.concurrent.Future; @@ -324,6 +325,50 @@ void explicitSharedRuntimeLimitsBothClients() throws Exception { } } + @Test + void queuedInvocationUsesItsArgvSnapshotAfterCallerMutation() throws Exception { + OpenCliProcessRuntime runtime = new OpenCliProcessRuntime(1); + OpenCliExecutor blocker = new OpenCliExecutor(properties(1), runtime); + OpenCliProperties echoProperties = properties(1); + List leading = echoProperties.getLeadingArguments(); + leading.set(leading.size() - 1, ContractProbe.class.getName()); + OpenCliExecutor echo = new OpenCliExecutor(echoProperties, runtime); + List expected = Arrays.asList("demo", "echo", "", " 原始值 "); + CountDownLatch copied = new CountDownLatch(1); + List input = new ArrayList(expected) { + @Override + public Object[] toArray() { + Object[] result = super.toArray(); + copied.countDown(); + return result; + } + }; + Path active = dir.resolve("argv-blocker"); + Path gate = dir.resolve("argv-release"); + ExecutorService workers = Executors.newFixedThreadPool(2); + try { + Future running = workers.submit(() -> + blocker.invoke("hold", active.toString(), gate.toString())); + assertTrue(awaitFile(active, 5_000L)); + Future queued = workers.submit(() -> echo.invoke(input)); + assertTrue(copied.await(2, TimeUnit.SECONDS)); + assertEquals(expected, input); + assertFalse(queued.isDone()); + + input.set(3, "changed"); + input.add("late"); + release(gate); + + assertTrue(running.get(5, TimeUnit.SECONDS).isSuccess()); + assertEquals(expected, OpenCliArgvContractTest.received(queued.get(5, TimeUnit.SECONDS))); + assertEquals(Arrays.asList("demo", "echo", "", "changed", "late"), input); + } finally { + release(gate); + workers.shutdownNow(); + assertTrue(workers.awaitTermination(5, TimeUnit.SECONDS)); + } + } + @Test void sharedRuntimeBoundsConcurrentChildrenAndCombinedCapture() throws Exception { int stdoutLimit = 131_073; From 05f6660125c272bf7a4dfbba6038ca93dc87fd54 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:53:22 +0800 Subject: [PATCH 020/105] docs: link shared OpenCLI argv history from backports --- openspec/changes/harden-opencli-argv-contract/tasks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openspec/changes/harden-opencli-argv-contract/tasks.md b/openspec/changes/harden-opencli-argv-contract/tasks.md index 457c60d..15d6d3c 100644 --- a/openspec/changes/harden-opencli-argv-contract/tasks.md +++ b/openspec/changes/harden-opencli-argv-contract/tasks.md @@ -28,7 +28,7 @@ ## C01 实现与参数保真证据(2026-11-18) - OC-ARGV-001、002、004、005。提交 `cdc8b66e74730ab1ed99a9f24a077f9077d2dbf5` 只引入契约夹具。在独立源码目录用 JDK 17 运行 `mvn -B -ntp -o -Dtest=OpenCliArgvContractTest test`,33 项中 21 项失败,0 错误、0 跳过,退出 1。真实子进程收到的完整向量显示空值被丢弃、两端空白被裁剪,typed browser fill 也丢失用于清空字段的空字符串。 -- OC-ARGV-003。提交 `d02b16ddc5e0fe7c1d98c6847f4b2999cf2f2566` 用同一环境运行 `OpenCliStructuredArgvContractTest`,10 项中 10 项失败,0 错误、0 跳过,退出 1。可变 Map 与 StringBuilder 改写了实际 argv。当前实现支持显式 schema、有序重复选项、值型 false、否定 flag,拒绝歧义,旧 Map 继续使用历史语义。[历史 RED/GREEN 执行记录](../../../docs/implementation/c10-c01-execution.md) +- OC-ARGV-003。提交 `d02b16ddc5e0fe7c1d98c6847f4b2999cf2f2566` 用同一环境运行 `OpenCliStructuredArgvContractTest`,10 项中 10 项失败,0 错误、0 跳过,退出 1。可变 Map 与 StringBuilder 改写了实际 argv。当前实现支持显式 schema、有序重复选项、值型 false、否定 flag,拒绝歧义,旧 Map 继续使用历史语义。[历史 RED/GREEN 执行记录](https://github.com/easy-4-java/opencli-java-sdk/blob/01513226e14c4e73e0ed602332285d407a1489a9/docs/implementation/c10-c01-execution.md) - 当前本地回归覆盖完整向量、argv 第三项为 null、空白标识符、等号、引号、反斜杠、`--`、Unicode 和换行。新增排队变更回归。一个真实 JVM 占住共享许可,下一次调用完成列表快照后,调用方修改原列表并释放许可。回显子进程收到提交时的完整向量,调用方原列表只包含它自己所作修改。JDK 17 定向 45 项通过。 - Windows 使用原生 `node.exe` 运行回显夹具,含空白、引号和末尾反斜杠的 token 保留。SDK 会在启动前拒绝 `.cmd`、`.bat` 批处理入口。JDK 17 曾运行真实安装包的启动器测试,仅执行只读元命令。对应 [JDK 8 平台 CI](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44339054705)、[JDK 17 Windows](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44339055208/job/134923652889)、[JDK 21 Windows](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44339054801) 与 [已安装启动器证据](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44313779366/job/134834399117)。 - 三条维护线使用同一套已校验 SHA-256 的 `argv.tsv`、`ContractProbe` 和 `OpenCliStructuredArgvContractTest`。JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,120 项通过,0 失败、0 错误、0 跳过,退出 0。本地报告为 `target/surefire-reports`。三个版本的 JDK/Jackson/Maven 允许差异见 fixture 的 `sources.lock.json`。远端分支最新 CI 单独记录于 PR。 From 12aa318243397663b6badbfb70d5f64943350ecf Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:56:20 +0800 Subject: [PATCH 021/105] test: use native Windows argv probe for queued calls --- openspec/changes/harden-opencli-argv-contract/tasks.md | 2 ++ .../easy4j/opencli/contract/OpenCliArgvContractTest.java | 2 +- .../easy4j/opencli/contract/OpenCliProcessContractTest.java | 5 +---- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/openspec/changes/harden-opencli-argv-contract/tasks.md b/openspec/changes/harden-opencli-argv-contract/tasks.md index 15d6d3c..8e41963 100644 --- a/openspec/changes/harden-opencli-argv-contract/tasks.md +++ b/openspec/changes/harden-opencli-argv-contract/tasks.md @@ -32,3 +32,5 @@ - 当前本地回归覆盖完整向量、argv 第三项为 null、空白标识符、等号、引号、反斜杠、`--`、Unicode 和换行。新增排队变更回归。一个真实 JVM 占住共享许可,下一次调用完成列表快照后,调用方修改原列表并释放许可。回显子进程收到提交时的完整向量,调用方原列表只包含它自己所作修改。JDK 17 定向 45 项通过。 - Windows 使用原生 `node.exe` 运行回显夹具,含空白、引号和末尾反斜杠的 token 保留。SDK 会在启动前拒绝 `.cmd`、`.bat` 批处理入口。JDK 17 曾运行真实安装包的启动器测试,仅执行只读元命令。对应 [JDK 8 平台 CI](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44339054705)、[JDK 17 Windows](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44339055208/job/134923652889)、[JDK 21 Windows](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44339054801) 与 [已安装启动器证据](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44313779366/job/134834399117)。 - 三条维护线使用同一套已校验 SHA-256 的 `argv.tsv`、`ContractProbe` 和 `OpenCliStructuredArgvContractTest`。JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,120 项通过,0 失败、0 错误、0 跳过,退出 0。本地报告为 `target/surefire-reports`。三个版本的 JDK/Jackson/Maven 允许差异见 fixture 的 `sources.lock.json`。远端分支最新 CI 单独记录于 PR。 + +- 排队回归与原始参数回归共用回显启动配置。首次 JDK 17 Windows CI 使用旧 Java 回显启动器时,子进程把原始中文 token 收成 `???`。改用同套 Windows 原生 Node 回显夹具,继续断言完整 Unicode token,并保留 Java 生命周期进程作为许可占用方。[首次 Windows 结果](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44340768729/job/134929785664) diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java index dd73e0c..0ed5dec 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java @@ -32,7 +32,7 @@ /** Shared Java 8-compatible contract tests, with a real child rather than Recording executor. */ class OpenCliArgvContractTest { - private static OpenCliProperties properties() { + static OpenCliProperties properties() { OpenCliProperties p = new OpenCliProperties(); String exe = System.getProperty("os.name").startsWith("Windows") ? "java.exe" : "java"; p.setExecutable(new File(new File(System.getProperty("java.home"), "bin"), exe).getAbsolutePath()); diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java index 58b3196..f9ddfe3 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java @@ -329,10 +329,7 @@ void explicitSharedRuntimeLimitsBothClients() throws Exception { void queuedInvocationUsesItsArgvSnapshotAfterCallerMutation() throws Exception { OpenCliProcessRuntime runtime = new OpenCliProcessRuntime(1); OpenCliExecutor blocker = new OpenCliExecutor(properties(1), runtime); - OpenCliProperties echoProperties = properties(1); - List leading = echoProperties.getLeadingArguments(); - leading.set(leading.size() - 1, ContractProbe.class.getName()); - OpenCliExecutor echo = new OpenCliExecutor(echoProperties, runtime); + OpenCliExecutor echo = new OpenCliExecutor(OpenCliArgvContractTest.properties(), runtime); List expected = Arrays.asList("demo", "echo", "", " 原始值 "); CountDownLatch copied = new CountDownLatch(1); List input = new ArrayList(expected) { From 4fe3e4d5624fe07073201cd93c0cac06b80e7414 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:03:40 +0800 Subject: [PATCH 022/105] fix: retire stopped OpenCLI WebSocket generations --- .../harden-opencli-reverse-agent/tasks.md | 12 +++- .../ws/OpenCliWsReverseAgentClient.java | 70 +++++++++++++------ .../ws/OpenCliWsReverseAgentSessionTest.java | 39 +++++++++++ 3 files changed, 98 insertions(+), 23 deletions(-) diff --git a/openspec/changes/harden-opencli-reverse-agent/tasks.md b/openspec/changes/harden-opencli-reverse-agent/tasks.md index e113e5c..fa39831 100644 --- a/openspec/changes/harden-opencli-reverse-agent/tasks.md +++ b/openspec/changes/harden-opencli-reverse-agent/tasks.md @@ -1,13 +1,13 @@ # C05 Tasks · 反向 Worker 状态机、背压与去重 -> 全部为待执行实现任务。文档/格式检查通过不允许提前勾选。 +> 已勾选项有对应的实现和回归证据。 关联规范:[spec](specs/opencli-reverse-agent/spec.md)。 ## 1. Worker fixture -- [ ] 1.1 新增可控本地 WS server,覆盖未注册 collect、超大/空 ID、队列满与重复消息。 -- [ ] 1.2 加入断线写任务、代际结果路由、close竞态和重启边界的失败测试。 +- [x] 1.1 新增可控本地 WS server,覆盖未注册 collect、超大/空 ID、队列满与重复消息。 +- [x] 1.2 加入断线写任务、代际结果路由、close竞态和重启边界的失败测试。 ## 2. 治理实现 @@ -29,3 +29,9 @@ ## JDK 8 回移验证 回移 JDK 17 版本的注册前拒绝、执行与等待上限、关闭保护、请求去重、缓存过期和连接隔离。通过本地回环服务器、真实子进程和测试证书验证普通连接和 TLS 重连。运行 `mvn -B -ntp -o clean verify`,2,112 项测试通过,零失败、零跳过,JaCoCo 行覆盖率为 2,905 / 3,167(91.73%)。 + +## 2026-11-19 OC-WS-005/006 代际发布与停止竞态 + +`stopDuringConnectionSetupDoesNotPublishAnotherGeneration` 在连接线程读取端点时阻塞配置读取,随后调用 `stop()`,再解除阻塞。修复前本地中心收到已停止 worker 的注册消息,1 项失败,退出 1。修复后停止和连接发布共用同步边界,晚到连接无法发布。异常、关闭及退出均只退役对应 socket,当前代际检查用于注册、收单和异步结果投递。同一个已验证 TLS 中心显式重发仍可读取对应缓存。异常的默认日志保持固定文本。 + +`OpenCliWsReverseAgentSessionTest` 的回环服务同时覆盖提前收单、空白和超大 ID、队列溢出、重复请求、断线时在途工作、TLS 显式重发、明文会话隔离、关闭丢弃队列及关闭后拒绝重启。JDK 17 定向验证 27 项通过。JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,121 项通过,0 失败、0 错误、0 跳过。显式状态机、可重启 stop 的任务收尾合同和平台资源验收仍由相应任务跟踪。 diff --git a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java index 026d669..e696d8e 100644 --- a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java +++ b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java @@ -65,7 +65,7 @@ public final class OpenCliWsReverseAgentClient implements AutoCloseable { private volatile boolean shutdownRequested; - private volatile WebSocketClient activeClient; + private final AtomicReference activeClient = new AtomicReference<>(); private Thread runnerThread; @@ -113,8 +113,7 @@ public synchronized void start() { */ public synchronized void stop() { shutdownRequested = true; - WebSocketClient client = activeClient; - activeClient = null; + WebSocketClient client = activeClient.getAndSet(null); if (Objects.nonNull(client)) { try { client.close(); @@ -201,6 +200,10 @@ private void runOneSession() throws Exception { new WebSocketClient(endpoint) { @Override public void onOpen(ServerHandshake handshake) { + if (!isCurrentSession(this)) { + closeSession(this); + return; + } try { send(buildRegisterJson()); } catch (Exception e) { @@ -221,6 +224,7 @@ public void onMessage(String message) { @Override public void onClose(int code, String reason, boolean remote) { + activeClient.compareAndSet(this, null); if (registered.getCount() > 0) { handshakeFailure.compareAndSet( null, @@ -235,6 +239,7 @@ public void onClose(int code, String reason, boolean remote) { @Override public void onError(Exception ex) { + activeClient.compareAndSet(this, null); log.warn("WebSocket error"); if (registered.getCount() > 0) { handshakeFailure.compareAndSet(null, ex); @@ -244,26 +249,48 @@ public void onError(Exception ex) { } }; - activeClient = client; - if (!client.connectBlocking(30, TimeUnit.SECONDS)) { - throw new IllegalStateException("WebSocket connectBlocking returned false"); + if (!publishSession(client)) { + return; } + try { + if (!client.connectBlocking(30, TimeUnit.SECONDS)) { + throw new IllegalStateException("WebSocket connectBlocking returned false"); + } + if (!registered.await(connectionProperties.getHandshakeTimeoutMillis(), TimeUnit.MILLISECONDS)) { + throw new IllegalStateException("Timeout waiting for 'registered' from center"); + } + Throwable hf = handshakeFailure.get(); + if (Objects.nonNull(hf)) { + if (hf instanceof Exception) { + throw (Exception) hf; + } + throw new IllegalStateException(hf); + } + sessionClosed.await(); + } finally { + activeClient.compareAndSet(client, null); + closeSession(client); + } + } - if (!registered.await(connectionProperties.getHandshakeTimeoutMillis(), TimeUnit.MILLISECONDS)) { - client.close(); - throw new IllegalStateException("Timeout waiting for 'registered' from center"); + private synchronized boolean publishSession(WebSocketClient client) { + if (shutdownRequested) { + return false; } - Throwable hf = handshakeFailure.get(); - if (Objects.nonNull(hf)) { + activeClient.set(client); + return true; + } + + private boolean isCurrentSession(WebSocketClient client) { + return !shutdownRequested && activeClient.get() == client; + } + + private static void closeSession(WebSocketClient client) { + try { client.close(); - if (hf instanceof Exception) { - throw (Exception) hf; - } - throw new IllegalStateException(hf); + } catch (Exception e) { + log.debug("ws session close failed"); } - - sessionClosed.await(); - activeClient = null; } private void validateConnectionProperties() { @@ -316,6 +343,9 @@ private void handleTextMessage( CountDownLatch registered, AtomicReference handshakeFailure) throws Exception { + if (!isCurrentSession(ws)) { + return; + } JsonNode root = MAPPER.readTree(payload); String type = root.path("type").asText(""); if ("registered".equals(type)) { @@ -336,7 +366,7 @@ private void handleTextMessage( sendResult(ws, result("", false, Collections.emptyList(), "invalid worker request ID")); return; } - if (shutdownRequested || !ws.isOpen() || registered.getCount() > 0 + if (!isCurrentSession(ws) || !ws.isOpen() || registered.getCount() > 0 || Objects.nonNull(handshakeFailure.get())) { sendResult(ws, result(requestId, false, Collections.emptyList(), "worker is not registered")); return; @@ -379,7 +409,7 @@ private void runCollectSafe(WebSocketClient ws, OpenCliWsCollectRequests.Key key } finally { collectRequests.complete(key, response); } - if (Objects.nonNull(response) && ws.isOpen()) { + if (Objects.nonNull(response) && isCurrentSession(ws) && ws.isOpen()) { sendResult(ws, response); } } diff --git a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java index 200a3cd..eff4e03 100644 --- a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java +++ b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java @@ -56,6 +56,45 @@ class OpenCliWsReverseAgentSessionTest { private static final ObjectMapper MAPPER = new ObjectMapper(); private static final String AGENT_URL = "http://127.0.0.1:19823"; + @Test + void stopDuringConnectionSetupDoesNotPublishAnotherGeneration() throws Exception { + CountDownLatch resolving = new CountDownLatch(1); + CountDownLatch release = new CountDownLatch(1); + try (LocalCenter center = new LocalCenter()) { + OpenCliWsAgentConnectionProperties connection = new OpenCliWsAgentConnectionProperties() { + @Override + public String getCentralApiBaseUrl() { + resolving.countDown(); + boolean interrupted = false; + while (release.getCount() > 0) { + try { + release.await(); + } catch (InterruptedException failure) { + interrupted = true; + } + } + if (interrupted) { + Thread.currentThread().interrupt(); + } + return super.getCentralApiBaseUrl(); + } + }; + connection.setCentralApiBaseUrl(center.agentProperties().getCentralApiBaseUrl()); + connection.setAgentAdvertiseUrl(AGENT_URL); + try (OpenCliWsReverseAgentClient agent = new OpenCliWsReverseAgentClient( + probe(ContractProbe.class.getName()), connection)) { + try { + agent.start(); + assertTrue(resolving.await(5, TimeUnit.SECONDS)); + agent.stop(); + } finally { + release.countDown(); + } + assertNull(center.messages.poll(1, TimeUnit.SECONDS), "stopped worker published a registration"); + } + } + } + @Test void exchangesRegistrationAndCollectResultsAndReconnectsAfterRemoteClose() throws Exception { try (LocalCenter center = new LocalCenter()) { From 95de832923be497da699245fe42580f96b1510f3 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:11:02 +0800 Subject: [PATCH 023/105] fix: drain OpenCLI reverse worker on restartable stop --- README.md | 4 +- README.zh-CN.md | 4 +- .../harden-opencli-reverse-agent/tasks.md | 10 +- .../ws/OpenCliWsReverseAgentClient.java | 184 +++++++++++++----- .../ws/OpenCliWsReverseAgentSessionTest.java | 47 +++++ 5 files changed, 201 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index b6a8726..59fda97 100644 --- a/README.md +++ b/README.md @@ -226,7 +226,9 @@ Protocol: edge sends `register`; center replies `registered`; center sends `coll The reverse agent accepts up to four concurrent collect tasks and 32 queued tasks by default. Set `maxConcurrentCollects` and `maxPendingCollects` on the connection properties before constructing the agent to change the limits. A queue capacity of zero disables waiting. When full, the agent replies with a failed `result` and the error `worker is busy`. -Collect request IDs must be nonblank strings of at most 128 UTF-8 bytes. The agent suppresses identical in-flight requests and rejects a reused ID with a different payload. An explicit retry may return a result marked `cached: true`. The in-memory cache keeps up to 1,024 completed results for at most ten minutes. Replay across reconnects requires the same TLS-verified endpoint. Plain WebSocket connections keep session-local deduplication. Restarting the agent discards its cache. +Collect request IDs must be nonblank strings of at most 128 UTF-8 bytes. The agent suppresses identical in-flight requests and rejects a reused ID with a different payload. An explicit retry may return a result marked `cached: true`. The in-memory cache keeps up to 1,024 completed results for at most ten minutes. Replay across reconnects requires the same TLS-verified endpoint. Plain WebSocket connections keep session-local deduplication. A new agent instance starts with an empty cache. + +`stop()` stops admission, discards queued tasks and allows in-flight work up to five seconds to finish before requesting cancellation. After the runner has stopped, `start()` can reconnect the same instance. `close()` immediately requests cancellation and closes the instance permanently. ### Diagnostic export diff --git a/README.zh-CN.md b/README.zh-CN.md index 06d0272..9a050c5 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -225,7 +225,9 @@ agent.close(); 反向 Agent 默认最多同时执行 4 个 collect 任务,另有 32 个等待名额。构建 Agent 前,可在连接配置中设置 `maxConcurrentCollects` 和 `maxPendingCollects`。等待容量为零时直接拒绝超额请求。容量用尽时返回失败的 `result`,错误为 `worker is busy`。 -collect 请求 ID 必须为非空白字符串,长度上限 128 个 UTF-8 字节。相同的在途请求只执行一次,同一个 ID 对应不同载荷时会明确拒绝。显式重试已完成的请求有可能收到标记为 `cached: true` 的结果。内存缓存最多保留 1,024 条完成结果,每条最长 10 分钟。跨连接重放要求使用同一个经过 TLS 校验的端点,明文 WebSocket 的去重范围为当前连接。Agent 重启后会清空缓存。 +collect 请求 ID 必须为非空白字符串,长度上限 128 个 UTF-8 字节。相同的在途请求只执行一次,同一个 ID 对应不同载荷时会明确拒绝。显式重试已完成的请求有可能收到标记为 `cached: true` 的结果。内存缓存最多保留 1,024 条完成结果,每条最长 10 分钟。跨连接重放要求使用同一个经过 TLS 校验的端点,明文 WebSocket 的去重范围为当前连接。创建新 Agent 实例时从空缓存开始。 + +`stop()` 停止接单并丢弃等待任务,为已在途任务保留最多 5 秒的收尾时间,随后请求取消。连接线程退出后,同一实例可再次调用 `start()` 重连。`close()` 立即请求取消,并永久关闭该实例。 ### 诊断导出 diff --git a/openspec/changes/harden-opencli-reverse-agent/tasks.md b/openspec/changes/harden-opencli-reverse-agent/tasks.md index fa39831..37a1fc5 100644 --- a/openspec/changes/harden-opencli-reverse-agent/tasks.md +++ b/openspec/changes/harden-opencli-reverse-agent/tasks.md @@ -14,7 +14,7 @@ - [ ] 2.1 建立显式状态机及 READY gate,接收线程仅做有界解析与准入。 - [ ] 2.2 用有限执行器替换 cached pool,加入容量校验和兼容 BUSY result。 - [ ] 2.3 实现 payload digest、在途记录与有界完成缓存;同 ID 不同载荷拒绝。 -- [ ] 2.4 实现连接代际与有界 drain/cancel,CLOSED 终态。 +- [x] 2.4 实现连接代际与有界 drain/cancel,CLOSED 终态。见 OC-WS-006 验证。 ## 3. 兼容与验收 @@ -35,3 +35,11 @@ `stopDuringConnectionSetupDoesNotPublishAnotherGeneration` 在连接线程读取端点时阻塞配置读取,随后调用 `stop()`,再解除阻塞。修复前本地中心收到已停止 worker 的注册消息,1 项失败,退出 1。修复后停止和连接发布共用同步边界,晚到连接无法发布。异常、关闭及退出均只退役对应 socket,当前代际检查用于注册、收单和异步结果投递。同一个已验证 TLS 中心显式重发仍可读取对应缓存。异常的默认日志保持固定文本。 `OpenCliWsReverseAgentSessionTest` 的回环服务同时覆盖提前收单、空白和超大 ID、队列溢出、重复请求、断线时在途工作、TLS 显式重发、明文会话隔离、关闭丢弃队列及关闭后拒绝重启。JDK 17 定向验证 27 项通过。JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,121 项通过,0 失败、0 错误、0 跳过。显式状态机、可重启 stop 的任务收尾合同和平台资源验收仍由相应任务跟踪。 + +## 2026-11-19 OC-WS-006 可重启停止 + +`restartableStopDropsQueuedCollectsAndCancelsPastDrainDeadline` 在回环中心提交持续心跳的真实 CLI 子进程,并填满等待队列。CLI 时限配置为 20 秒,确保 SDK 命令时限不会代替 Worker 的停止预算。旧实现返回后在途心跳仍递增,定向 1 项失败,退出 1。修复后 `stop()` 先停止准入、退役原连接、撤销未启动的排队任务,给已运行任务最多 5 秒收尾,再取消剩余任务。回归验证停止调用在 7 秒测试窗口内返回、心跳停止、排队任务没有启动、同一实例重连可接收任务。 + +已启动任务保留去重占位到实际执行收尾。等待任务撤销时释放占位。重连使用原有固定线程池及其容量。终态 `close()` 仍立即取消在途工作,丢弃队列并在共用预算内等待资源回收,关闭后拒绝重启。 + +JDK 17 定向 28 项通过。JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,122 项通过,0 失败、0 错误、0 跳过。显式连接状态机和独立平台资源验收仍由 2.1 和 3.3 跟踪。 diff --git a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java index e696d8e..462cb11 100644 --- a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java +++ b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java @@ -5,6 +5,7 @@ import com.fasterxml.jackson.databind.node.ArrayNode; import com.fasterxml.jackson.databind.node.ObjectNode; import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.core.OpenCliCancellationToken; import io.github.easy4j.opencli.core.OpenCliExecutor; import io.github.easy4j.opencli.core.OpenCliResult; import io.github.easy4j.opencli.exception.OpenCliException; @@ -14,14 +15,15 @@ import java.security.MessageDigest; import java.util.ArrayList; import java.util.Collections; +import java.util.HashSet; import java.util.Iterator; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; import java.util.Objects; +import java.util.Set; import java.util.concurrent.BlockingQueue; import java.util.concurrent.CountDownLatch; -import java.util.concurrent.ExecutorService; import java.util.concurrent.LinkedBlockingQueue; import java.util.concurrent.RejectedExecutionException; import java.util.concurrent.SynchronousQueue; @@ -59,7 +61,8 @@ public final class OpenCliWsReverseAgentClient implements AutoCloseable { private final OpenCliWsAgentConnectionProperties connectionProperties; - private final ExecutorService collectPool; + private final ThreadPoolExecutor collectPool; + private final Set collectTasks = new HashSet<>(); private final OpenCliWsCollectRequests collectRequests = new OpenCliWsCollectRequests(1024, TimeUnit.MINUTES.toNanos(10), System::nanoTime); @@ -68,6 +71,8 @@ public final class OpenCliWsReverseAgentClient implements AutoCloseable { private final AtomicReference activeClient = new AtomicReference<>(); private Thread runnerThread; + private boolean stopping; + private long admissionEpoch; /** * @param openCliProperties 本地 opencli 配置 @@ -99,7 +104,7 @@ public synchronized void start() { if (collectPool.isShutdown()) { throw new IllegalStateException("WebSocket worker is closed"); } - if (runnerThread != null && runnerThread.isAlive()) { + if (stopping || (Objects.nonNull(runnerThread) && runnerThread.isAlive())) { return; } shutdownRequested = false; @@ -109,47 +114,101 @@ public synchronized void start() { } /** - * 请求停止并关闭当前 WebSocket。 + * 停止接单并丢弃未开始的任务。在有限时间内等待已在途任务,随后请求取消。 + * 停止完成后可重新启动同一实例。 */ - public synchronized void stop() { - shutdownRequested = true; - WebSocketClient client = activeClient.getAndSet(null); - if (Objects.nonNull(client)) { - try { - client.close(); - } catch (Exception e) { - log.debug("ws close failed during stop"); + public void stop() { + long deadline = System.nanoTime() + CLOSE_WAIT_NANOS; + WebSocketClient client; + Thread runner; + synchronized (this) { + if (shutdownRequested || collectPool.isShutdown()) { + return; } + stopping = true; + client = stopAdmission(); + runner = runnerThread; } - if (runnerThread != null) { - runnerThread.interrupt(); + try { + if (Objects.nonNull(client)) { + closeSession(client); + } + synchronized (this) { + long remaining = deadline - System.nanoTime(); + while (!collectTasks.isEmpty() && remaining > 0) { + TimeUnit.NANOSECONDS.timedWait(this, remaining); + remaining = deadline - System.nanoTime(); + } + } + awaitRunner(runner, deadline); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } finally { + synchronized (this) { + cancelOutstandingCollects(); + stopping = false; + } } } @Override public void close() { + long deadline = System.nanoTime() + CLOSE_WAIT_NANOS; + WebSocketClient client; Thread runner; synchronized (this) { if (collectPool.isShutdown()) { return; } - stop(); + client = stopAdmission(); + cancelOutstandingCollects(); collectPool.shutdownNow(); collectRequests.clear(); runner = runnerThread; } - long deadline = System.nanoTime() + CLOSE_WAIT_NANOS; + if (Objects.nonNull(client)) { + closeSession(client); + } try { - collectPool.awaitTermination(CLOSE_WAIT_NANOS, TimeUnit.NANOSECONDS); long remaining = deadline - System.nanoTime(); - if (remaining > 0 && Objects.nonNull(runner) && runner != Thread.currentThread()) { - TimeUnit.NANOSECONDS.timedJoin(runner, remaining); + if (remaining > 0) { + collectPool.awaitTermination(remaining, TimeUnit.NANOSECONDS); } + awaitRunner(runner, deadline); } catch (InterruptedException e) { Thread.currentThread().interrupt(); } } + // The caller holds this worker's monitor while invalidating admission and the queue. + private WebSocketClient stopAdmission() { + shutdownRequested = true; + admissionEpoch++; + WebSocketClient client = activeClient.getAndSet(null); + List pending = new ArrayList<>(); + collectPool.getQueue().drainTo(pending); + for (Runnable waiting : pending) { + finishCollect((CollectTask) waiting, null); + } + if (Objects.nonNull(runnerThread)) { + runnerThread.interrupt(); + } + return client; + } + + private void cancelOutstandingCollects() { + for (CollectTask task : collectTasks) { + task.cancellation.cancel(); + } + } + + private static void awaitRunner(Thread runner, long deadline) throws InterruptedException { + long remaining = deadline - System.nanoTime(); + if (remaining > 0 && Objects.nonNull(runner) && runner != Thread.currentThread()) { + TimeUnit.NANOSECONDS.timedJoin(runner, remaining); + } + } + private void runLoop() { int attempt = 0; while (!shutdownRequested) { @@ -379,42 +438,77 @@ private void admitCollect(WebSocketClient ws, Object centerIdentity, String requ throws Exception { OpenCliWsCollectRequests.Key key = new OpenCliWsCollectRequests.Key(centerIdentity, requestId); byte[] digest = MessageDigest.getInstance("SHA-256").digest(MAPPER.writeValueAsBytes(payload)); - OpenCliWsCollectRequests.Admission admission = collectRequests.reserve(key, digest); - switch (admission.status()) { - case IN_FLIGHT: - return; - case CONFLICT: - sendResult(ws, result(requestId, false, Collections.emptyList(), "worker request ID conflict")); - return; - case CACHED: - sendResult(ws, admission.cachedResult()); + OpenCliWsCollectRequests.Admission admission; + boolean busy = false; + synchronized (this) { + if (!isCurrentSession(ws)) { return; - case ACCEPTED: + } + admission = collectRequests.reserve(key, digest); + if (admission.status() == OpenCliWsCollectRequests.Status.ACCEPTED) { + CollectTask task = new CollectTask(ws, key, payload, admissionEpoch); + collectTasks.add(task); try { - collectPool.execute(() -> runCollectSafe(ws, key, payload)); + collectPool.execute(task); } catch (RejectedExecutionException e) { - collectRequests.complete(key, null); - sendResult(ws, result(requestId, false, Collections.emptyList(), "worker is busy")); + finishCollect(task, null); + busy = true; } - return; + } + } + if (!isCurrentSession(ws)) { + return; + } + if (busy) { + sendResult(ws, result(requestId, false, Collections.emptyList(), "worker is busy")); + } else if (admission.status() == OpenCliWsCollectRequests.Status.CONFLICT) { + sendResult(ws, result(requestId, false, Collections.emptyList(), "worker request ID conflict")); + } else if (admission.status() == OpenCliWsCollectRequests.Status.CACHED) { + sendResult(ws, admission.cachedResult()); } } - private void runCollectSafe(WebSocketClient ws, OpenCliWsCollectRequests.Key key, JsonNode msg) { - ObjectNode response = null; - try { - if (!collectPool.isShutdown() && !Thread.currentThread().isInterrupted()) { - response = executeCollect(key.requestId(), msg); - } - } finally { - collectRequests.complete(key, response); + private synchronized void finishCollect(CollectTask task, ObjectNode response) { + collectRequests.complete(task.key, response); + collectTasks.remove(task); + notifyAll(); + } + + private synchronized boolean mayStartCollect(long epoch) { + return !shutdownRequested && epoch == admissionEpoch && !Thread.currentThread().isInterrupted(); + } + + private final class CollectTask implements Runnable { + private final WebSocketClient socket; + private final OpenCliWsCollectRequests.Key key; + private final JsonNode message; + private final long epoch; + private final OpenCliCancellationToken cancellation = new OpenCliCancellationToken(); + + CollectTask(WebSocketClient socket, OpenCliWsCollectRequests.Key key, JsonNode message, long epoch) { + this.socket = socket; + this.key = key; + this.message = message; + this.epoch = epoch; } - if (Objects.nonNull(response) && isCurrentSession(ws) && ws.isOpen()) { - sendResult(ws, response); + + @Override + public void run() { + ObjectNode response = null; + try { + if (mayStartCollect(epoch)) { + response = executeCollect(key.requestId(), message, cancellation); + } + } finally { + finishCollect(this, response); + } + if (Objects.nonNull(response) && isCurrentSession(socket) && socket.isOpen()) { + sendResult(socket, response); + } } } - private ObjectNode executeCollect(String requestId, JsonNode msg) { + private ObjectNode executeCollect(String requestId, JsonNode msg, OpenCliCancellationToken cancellation) { try { String site = msg.path("site").asText(""); String command = msg.path("command").asText(""); @@ -424,7 +518,7 @@ private ObjectNode executeCollect(String requestId, JsonNode msg) { List argv = OpenCliCenterWsCollectToArgv.toArgv(site, command, positional, args, format); - OpenCliResult r = localExecutor.invoke(argv); + OpenCliResult r = localExecutor.invoke(argv, cancellation); List items = OpenCliWsCollectStdoutItems.parseItems(r.getStdout(), format); if (!r.isSuccess()) { return result(requestId, false, items, "opencli reported failure"); diff --git a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java index eff4e03..845e71e 100644 --- a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java +++ b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java @@ -260,6 +260,53 @@ void rejectsInvalidCapacityBeforeConnection(int workers, int pending) { () -> new OpenCliWsReverseAgentClient(new OpenCliProperties(), connection)); } + @Test + void restartableStopDropsQueuedCollectsAndCancelsPastDrainDeadline(@TempDir Path temporary) throws Exception { + Path release = temporary.resolve("stop-release"); + Path heartbeat = temporary.resolve("stop-heartbeat"); + Path queued = temporary.resolve("stop-queued"); + Path restarted = temporary.resolve("stop-restarted"); + try (LocalCenter center = new LocalCenter()) { + OpenCliWsAgentConnectionProperties connection = center.agentProperties(); + connection.setMaxConcurrentCollects(1); + connection.setMaxPendingCollects(1); + OpenCliProperties cli = probe(LifecycleProbe.class.getName()); + cli.setCommandTimeoutMillis(20_000L); + try (OpenCliWsReverseAgentClient agent = new OpenCliWsReverseAgentClient(cli, connection)) { + agent.start(); + WebSocket first = center.receive("register").socket; + first.send("{\"type\":\"registered\"}"); + try { + ObjectNode active = collect("active-stop", "heartbeat", heartbeat); + active.putArray("positional_args").add(release.toString()); + first.send(active.toString()); + assertTrue(awaitMarker(heartbeat, 3_000L), "first collect did not start"); + sendHeldCollect(first, "queued-stop", queued, release); + first.send("{\"type\":\"ping\"}"); + center.receive("pong"); + + long stopStarted = System.nanoTime(); + agent.stop(); + assertTrue(System.nanoTime() - stopStarted < TimeUnit.SECONDS.toNanos(7)); + assertFalse(awaitMarker(queued, 500L), "queued collect started after stop"); + byte[] before = Files.readAllBytes(heartbeat); + Thread.sleep(300L); + assertTrue(Arrays.equals(before, Files.readAllBytes(heartbeat)), "active collect kept running after stop"); + + agent.start(); + WebSocket second = center.receive("register").socket; + assertNotSame(first, second); + second.send("{\"type\":\"registered\"}"); + second.send(collect("queued-stop", "write", restarted).toString()); + assertTrue(center.receive("result").body.path("success").asBoolean()); + assertTrue(Files.exists(restarted)); + } finally { + Files.createFile(release); + } + } + } + } + @Test void closeDropsQueuedCollectsAndRejectsRestart(@TempDir Path temporary) throws Exception { Path release = temporary.resolve("release"); From b71db728248433dd925644dda4edcd08318faf2f Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:18:47 +0800 Subject: [PATCH 024/105] fix: bound and gate OpenCLI WebSocket ingress --- README.md | 2 + README.zh-CN.md | 2 + .../harden-opencli-reverse-agent/tasks.md | 10 +- .../OpenCliWsAgentConnectionProperties.java | 3 + .../ws/OpenCliWsReverseAgentClient.java | 166 ++++++++++-------- .../ws/OpenCliWsReverseAgentSessionTest.java | 69 +++++++- 6 files changed, 177 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 59fda97..fc8b8aa 100644 --- a/README.md +++ b/README.md @@ -226,6 +226,8 @@ Protocol: edge sends `register`; center replies `registered`; center sends `coll The reverse agent accepts up to four concurrent collect tasks and 32 queued tasks by default. Set `maxConcurrentCollects` and `maxPendingCollects` on the connection properties before constructing the agent to change the limits. A queue capacity of zero disables waiting. When full, the agent replies with a failed `result` and the error `worker is busy`. +The reverse agent accepts collect only after the current connection acknowledges registration. Incoming WebSocket messages are capped at 1 MiB by default, including the assembled size of fragments. Set `maxInboundMessageBytes` before constructing the agent to configure the finite byte limit. Oversized messages close the affected connection before any command is queued. + Collect request IDs must be nonblank strings of at most 128 UTF-8 bytes. The agent suppresses identical in-flight requests and rejects a reused ID with a different payload. An explicit retry may return a result marked `cached: true`. The in-memory cache keeps up to 1,024 completed results for at most ten minutes. Replay across reconnects requires the same TLS-verified endpoint. Plain WebSocket connections keep session-local deduplication. A new agent instance starts with an empty cache. `stop()` stops admission, discards queued tasks and allows in-flight work up to five seconds to finish before requesting cancellation. After the runner has stopped, `start()` can reconnect the same instance. `close()` immediately requests cancellation and closes the instance permanently. diff --git a/README.zh-CN.md b/README.zh-CN.md index 9a050c5..e7fefa3 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -225,6 +225,8 @@ agent.close(); 反向 Agent 默认最多同时执行 4 个 collect 任务,另有 32 个等待名额。构建 Agent 前,可在连接配置中设置 `maxConcurrentCollects` 和 `maxPendingCollects`。等待容量为零时直接拒绝超额请求。容量用尽时返回失败的 `result`,错误为 `worker is busy`。 +当前连接收到合法注册确认后,反向 Agent 才开始收单。入站 WebSocket 消息默认上限为 1 MiB,分片按聚合后的字节数计量。需要调整上限时,在创建 Agent 前设置有限的 `maxInboundMessageBytes`。超限消息会关闭对应连接,不会提交命令。 + collect 请求 ID 必须为非空白字符串,长度上限 128 个 UTF-8 字节。相同的在途请求只执行一次,同一个 ID 对应不同载荷时会明确拒绝。显式重试已完成的请求有可能收到标记为 `cached: true` 的结果。内存缓存最多保留 1,024 条完成结果,每条最长 10 分钟。跨连接重放要求使用同一个经过 TLS 校验的端点,明文 WebSocket 的去重范围为当前连接。创建新 Agent 实例时从空缓存开始。 `stop()` 停止接单并丢弃等待任务,为已在途任务保留最多 5 秒的收尾时间,随后请求取消。连接线程退出后,同一实例可再次调用 `start()` 重连。`close()` 立即请求取消,并永久关闭该实例。 diff --git a/openspec/changes/harden-opencli-reverse-agent/tasks.md b/openspec/changes/harden-opencli-reverse-agent/tasks.md index 37a1fc5..a9e30e7 100644 --- a/openspec/changes/harden-opencli-reverse-agent/tasks.md +++ b/openspec/changes/harden-opencli-reverse-agent/tasks.md @@ -11,7 +11,7 @@ ## 2. 治理实现 -- [ ] 2.1 建立显式状态机及 READY gate,接收线程仅做有界解析与准入。 +- [x] 2.1 建立显式状态机及 READY gate,接收线程仅做有界解析与准入。见本文入站验证。 - [ ] 2.2 用有限执行器替换 cached pool,加入容量校验和兼容 BUSY result。 - [ ] 2.3 实现 payload digest、在途记录与有界完成缓存;同 ID 不同载荷拒绝。 - [x] 2.4 实现连接代际与有界 drain/cancel,CLOSED 终态。见 OC-WS-006 验证。 @@ -43,3 +43,11 @@ 已启动任务保留去重占位到实际执行收尾。等待任务撤销时释放占位。重连使用原有固定线程池及其容量。终态 `close()` 仍立即取消在途工作,丢弃队列并在共用预算内等待资源回收,关闭后拒绝重启。 JDK 17 定向 28 项通过。JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,122 项通过,0 失败、0 错误、0 跳过。显式连接状态机和独立平台资源验收仍由 2.1 和 3.3 跟踪。 + +## 2026-11-19 OC-WS-001 入站状态与消息上限 + +每条连接的状态从 `CONNECTING` 经 `REGISTERING` 到 `READY`,退役为 `RETIRED`。只有当前连接收到单个 JSON 对象的合法注册确认后才接单。WebSocket 解码使用默认 1 MiB 的有限上限,覆盖单帧和分片聚合,可在创建 Agent 前配置。超限在 JSON 解析和任务入队前关闭该连接,后续重连需要重新注册。 + +JDK 17 定向红灯复现三项失败,退出 1。拼接 JSON 错误推进注册,超长单帧和分片均未关闭连接。修复后验证合法确认仍可接单,两个超限场景均关闭连接、没有 CLI 标记且重新注册。发送单个超长帧时,接收方可能在对端写完前关闭连接,对端可观察到 1006 或 1009。分片超限场景验证 1009。补充拒绝零、负数及库定义的无限哨兵设置。JDK 17 定向 34 项通过。 + +JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,128 项通过,0 失败、0 错误、0 跳过。 diff --git a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsAgentConnectionProperties.java b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsAgentConnectionProperties.java index 7aa4c9d..fc33cdd 100644 --- a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsAgentConnectionProperties.java +++ b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsAgentConnectionProperties.java @@ -65,6 +65,9 @@ public class OpenCliWsAgentConnectionProperties { /** 排队的 collect 任务上限,零表示没有等待队列。 */ private int maxPendingCollects = 32; + /** 单条入站 WebSocket 消息的 UTF-8 字节上限,包括分片聚合。 */ + private int maxInboundMessageBytes = 1024 * 1024; + /** * 首次 {@code registered} 应答等待上限(毫秒)。 */ diff --git a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java index 462cb11..6b7a8f8 100644 --- a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java +++ b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java @@ -1,6 +1,8 @@ package io.github.easy4j.opencli.center.ws; +import com.fasterxml.jackson.databind.DeserializationFeature; import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectReader; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ArrayNode; import com.fasterxml.jackson.databind.node.ObjectNode; @@ -32,6 +34,7 @@ import java.util.concurrent.atomic.AtomicReference; import lombok.extern.slf4j.Slf4j; import org.java_websocket.client.WebSocketClient; +import org.java_websocket.drafts.Draft_6455; import org.java_websocket.handshake.ServerHandshake; /** @@ -55,12 +58,14 @@ public final class OpenCliWsReverseAgentClient implements AutoCloseable { private static final ObjectMapper MAPPER = new ObjectMapper(); + private static final ObjectReader MESSAGE_READER = MAPPER.reader().with(DeserializationFeature.FAIL_ON_TRAILING_TOKENS); private static final long CLOSE_WAIT_NANOS = TimeUnit.SECONDS.toNanos(5); private final OpenCliExecutor localExecutor; private final OpenCliWsAgentConnectionProperties connectionProperties; + private final int maxInboundMessageBytes; private final ThreadPoolExecutor collectPool; private final Set collectTasks = new HashSet<>(); private final OpenCliWsCollectRequests collectRequests = @@ -83,6 +88,10 @@ public OpenCliWsReverseAgentClient( Objects.requireNonNull(openCliProperties, "openCliProperties"); this.connectionProperties = Objects.requireNonNull(connectionProperties, "connectionProperties"); + this.maxInboundMessageBytes = connectionProperties.getMaxInboundMessageBytes(); + if (maxInboundMessageBytes <= 0 || maxInboundMessageBytes == Integer.MAX_VALUE) { + throw new IllegalArgumentException("Inbound WebSocket message size must have a positive finite limit"); + } int workers = connectionProperties.getMaxConcurrentCollects(); int pending = connectionProperties.getMaxPendingCollects(); if (workers <= 0 || pending < 0 || (long) workers + pending >= Integer.MAX_VALUE) { @@ -250,64 +259,8 @@ private void runOneSession() throws Exception { // The default TLS client verifies the endpoint hostname. Plain WS has session-local identity. Object centerIdentity = "wss".equalsIgnoreCase(endpoint.getScheme()) ? endpoint : new Object(); - final CountDownLatch registered = new CountDownLatch(1); - final CountDownLatch sessionClosed = new CountDownLatch(1); - final AtomicReference handshakeFailure = new AtomicReference<>(); - log.info("opencli ws connecting"); - WebSocketClient client = - new WebSocketClient(endpoint) { - @Override - public void onOpen(ServerHandshake handshake) { - if (!isCurrentSession(this)) { - closeSession(this); - return; - } - try { - send(buildRegisterJson()); - } catch (Exception e) { - handshakeFailure.set(e); - registered.countDown(); - close(); - } - } - - @Override - public void onMessage(String message) { - try { - handleTextMessage(this, centerIdentity, message, registered, handshakeFailure); - } catch (Exception e) { - log.warn("handle ws message failed"); - } - } - - @Override - public void onClose(int code, String reason, boolean remote) { - activeClient.compareAndSet(this, null); - if (registered.getCount() > 0) { - handshakeFailure.compareAndSet( - null, - new IllegalStateException( - "WebSocket closed before 'registered' (code=" - + code - + ")")); - registered.countDown(); - } - sessionClosed.countDown(); - } - - @Override - public void onError(Exception ex) { - activeClient.compareAndSet(this, null); - log.warn("WebSocket error"); - if (registered.getCount() > 0) { - handshakeFailure.compareAndSet(null, ex); - registered.countDown(); - } - sessionClosed.countDown(); - } - }; - + WorkerSession client = new WorkerSession(endpoint, centerIdentity); if (!publishSession(client)) { return; } @@ -315,23 +268,94 @@ public void onError(Exception ex) { if (!client.connectBlocking(30, TimeUnit.SECONDS)) { throw new IllegalStateException("WebSocket connectBlocking returned false"); } - if (!registered.await(connectionProperties.getHandshakeTimeoutMillis(), TimeUnit.MILLISECONDS)) { + if (!client.registered.await(connectionProperties.getHandshakeTimeoutMillis(), TimeUnit.MILLISECONDS)) { throw new IllegalStateException("Timeout waiting for 'registered' from center"); } - Throwable hf = handshakeFailure.get(); + Throwable hf = client.handshakeFailure.get(); if (Objects.nonNull(hf)) { if (hf instanceof Exception) { throw (Exception) hf; } throw new IllegalStateException(hf); } - sessionClosed.await(); + client.sessionClosed.await(); } finally { - activeClient.compareAndSet(client, null); + client.retire(null); closeSession(client); } } + private enum SessionPhase { + CONNECTING, REGISTERING, READY, RETIRED + } + + private final class WorkerSession extends WebSocketClient { + private final Object centerIdentity; + private final AtomicReference phase = new AtomicReference<>(SessionPhase.CONNECTING); + private final CountDownLatch registered = new CountDownLatch(1); + private final CountDownLatch sessionClosed = new CountDownLatch(1); + private final AtomicReference handshakeFailure = new AtomicReference<>(); + + WorkerSession(URI endpoint, Object centerIdentity) { + super(endpoint, new Draft_6455(Collections.emptyList(), maxInboundMessageBytes)); + this.centerIdentity = centerIdentity; + } + + @Override + public void onOpen(ServerHandshake handshake) { + if (!isCurrentSession(this) || !phase.compareAndSet(SessionPhase.CONNECTING, SessionPhase.REGISTERING)) { + closeSession(this); + return; + } + try { + send(buildRegisterJson()); + } catch (Exception e) { + retire(e); + closeSession(this); + } + } + + @Override + public void onMessage(String message) { + try { + handleTextMessage(this, message); + } catch (Exception e) { + log.warn("handle ws message failed"); + } + } + + @Override + public void onClose(int code, String reason, boolean remote) { + retire(new IllegalStateException("WebSocket closed before 'registered' (code=" + code + ")")); + } + + @Override + public void onError(Exception ex) { + log.warn("WebSocket error"); + retire(ex); + } + + void acknowledgeRegistration() { + if (phase.compareAndSet(SessionPhase.REGISTERING, SessionPhase.READY)) { + registered.countDown(); + } + } + + boolean isReady() { + return phase.get() == SessionPhase.READY; + } + + void retire(Throwable cause) { + SessionPhase previous = phase.getAndSet(SessionPhase.RETIRED); + activeClient.compareAndSet(this, null); + if (previous == SessionPhase.CONNECTING || previous == SessionPhase.REGISTERING) { + handshakeFailure.compareAndSet(null, cause); + registered.countDown(); + } + sessionClosed.countDown(); + } + } + private synchronized boolean publishSession(WebSocketClient client) { if (shutdownRequested) { return false; @@ -395,20 +419,17 @@ private String buildRegisterJson() throws Exception { return MAPPER.writeValueAsString(reg); } - private void handleTextMessage( - WebSocketClient ws, - Object centerIdentity, - String payload, - CountDownLatch registered, - AtomicReference handshakeFailure) - throws Exception { + private void handleTextMessage(WorkerSession ws, String payload) throws Exception { if (!isCurrentSession(ws)) { return; } - JsonNode root = MAPPER.readTree(payload); + JsonNode root = MESSAGE_READER.readTree(payload); + if (Objects.isNull(root) || !root.isObject()) { + return; + } String type = root.path("type").asText(""); if ("registered".equals(type)) { - registered.countDown(); + ws.acknowledgeRegistration(); return; } if ("ping".equals(type)) { @@ -425,12 +446,11 @@ private void handleTextMessage( sendResult(ws, result("", false, Collections.emptyList(), "invalid worker request ID")); return; } - if (!isCurrentSession(ws) || !ws.isOpen() || registered.getCount() > 0 - || Objects.nonNull(handshakeFailure.get())) { + if (!isCurrentSession(ws) || !ws.isOpen() || !ws.isReady()) { sendResult(ws, result(requestId, false, Collections.emptyList(), "worker is not registered")); return; } - admitCollect(ws, centerIdentity, requestId, root); + admitCollect(ws, ws.centerIdentity, requestId, root); } } diff --git a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java index 845e71e..d9e255e 100644 --- a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java +++ b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java @@ -10,6 +10,7 @@ import java.io.IOException; import java.io.InputStream; import java.net.InetSocketAddress; +import java.nio.ByteBuffer; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; @@ -32,6 +33,7 @@ import javax.net.ssl.SSLContext; import javax.net.ssl.TrustManagerFactory; import org.java_websocket.WebSocket; +import org.java_websocket.enums.Opcode; import org.java_websocket.handshake.ClientHandshake; import org.java_websocket.server.DefaultSSLWebSocketServerFactory; import org.java_websocket.server.WebSocketServer; @@ -168,6 +170,68 @@ void collectBeforeRegistrationAcknowledgementDoesNotStartChild(@TempDir Path tem } } + @Test + void trailingJsonCannotAcknowledgeRegistration(@TempDir Path temporary) throws Exception { + Path rejectedMarker = temporary.resolve("invalid-ack-child"); + Path readyMarker = temporary.resolve("ready-child"); + try (LocalCenter center = new LocalCenter(); + OpenCliWsReverseAgentClient agent = new OpenCliWsReverseAgentClient( + probe(LifecycleProbe.class.getName()), center.agentProperties())) { + agent.start(); + WebSocket socket = center.receive("register").socket; + socket.send("{\"type\":\"registered\"} {\"type\":\"ping\"}"); + socket.send(collect("invalid-ack", "write", rejectedMarker).toString()); + JsonNode rejected = center.receive("result").body; + assertFalse(rejected.path("success").asBoolean(), "malformed acknowledgement enabled collection"); + assertFalse(Files.exists(rejectedMarker)); + + socket.send("{\"type\":\"registered\"}"); + socket.send(collect("valid-ack", "write", readyMarker).toString()); + assertTrue(center.receive("result").body.path("success").asBoolean()); + assertTrue(Files.exists(readyMarker)); + } + } + + @ParameterizedTest + @ValueSource(booleans = {false, true}) + void oversizedMessageRetiresGenerationBeforeCollect(boolean fragmented, @TempDir Path temporary) throws Exception { + Path marker = temporary.resolve("oversized-child"); + char[] padding = new char[1024 * 1024]; + Arrays.fill(padding, 'x'); + byte[] bytes = collect("oversized", "write", marker).put("fixture", new String(padding)) + .toString().getBytes(StandardCharsets.UTF_8); + try (LocalCenter center = new LocalCenter(); + OpenCliWsReverseAgentClient agent = new OpenCliWsReverseAgentClient( + probe(LifecycleProbe.class.getName()), center.agentProperties())) { + agent.start(); + WebSocket socket = center.receive("register").socket; + socket.send("{\"type\":\"registered\"}"); + if (fragmented) { + int midpoint = bytes.length / 2; + socket.sendFragmentedFrame(Opcode.TEXT, ByteBuffer.wrap(bytes, 0, midpoint).slice(), false); + socket.sendFragmentedFrame(Opcode.TEXT, + ByteBuffer.wrap(bytes, midpoint, bytes.length - midpoint).slice(), true); + } else { + socket.send(new String(bytes, StandardCharsets.UTF_8)); + } + Integer code = center.closeCodes.poll(3, TimeUnit.SECONDS); + // Rejecting a complete frame from its header can reset the peer's still-active write. + assertTrue(Integer.valueOf(1009).equals(code) || (!fragmented && Integer.valueOf(1006).equals(code)), + "oversized message should close the socket, observed code=" + code); + assertFalse(Files.exists(marker), "oversized request started a child"); + assertNotSame(socket, center.receive("register").socket); + } + } + + @ParameterizedTest + @ValueSource(ints = {0, -1, Integer.MAX_VALUE}) + void rejectsUnboundedInboundLimitBeforeConnection(int limit) { + OpenCliWsAgentConnectionProperties connection = new OpenCliWsAgentConnectionProperties(); + connection.setMaxInboundMessageBytes(limit); + assertThrows(IllegalArgumentException.class, () -> new OpenCliWsReverseAgentClient( + probe(LifecycleProbe.class.getName()), connection)); + } + @Test void defaultsToFourActiveCollects(@TempDir Path temporary) throws Exception { Path release = temporary.resolve("release"); @@ -553,6 +617,7 @@ private WireMessage(WebSocket socket, JsonNode body) { private static final class LocalCenter extends WebSocketServer implements AutoCloseable { private final CountDownLatch started = new CountDownLatch(1); private final BlockingQueue messages = new LinkedBlockingQueue<>(); + private final BlockingQueue closeCodes = new LinkedBlockingQueue<>(); private final AtomicReference failure = new AtomicReference<>(); private final boolean secure; @@ -596,7 +661,9 @@ private WireMessage receive(String type) throws InterruptedException { public void onOpen(WebSocket socket, ClientHandshake handshake) { } @Override - public void onClose(WebSocket socket, int code, String reason, boolean remote) { } + public void onClose(WebSocket socket, int code, String reason, boolean remote) { + closeCodes.add(code); + } @Override public void onMessage(WebSocket socket, String payload) { From b4b6f817f4414be7eaf76a6db51c283a58adb35b Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:26:14 +0800 Subject: [PATCH 025/105] fix: reconnect OpenCLI worker after failed result delivery --- .../harden-opencli-reverse-agent/tasks.md | 10 ++- .../ws/OpenCliWsReverseAgentClient.java | 20 ++++-- .../ws/OpenCliWsReverseAgentSessionTest.java | 68 +++++++++++++++++-- 3 files changed, 87 insertions(+), 11 deletions(-) diff --git a/openspec/changes/harden-opencli-reverse-agent/tasks.md b/openspec/changes/harden-opencli-reverse-agent/tasks.md index a9e30e7..6f8d925 100644 --- a/openspec/changes/harden-opencli-reverse-agent/tasks.md +++ b/openspec/changes/harden-opencli-reverse-agent/tasks.md @@ -18,8 +18,8 @@ ## 3. 兼容与验收 -- [ ] 3.1 证明重连不自动重复写入,完成发送失败不被误标为执行失败。 -- [ ] 3.2 验证现有消息结构在 legacy fixture 中不变,安全日志符合 C09。 +- [x] 3.1 证明重连不自动重复写入,完成发送失败不被误标为执行失败。 +- [x] 3.2 验证现有消息结构在 legacy fixture 中不变,安全日志符合 C09。 - [ ] 3.3 分别在三线运行 WS压力/断线fixture,记录执行次数、线程数与终结资源结果。 ## 证据交付模板(实施时填写) @@ -51,3 +51,9 @@ JDK 17 定向 28 项通过。JDK 8 使用系统 Maven 执行 `-B -ntp -o clean v JDK 17 定向红灯复现三项失败,退出 1。拼接 JSON 错误推进注册,超长单帧和分片均未关闭连接。修复后验证合法确认仍可接单,两个超限场景均关闭连接、没有 CLI 标记且重新注册。发送单个超长帧时,接收方可能在对端写完前关闭连接,对端可观察到 1006 或 1009。分片超限场景验证 1009。补充拒绝零、负数及库定义的无限哨兵设置。JDK 17 定向 34 项通过。 JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,128 项通过,0 失败、0 错误、0 跳过。 + +## 2026-11-19 OC-WS-005 投递失败和旧协议兼容 + +在 TLS 回环环境向第一次结果发送注入异常,CLI 子进程实际写入执行标记。修复前中心等待第二次注册超时,定向 2 项中 1 项失败,退出 1。修复后失败连接退役。第二条连接完成注册和心跳时,中心仍未收到自动投递。中心显式重发相同请求后,收到原成功结果和 `cached: true`,`error` 为空,实际子进程标记始终为一条。日志捕获包含固定的投递失败消息,异常内测试密钥未出现在日志中。 + +旧协议夹具继续核对 register 的五个字段、pong 的单字段、成功与失败 result 的五个字段,以及实际进程收到的完整 argv。三个版本的直接字段断言通过。JDK 17 定向 35 项通过。JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,129 项通过,0 失败、0 错误、0 跳过。全量通过后单独复跑加严的旧协议字段断言,1 项通过。此处的诊断结论覆盖反向 Worker,跨传输隐私仍由 C09 跟踪。 diff --git a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java index 6b7a8f8..f055f54 100644 --- a/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java +++ b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java @@ -32,6 +32,7 @@ import java.util.concurrent.ThreadPoolExecutor; import java.util.concurrent.TimeUnit; import java.util.concurrent.atomic.AtomicReference; +import java.util.function.BiConsumer; import lombok.extern.slf4j.Slf4j; import org.java_websocket.client.WebSocketClient; import org.java_websocket.drafts.Draft_6455; @@ -62,6 +63,7 @@ public final class OpenCliWsReverseAgentClient implements AutoCloseable { private static final long CLOSE_WAIT_NANOS = TimeUnit.SECONDS.toNanos(5); private final OpenCliExecutor localExecutor; + private final BiConsumer resultSender; private final OpenCliWsAgentConnectionProperties connectionProperties; @@ -85,6 +87,12 @@ public final class OpenCliWsReverseAgentClient implements AutoCloseable { */ public OpenCliWsReverseAgentClient( OpenCliProperties openCliProperties, OpenCliWsAgentConnectionProperties connectionProperties) { + this(openCliProperties, connectionProperties, WebSocketClient::send); + } + + OpenCliWsReverseAgentClient(OpenCliProperties openCliProperties, + OpenCliWsAgentConnectionProperties connectionProperties, BiConsumer resultSender) { + this.resultSender = Objects.requireNonNull(resultSender, "resultSender"); Objects.requireNonNull(openCliProperties, "openCliProperties"); this.connectionProperties = Objects.requireNonNull(connectionProperties, "connectionProperties"); @@ -454,7 +462,7 @@ private void handleTextMessage(WorkerSession ws, String payload) throws Exceptio } } - private void admitCollect(WebSocketClient ws, Object centerIdentity, String requestId, JsonNode payload) + private void admitCollect(WorkerSession ws, Object centerIdentity, String requestId, JsonNode payload) throws Exception { OpenCliWsCollectRequests.Key key = new OpenCliWsCollectRequests.Key(centerIdentity, requestId); byte[] digest = MessageDigest.getInstance("SHA-256").digest(MAPPER.writeValueAsBytes(payload)); @@ -499,13 +507,13 @@ private synchronized boolean mayStartCollect(long epoch) { } private final class CollectTask implements Runnable { - private final WebSocketClient socket; + private final WorkerSession socket; private final OpenCliWsCollectRequests.Key key; private final JsonNode message; private final long epoch; private final OpenCliCancellationToken cancellation = new OpenCliCancellationToken(); - CollectTask(WebSocketClient socket, OpenCliWsCollectRequests.Key key, JsonNode message, long epoch) { + CollectTask(WorkerSession socket, OpenCliWsCollectRequests.Key key, JsonNode message, long epoch) { this.socket = socket; this.key = key; this.message = message; @@ -620,11 +628,13 @@ private static ObjectNode result(String requestId, boolean success, List { + if (firstSend.getAndSet(false)) { + throw new IllegalStateException(canary); + } + socket.send(json); + }); + PrintStream capture = new PrintStream(diagnostics, true, "UTF-8")) { + System.setErr(capture); + try { + agent.start(); + WebSocket first = center.receive("register").socket; + first.send("{\"type\":\"registered\"}"); + first.send(request.toString()); + + WebSocket second = center.receive("register").socket; + assertNotSame(first, second); + second.send("{\"type\":\"registered\"}"); + second.send("{\"type\":\"ping\"}"); + center.receive("pong"); + assertEquals(Arrays.asList("started"), Files.readAllLines(marker, StandardCharsets.UTF_8)); + + second.send(request.toString()); + JsonNode replayed = center.receive("result").body; + assertEquals("delivery", replayed.path("request_id").asText()); + assertTrue(replayed.path("success").asBoolean()); + assertTrue(replayed.path("cached").asBoolean()); + assertTrue(replayed.path("error").isNull()); + assertEquals(Arrays.asList("started"), Files.readAllLines(marker, StandardCharsets.UTF_8)); + } finally { + System.setErr(previousErr); + } + } + String logText = diagnostics.toString(StandardCharsets.UTF_8.name()); + assertTrue(logText.contains("failed to send WS result")); + assertFalse(logText.contains(canary)); + } + private static void verifyReconnectReplay(Path temporary, SSLContext tls, boolean expectCache) throws Exception { Path marker = temporary.resolve("reconnect-start"); Path release = temporary.resolve("reconnect-release"); From 47c2009d57e76fd95ad7fcbfe5e46c490bd04051 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:31:38 +0800 Subject: [PATCH 026/105] test: verify OpenCLI worker resources across disconnect and close --- .../harden-opencli-reverse-agent/tasks.md | 10 ++- .../ws/OpenCliWsReverseAgentSessionTest.java | 78 +++++++++++++++++++ .../opencli/contract/LifecycleProbe.java | 6 +- 3 files changed, 92 insertions(+), 2 deletions(-) diff --git a/openspec/changes/harden-opencli-reverse-agent/tasks.md b/openspec/changes/harden-opencli-reverse-agent/tasks.md index 6f8d925..837a7cb 100644 --- a/openspec/changes/harden-opencli-reverse-agent/tasks.md +++ b/openspec/changes/harden-opencli-reverse-agent/tasks.md @@ -20,7 +20,7 @@ - [x] 3.1 证明重连不自动重复写入,完成发送失败不被误标为执行失败。 - [x] 3.2 验证现有消息结构在 legacy fixture 中不变,安全日志符合 C09。 -- [ ] 3.3 分别在三线运行 WS压力/断线fixture,记录执行次数、线程数与终结资源结果。 +- [x] 3.3 分别在三线运行 WS压力/断线fixture,记录执行次数、线程数与终结资源结果。 ## 证据交付模板(实施时填写) @@ -57,3 +57,11 @@ JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,128 项通过,0 在 TLS 回环环境向第一次结果发送注入异常,CLI 子进程实际写入执行标记。修复前中心等待第二次注册超时,定向 2 项中 1 项失败,退出 1。修复后失败连接退役。第二条连接完成注册和心跳时,中心仍未收到自动投递。中心显式重发相同请求后,收到原成功结果和 `cached: true`,`error` 为空,实际子进程标记始终为一条。日志捕获包含固定的投递失败消息,异常内测试密钥未出现在日志中。 旧协议夹具继续核对 register 的五个字段、pong 的单字段、成功与失败 result 的五个字段,以及实际进程收到的完整 argv。三个版本的直接字段断言通过。JDK 17 定向 35 项通过。JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,129 项通过,0 失败、0 错误、0 跳过。全量通过后单独复跑加严的旧协议字段断言,1 项通过。此处的诊断结论覆盖反向 Worker,跨传输隐私仍由 C09 跟踪。 + +## 2026-11-19 C05 压力、断线与资源收尾 + +`disconnectAndCloseReleaseBoundedWorkerResources` 通过回环 WS 中心启动两个持续心跳的真实 CLI 子进程,排队一项并拒绝一项超额请求,随后断开旧连接并重新注册。重连后,每项有效命令仍只执行一次,排队和超额请求均没有启动标记。观测到 2 个收单线程、1 个连接发起线程、2 个 stdout 与 2 个 stderr 读取线程。计数以场景前 JVM 线程集合为基线。 + +终态关闭后,上述线程和 SDK 的终止工作线程新增数回到零,两个真实子进程的心跳停止,执行标记仍为两条。Surefire 报告保留 `C05 resources: started=2 workerThreads=2 runnerThreads=1 readers=4 threadsAfterClose=0`。该计数覆盖 SDK 自有线程,回环中心和 Java-WebSocket 内部线程由各自生命周期管理。 + +JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,130 项通过,0 失败、0 错误、0 跳过。三条线在本地 macOS 得到相同观测。最新托管平台结果单独记录于 PR。 diff --git a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java index a66e2a5..4f308ce 100644 --- a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java +++ b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java @@ -239,6 +239,84 @@ void rejectsUnboundedInboundLimitBeforeConnection(int limit) { probe(LifecycleProbe.class.getName()), connection)); } + @Test + void disconnectAndCloseReleaseBoundedWorkerResources(@TempDir Path temporary) throws Exception { + Set baseline = Thread.getAllStackTraces().keySet(); + Path gate = temporary.resolve("resource-release"); + Path queued = temporary.resolve("resource-queued"); + Path overflow = temporary.resolve("resource-overflow"); + List pulses = Arrays.asList(temporary.resolve("heartbeat-0"), temporary.resolve("heartbeat-1")); + List starts = Arrays.asList(temporary.resolve("start-0"), temporary.resolve("start-1")); + try (LocalCenter center = new LocalCenter()) { + OpenCliWsAgentConnectionProperties connection = center.agentProperties(); + connection.setMaxConcurrentCollects(2); + connection.setMaxPendingCollects(1); + OpenCliProperties cli = probe(LifecycleProbe.class.getName()); + cli.setCommandTimeoutMillis(20_000L); + try (OpenCliWsReverseAgentClient agent = new OpenCliWsReverseAgentClient(cli, connection)) { + agent.start(); + WebSocket first = center.receive("register").socket; + first.send("{\"type\":\"registered\"}"); + try { + for (int index = 0; index < pulses.size(); index++) { + ObjectNode payload = collect("resource-" + index, "heartbeat-log", pulses.get(index)); + payload.putArray("positional_args").add(gate.toString()).add(starts.get(index).toString()); + first.send(payload.toString()); + assertTrue(awaitMarker(pulses.get(index), 5_000L)); + } + first.send(collect("queued-resource", "write", queued).toString()); + first.send(collect("overflow-resource", "write", overflow).toString()); + JsonNode rejected = center.receive("result").body; + assertEquals("overflow-resource", rejected.path("request_id").asText()); + assertEquals("worker is busy", rejected.path("error").asText()); + assertFalse(Files.exists(queued)); + assertFalse(Files.exists(overflow)); + + first.close(); + WebSocket second = center.receive("register").socket; + assertNotSame(first, second); + second.send("{\"type\":\"registered\"}"); + second.send("{\"type\":\"ping\"}"); + center.receive("pong"); + + Set running = workerThreadsSince(baseline); + assertEquals(2, running.stream().filter(t -> "opencli-ws-collect".equals(t.getName())).count()); + assertEquals(1, running.stream().filter(t -> "opencli-ws-agent-runner".equals(t.getName())).count()); + assertEquals(2, running.stream().filter(t -> "opencli-stdout".equals(t.getName())).count()); + assertEquals(2, running.stream().filter(t -> "opencli-stderr".equals(t.getName())).count()); + + agent.close(); + long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(2L); + while (!workerThreadsSince(baseline).isEmpty() && System.nanoTime() < deadline) { + Thread.sleep(20L); + } + assertTrue(workerThreadsSince(baseline).isEmpty(), "worker threads survived close"); + byte[] firstPulse = Files.readAllBytes(pulses.get(0)); + byte[] secondPulse = Files.readAllBytes(pulses.get(1)); + Thread.sleep(300L); + assertTrue(Arrays.equals(firstPulse, Files.readAllBytes(pulses.get(0)))); + assertTrue(Arrays.equals(secondPulse, Files.readAllBytes(pulses.get(1)))); + for (Path started : starts) { + assertEquals(Arrays.asList("started"), Files.readAllLines(started, StandardCharsets.UTF_8)); + } + assertFalse(Files.exists(queued)); + assertFalse(Files.exists(overflow)); + System.out.println("C05 resources: started=2 workerThreads=2 runnerThreads=1 readers=4 threadsAfterClose=0"); + } finally { + Files.createFile(gate); + } + } + } + } + + private static Set workerThreadsSince(Set baseline) { + List names = Arrays.asList("opencli-ws-collect", "opencli-ws-agent-runner", + "opencli-stdout", "opencli-stderr", "opencli-stop", "opencli-force-stop"); + return Thread.getAllStackTraces().keySet().stream() + .filter(thread -> !baseline.contains(thread) && names.contains(thread.getName())) + .collect(Collectors.toSet()); + } + @Test void defaultsToFourActiveCollects(@TempDir Path temporary) throws Exception { Path release = temporary.resolve("release"); diff --git a/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java index 3ed062b..0b2bc3b 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java +++ b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java @@ -41,6 +41,10 @@ public static void main(String[] args) throws Exception { writeStream(System.out, Integer.parseInt(args[3])); writeStream(System.err, Integer.parseInt(args[4])); } + if ("heartbeat-log".equals(mode)) { + Files.write(Paths.get(args[3]), "started\n".getBytes(StandardCharsets.UTF_8), + StandardOpenOption.CREATE, StandardOpenOption.APPEND); + } Path marker = Paths.get(args[1]); if ("count-hold".equals(mode)) { Files.write(marker, "started\n".getBytes(StandardCharsets.UTF_8), @@ -53,7 +57,7 @@ public static void main(String[] args) throws Exception { long start = System.nanoTime(); int tick = 0; while (!Files.exists(release) && System.nanoTime() - start < 10_000_000_000L) { - if ("heartbeat".equals(mode)) { + if ("heartbeat".equals(mode) || "heartbeat-log".equals(mode)) { Files.write(marker, Integer.toString(++tick).getBytes(StandardCharsets.UTF_8)); } Thread.sleep(20L); From 0c6150678f4aec99887717700f44eb9bc89ed00e Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:39:17 +0800 Subject: [PATCH 027/105] fix: keep private data out of OpenCLI exception diagnostics --- README.md | 2 ++ README.zh-CN.md | 2 ++ .../tasks.md | 20 ++++++++++++--- .../opencli/core/OpenCliArgSupport.java | 7 +++++- .../support/SubprocessExecutionSupport.java | 3 ++- .../opencli/core/OpenCliArgSupportTest.java | 25 +++++++++++++++++++ .../core/OpenCliProcessPrivacyTest.java | 25 +++++++++++++++++++ .../SubprocessExecutionSupportTest.java | 24 ++++++++++++++++++ src/test/resources/simplelogger.properties | 1 + 9 files changed, 104 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index fc8b8aa..fa5dec0 100644 --- a/README.md +++ b/README.md @@ -238,6 +238,8 @@ Call `OpenCliDiagnosticExport.export(result, 512)` explicitly with an `OpenCliRe The SDK returns the text in memory. Your application controls the destination and retention. SDK diagnostics omit argv values, raw content, URLs and filesystem paths. Applications that use or log raw results should protect that data. `remoteCaptureRawHttpResponse` is still opt-in. +At the low-level process boundary, `RunSession.getHandler().getException()` returns a safe I/O summary. `RunSession.getIoFailure()` is the explicit raw diagnostic accessor. Handle that exception as sensitive data because it can include local paths. + ## 9. Testing & Build diff --git a/README.zh-CN.md b/README.zh-CN.md index e7fefa3..2b21679 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -237,6 +237,8 @@ collect 请求 ID 必须为非空白字符串,长度上限 128 个 UTF-8 字 SDK 在内存中返回文本,由应用决定目的地和保留时间。SDK 诊断会排除命令参数、原始内容、URL 和文件路径。应用读取或记录原始结果时应自行保护这些数据。`remoteCaptureRawHttpResponse` 仍需显式开启。 +低层进程接口的 `RunSession.getHandler().getException()` 返回安全的 I/O 摘要。`RunSession.getIoFailure()` 是显式读取原始诊断的入口,异常可能包含本地路径,应按敏感数据处理。 + ## 9. 测试与构建 diff --git a/openspec/changes/harden-opencli-diagnostics-privacy/tasks.md b/openspec/changes/harden-opencli-diagnostics-privacy/tasks.md index 2f95b95..71c2eda 100644 --- a/openspec/changes/harden-opencli-diagnostics-privacy/tasks.md +++ b/openspec/changes/harden-opencli-diagnostics-privacy/tasks.md @@ -7,7 +7,7 @@ ## 1. 泄露负例 - [ ] 1.1 对Executor、AdapterChannel、HTTP、WS、JSON/YAML parser所有日志/异常点建立canary矩阵。 -- [ ] 1.2 新增完整日志捕获与nested cause测试,先证明当前泄露可被测试检测。 +- [x] 1.2 新增完整日志捕获与nested cause测试,先证明当前泄露可被测试检测。 ## 2. 安全投影 @@ -17,10 +17,24 @@ ## 3. 验证 -- [ ] 3.1 覆盖DEBUG、timeout、malformedresponse、断线和超限路径,任何canary出现均失败。 +- [x] 3.1 覆盖DEBUG、timeout、malformedresponse、断线和超限路径,任何canary出现均失败。 - [ ] 3.2 验证raw结果内容未被脱敏逻辑无声修改。 -- [ ] 3.3 三线执行相同隐私矩阵并记录证据;文档标明SDK与应用日志责任边界。 +- [x] 3.3 三线执行相同隐私矩阵并记录证据;文档标明SDK与应用日志责任边界。 ## 证据交付模板(实施时填写) 每项任务的完成记录包含:Requirement/Scenario、分支HEAD、测试命令、失败→通过证据、测试数/跳过数、退出码、报告位置。没有记录的任务保持未完成。 + +## 2026-11-19 C09 默认异常链与三线隐私矩阵 + +JDK 17 两项定向红灯实际退出 1。选项对象的 `toString()` 抛出带嵌套 cause 和 suppressed 项的异常,栈文本泄露测试密钥。真实缺失可执行文件的低层 result handler 异常链泄露路径。修复后,值转换报告固定字段诊断,result handler 保留安全摘要。显式 `RunSession.getIoFailure()` 仍返回原始低层诊断。两项回归都扫描完整栈文本,保留原始数据的测试同时验证权限边界。 + +| 场景 | 现有三线回归 | +| --- | --- | +| Adapter DEBUG、本地非零退出、超时、超限、原始 stdout/stderr | `OpenCliProcessPrivacyTest` | +| 参数对象的嵌套 cause/suppressed、底层原生路径 | `OpenCliArgSupportTest`、`SubprocessExecutionSupportTest` | +| HTTP 503、凭据 URL、畸形 JSON、原文捕获开关 | `OpenCliRemoteAgentHttpClientTest` | +| WebSocket 断线和投递异常、配置 URL、日志测试密钥 | `OpenCliWsReverseAgentSessionTest`、`OpenCliWsReverseAgentClientTest` | +| JSON 解析 DEBUG、默认不写入的有界导出 | `OpenCliStdoutJsonTest`、`OpenCliDiagnosticExportTest` | + +JDK 8 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,133 项通过,0 失败、0 错误、0 跳过。中英文 README 记录应用显式访问原始低层诊断的责任。C03 的 YAML 解码器仍待实施,对其解析日志的验证保留在后续矩阵中。 diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliArgSupport.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliArgSupport.java index 9531dbc..b0ea0f6 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliArgSupport.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliArgSupport.java @@ -97,7 +97,12 @@ public static void addOptionPairIfPresent(List target, String flag, Obje } static String stringValue(Object value, String field) { - String text = String.valueOf(value); + String text; + try { + text = String.valueOf(value); + } catch (RuntimeException ex) { + throw new IllegalArgumentException(field + " cannot be converted to a string"); + } if (Objects.isNull(text)) { throw new IllegalArgumentException(field + " string form must not be null"); } diff --git a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java index 40ee072..f30e628 100644 --- a/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java +++ b/src/main/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupport.java @@ -274,7 +274,7 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup } DefaultExecuteResultHandler handler = new DefaultExecuteResultHandler(); if (ioFailure != null) { - handler.onProcessFailed(new ExecuteException("Native process I/O failure", exit == null ? -1 : exit, ioFailure)); + handler.onProcessFailed(new ExecuteException("Native process I/O failure", exit == null ? -1 : exit)); } else if (exit != null && exit != 0) { handler.onProcessFailed(new ExecuteException("Native process returned nonzero status", exit)); } else if (exit != null) { @@ -567,6 +567,7 @@ public static final class RunSession { private final boolean waitTimedOut; private final OpenCliExecutionDetails executionDetails; private final Integer observedExitCode; + /** Raw low-level I/O evidence, which can include local paths. Exclude it from default diagnostics. */ private final IOException ioFailure; RunSession(ByteArrayOutputStream stdout, ByteArrayOutputStream stderr, diff --git a/src/test/java/io/github/easy4j/opencli/core/OpenCliArgSupportTest.java b/src/test/java/io/github/easy4j/opencli/core/OpenCliArgSupportTest.java index 20f0abc..3f41153 100644 --- a/src/test/java/io/github/easy4j/opencli/core/OpenCliArgSupportTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/OpenCliArgSupportTest.java @@ -1,5 +1,7 @@ package io.github.easy4j.opencli.core; +import java.io.PrintWriter; +import java.io.StringWriter; import static org.junit.jupiter.api.Assertions.*; import java.util.ArrayList; import java.util.Arrays; @@ -107,6 +109,29 @@ public String toString() { assertTrue(target.isEmpty()); } + @Test + void shouldKeepConversionExceptionAndNestedCausePrivate() { + List target = new ArrayList<>(); + String canary = "private-conversion-" + UUID.randomUUID(); + Object value = new Object() { + @Override + public String toString() { + IllegalArgumentException failure = new IllegalArgumentException("conversion failed", + new IllegalStateException(canary)); + failure.addSuppressed(new IllegalStateException(canary)); + throw failure; + } + }; + + IllegalArgumentException failure = assertThrows(IllegalArgumentException.class, + () -> OpenCliArgSupport.addOptionPairIfPresent(target, "--flag", value)); + StringWriter diagnostics = new StringWriter(); + failure.printStackTrace(new PrintWriter(diagnostics)); + assertFalse(diagnostics.toString().contains(canary)); + assertTrue(failure.getMessage().contains("value")); + assertTrue(target.isEmpty()); + } + @Test void shouldAddFlagIfTrue() { List target = new ArrayList<>(); diff --git a/src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java b/src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java index 03c9515..fbcd40e 100644 --- a/src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java @@ -1,5 +1,6 @@ package io.github.easy4j.opencli.core; +import org.junit.jupiter.api.parallel.Isolated; import io.github.easy4j.opencli.OpenCliProperties; import io.github.easy4j.opencli.contract.LifecycleProbe; import io.github.easy4j.opencli.exception.OpenCliException; @@ -22,6 +23,7 @@ import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; +@Isolated class OpenCliProcessPrivacyTest { @Test @@ -46,6 +48,29 @@ void preservesStderrOnNonzeroExitWithoutLeakingArgsOrStderr() throws Exception { } } + @Test + void adapterDebugLogsOnlyArgumentCount() throws Exception { + String canary = "adapter-value-" + UUID.randomUUID(); + ByteArrayOutputStream output = new ByteArrayOutputStream(); + PrintStream original = System.err; + try (OpenCliExecutor executor = new OpenCliExecutor(childProperties()); + PrintStream capture = new PrintStream(output, true, StandardCharsets.UTF_8.name())) { + System.setErr(capture); + try { + OpenCliAdapterChannel adapter = new OpenCliAdapterChannel(executor, "privacy"); + OpenCliNonZeroExitException failure = assertThrows(OpenCliNonZeroExitException.class, + () -> adapter.invoke("nonzero", canary)); + failure.printStackTrace(capture); + assertEquals(canary, failure.getPartialResult().getStderr()); + } finally { + System.setErr(original); + } + } + String diagnostics = output.toString(StandardCharsets.UTF_8.name()); + assertTrue(diagnostics.contains("OpenCLI adapter invoke argvSize=3")); + assertFalse(diagnostics.contains(canary)); + } + @Test void keepsArgumentsAndPartialStderrOutOfTimeoutDiagnostics() throws Exception { String canary = "timeout-" + UUID.randomUUID(); diff --git a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupportTest.java b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupportTest.java index 9123715..1262279 100644 --- a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupportTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessExecutionSupportTest.java @@ -1,5 +1,11 @@ package io.github.easy4j.opencli.core.support; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails.TerminationReason; +import java.io.PrintWriter; +import java.io.StringWriter; +import java.nio.file.Path; +import org.apache.commons.exec.CommandLine; +import org.junit.jupiter.api.io.TempDir; import static org.junit.jupiter.api.Assertions.*; import org.junit.jupiter.api.Test; @@ -34,6 +40,24 @@ void shouldBoundBackingBufferGrowthAtTheConfiguredLimit() { assertTrue(capture.isTruncated()); } + @Test + void shouldKeepNativePathOutOfDefaultHandlerException(@TempDir Path temporary) throws Exception { + String canary = "private-native-path"; + CommandLine command = new CommandLine(temporary.resolve(canary + ".exe").toString()); + SubprocessExecutionSupport.ExecutionRequest request = new SubprocessExecutionSupport.ExecutionRequest( + command, null, null, 5_000L); + + SubprocessExecutionSupport.RunSession session = SubprocessExecutionSupport.execute(request); + + assertEquals(TerminationReason.SPAWN_FAILED, session.getExecutionDetails().getTerminationReason()); + assertNotNull(session.getIoFailure()); + assertTrue(session.getIoFailure().getMessage().contains(canary)); + assertNotNull(session.getHandler().getException()); + StringWriter diagnostics = new StringWriter(); + session.getHandler().getException().printStackTrace(new PrintWriter(diagnostics)); + assertFalse(diagnostics.toString().contains(canary)); + } + @Test void shouldReturnDefaultMaxConcurrent() { int defaultVal = SubprocessExecutionSupport.defaultMaxConcurrentExecutions(); diff --git a/src/test/resources/simplelogger.properties b/src/test/resources/simplelogger.properties index ad97fd1..847e228 100644 --- a/src/test/resources/simplelogger.properties +++ b/src/test/resources/simplelogger.properties @@ -1,3 +1,4 @@ org.slf4j.simpleLogger.log.io.github.easy4j.opencli.browser.OpenCliBrowserSession=debug org.slf4j.simpleLogger.log.io.github.easy4j.opencli.remote.OpenCliArgvToCollectParser=debug org.slf4j.simpleLogger.log.io.github.easy4j.opencli.parser.OpenCliStdoutJson=debug +org.slf4j.simpleLogger.log.io.github.easy4j.opencli.core.OpenCliAdapterChannel=debug From db70054df1446e3b7d6640ecf9ecb68d8e0fbc2b Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:41:53 +0800 Subject: [PATCH 028/105] ci: require exception privacy evidence on hosted platforms --- .github/workflows/platform-contracts.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/platform-contracts.yml b/.github/workflows/platform-contracts.yml index df48f21..056ae5a 100644 --- a/.github/workflows/platform-contracts.yml +++ b/.github/workflows/platform-contracts.yml @@ -44,7 +44,7 @@ jobs: mvn -version > platform-evidence/maven.txt 2>&1 result=0 mvn -B --no-transfer-progress \ - -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,SubprocessCleanupFaultTest,SubprocessStreamFailureTest,OpenCliWsReverseAgentSessionTest,OpenCliWsCollectRequestsTest,OpenCliProcessPrivacyTest \ + -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,SubprocessCleanupFaultTest,SubprocessStreamFailureTest,OpenCliWsReverseAgentSessionTest,OpenCliWsCollectRequestsTest,OpenCliProcessPrivacyTest,OpenCliArgSupportTest#shouldKeepConversionExceptionAndNestedCausePrivate,SubprocessExecutionSupportTest#shouldKeepNativePathOutOfDefaultHandlerException \ test > platform-evidence/maven.log 2>&1 || result=$? tail -100 platform-evidence/maven.log python scripts/contract_report.py \ @@ -63,6 +63,8 @@ jobs: --suite protocol=io.github.easy4j.opencli.center.ws.OpenCliWsReverseAgentSessionTest \ --suite protocol=io.github.easy4j.opencli.center.ws.OpenCliWsCollectRequestsTest \ --suite process=io.github.easy4j.opencli.core.OpenCliProcessPrivacyTest \ + --suite argv=io.github.easy4j.opencli.core.OpenCliArgSupportTest \ + --suite process=io.github.easy4j.opencli.core.support.SubprocessExecutionSupportTest \ --output platform-evidence/report.json exit "$result" - name: Upload platform subprocess evidence From f89c0ce4f2e6b832a7ae97b16c5244df99776b20 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:50:34 +0800 Subject: [PATCH 029/105] build: restore the Java 8 Maven Wrapper and align version docs --- .github/workflows/platform-contracts.yml | 7 ++++++ .mvn/wrapper/maven-wrapper.jar | Bin 0 -> 63093 bytes .mvn/wrapper/maven-wrapper.properties | 2 +- README.md | 29 ++++++++++++----------- README.zh-CN.md | 29 ++++++++++++----------- 5 files changed, 38 insertions(+), 29 deletions(-) create mode 100644 .mvn/wrapper/maven-wrapper.jar diff --git a/.github/workflows/platform-contracts.yml b/.github/workflows/platform-contracts.yml index 056ae5a..701606e 100644 --- a/.github/workflows/platform-contracts.yml +++ b/.github/workflows/platform-contracts.yml @@ -33,6 +33,13 @@ jobs: if: runner.os == 'Windows' with: node-version: '22' + - name: Verify Maven Wrapper on macOS + if: runner.os == 'macOS' + run: ./mvnw -version + - name: Verify Maven Wrapper on Windows + if: runner.os == 'Windows' + shell: cmd + run: call mvnw.cmd -version - name: Exercise real subprocess contracts run: | mkdir -p platform-evidence diff --git a/.mvn/wrapper/maven-wrapper.jar b/.mvn/wrapper/maven-wrapper.jar new file mode 100644 index 0000000000000000000000000000000000000000..eebc3c18b4e0bce4a2a9e66be24c4a410f17a1fa GIT binary patch literal 63093 zcmb4q1CS^|ljh)!ZQHhO+qP}nwr$(CZNIVYnK!z(xZVBl_Wq0Q=!)p*{xT!8I=ia! z%W8Qk;9rmc0N?-s#g^n+0RQEH_XFfH63%(B0aB>@2d z{@(phn2dm|gs6y;GOdhgOw1JIAU(41YryBwSHQ0ib(b~Bz>vW8!pr$>OL`f>Ov>*b z75QSw&ddOg>554cv7|de9+Yzpjo38tW z+=G*`qP+Byt36BWMG$?m<<$dmG_e*g41GnCEzNIESyJF4IB2=^$1Fg3mFMg`8~9&w;Rxvp8L9uH(7dl zZw2WpHXlNS;|=hS-%E4zL8#5&KGvlM0D%9mHcCqfiO4F6>}YB^ZH=P%zSgZfmMU3* zmgX>9V4X%Z9EH{hSqOL7k|u?b)Z@2-){oQTM}9r?r1b<88@v5cl__PBxY}qseaN}Z z9)Y^==o6uv%0aw!so*Tr<$gTkOLp0GKDd0p6#SHNEouh4f4*GXC{5{#@831)#ck8PeHF6=@-J_vHbDPFi)#C2vM8;cP2j$@ABZNo$W*wnuGnzy0Zll z)m6)Le2YMd-^PTfR^llF(I^az_&Oz?L;^z7A7f90ZnPg*SD*&l4h9sb+5(cG1`-cb zv9o_^ugyqppmDLe=DeHuCx89YV9e2dsKeci`g|d-l?|R@qHK#YmbL{!Y-Kv3^N zu}Q5J;8o)ek+Oj6+l>H}ND@MJ?6e#CJAztYgo>*}<&1lKE#`QZN;UjTcHw^Dqq&ZF zqr>C{vk0PC+k8HF`_Q#hOroWBAhV~DB(nGI<@uJ*f(!V>U%nnez0N?71<&aPtueh>!GxEzvgFJj?Rg0*v~vETqmYNDvF1V>7qTega!(Bbyp+C1af?E zAybgKbCrYJT@llB{n(vjGXZ-E&}G;*k$^5VpM3CV-Lq@+6IXkQ0*3dt^*2a?eP!nr z>?cmUku^D=rIqGe!}bJhGb{vQq1k%)e4N2-w1cFmUbXs1B4Q<@m$V5;waE*x`hy@ub9gqcSb*)rZkW&W z9^zI3d2b>d&blJyYJ0e7-*DVf%I(PQkdFG@bH}s*Kz1vCOn?lFl^{|zL*yU}?_6*Y zR904RAcWsD9;_Y)>c`1J;slpc>(k81$o0~8E?`~Re?F1pfMr*bp6G@f-n*aaGkb2u zyX!DjTNKAWm3x|zDa_G0MXRbUVdKGe$QZXl3qcNxlWIDlW!C_NTT@9;A_%Jz7Rt#a z3tW;blGb(!lRq&1Ru9KG;FVan=rHHWw988r;E-AGAx7+vGsNSK*IAn(ef=cg38f+d z6?XeqW&CZ}Yyr5q-GBWSSP;of^5jJ^CmOs*(nRQ%KEBzoOh7^rHrd2I^eO63XGuS> zcz7^b(VafXFx5p}`v9M+7iWq0Uj;x%I}3@iCXanVU2_rU9i7$E(?>lLRhy7EFB>Q^ zCiv(&*ib}npxOogmf{2?yZ}XGrDH_T5Ed}CX~weOc63%gwirvjTU;8C3wEzyt{Bq~KGzW99#qh-n_7s5O>9ef zK@!Z9xgwXRJ$`B>x(bsQ#!E1m6D15>u?BfbC7fG%zhVxFdvoD-9q*r0%-!}6kGozd zH3XZqMjl3z7ZnkQl|20@CU(APLpUfKu#p0OIdO~$W|QIrEv!2|s1vWU-)g&m3($yo z9v@j5yVx)#m1@FHK~a`Sz!1j|_MaU-2uB0p2v!0bx?BNBh1dt1UsLvq(Jo@zk$UJ3 zLOL8v>-W4u#UgWxpRsq>&;rS0hVKGXB8<;dcG~^f4=vaVM2R=z8NG*CBw@cDgQ*6g z63l;z3FeR6^`F(Y#PK7ElMwfa^U!{1_ypJdV{Rh8r%@-x9$0-49S98fTpW0gPMW zr8-`pG#gr`pBJ)gve&MDhZ%=Gr#gE5ScM9!V&M0uwJUo)A;d%tmP1p}m5Z#V%!Y;* zf8P88IgX`X?i<<-;->x*g&qRnw||1Ls@zm8S}?Ff*ku(>`5dubW%jONTrGHuEo~~x zAHEks*my`IPEM0~EmZ+ql5c7JQ>@o0<$A)l*3phMV|s2;3(+IFPYiB45u#VyWnkPE z1ua@2{f2z+gI{9hZ`l0`GWsJqb}dQSj2x%%u_&Jlh)N&~(j%n_=;TV~qCTa;qD05( zbRGdJ4le!3BDW#x3AFI7kiF0YXf;ra^>Wqdki8jETq$y)C(SNYa1a}@3gGtgV75#H zMP}-_9ltDytXYA^6|f140)E&U2<5g+Y4_#uH4-!l7{wuLR4HB@Z7|Ow+IzvSJdrN0 zLb{KVV&N^cmeE!YeSx6p`}(D?iO_LsZ}98loApkAQuQqviPv#@Mq7Qpex?e(y@xn;sqvELcwX2F}O)H zlbB{$%~wbQRiFCoKId1OR%X5)uAiY3ZyoTxj5gnS;vLOCjy6&R`ZJ_C z8mQl?kWe(`Ab68ep3^DLmNl9P$tAKMO%1ur5g6|T&cH{~)>)98eh->mOAdfCVv^vr zD!nKFrjyu!90q6gL0V207&E>!E|5^}Fmrk11$&f;Klb3k;fK&6%N|JVkU_aq?rj*U zNHN*-+(@2!1vRTy#xsFL06zoR(7>NprMr(0JIjJSb(*IqYLG|Fod3XaGYHo!GoAgE zISSA^XFm$UC1j}^moL3|+a?_5ls0{AupX}*^wYX>dkCK{{!@N96tGMbPry2@$LVTSIFd7ab2XvnaklTa~du2kGyQK7-jy%2e{ z)R8Vp4A(YW>LC%3v{fmA5?hUBHX&TX5KC&5v0j1g0)!OiEj1I{2eGHi(!kG#hR0c6 z7@J*+Yfz+U^dW`V1eM6X%Z}YNZk?VI(~yg;LsA;Yg$w7Heqr-){^+-q>5(a7X$m+* znBJ+n|B|p)H|-yFa1FDP7PDUpz2qu&jgyL?I1?ien_Y>l_sam&nD!ovp=%G2LY<*i zSnKSZ{0@#+sGLYCu5ubb*Pjh@xU#0%yUuyr>#fV54-gp?=l~v-30DV0a5jL#&6OxP z^cBrgT5pgg)Y`!o6$3`LC)uYzqxT1#^Bw&pOlTf7MyR-$b)|Aw^x7`2KA-CjBGuWE z0@-)z;F;MHSQYfQ!XRJ|mElrA(q_`T^?2zXn;y(;GC=Ec-syoPmu1e~Vk;_MfM1{v zECWPgWfm}7{j!HqREoZTxA=@yW+2Lh0q?7h;xmxTNWp+ZR3=}{;Z%eZokJ~1JfBwe zh$9aYANA^#3;oU5@mCxh-p$C^$j*+TOJBEcR94rg=J!dCdbKaApI&XP|BZPspzrW` zxfIz#FqH}`sSJj&lOl%w1%M1~MkFSo7i5F}^vChn$0bm8uV;sLPnTBhx98W=^F=Q_ zpU!U27ecf4XT5h{_fLl4+0KKnOV7y~7^?2*^#LsQ%l_Aa?6z-vSC59CQ_JzzAgCQG z{|_$fit{Bu8`Cz5><|dInT#FFq7$b*%tA<<{3prq%t;BijWaAe0xnyBi)--JY%*u- z1oXvsZc1sxyU3*l(^SK28izM5>4?Z}%l26)?Od9=2grP$Ek2JrsQ1czJ(6>zvv*nh#zFtWu^?{8W1IF>_#GKjTS6~Ft>=RZGfuPu=jRP*iEzMvmaBslg znd_&wFTJPiBp9qo;1s3|)<*4=IcVD49wa!;{RXTd zz%G{3%}dfe9N)k~>p!{&$?zNl;gM^KY(>YG#95wKh#dul?k6(v-5~vYGuH!HRA2!? z4&lGP+~H46h7CHaahY`zSHGWO#sTbt?;L~B<}mJdw5cVlA6i+WAX$M>^ws1gQnB!H21jE>3aJX0R@bL?u#~z$cAf-nb9|xkg{jR?3$fr zT(J;2+WJrn2x@;Y1DFTM&!wcvb_$7w<&p}ip+BY3y-0PKc#Q^~dXsD}%(Em{=40m41+>gbN@ZuaepCwYI94D5cP(UN~! zAum}7=C6P@jtXM&23LqCaK39+l{x}J{vzfI`UbV5KoLH^ z`=?RXla{tt`ZesWmp`>g;O&+c#N~3ilrtX<9)kbA2)CDOeA3mGEvn-H*8eo_o-jGn zQx(7-2$dCpj@%G>b}K8 zUh&Fmv&>Mrgg$sm+Pi?a+2i9^a>6Gf@L$@!pKsjr?mO?S$@vVT%Ej!2E?=fXON<;C z8zKCuLg24+J&u2H+dnLQz7Um5N%RKi^A2#obC{5mVwPoh?FXfTJ_E|o-+sjVfbU70 zYEm-G;RCbHVTPfxYqnzH?fD_{sh!8{UfwMv4lZw=v>(xa0RJ&HA4+2l_y3!cSO0DQ zz=FuiDgRB*eWn}!vRLr``#f?EMX;qU2M45rU;`6@j|QGEH+Dlr z*aJznm&?SMjHOEAGbg|hpbKV?yILMAj?Fuh)YQlv>6o-M=CmR&mQu_^t+oC#FHrNO zE2yC>4)DDQ`!4dO@G&b3|D3|=HHFg?0=Oc(tHeS*L!+qBOx9f1 zqn$6jT)(OxCkA9^B0F<3MzvX!#>|3bN3~vt-$w6B6uXV;OrZgo3*-Qc1u_`tGTCPS zI=QWgii;I{C`X)py~L31=79>=DqQB6HT;;|74AkQUiluwTUCGTXWp7gCErZe?IF!F zmiLy3jN9dsM7t+XX@M%mRpBkz^s*Fb2=!^AzvR~+B_>}b)&*iAcK;qoP!(u`>!`Ph z#u_V<0Gg3bnrE*^+&mqai+bfp50qCUyszr>*>V%kKZ%D<=4zHoRE6&Hd%mS|o#rV| zjjDAeRVY3YLJAKwnyw|vQfiqMi7$?#ouBcMbb9~+`kzoT@zc19opjfID-JV2kucSdt3z9vQM+~@0;a#dnbuSq#HQ|R2 z-312_P~;BE;VwjdP!9k5%yDauk`$jtS)0)S;iA{^U)= zx5<-dh(H30tXbLu(ZO%waP?g)N=F2rY05{*HfE>`QX8-c*fI;$A3v0$EOls2=sE0E zYE4&*1GVOEA~3(c+5BT2B15q>&p#r!ZvmpG>Hw>U(C)+}%E~aLT~9l|5p?avs+ny! zM_S=WL=g$pLswr%LGF>&0x*ej5;9R~q;3k`l&&PNYOu!*c>jpAAN0Oyvy97TUD;wi z>Z7NRls#e7I%5B`K~C9Rpui|(6M%;)p0{Rg5mYfKm=ZI$jHcyBo+{N zozfy*#&Tkh!W#L)@xxfpu7(b02=1N;girMzwDvtqu_;Z&l*UV!D0WN<>$=@#0yJ5! z3Zgr_?a1JnbuKDDcIX5F^H`&QbWnPY?BWq*hnHd?#eIB6&Z?E*RK{?e0*jgi^W{fd zFcjk}(>uj2&fgTp9VemH;sx97($S55awy0Gb$E){O=EjYrW@U!lGGc_<)h)Ol5P4V zqt!=<${CJs=qYovc7}`Satdyvq!LVP&a;IGI8J<~hT4S3Z?7t9RZ?nQuL%f;WYg=m z>AG>2UPHG^TU2MYCMY?% z-J)XbS|>T(^g|tzpl-(dCxjVBY@m_5KF9&59_O7BFA;46+U;EhEBYO+@2JAw=^ID~ zIrX23vUpbyeS46}VHoQS*qvdUr5quvb=vx9u7|32FAOhLdp*|X$ZuhDj0|D&?|#M? zv!VN-AglZ)D|X`g$OWeRhJm+xmT0$rIl16Nz2bvUXR}XbUktOx1YzO$d4`>iw8spl zHJ!fVeYpEvkf()uDxUiWG| z&}#R8Ab)?Rt6q-^=z7-P%{sw?#1f#bFx!B_=0{cWj3-*5d(jIj8^H;E8ZCu~hL5OgdiYL^^guE7#K zK(s}Xhf{`k@%akU+=INaaXLcQdI#2kf2`H<-yx6)QNiOq{M_31?tcDjz2iR%1>0dy zb>ct(078EYJB>O;w`~dDw48yEWTpm9_%GTA? zHrK<{%mB`u2 zhk@AmyxoJm#pL&Pns56oefGpE4KccDoKRKw+Ll_U3(x@-M=0@-afhx&x1Sc3t?I*Z zVa#QEW4t4M3>I_*xlq5!Rt?UR-~vfzD|pDZk@|SDtT#*x-B!ny#TvTpH%Y~bRmfRr9J*n~RjL_L>_;isBlMD)yq(7eXHZs$v=t2D zNkyuDc$zl_<=0K?yxp5Cf3C3vi--K_CfiE_lWA5!;N{K8&T{?7gQ=v6zr5F$9vVMT5!~MZCm%HJK zZD++%?Cy=#yZ;8isms=@IN77j-vK z%w+U`<8t?JTq^y~;!?@O$=Sq4-qG%FVbIya#Od#qyN7^_v$=__vxSj?v)#Wh`f8M{ ztdInddDvvS9I|+|SsHpZw=|Q~n_^TI2n8h&f|a3G0-u(cagtJu*`{Uxys1UbgM#?^ z^GS9$X?)}(VA-R&-fVNcW;eN+`hNd;0q$qa-4xd!7i5evh=yMUQgIW}TE<+oiO@Ok z@{(-cQtYUDC^}<)wyZy818yK%`5YA}H?h(I>8|F%aBTLgUtEAWx2hv`&Ic!=#L3|Upk#J=e8>;xI=q8 zvCoc;DcLb7oib%+j_f53d}QDP{6%zLf#rRY31=dE2suVg@K4LFl!`^89)_m7FuAsN z82!g>tA@LvI`%NP=^J60el9`m8)Fdt98;PYZ#6nC_Q0P(0if46E<}<(!+^eXT!7bv zLxu=$NQZk&vl-17t}8g%&M1e|%B1syKLob8`!}aXoMBV`LZv)|=$+&C-hw&T3UZhU zU<}VrxJV6j7q?VPz{9=L&Ea7R8VrM7>XF4rpQ(50bR&+zLw5fdpn+h>OuaAw0Jzuy z0QCQ(0R8u2Qv*UDX)WVBm&R(;P>>(UT0j!H_ANP3h?WbCm3?4XjmF3be_jA{3&=wh zBL={&?VQwNk(DQHNB63Ai^<}ZvLMEO5NIdr%JtT($*k+u$2iW`ZOgQejVX~tOBM(s z(__ug_vb#e&hNH_3cxkO2=d~WCXE+q!Rga-bwc`*9ERyZbIqw^XbyT}k%S$6vDq{{ zkhwhkay~zbx|1MZ30Y$&M-n=R@1Qsb(0~_{>1c;ues76OAp$|QV!lN?U=_%w>QU2L z`YM!$S)I$~w5I1~J&5g*Bx}-QPP7T^rBf)syM2PrVgu8ObewU$=#ZuakG6yUVEv%m#b-6BJ#+u9~^N8Y~~PJXG*pu=J)N|@>Di%mJ=Xr{?gw2SDU&1hL=jm?}U zF+51AG?QCEYn5!ZLR?v6bi;0Pd1;aft_NtLG@F}?Wc7op87|o)s&M}j^ccFQ0JnZf z(P@qQrQ!^}P0!50?QzB5=x5#TR<5_nSW7?vgHgN!{g@n?Q=(JUGjVh@zOD<>2IZ_B z_eS8n4_on`0~B$&kZnlWu9d&BL})}(%A`TWkj@|%d&Ir$9Ms#XHsphUK(z9KdnA`z ziEhT|5k{v&;*`u9eKBi2w?B|l{@RSI8M1SxGGAr@_ky@TH3!8k>3_}|Bh}a3yn0Zu zClGMG0@W#0jzhaWz>l=mF___!VPaEO5YJA8^NJUeN99xDn7OijUlx(QX9LC z7#Cv-!*iQEX%=3jK0wlL=k3jm0k;p1t6;A@#Lz9XcY?CdZayfkj6Ept=`PA(G7)`g#KaTW0Vz-;z@R>n7}dX*|~FG?p$%D5{;Ci%|sf)qx7CR zxp;rDk|(RmIASv+$Lnl-VdRpul;iq&tWf&c7K(RX=km2pcPrMT6UsB-J>aLQ%1mEy^i}!{wec{bCnzns{U0DT$nQ)D3C8FmT zIf}t(G`*$SmQbZ~4(b}_)4G2`%d}1Ts`rWB%Ka@d&9VigKq*SpGo)PDv7j^6t3gn+a_chA)0reE|H z?o_(@KZ@Du?&PIpJa(m5>+q>_)?%VCQSS&P<}?-yl~}CCo)v4a1EtGXC^s?)%fSz3)2_RkN*>?%B#^cH&L{* zvVuz@t2dBO@oo(B`XyosnI}QzdRW3$4nBSIlp~pEDK&A<%2lwwqdk>pMov zlqVY_&Z(=cJM#Diz7GZMiZ#}}nn=Hr6lgd4n^R1XA6j|0cDmr7em}}LI+&jryA(zN z7*uDAQErnQP~J&>QWeXh6Kei{?yQd5^K7h47vcO%Ts{rOvoui!|RR?0P^Ux#1f+=nHXoSYS zZZ6v(Rv?ZT2B5B%3~B7j|EA$}dOvh8j9 zD%MYjY`&JZ4iBWNTvT{$8!qLBOu(T*4~ElP%h$`+MeBsEl!jTPtx-57wVO0owm4*r zz(zzwhsPftBZ_g9n(lDhxpLNXW16j}UfVxfRJss^3#AdR1DE>tn~kT=t#EK{)MZb9 z5;_f)mW#sM`&U!wd{FeTfxOVmo004EN9_%6+705Q=p;spp^-Xs5{ _ohw3Ut=#j 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 literal 0 HcmV?d00001 diff --git a/.mvn/wrapper/maven-wrapper.properties b/.mvn/wrapper/maven-wrapper.properties index 216df05..27e7135 100755 --- a/.mvn/wrapper/maven-wrapper.properties +++ b/.mvn/wrapper/maven-wrapper.properties @@ -1,3 +1,3 @@ wrapperVersion=3.3.4 -distributionType=only-script +distributionType=bin distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.16/apache-maven-3.9.16-bin.zip diff --git a/README.md b/README.md index fa5dec0..182a4f0 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,15 @@ [English](./README.md) | [简体中文](./README.zh-CN.md) -[![Java](https://img.shields.io/badge/Java-21-orange)](https://github.com/easy-4-java/opencli-java-sdk) [![License](https://img.shields.io/badge/license-Apache%202.0-green)](./LICENSE) +[![Java](https://img.shields.io/badge/Java-8-orange)](https://github.com/easy-4-java/opencli-java-sdk) [![License](https://img.shields.io/badge/license-Apache%202.0-green)](./LICENSE) Multi-adapter CLI integration SDK for OpenCLI: browser / desktop / public-API adapters, remote agent and center WebSocket [简体中文](./README.zh-CN.md) -> **Current branch**: `feature/3.0.x` -> **Version**: `3.0.x.20260630-SNAPSHOT` -> **JDK baseline**: 21 -> **Project status**: stable (3.0.x line). Not yet published to Maven Central; artifacts are distributed via the Aliyun Maven repository and GitHub Releases. +> **Maintenance line**: `feature/1.0.x` +> **Version**: `1.0.x.20260630-SNAPSHOT` +> **JDK baseline**: 8 +> **Release notes**: [1.0.x.20260630](https://github.com/easy-4-java/opencli-java-sdk/releases/tag/v1.0.x.20260630) ## Table of Contents @@ -70,11 +70,12 @@ Multi-adapter CLI integration SDK for OpenCLI: browser / desktop / public-API ad | Component | Version | Notes | |---|---:|---| -| JDK | 21+ | 1.0.x line baseline | -| commons-exec | — | Local subprocess execution | -| Unirest Java | — | Remote agent HTTP | -| Java-WebSocket | — | Center WebSocket | -| Jackson databind | 2.17.x | JSON parsing | +| JDK | 8+ | 1.0.x line baseline | +| Maven | 3.9.16 | Repository Maven Wrapper version | +| commons-exec | 1.6.0 | Local subprocess execution | +| Unirest Java | 3.14.5 | Remote agent HTTP | +| Java-WebSocket | 1.6.0 | Center WebSocket | +| `com.fasterxml.jackson.core:jackson-databind` | 2.18.9 | JSON parsing | | SLF4J | 2.0.18 | Logging facade | Version-line matrix: @@ -133,14 +134,14 @@ Maven: io.github.easy4j opencli-java-sdk - 3.0.x.20260630-SNAPSHOT + 1.0.x.20260630-SNAPSHOT ``` Gradle: ```groovy -implementation 'io.github.easy4j:opencli-java-sdk:3.0.x.x.20260630-SNAPSHOT' +implementation 'io.github.easy4j:opencli-java-sdk:1.0.x.20260630-SNAPSHOT' ``` Snapshot builds require an enabled snapshot repository (Aliyun Maven snapshot repository per `distributionManagement` in `pom.xml`). @@ -257,9 +258,9 @@ mvn clean verify | Branch | Version pattern | JDK | Maintenance policy | |---|---|---|---| -| `feature/1.0.x` (this branch) | `1.0.x.*` | 8 | Compatibility fixes and JDK-8-safe dependency upgrades only | +| `feature/1.0.x` | `1.0.x.*` | 8 | Compatibility fixes and JDK-8-safe dependency upgrades only | | `feature/2.0.x` | `2.0.x.*` | 17 | JDK 17 line | -| `feature/3.0.x` (this branch) | `3.0.x.*` | 21 | JDK 21 line | +| `feature/3.0.x` | `3.0.x.*` | 21 | JDK 21 line | Branch POMs (JDK and dependency stack per line) are rendered by `scripts/render-branch-pom.py`. diff --git a/README.zh-CN.md b/README.zh-CN.md index 2b21679..a3fd060 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -2,14 +2,14 @@ [English](./README.md) | [简体中文](./README.zh-CN.md) -[![Java](https://img.shields.io/badge/Java-21-orange)](https://github.com/easy-4-java/opencli-java-sdk) [![License](https://img.shields.io/badge/license-Apache%202.0-green)](./LICENSE) +[![Java](https://img.shields.io/badge/Java-8-orange)](https://github.com/easy-4-java/opencli-java-sdk) [![License](https://img.shields.io/badge/license-Apache%202.0-green)](./LICENSE) 面向 OpenCLI 多适配器体系的 Java SDK:browser / desktop / public-api 适配器、远程 Agent 与中心 WebSocket -> **当前分支**:`feature/3.0.x` -> **版本**:`3.0.x.20260630-SNAPSHOT` -> **JDK 基线**:21 -> **项目状态**:稳定(3.0.x 线)。尚未发布 Maven Central;制品通过 Aliyun Maven 仓库与 GitHub Releases 分发。 +> **维护线**:`feature/1.0.x` +> **版本**:`1.0.x.20260630-SNAPSHOT` +> **JDK 基线**:8 +> **发布说明**:[1.0.x.20260630](https://github.com/easy-4-java/opencli-java-sdk/releases/tag/v1.0.x.20260630) ## 目录 @@ -69,11 +69,12 @@ | 组件 | 版本 | 说明 | |---|---:|---| -| JDK | 21+ | 1.0.x 线基线 | -| commons-exec | — | 本地子进程执行 | -| Unirest Java | — | 远程 Agent HTTP | -| Java-WebSocket | — | 中心 WebSocket | -| Jackson databind | 2.17.x | JSON 解析 | +| JDK | 8+ | 1.0.x 线基线 | +| Maven | 3.9.16 | 仓库 Maven Wrapper 版本 | +| commons-exec | 1.6.0 | 本地子进程执行 | +| Unirest Java | 3.14.5 | 远程 Agent HTTP | +| Java-WebSocket | 1.6.0 | 中心 WebSocket | +| `com.fasterxml.jackson.core:jackson-databind` | 2.18.9 | JSON 解析 | | SLF4J | 2.0.18 | 日志门面 | 版本线矩阵: @@ -132,14 +133,14 @@ Maven: io.github.easy4j opencli-java-sdk - 3.0.x.20260630-SNAPSHOT + 1.0.x.20260630-SNAPSHOT ``` Gradle: ```groovy -implementation 'io.github.easy4j:opencli-java-sdk:3.0.x.x.20260630-SNAPSHOT' +implementation 'io.github.easy4j:opencli-java-sdk:1.0.x.20260630-SNAPSHOT' ``` 快照版本需要启用对应快照仓库(`pom.xml` 中 `distributionManagement` 指向 Aliyun Maven 仓库)。 @@ -256,9 +257,9 @@ mvn clean verify | 分支 | 版本模式 | JDK | 维护策略 | |---|---|---|---| -| `feature/1.0.x`(当前分支) | `1.0.x.*` | 8 | 仅接受兼容性修复与 JDK 8 安全的依赖升级 | +| `feature/1.0.x` | `1.0.x.*` | 8 | 仅接受兼容性修复与 JDK 8 安全的依赖升级 | | `feature/2.0.x` | `2.0.x.*` | 17 | JDK 17 线 | -| `feature/3.0.x`(当前分支) | `3.0.x.*` | 21 | JDK 21 线 | +| `feature/3.0.x` | `3.0.x.*` | 21 | JDK 21 线 | 各分支 POM(JDK 与依赖栈随线变化)由 `scripts/render-branch-pom.py` 渲染。 From e725db20be6ca3710802c0181fc3cec8ff87b4de Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:08:52 +0800 Subject: [PATCH 030/105] Reject malformed legacy collect response envelopes Refs #5 (cherry picked from commit cf9360e99647c935d7ee10c87a391ed602647682) --- README.md | 1 + README.zh-CN.md | 1 + .../harden-opencli-remote-collect/tasks.md | 13 ++++- .../OpenCliRemoteProtocolException.java | 9 ++++ .../remote/OpenCliRemoteAgentHttpClient.java | 47 ++++++++++--------- .../OpenCliRemoteAgentHttpClientTest.java | 39 +++++++++++++++ 6 files changed, 86 insertions(+), 24 deletions(-) create mode 100644 src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteProtocolException.java diff --git a/README.md b/README.md index 182a4f0..3cd3e37 100644 --- a/README.md +++ b/README.md @@ -190,6 +190,7 @@ Configuration is object-based via `OpenCliProperties`: Notes: - In remote mode the `stdout` is the JSON `items` the agent returned (parsed into line items per `format`), which may differ from local raw subprocess text; `leadingArguments` are local-only and are not injected on the remote path. +- A legacy HTTP `/collect` reply must contain a JSON boolean `success`. Invalid envelopes raise `OpenCliRemoteProtocolException`, which extends `OpenCliExecutableFailureException`. A valid reply with `success: true` and omitted or null `items` still returns `[]`. - `execution-target=REMOTE_AGENT_HTTP` makes the availability probe report `SKIPPED_REMOTE_MODE` (treated as startable). diff --git a/README.zh-CN.md b/README.zh-CN.md index a3fd060..17058d7 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -189,6 +189,7 @@ cli.gemini().deepResearch("topic", 注意事项: - 远程模式下 `stdout` 为 Agent 返回的 `items` 的 JSON(已按 `format` 解析为行列表),与本地原始子进程文本可能不同;`leadingArguments` 等仅影响本地进程拼装,**远程路径不注入**。 +- 旧版 HTTP `/collect` 响应须包含 JSON 布尔字段 `success`。无效响应抛出 `OpenCliRemoteProtocolException`,它继承 `OpenCliExecutableFailureException`。当 `success: true` 且 `items` 缺失或为 null 时,仍返回 `[]`。 - `execution-target=REMOTE_AGENT_HTTP` 时可用性探测报告 `SKIPPED_REMOTE_MODE`(视为可启动)。 diff --git a/openspec/changes/harden-opencli-remote-collect/tasks.md b/openspec/changes/harden-opencli-remote-collect/tasks.md index 8407a8e..ba2364d 100644 --- a/openspec/changes/harden-opencli-remote-collect/tasks.md +++ b/openspec/changes/harden-opencli-remote-collect/tasks.md @@ -1,12 +1,12 @@ # C04 Tasks · Legacy HTTP collect 边界与保真 -> 全部为待执行实现任务。文档/格式检查通过不允许提前勾选。 +> 勾选项具备对应的实现或执行证据。待验收项继续保留。 关联规范:[spec](specs/opencli-remote-collect/spec.md)。 ## 1. 服务端契约与失败测试 -- [ ] 1.1 固定 opencli-admin server 协议版本或可控 fixture,标明它不是 jackwener/OpenCLI 的官方 RPC。 +- [x] 1.1 固定可控的 legacy `POST /collect` fixture,记录本地桩与上游 CLI 的范围差异。见下方 OC-REMOTE-004 证据。 - [ ] 1.2 对 Browser/root/external/重复flag/负数/--/空值编写“拒绝且零请求”的测试。 - [ ] 1.3 编写 success=false、503、malformed、null、超大body与超时结果未知用例。 @@ -25,3 +25,12 @@ ## 证据交付模板(实施时填写) 每项任务的完成记录包含:Requirement/Scenario、分支HEAD、测试命令、失败→通过证据、测试数/跳过数、退出码、报告位置。没有记录的任务保持未完成。 + + +## OC-REMOTE-004 响应校验 + +`OpenCliRemoteAgentHttpClientTest.JsonCollectStub` 通过本机 HTTP 服务器提供可控的 legacy `POST /collect` 响应。证据只覆盖 SDK 到此测试桩的 HTTP 交互。jackwener/OpenCLI 提供本地 CLI 接口,真实 opencli-admin 部署仍需验收。 + +JDK 17 基线 `5ac4bb1` 的 20 项用例实际执行,7 项失败。缺少或显式设为 null 的 `success` 被当成业务失败。字符串和数字布尔值、数字 `error`、重复状态字段及拼接文档曾被当成成功。修正后,具备布尔状态字段的单个 JSON 对象才会继续映射结果,无效响应通过 `OpenCliRemoteProtocolException` 保留类别和相关 ID。现有异常父类保持兼容。合法的成功响应允许省略或置空 `items`,空结果仍为 `[]`。 + +定向测试命令为 `-Dtest=OpenCliRemoteAgentHttpClientTest test`。使用各维护线的 Maven 和 JDK,报告位于 `target/surefire-reports`。Body 大小限制、总超时和退出码来源仍由其他任务验收。 diff --git a/src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteProtocolException.java b/src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteProtocolException.java new file mode 100644 index 0000000..78a0f0e --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteProtocolException.java @@ -0,0 +1,9 @@ +package io.github.easy4j.opencli.exception; + +/** 远端 /collect 响应不符合协议,保留既有远程异常捕获类型。 */ +public final class OpenCliRemoteProtocolException extends OpenCliExecutableFailureException { + + public OpenCliRemoteProtocolException(String message, String correlationId) { + super(message + " correlationId=" + correlationId, null); + } +} diff --git a/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java index 482c411..130b4be 100644 --- a/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java +++ b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java @@ -1,13 +1,15 @@ package io.github.easy4j.opencli.remote; -import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.databind.DeserializationFeature; import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectReader; import com.fasterxml.jackson.databind.json.JsonMapper; import io.github.easy4j.opencli.OpenCliProperties; import io.github.easy4j.opencli.core.OpenCliOutputParser; import io.github.easy4j.opencli.core.OpenCliResult; import io.github.easy4j.opencli.exception.OpenCliExecutableFailureException; import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; +import io.github.easy4j.opencli.exception.OpenCliRemoteProtocolException; import io.github.easy4j.opencli.parser.OpenCliParsedFields; import io.github.easy4j.opencli.util.OpenCliStrings; import java.util.Objects; @@ -41,6 +43,9 @@ public final class OpenCliRemoteAgentHttpClient implements AutoCloseable { private static final JsonMapper MAPPER = new JsonMapper(); + private static final ObjectReader ENVELOPE_READER = MAPPER.reader().with( + DeserializationFeature.FAIL_ON_TRAILING_TOKENS, + DeserializationFeature.FAIL_ON_READING_DUP_TREE_KEY); private final OpenCliProperties properties; @@ -158,28 +163,35 @@ private static OpenCliExecutableFailureException failure(String message, String private OpenCliResult mapResponse(String respBody, String correlationId) throws com.fasterxml.jackson.core.JsonProcessingException { String rawCapture = captureRawIfEnabled(respBody); - AgentCollectEnvelope env; + JsonNode envelope; try { - env = MAPPER.readValue(respBody, AgentCollectEnvelope.class); + envelope = ENVELOPE_READER.readTree(respBody); } catch (com.fasterxml.jackson.core.JsonProcessingException e) { log.warn("Agent response envelope parse failed correlationId={} responseChars={}", correlationId, respBody.length()); - throw failure("Failed to parse agent response envelope", correlationId); + throw new OpenCliRemoteProtocolException("Failed to parse agent response envelope", correlationId); } - if (Objects.isNull(env)) { - log.warn("Agent response envelope missing correlationId={} responseChars={}", + if (Objects.isNull(envelope) || !envelope.isObject() || !envelope.path("success").isBoolean()) { + log.warn("Agent response envelope status invalid correlationId={} responseChars={}", correlationId, respBody.length()); - throw failure("Missing agent response envelope", correlationId); + throw new OpenCliRemoteProtocolException("Invalid agent response envelope status", correlationId); } - boolean success = Objects.nonNull(env.success) && env.success; - String err = Objects.isNull(env.error) ? "" : env.error; + JsonNode error = envelope.path("error"); + if (!error.isMissingNode() && !error.isNull() && !error.isTextual()) { + log.warn("Agent response envelope error field invalid correlationId={} responseChars={}", + correlationId, respBody.length()); + throw new OpenCliRemoteProtocolException("Invalid agent response envelope error field", correlationId); + } + boolean success = envelope.path("success").booleanValue(); + String err = error.isTextual() ? error.asText() : ""; + JsonNode items = envelope.path("items"); String stdout; - if (Objects.isNull(env.items) || env.items.isNull()) { + if (items.isMissingNode() || items.isNull()) { stdout = "[]"; - } else if (env.items.isArray()) { - stdout = MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(env.items); + } else if (items.isArray()) { + stdout = MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(items); } else { - stdout = env.items.toPrettyString(); + stdout = items.toPrettyString(); } OpenCliParsedFields parsed = OpenCliOutputParser.parseBestEffort(stdout, err); if (!success) { @@ -216,13 +228,4 @@ private String captureRawIfEnabled(String respBody) { return respBody; } - @JsonIgnoreProperties(ignoreUnknown = true) - private static final class AgentCollectEnvelope { - - public Boolean success; - - public JsonNode items; - - public String error; - } } diff --git a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java index 6e8974e..b291029 100644 --- a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java +++ b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java @@ -8,6 +8,7 @@ import io.github.easy4j.opencli.core.OpenCliResult; import io.github.easy4j.opencli.exception.OpenCliExecutableFailureException; import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; +import io.github.easy4j.opencli.exception.OpenCliRemoteProtocolException; import java.io.ByteArrayOutputStream; import java.io.IOException; import java.io.InputStream; @@ -22,6 +23,8 @@ import java.util.regex.Pattern; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; /** * 使用 JDK {@link HttpServer} 模拟 Agent {@code POST /collect},校验 HTTP 客户端与原始报文保留选项。 @@ -157,6 +160,42 @@ void nullEnvelopeUsesSafeCorrelatedParseFailure() throws IOException { } } + @Test + void explicitSuccessfulReplyCanOmitItems() throws IOException { + try (JsonCollectStub stub = JsonCollectStub.start("{\"success\":true,\"extension\":42}"); + OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(baseProps(stub.port()))) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("x").command("y").build(); + OpenCliResult result = client.collect(request); + Assertions.assertTrue(result.isSuccess()); + Assertions.assertEquals("[]", result.getStdout()); + } + } + + @ParameterizedTest + @ValueSource(strings = { + "", + "null", + "[]", + "{\"items\":[]}", + "{\"success\":null}", + "{\"success\":\"true\"}", + "{\"success\":1}", + "{\"success\":true,\"error\":42}", + "{\"success\":false,\"success\":true}", + "{\"success\":true} {\"success\":false}" + }) + void invalidLegacyEnvelopeIsAProtocolFailure(String body) throws IOException { + try (JsonCollectStub stub = JsonCollectStub.start(body); + OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(baseProps(stub.port()))) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("x").command("y").build(); + OpenCliRemoteProtocolException failure = Assertions.assertThrows( + OpenCliRemoteProtocolException.class, () -> client.collect(request)); + Assertions.assertTrue(failure.getMessage().contains("response envelope")); + Assertions.assertTrue(failure.getMessage().contains("correlationId=")); + Assertions.assertNull(failure.getCause()); + } + } + @Test void malformedResponseDoesNotExposeParserSnippetInException() throws IOException { String canary = "parser-secret-" + UUID.randomUUID(); From 4564166b184d480dc0846151740ecbb1700327c4 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:18:15 +0800 Subject: [PATCH 031/105] Reject lossy legacy collect argv before dispatch Refs #5 (cherry picked from commit a5448e1fdc40f26d3931e98bee7919dc7eef1c67) --- README.md | 1 + README.zh-CN.md | 1 + .../harden-opencli-remote-collect/tasks.md | 9 +- .../easy4j/opencli/core/OpenCliExecutor.java | 25 ++- .../opencli/meta/OpenCliExternalClient.java | 2 +- .../remote/OpenCliArgvToCollectParser.java | 146 ++++++------------ .../OpenCliArgvToCollectParserFullTest.java | 14 +- .../OpenCliRemoteAgentHttpClientTest.java | 78 +++++++--- 8 files changed, 146 insertions(+), 130 deletions(-) diff --git a/README.md b/README.md index 3cd3e37..8bf0407 100644 --- a/README.md +++ b/README.md @@ -191,6 +191,7 @@ Notes: - In remote mode the `stdout` is the JSON `items` the agent returned (parsed into line items per `format`), which may differ from local raw subprocess text; `leadingArguments` are local-only and are not injected on the remote path. - A legacy HTTP `/collect` reply must contain a JSON boolean `success`. Invalid envelopes raise `OpenCliRemoteProtocolException`, which extends `OpenCliExecutableFailureException`. A valid reply with `success: true` and omitted or null `items` still returns `[]`. +- Legacy HTTP argv dispatch accepts SDK-listed adapters and one subcommand. Root metadata, Browser sessions, external passthrough, repeated options, `--`, and tokens whose spacing or leading dash cannot be preserved are rejected before HTTP. Place positionals before options. Use local execution for commands that need the original argv. A deployment with its own adapter contract can use the explicit `OpenCliCollectRequest` API. - `execution-target=REMOTE_AGENT_HTTP` makes the availability probe report `SKIPPED_REMOTE_MODE` (treated as startable). diff --git a/README.zh-CN.md b/README.zh-CN.md index 17058d7..5767996 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -190,6 +190,7 @@ cli.gemini().deepResearch("topic", - 远程模式下 `stdout` 为 Agent 返回的 `items` 的 JSON(已按 `format` 解析为行列表),与本地原始子进程文本可能不同;`leadingArguments` 等仅影响本地进程拼装,**远程路径不注入**。 - 旧版 HTTP `/collect` 响应须包含 JSON 布尔字段 `success`。无效响应抛出 `OpenCliRemoteProtocolException`,它继承 `OpenCliExecutableFailureException`。当 `success: true` 且 `items` 缺失或为 null 时,仍返回 `[]`。 +- 旧版 HTTP argv 调用仅接收 SDK 清单中的适配器及其子命令。根命令、Browser 会话、外部程序透传、重复选项、`--` 以及无法保留边界空格或前导短横的参数会在发请求前被拒绝。位置参数应在选项前。需要原样传递 argv 时使用本地执行,已有自定义 Agent 契约时可用显式 `OpenCliCollectRequest` API。 - `execution-target=REMOTE_AGENT_HTTP` 时可用性探测报告 `SKIPPED_REMOTE_MODE`(视为可启动)。 diff --git a/openspec/changes/harden-opencli-remote-collect/tasks.md b/openspec/changes/harden-opencli-remote-collect/tasks.md index ba2364d..aadb8b3 100644 --- a/openspec/changes/harden-opencli-remote-collect/tasks.md +++ b/openspec/changes/harden-opencli-remote-collect/tasks.md @@ -7,7 +7,7 @@ ## 1. 服务端契约与失败测试 - [x] 1.1 固定可控的 legacy `POST /collect` fixture,记录本地桩与上游 CLI 的范围差异。见下方 OC-REMOTE-004 证据。 -- [ ] 1.2 对 Browser/root/external/重复flag/负数/--/空值编写“拒绝且零请求”的测试。 +- [x] 1.2 验证 Browser、根命令、外部透传和旧 DTO 无法保真的输入均在发送前拒绝。见下方 OC-REMOTE-001/002 证据。 - [ ] 1.3 编写 success=false、503、malformed、null、超大body与超时结果未知用例。 ## 2. 最小适配修复 @@ -34,3 +34,10 @@ JDK 17 基线 `5ac4bb1` 的 20 项用例实际执行,7 项失败。缺少或显式设为 null 的 `success` 被当成业务失败。字符串和数字布尔值、数字 `error`、重复状态字段及拼接文档曾被当成成功。修正后,具备布尔状态字段的单个 JSON 对象才会继续映射结果,无效响应通过 `OpenCliRemoteProtocolException` 保留类别和相关 ID。现有异常父类保持兼容。合法的成功响应允许省略或置空 `items`,空结果仍为 `[]`。 定向测试命令为 `-Dtest=OpenCliRemoteAgentHttpClientTest test`。使用各维护线的 Maven 和 JDK,报告位于 `target/surefire-reports`。Body 大小限制、总超时和退出码来源仍由其他任务验收。 + + +## OC-REMOTE-001/002 发请求前校验 + +基线 `cf9360e` 的集成测试中,16 组输入有 15 组未按要求在 HTTP 前拒绝。既有 SDK 适配器名可能和外部透传调用重名,额外测试复现了该路径;改为仅本地执行后,HTTP 桩记录为零请求。正常 npm search 调用仍发送一次,并检查实际 JSON 的 site、command、positional_args 和 args。公开的低层 `collect(OpenCliCollectRequest)` 继续接收应用已经验证过的服务端 DTO。 + +本轮证据来自本地桩和各维护线全量验证,当前 SDK 适配器清单用于限制 argv 路由。各 Agent 部署的实际命令与选项契约仍需验证。 diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java index 9b853ae..fd9c79d 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java @@ -8,6 +8,7 @@ import io.github.easy4j.opencli.exception.OpenCliExecutableFailureException; import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; import io.github.easy4j.opencli.exception.OpenCliTimeoutException; +import io.github.easy4j.opencli.registry.OpenCliAdapterTaxonomy; import io.github.easy4j.opencli.remote.OpenCliArgvToCollectParser; import io.github.easy4j.opencli.remote.OpenCliCollectRequest; import io.github.easy4j.opencli.remote.OpenCliRemoteAgentHttpClient; @@ -55,7 +56,7 @@ public OpenCliExecutor(OpenCliProperties properties, OpenCliProcessRuntime proce /** @param adapterAndRest command and literal values @return execution result */ public OpenCliResult invoke(List adapterAndRest) { - return invokeInternal(adapterAndRest, new OpenCliCancellationToken(), false); + return invokeInternal(adapterAndRest, new OpenCliCancellationToken(), false, false); } /** @@ -67,11 +68,22 @@ public OpenCliResult invoke(List adapterAndRest) { * @return execution result */ public OpenCliResult invoke(List adapterAndRest, OpenCliCancellationToken cancellationToken) { - return invokeInternal(adapterAndRest, Objects.requireNonNull(cancellationToken, "cancellationToken"), true); + return invokeInternal(adapterAndRest, Objects.requireNonNull(cancellationToken, "cancellationToken"), true, false); + } + + /** + * Executes argv whose semantics require a local process, such as external CLI passthrough. + * + * @param argv command and literal values + * @return local execution result + * @throws UnsupportedOperationException when configured for legacy HTTP collect + */ + public OpenCliResult invokeLocalOnly(List argv) { + return invokeInternal(argv, new OpenCliCancellationToken(), false, true); } private OpenCliResult invokeInternal(List adapterAndRest, - OpenCliCancellationToken cancellationToken, boolean explicitCancellation) { + OpenCliCancellationToken cancellationToken, boolean explicitCancellation, boolean localOnly) { long submittedAtNanos = System.nanoTime(); long timeoutMillis = properties.getCommandTimeoutMillis(); List tokens = OpenCliArgSupport.snapshotValues(adapterAndRest, "adapterAndRest"); @@ -82,9 +94,16 @@ private OpenCliResult invokeInternal(List adapterAndRest, throw new IllegalArgumentException("adapterAndRest[0] command identifier must not be blank"); } if (properties.getExecutionTarget() == OpenCliExecutionTarget.REMOTE_AGENT_HTTP) { + if (localOnly) { + throw new UnsupportedOperationException("This command requires local process execution"); + } if (explicitCancellation) { throw new UnsupportedOperationException("Explicit process cancellation is local-only for legacy collect"); } + String site = tokens.get(0); + if (!OpenCliAdapterTaxonomy.BROWSER_IDS.contains(site) && !OpenCliAdapterTaxonomy.isDesktopAdapter(site)) { + throw new IllegalArgumentException("Legacy collect requires an adapter registered in the SDK"); + } OpenCliCollectRequest req = OpenCliArgvToCollectParser.parse(tokens, properties.getRemoteOutputFormat(), properties.getRemoteCollectMode(), properties.getRemoteCdpEndpoint()); return remoteAgent().collect(req); diff --git a/src/main/java/io/github/easy4j/opencli/meta/OpenCliExternalClient.java b/src/main/java/io/github/easy4j/opencli/meta/OpenCliExternalClient.java index 23d18b5..b23d130 100644 --- a/src/main/java/io/github/easy4j/opencli/meta/OpenCliExternalClient.java +++ b/src/main/java/io/github/easy4j/opencli/meta/OpenCliExternalClient.java @@ -87,7 +87,7 @@ public OpenCliResult passthrough(String externalCliName, List passthroug if (passthroughArgs != null) { tokens.addAll(passthroughArgs); } - return executor.invoke(tokens); + return executor.invokeLocalOnly(tokens); } /** diff --git a/src/main/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParser.java b/src/main/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParser.java index b73e57b..bd22934 100644 --- a/src/main/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParser.java +++ b/src/main/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParser.java @@ -4,48 +4,17 @@ import java.util.ArrayList; import java.util.LinkedHashMap; import java.util.List; -import java.util.Locale; import java.util.Map; import java.util.Objects; +import java.util.regex.Pattern; import lombok.extern.slf4j.Slf4j; -/** - * 将 {@link io.github.easy4j.opencli.core.OpenCliExecutor#invoke(List)} 使用的 argv 列表 - *({@code [adapter, command, ...]}) best-effort 映射为 Agent {@link OpenCliCollectRequest}。 - * 规则:前两个 token 为 {@code site}、{@code command};其后从左到右扫描: - *
    - *
  • {@code -f} / {@code --format} 及其下一 token 写入请求 {@code format},不进入 args;
  • - *
  • {@code --key=value} 或 {@code --key} + 下一非选项值 → 进入 {@code args}(key 无 {@code --} 前缀);
  • - *
  • 单独 {@code --flag}(下一 token 以 {@code -} 开头或缺失)→ {@code args[flag]=true};
  • - *
  • 其余 token 按顺序进入 {@code positional_args}。
  • - *
- * Agent 会自行追加 {@code -f <format>},故本解析器会消费调用方已写的 {@code -f},避免重复。 - */ -@Slf4j/** - - * Best-effort mapping from the argv list used by - * {@link io.github.easy4j.opencli.core.OpenCliExecutor#invoke(List)} - * ({@code [adapter, command, ...]}) to an Agent {@link OpenCliCollectRequest}. - * - *

Parsing rules: the first two tokens are {@code site} and {@code command}; - * subsequent tokens are scanned left-to-right:

- *
    - *
  • {@code -f} / {@code --format} and its next token are written to {@code format}, not args;
  • - *
  • {@code --key=value} or {@code --key} + next non-option value go to {@code args} (key without {@code --} prefix);
  • - *
  • Standalone {@code --flag} (next token starts with {@code -} or is absent) goes to {@code args[flag]=true};
  • - *
  • All other tokens go to {@code positional_args} in order.
  • - *
- - * - - * @author Loong Wan - - * @since 3.0.0 - - */ - +/** Maps the supported adapter argv grammar to the legacy HTTP collect DTO. */ +@Slf4j public final class OpenCliArgvToCollectParser { + private static final Pattern IDENTIFIER = Pattern.compile("[A-Za-z0-9][A-Za-z0-9_-]*"); + private OpenCliArgvToCollectParser() { } @@ -66,75 +35,53 @@ public static OpenCliCollectRequest parse( throw new IllegalArgumentException( "remote invoke requires at least [adapter, command], got " + adapterAndRest.size() + " tokens"); } - String site = adapterAndRest.get(0).trim(); - String command = adapterAndRest.get(1).trim(); - if (OpenCliStrings.isBlank(site) || OpenCliStrings.isBlank(command)) { - throw new IllegalArgumentException("adapter and command must not be blank"); - } + String site = requireIdentifier(adapterAndRest.get(0)); + String command = requireIdentifier(adapterAndRest.get(1)); String format = OpenCliStrings.isNotBlank(defaultFormat) ? defaultFormat.trim() : "json"; String mode = OpenCliStrings.isNotBlank(defaultMode) ? defaultMode.trim() : "cdp"; Map args = new LinkedHashMap<>(); List positional = new ArrayList<>(); + boolean formatSpecified = false; - int i = 2; - while (i < adapterAndRest.size()) { - String raw = adapterAndRest.get(i); - if (Objects.isNull(raw) || raw.isEmpty()) { - log.warn("Skipping null or empty argv token at index={}", i); - i++; - continue; + int index = 2; + while (index < adapterAndRest.size()) { + String token = adapterAndRest.get(index++); + if (Objects.isNull(token) || token.isEmpty() || !token.equals(token.trim())) { + throw new IllegalArgumentException("Legacy collect cannot preserve an empty or padded token"); } - String t = raw.trim(); - if (t.isEmpty()) { - i++; - continue; - } - - if ("-f".equals(t) || "--format".equals(t)) { - if (i + 1 >= adapterAndRest.size()) { - throw new IllegalArgumentException("-f requires a value"); + if (!token.startsWith("-")) { + if (formatSpecified || !args.isEmpty()) { + throw new IllegalArgumentException("Legacy collect requires positional arguments before options"); } - format = Objects.requireNonNull(adapterAndRest.get(i + 1)).trim(); - i += 2; + positional.add(token); continue; } - if (t.startsWith("--")) { - if (t.contains("=")) { - int eq = t.indexOf('='); - String key = normalizeKey(t.substring(2, eq)); - String val = t.substring(eq + 1); - if (isFormatKey(key)) { - format = val; - } else { - args.put(key, val); - } - i++; - continue; - } - String key = normalizeKey(t.substring(2)); - if (isFormatKey(key)) { - if (i + 1 >= adapterAndRest.size()) { - throw new IllegalArgumentException("--" + key + " requires a value"); - } - format = adapterAndRest.get(i + 1).trim(); - i += 2; - continue; - } - String next = i + 1 < adapterAndRest.size() ? adapterAndRest.get(i + 1) : null; - if (Objects.nonNull(next) && !next.trim().startsWith("-")) { - args.put(key, next.trim()); - i += 2; - } else { - args.put(key, Boolean.TRUE); - i++; + int separator = token.indexOf('='); + String option = separator < 0 ? token : token.substring(0, separator); + boolean shortFormat = "-f".equals(option) && separator < 0; + if (!shortFormat && !option.startsWith("--")) { + throw new IllegalArgumentException("Legacy collect does not support this option syntax"); + } + String key = shortFormat ? "format" : requireIdentifier(option.substring(2)); + boolean isFormat = "format".equals(key) || "f".equals(key); + Object value = Boolean.TRUE; + if (separator >= 0) { + value = requireValue(token.substring(separator + 1)); + } else if (index < adapterAndRest.size() + && (Objects.isNull(adapterAndRest.get(index)) || !adapterAndRest.get(index).startsWith("-"))) { + value = requireValue(adapterAndRest.get(index++)); + } + if (isFormat) { + if (formatSpecified || !(value instanceof String)) { + throw new IllegalArgumentException("Legacy collect requires a single explicit format value"); } - continue; + format = (String) value; + formatSpecified = true; + } else if (Objects.nonNull(args.putIfAbsent(key, value))) { + throw new IllegalArgumentException("Legacy collect cannot preserve a repeated option"); } - - positional.add(t); - i++; } OpenCliCollectRequest.OpenCliCollectRequestBuilder b = @@ -149,14 +96,17 @@ public static OpenCliCollectRequest parse( return request; } - private static String normalizeKey(String key) { - if (Objects.isNull(key) || key.isEmpty()) { - throw new IllegalArgumentException("empty option key"); + private static String requireIdentifier(String value) { + if (Objects.isNull(value) || !IDENTIFIER.matcher(value).matches()) { + throw new IllegalArgumentException("Legacy collect requires a valid adapter, command or option identifier"); } - return key.toLowerCase(Locale.ROOT); + return value; } - private static boolean isFormatKey(String key) { - return "format".equals(key) || "f".equals(key); + private static String requireValue(String value) { + if (Objects.isNull(value) || value.isEmpty() || !value.equals(value.trim()) || value.startsWith("-")) { + throw new IllegalArgumentException("Legacy collect cannot preserve this option value"); + } + return value; } } diff --git a/src/test/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParserFullTest.java b/src/test/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParserFullTest.java index bd585a9..4f80fa6 100644 --- a/src/test/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParserFullTest.java +++ b/src/test/java/io/github/easy4j/opencli/remote/OpenCliArgvToCollectParserFullTest.java @@ -30,17 +30,15 @@ void shouldParseDashDashFormatEquals() { } @Test - void shouldSkipNullTokens() { - List argv = new ArrayList<>(Arrays.asList("npm", "search", null, "react")); - OpenCliCollectRequest req = OpenCliArgvToCollectParser.parse(argv, "json", "cdp", ""); - assertTrue(req.getPositionalArgs().contains("react")); + void shouldRejectNullTokens() { + assertThrows(IllegalArgumentException.class, () -> OpenCliArgvToCollectParser.parse( + Arrays.asList("npm", "search", null, "react"), "json", "cdp", "")); } @Test - void shouldSkipEmptyTokens() { - OpenCliCollectRequest req = OpenCliArgvToCollectParser.parse( - Arrays.asList("npm", "search", "", "react"), "json", "cdp", ""); - assertTrue(req.getPositionalArgs().contains("react")); + void shouldRejectEmptyTokens() { + assertThrows(IllegalArgumentException.class, () -> OpenCliArgvToCollectParser.parse( + Arrays.asList("npm", "search", "", "react"), "json", "cdp", "")); } @Test diff --git a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java index b291029..89249d3 100644 --- a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java +++ b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java @@ -6,19 +6,23 @@ import io.github.easy4j.opencli.OpenCliExecutionTarget; import io.github.easy4j.opencli.OpenCliProperties; import io.github.easy4j.opencli.core.OpenCliResult; +import io.github.easy4j.opencli.core.OpenCliExecutor; import io.github.easy4j.opencli.exception.OpenCliExecutableFailureException; import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; import io.github.easy4j.opencli.exception.OpenCliRemoteProtocolException; +import io.github.easy4j.opencli.meta.OpenCliExternalClient; import java.io.ByteArrayOutputStream; import java.io.IOException; -import java.io.InputStream; import java.io.OutputStream; import java.io.PrintStream; import java.io.PrintWriter; import java.io.StringWriter; import java.net.InetSocketAddress; import java.nio.charset.StandardCharsets; +import java.util.Arrays; +import java.util.Scanner; import java.util.UUID; +import java.util.concurrent.atomic.AtomicInteger; import java.util.regex.Matcher; import java.util.regex.Pattern; import org.junit.jupiter.api.Assertions; @@ -160,6 +164,47 @@ void nullEnvelopeUsesSafeCorrelatedParseFailure() throws IOException { } } + @Test + void losslessAdapterRequestReachesLegacyEndpoint() throws IOException { + try (JsonCollectStub stub = JsonCollectStub.start("{\"success\":true}"); + OpenCliExecutor executor = new OpenCliExecutor(baseProps(stub.port()))) { + OpenCliResult result = executor.invoke("npm", "search", "react components", "--limit", "5"); + Assertions.assertTrue(result.isSuccess()); + Assertions.assertEquals(1, stub.requests()); + Assertions.assertTrue(stub.requestBody.contains("\"site\":\"npm\"")); + Assertions.assertTrue(stub.requestBody.contains("\"command\":\"search\"")); + Assertions.assertTrue(stub.requestBody.contains("\"positional_args\":[\"react components\"]")); + Assertions.assertTrue(stub.requestBody.contains("\"args\":{\"limit\":\"5\"}")); + } + } + + @ParameterizedTest + @ValueSource(strings = { + "browser|session-a|state", "list|-f|json", "external|list", "unverified-tool|version", + "npm|search|--tag|one|--tag=two", "npm|search|--|react", "npm|search|--limit|-1", + "npm|search|--limit=-1", "npm|search|", "npm|search|--query=", "npm|search|--query| padded ", + "npm|search|-f|json|--format=yaml", "npm|search|--format|--verbose", + "npm|search|-v", "npm|search|--limit|5|react", " npm|search" + }) + void unrepresentableArgvIsRejectedBeforeHttp(String input) throws IOException { + try (JsonCollectStub stub = JsonCollectStub.start("{\"success\":true}"); + OpenCliExecutor executor = new OpenCliExecutor(baseProps(stub.port()))) { + Assertions.assertThrows(IllegalArgumentException.class, () -> executor.invoke(input.split("\\|", -1))); + Assertions.assertEquals(0, stub.requests()); + } + } + + @Test + void externalPassthroughCannotBeRoutedAsAnAdapter() throws IOException { + try (JsonCollectStub stub = JsonCollectStub.start("{\"success\":true}"); + OpenCliExecutor executor = new OpenCliExecutor(baseProps(stub.port()))) { + OpenCliExternalClient external = new OpenCliExternalClient(executor); + Assertions.assertThrows(UnsupportedOperationException.class, + () -> external.passthrough("npm", Arrays.asList("search", "react"))); + Assertions.assertEquals(0, stub.requests()); + } + } + @Test void explicitSuccessfulReplyCanOmitItems() throws IOException { try (JsonCollectStub stub = JsonCollectStub.start("{\"success\":true,\"extension\":42}"); @@ -242,6 +287,8 @@ private static final class JsonCollectStub implements AutoCloseable { private final HttpServer server; private final int port; + private final AtomicInteger requestCount = new AtomicInteger(); + private volatile String requestBody; private JsonCollectStub(HttpServer server, int port) { this.server = server; @@ -261,17 +308,22 @@ static JsonCollectStub start(String jsonBody) throws IOException { static JsonCollectStub start(String jsonBody, int status) throws IOException { byte[] bytes = jsonBody.getBytes(StandardCharsets.UTF_8); HttpServer server = HttpServer.create(new InetSocketAddress(0), 0); + JsonCollectStub stub = new JsonCollectStub(server, server.getAddress().getPort()); server.createContext( "/collect", new HttpHandler() { @Override public void handle(HttpExchange exchange) throws IOException { + stub.requestCount.incrementAndGet(); if (!"POST".equalsIgnoreCase(exchange.getRequestMethod())) { exchange.sendResponseHeaders(405, -1); exchange.close(); return; } - drain(exchange.getRequestBody()); + try (Scanner request = new Scanner(exchange.getRequestBody(), StandardCharsets.UTF_8.name())) { + request.useDelimiter("\\A"); + stub.requestBody = request.hasNext() ? request.next() : ""; + } exchange .getResponseHeaders() .set("Content-Type", "application/json; charset=utf-8"); @@ -282,35 +334,23 @@ public void handle(HttpExchange exchange) throws IOException { } }); server.start(); - int port = server.getAddress().getPort(); - return new JsonCollectStub(server, port); + return stub; } int port() { return port; } + int requests() { + return requestCount.get(); + } + @Override public void close() { server.stop(0); } } - /** JDK 8 兼容:丢弃请求体。 */ - private static void drain(InputStream in) throws IOException { - if (in == null) { - return; - } - byte[] buf = new byte[8192]; - try { - while (in.read(buf) != -1) { - // discard - } - } finally { - in.close(); - } - } - /** * close 幂等;close 之后 collect 抛 {@link IllegalStateException}。 */ From a595434f2cf47f07b6d92f086e39122a96a68f7f Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:19:37 +0800 Subject: [PATCH 032/105] Preserve executor overrides for local passthrough Refs #5 (cherry picked from commit 624e7586da0317e4ae36fa06b1e2d4b01d91004d) --- .../easy4j/opencli/core/OpenCliExecutor.java | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java index fd9c79d..ad603f7 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java @@ -56,7 +56,7 @@ public OpenCliExecutor(OpenCliProperties properties, OpenCliProcessRuntime proce /** @param adapterAndRest command and literal values @return execution result */ public OpenCliResult invoke(List adapterAndRest) { - return invokeInternal(adapterAndRest, new OpenCliCancellationToken(), false, false); + return invokeInternal(adapterAndRest, new OpenCliCancellationToken(), false); } /** @@ -68,7 +68,7 @@ public OpenCliResult invoke(List adapterAndRest) { * @return execution result */ public OpenCliResult invoke(List adapterAndRest, OpenCliCancellationToken cancellationToken) { - return invokeInternal(adapterAndRest, Objects.requireNonNull(cancellationToken, "cancellationToken"), true, false); + return invokeInternal(adapterAndRest, Objects.requireNonNull(cancellationToken, "cancellationToken"), true); } /** @@ -79,11 +79,14 @@ public OpenCliResult invoke(List adapterAndRest, OpenCliCancellationToke * @throws UnsupportedOperationException when configured for legacy HTTP collect */ public OpenCliResult invokeLocalOnly(List argv) { - return invokeInternal(argv, new OpenCliCancellationToken(), false, true); + if (properties.getExecutionTarget() == OpenCliExecutionTarget.REMOTE_AGENT_HTTP) { + throw new UnsupportedOperationException("This command requires local process execution"); + } + return invoke(argv); } private OpenCliResult invokeInternal(List adapterAndRest, - OpenCliCancellationToken cancellationToken, boolean explicitCancellation, boolean localOnly) { + OpenCliCancellationToken cancellationToken, boolean explicitCancellation) { long submittedAtNanos = System.nanoTime(); long timeoutMillis = properties.getCommandTimeoutMillis(); List tokens = OpenCliArgSupport.snapshotValues(adapterAndRest, "adapterAndRest"); @@ -94,9 +97,6 @@ private OpenCliResult invokeInternal(List adapterAndRest, throw new IllegalArgumentException("adapterAndRest[0] command identifier must not be blank"); } if (properties.getExecutionTarget() == OpenCliExecutionTarget.REMOTE_AGENT_HTTP) { - if (localOnly) { - throw new UnsupportedOperationException("This command requires local process execution"); - } if (explicitCancellation) { throw new UnsupportedOperationException("Explicit process cancellation is local-only for legacy collect"); } From c3789a279de96296d8ccefe66d3870cdaa94003b Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:26:12 +0800 Subject: [PATCH 033/105] Bound decoded legacy collect response bodies Refs #5 (cherry picked from commit bf05ba69dbaaa27002c874ce72b4bee2707c3f64) --- README.md | 1 + README.zh-CN.md | 1 + .../harden-opencli-remote-collect/tasks.md | 7 + .../easy4j/opencli/OpenCliProperties.java | 2 + .../OpenCliRemoteResponseLimitException.java | 23 +++ .../remote/OpenCliRemoteAgentHttpClient.java | 53 ++++++- .../OpenCliRemoteAgentHttpClientTest.java | 145 +++++++++++++++++- 7 files changed, 224 insertions(+), 8 deletions(-) create mode 100644 src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteResponseLimitException.java diff --git a/README.md b/README.md index 8bf0407..6feea1c 100644 --- a/README.md +++ b/README.md @@ -186,6 +186,7 @@ Configuration is object-based via `OpenCliProperties`: | `remoteOutputFormat` | `json` | Output format requested from the agent | | `remoteCdpEndpoint` | — | Optional CDP endpoint overriding the agent default | | `remoteCaptureRawHttpResponse` | `false` | Keep the raw HTTP body in `OpenCliResult#getRemoteRawHttpBody()` (large responses — use with care) | +| `maxRemoteResponseBytes` | `10485760` | Positive byte limit after HTTP decompression. An oversized response raises `OpenCliRemoteResponseLimitException` with its HTTP status and limit. Raw capture only applies to accepted bodies. | Notes: diff --git a/README.zh-CN.md b/README.zh-CN.md index 5767996..0fefdef 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -185,6 +185,7 @@ cli.gemini().deepResearch("topic", | `remoteOutputFormat` | `json` | 向 Agent 请求的输出格式 | | `remoteCdpEndpoint` | — | 可选,覆盖 Agent 默认 CDP 端点 | | `remoteCaptureRawHttpResponse` | `false` | 在 `OpenCliResult#getRemoteRawHttpBody()` 中保留原始 HTTP 报文(大响应请谨慎开启) | +| `maxRemoteResponseBytes` | `10485760` | HTTP 解压后的响应体字节上限,须为正数。超限抛出 `OpenCliRemoteResponseLimitException`,含 HTTP 状态和上限。原文捕获受同一上限约束。 | 注意事项: diff --git a/openspec/changes/harden-opencli-remote-collect/tasks.md b/openspec/changes/harden-opencli-remote-collect/tasks.md index aadb8b3..6061024 100644 --- a/openspec/changes/harden-opencli-remote-collect/tasks.md +++ b/openspec/changes/harden-opencli-remote-collect/tasks.md @@ -41,3 +41,10 @@ JDK 17 基线 `5ac4bb1` 的 20 项用例实际执行,7 项失败。缺少或 基线 `cf9360e` 的集成测试中,16 组输入有 15 组未按要求在 HTTP 前拒绝。既有 SDK 适配器名可能和外部透传调用重名,额外测试复现了该路径;改为仅本地执行后,HTTP 桩记录为零请求。正常 npm search 调用仍发送一次,并检查实际 JSON 的 site、command、positional_args 和 args。公开的低层 `collect(OpenCliCollectRequest)` 继续接收应用已经验证过的服务端 DTO。 本轮证据来自本地桩和各维护线全量验证,当前 SDK 适配器清单用于限制 argv 路由。各 Agent 部署的实际命令与选项契约仍需验证。 + + +## OC-REMOTE-005 响应体预算 + +JDK 17 基线在 42 项 HTTP 用例中有 4 项失败,覆盖多字节响应超出一字节、HTTP 200 和 503 的分块响应,以及 gzip 解压超限。修改复用现有 Unirest 的原始响应流,从解压后的流读取至上限。读取超限检测只需额外一个字节,超限后由 Unirest 释放响应连接。既有整包读取 API 无法在流尚未结束时执行这一限制。分块桩在收到结果前保持响应开启,验证客户端不等待 EOF。 + +默认上限为 10 MiB,可通过 `maxRemoteResponseBytes` 配置正数。异常保留 HTTP 状态、上限和相关 ID。启用原文捕获的客户端也无法取得超限内容。补充验证恰好满足预算、声明字符集、无效配置零请求以及超限后同一客户端继续执行。总超时、结果不确定性和认证 header 仍待相应场景验收。 diff --git a/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java b/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java index 4f9eabf..0566c1b 100644 --- a/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java +++ b/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java @@ -72,6 +72,8 @@ public class OpenCliProperties { * 本地模式无效果。大响应时请谨慎开启。 */ private boolean remoteCaptureRawHttpResponse = false; + /** Maximum decoded HTTP response body bytes accepted from a remote Agent. */ + private int maxRemoteResponseBytes = 10 * 1024 * 1024; /** * OpenCLI 可执行文件名或绝对路径;默认假定已在 {@code PATH} 中。 diff --git a/src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteResponseLimitException.java b/src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteResponseLimitException.java new file mode 100644 index 0000000..dd0efd6 --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteResponseLimitException.java @@ -0,0 +1,23 @@ +package io.github.easy4j.opencli.exception; + +import lombok.Getter; + +/** 远端 HTTP 响应体超出允许字节数,保留 HTTP 状态及上限。 */ +@Getter +public final class OpenCliRemoteResponseLimitException extends OpenCliExecutableFailureException { + + private final int httpStatus; + private final int maxResponseBytes; + + /** + * @param httpStatus HTTP 响应状态码 + * @param maxResponseBytes 客户端允许读取的最大响应字节数 + * @param correlationId SDK 请求关联标识 + */ + public OpenCliRemoteResponseLimitException(int httpStatus, int maxResponseBytes, String correlationId) { + super("Agent HTTP response body exceeded " + maxResponseBytes + " bytes, status=" + + httpStatus + " correlationId=" + correlationId, null); + this.httpStatus = httpStatus; + this.maxResponseBytes = maxResponseBytes; + } +} diff --git a/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java index 130b4be..ead42a6 100644 --- a/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java +++ b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java @@ -10,14 +10,22 @@ import io.github.easy4j.opencli.exception.OpenCliExecutableFailureException; import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; import io.github.easy4j.opencli.exception.OpenCliRemoteProtocolException; +import io.github.easy4j.opencli.exception.OpenCliRemoteResponseLimitException; import io.github.easy4j.opencli.parser.OpenCliParsedFields; import io.github.easy4j.opencli.util.OpenCliStrings; +import java.io.ByteArrayOutputStream; +import java.io.IOException; +import java.io.InputStream; +import java.nio.charset.Charset; import java.util.Objects; +import java.util.Optional; import java.util.UUID; import kong.unirest.HttpResponse; -import kong.unirest.Unirest; +import kong.unirest.RawResponse; +import kong.unirest.UnrecoverableException; import kong.unirest.UnirestException; import lombok.extern.slf4j.Slf4j; +import org.apache.http.entity.ContentType; /** * 调用 opencli-admin 边缘 Agent 的 HTTP {@code POST /collect}。 @@ -74,6 +82,10 @@ public OpenCliResult collect(OpenCliCollectRequest request) { } String url = base.trim().replaceAll("/+$", "") + "/collect"; int timeout = resolveTimeoutMillis(); + int maxResponseBytes = properties.getMaxRemoteResponseBytes(); + if (maxResponseBytes <= 0) { + throw new IllegalArgumentException("maxRemoteResponseBytes must be positive"); + } String correlationId = UUID.randomUUID().toString(); String bodyJson; try { @@ -83,16 +95,21 @@ public OpenCliResult collect(OpenCliCollectRequest request) { throw failure("Failed to serialize collect request", correlationId); } try { - HttpResponse response = + HttpResponse> response = transport() .post(url) .connectTimeout(timeout) .socketTimeout(timeout) .header("Content-Type", "application/json; charset=UTF-8") .body(bodyJson) - .asString(); + .asObject(raw -> readBoundedBody(raw, maxResponseBytes)); int status = response.getStatus(); - String respBody = Objects.isNull(response.getBody()) ? "" : response.getBody(); + if (response.getParsingError().isPresent()) { + log.warn("Agent HTTP body read failed correlationId={} status={}", correlationId, status); + throw failure("Agent HTTP I/O error", correlationId); + } + String respBody = response.getBody().orElseThrow( + () -> new OpenCliRemoteResponseLimitException(status, maxResponseBytes, correlationId)); if (status < 200 || status >= 300) { log.warn("Agent HTTP non-2xx correlationId={} status={} responseChars={}", correlationId, status, respBody.length()); @@ -148,6 +165,34 @@ public void close() { } } + private static Optional readBoundedBody(RawResponse response, int limit) { + try { + // Unirest owns the response stream. Closing it here can drain an oversized HTTP entity. + InputStream input = response.getContent(); + byte[] buffer = new byte[Math.min(8192, limit)]; + ByteArrayOutputStream body = new ByteArrayOutputStream(buffer.length); + while (true) { + int remaining = limit - body.size(); + int length = (int) Math.min(buffer.length, (long) remaining + 1); + int read = input.read(buffer, 0, length); + if (read < 0) { + break; + } + if (read > remaining) { + return Optional.empty(); + } + body.write(buffer, 0, read); + } + String contentType = response.getContentType(); + Charset charset = OpenCliStrings.isBlank(contentType) ? null : ContentType.parse(contentType).getCharset(); + String encoding = Objects.nonNull(charset) ? charset.name() : response.getConfig().getDefaultResponseEncoding(); + return Optional.of(body.toString(encoding)); + } catch (IOException | RuntimeException exception) { + // Avoid Unirest's fallback, which otherwise retries by reading the full body for diagnostics. + throw new UnrecoverableException(exception); + } + } + private int resolveTimeoutMillis() { long timeoutMs = properties.getCommandTimeoutMillis(); if (timeoutMs <= 0) { diff --git a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java index 89249d3..6fcb455 100644 --- a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java +++ b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java @@ -10,6 +10,7 @@ import io.github.easy4j.opencli.exception.OpenCliExecutableFailureException; import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; import io.github.easy4j.opencli.exception.OpenCliRemoteProtocolException; +import io.github.easy4j.opencli.exception.OpenCliRemoteResponseLimitException; import io.github.easy4j.opencli.meta.OpenCliExternalClient; import java.io.ByteArrayOutputStream; import java.io.IOException; @@ -19,12 +20,16 @@ import java.io.StringWriter; import java.net.InetSocketAddress; import java.nio.charset.StandardCharsets; +import java.time.Duration; import java.util.Arrays; import java.util.Scanner; import java.util.UUID; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; import java.util.concurrent.atomic.AtomicInteger; import java.util.regex.Matcher; import java.util.regex.Pattern; +import java.util.zip.GZIPOutputStream; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; import org.junit.jupiter.params.ParameterizedTest; @@ -95,6 +100,132 @@ void collectFailureIncludesRawBodyWhenEnabled() throws IOException { } } + @Test + void permitsABodyAtTheByteLimitAndRejectsOneByteLess() throws IOException { + String body = "{\"success\":true,\"items\":[\"你好\"]}"; + try (JsonCollectStub stub = JsonCollectStub.start(body)) { + OpenCliProperties props = baseProps(stub.port()); + props.setMaxRemoteResponseBytes(body.getBytes(StandardCharsets.UTF_8).length); + props.setRemoteCaptureRawHttpResponse(true); + try (OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(props)) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("npm").command("search").build(); + Assertions.assertEquals(body, client.collect(request).getRemoteRawHttpBody()); + props.setMaxRemoteResponseBytes(props.getMaxRemoteResponseBytes() - 1); + OpenCliRemoteResponseLimitException exception = Assertions.assertThrows( + OpenCliRemoteResponseLimitException.class, () -> client.collect(request)); + Assertions.assertEquals(200, exception.getHttpStatus()); + Assertions.assertEquals(props.getMaxRemoteResponseBytes(), exception.getMaxResponseBytes()); + Assertions.assertNull(exception.getPartialResult()); + props.setMaxRemoteResponseBytes(props.getMaxRemoteResponseBytes() + 1); + Assertions.assertEquals(body, client.collect(request).getRemoteRawHttpBody()); + } + } + } + + @ParameterizedTest + @ValueSource(ints = {200, 503}) + void stopsReadingOversizedChunkedBodiesWithoutWaitingForEof(int status) throws IOException { + CountDownLatch release = new CountDownLatch(1); + byte[] prefix = ("{\"success\":true,\"items\":[\"private-body-" + UUID.randomUUID()).getBytes(StandardCharsets.UTF_8); + try (JsonCollectStub stub = JsonCollectStub.start(exchange -> { + exchange.sendResponseHeaders(status, 0); + try (OutputStream output = exchange.getResponseBody()) { + output.write(prefix); + output.flush(); + try { + release.await(10, TimeUnit.SECONDS); + } catch (InterruptedException interrupted) { + Thread.currentThread().interrupt(); + } + } + })) { + try { + OpenCliProperties props = baseProps(stub.port()); + props.setMaxRemoteResponseBytes(24); + props.setCommandTimeoutMillis(8_000); + props.setRemoteCaptureRawHttpResponse(true); + try (OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(props)) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("npm").command("search").build(); + OpenCliRemoteResponseLimitException exception = Assertions.assertTimeoutPreemptively( + Duration.ofSeconds(3), () -> Assertions.assertThrows( + OpenCliRemoteResponseLimitException.class, () -> client.collect(request))); + Assertions.assertEquals(status, exception.getHttpStatus()); + Assertions.assertEquals(24, exception.getMaxResponseBytes()); + Assertions.assertFalse(exception.getMessage().contains("private-body-")); + Assertions.assertNull(exception.getCause()); + Assertions.assertNull(exception.getPartialResult()); + Assertions.assertEquals(1, stub.requests()); + } + } finally { + release.countDown(); + } + } + } + + @Test + void capsDecodedGzipBodyRatherThanCompressedContentLength() throws IOException { + StringBuilder body = new StringBuilder("{\"success\":true,\"items\":[\""); + for (int i = 0; i < 500; i++) { + body.append('a'); + } + body.append("\"]}"); + ByteArrayOutputStream compressed = new ByteArrayOutputStream(); + try (GZIPOutputStream gzip = new GZIPOutputStream(compressed)) { + gzip.write(body.toString().getBytes(StandardCharsets.UTF_8)); + } + Assertions.assertTrue(compressed.size() < 128); + try (JsonCollectStub stub = JsonCollectStub.start(exchange -> { + exchange.getResponseHeaders().set("Content-Encoding", "gzip"); + exchange.sendResponseHeaders(200, compressed.size()); + try (OutputStream output = exchange.getResponseBody()) { + compressed.writeTo(output); + } + })) { + OpenCliProperties props = baseProps(stub.port()); + props.setMaxRemoteResponseBytes(128); + try (OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(props)) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("npm").command("search").build(); + OpenCliRemoteResponseLimitException exception = Assertions.assertThrows( + OpenCliRemoteResponseLimitException.class, () -> client.collect(request)); + Assertions.assertTrue(exception.getMessage().contains("response body exceeded")); + } + } + } + + @Test + void rejectsNonpositiveResponseLimitBeforeHttp() throws IOException { + try (JsonCollectStub stub = JsonCollectStub.start("{\"success\":true}")) { + OpenCliProperties props = baseProps(stub.port()); + props.setMaxRemoteResponseBytes(0); + try (OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(props)) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("npm").command("search").build(); + Assertions.assertThrows(IllegalArgumentException.class, () -> client.collect(request)); + Assertions.assertEquals(0, stub.requests()); + } + } + } + + @Test + void keepsDeclaredCharsetWithinTheResponseLimit() throws IOException { + String body = "{\"success\":true,\"items\":[\"café\"]}"; + byte[] bytes = body.getBytes(StandardCharsets.ISO_8859_1); + try (JsonCollectStub stub = JsonCollectStub.start(exchange -> { + exchange.getResponseHeaders().set("Content-Type", "application/json; charset=ISO-8859-1"); + exchange.sendResponseHeaders(200, bytes.length); + try (OutputStream output = exchange.getResponseBody()) { + output.write(bytes); + } + })) { + OpenCliProperties props = baseProps(stub.port()); + props.setMaxRemoteResponseBytes(bytes.length); + props.setRemoteCaptureRawHttpResponse(true); + try (OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(props)) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("npm").command("search").build(); + Assertions.assertEquals(body, client.collect(request).getRemoteRawHttpBody()); + } + } + } + @Test void nonSuccessHttpResponseDoesNotExposeBodyCanaryInException() throws IOException { String canary = "body-secret-" + UUID.randomUUID(); @@ -307,6 +438,15 @@ static JsonCollectStub start(String jsonBody) throws IOException { static JsonCollectStub start(String jsonBody, int status) throws IOException { byte[] bytes = jsonBody.getBytes(StandardCharsets.UTF_8); + return start(exchange -> { + exchange.sendResponseHeaders(status, bytes.length); + try (OutputStream os = exchange.getResponseBody()) { + os.write(bytes); + } + }); + } + + static JsonCollectStub start(HttpHandler response) throws IOException { HttpServer server = HttpServer.create(new InetSocketAddress(0), 0); JsonCollectStub stub = new JsonCollectStub(server, server.getAddress().getPort()); server.createContext( @@ -327,10 +467,7 @@ public void handle(HttpExchange exchange) throws IOException { exchange .getResponseHeaders() .set("Content-Type", "application/json; charset=utf-8"); - exchange.sendResponseHeaders(status, bytes.length); - try (OutputStream os = exchange.getResponseBody()) { - os.write(bytes); - } + response.handle(exchange); } }); server.start(); From 9aec36c0e2566d126f78bf15b52acef8461963c9 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:33:49 +0800 Subject: [PATCH 034/105] Apply a total budget to legacy HTTP collect Refs #5 (cherry picked from commit 8d826a11a5f56c926c1df4946e07390caa65dc0c) --- README.md | 9 +- README.zh-CN.md | 9 +- .../harden-opencli-remote-collect/tasks.md | 9 +- .../github/easy4j/opencli/OpenCliClient.java | 2 +- .../easy4j/opencli/OpenCliProperties.java | 4 +- .../easy4j/opencli/core/OpenCliExecutor.java | 2 +- .../OpenCliRemoteTimeoutException.java | 24 ++ .../remote/OpenCliRemoteAgentHttpClient.java | 218 ++++++++++-------- .../OpenCliRemoteAgentHttpClientTest.java | 81 +++++++ 9 files changed, 249 insertions(+), 109 deletions(-) create mode 100644 src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteTimeoutException.java diff --git a/README.md b/README.md index 6feea1c..827a4a7 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ Multi-adapter CLI integration SDK for OpenCLI: browser / desktop / public-API ad ### 1.1 What it is -**opencli-java-sdk** integrates Java applications with the [OpenCLI](https://github.com/partme-ai/opencli) multi-adapter CLI ecosystem. It executes `opencli ...` subprocesses via Commons Exec, exposes typed results (`OpenCliResult` / `OpenCliTypedResult`), unified exception semantics, remote HTTP agent support (Unirest) and a center WebSocket reverse-agent client (Java-WebSocket). It compiles and runs on JDK 8. +**opencli-java-sdk** integrates Java applications with the [OpenCLI](https://github.com/partme-ai/opencli) multi-adapter CLI ecosystem. It executes `opencli ...` subprocesses via Commons Exec, exposes typed results (`OpenCliResult` / `OpenCliTypedResult`), unified exception semantics, remote HTTP agent support (Apache HttpClient) and a center WebSocket reverse-agent client (Java-WebSocket). It compiles and runs on JDK 8. ### 1.2 What it is not @@ -73,7 +73,7 @@ Multi-adapter CLI integration SDK for OpenCLI: browser / desktop / public-API ad | JDK | 8+ | 1.0.x line baseline | | Maven | 3.9.16 | Repository Maven Wrapper version | | commons-exec | 1.6.0 | Local subprocess execution | -| Unirest Java | 3.14.5 | Remote agent HTTP | +| Apache HttpClient | Provided by Unirest Java 3.14.5 | Remote agent HTTP | | Java-WebSocket | 1.6.0 | Center WebSocket | | `com.fasterxml.jackson.core:jackson-databind` | 2.18.9 | JSON parsing | | SLF4J | 2.0.18 | Logging facade | @@ -102,7 +102,7 @@ Version-line matrix: | typed wrappers (codex, npm...) | | meta list / validate / plugin / ... | | browser session API (wait, extract...) | -| remote POST {base}/collect (Unirest) | +| remote POST {base}/collect (Apache HttpClient) | | center WebSocket reverse agent | +------------------------------------------+ | @@ -177,7 +177,7 @@ Configuration is object-based via `OpenCliProperties`: | `executionTarget` | `LOCAL_PROCESS` | `LOCAL_PROCESS` or `REMOTE_AGENT_HTTP` | | `executable` | `opencli` | Executable name or absolute path | | `workingDirectory` | — | Subprocess working directory | -| `commandTimeoutMillis` | `300000` | Command timeout (ms; reused as HTTP timeout in remote mode) | +| `commandTimeoutMillis` | `300000` | Command timeout in milliseconds. Remote pool acquisition, connection and response reading share the invocation budget. | | `maxConcurrentExecutions` | `0` | Max concurrent subprocesses (0 = unlimited) | | `startupProbeTimeoutMillis` | `30000` | Availability-probe timeout | | `environment` | `{}` | Extra environment variables (e.g. `OPENCLI_CDP_ENDPOINT`) | @@ -193,6 +193,7 @@ Notes: - In remote mode the `stdout` is the JSON `items` the agent returned (parsed into line items per `format`), which may differ from local raw subprocess text; `leadingArguments` are local-only and are not injected on the remote path. - A legacy HTTP `/collect` reply must contain a JSON boolean `success`. Invalid envelopes raise `OpenCliRemoteProtocolException`, which extends `OpenCliExecutableFailureException`. A valid reply with `success: true` and omitted or null `items` still returns `[]`. - Legacy HTTP argv dispatch accepts SDK-listed adapters and one subcommand. Root metadata, Browser sessions, external passthrough, repeated options, `--`, and tokens whose spacing or leading dash cannot be preserved are rejected before HTTP. Place positionals before options. Use local execution for commands that need the original argv. A deployment with its own adapter contract can use the explicit `OpenCliCollectRequest` API. +- A collect timeout raises `OpenCliRemoteTimeoutException`. After dispatch to the HTTP transport, `isRemoteOutcomeUnknown()` is true. Collect does not automatically retry or follow redirects. - `execution-target=REMOTE_AGENT_HTTP` makes the availability probe report `SKIPPED_REMOTE_MODE` (treated as startable). diff --git a/README.zh-CN.md b/README.zh-CN.md index 0fefdef..e44c56b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -29,7 +29,7 @@ ### 1.1 是什么 -**opencli-java-sdk** 将 Java 应用与 [OpenCLI](https://github.com/partme-ai/opencli) 多适配器 CLI 生态对接。它通过 Commons Exec 执行 `opencli ...` 子进程,提供类型化结果(`OpenCliResult` / `OpenCliTypedResult`)与统一异常语义,并支持远程 HTTP Agent(Unirest)与中心 WebSocket 反向 Agent 客户端(Java-WebSocket)。可在 JDK 8 线编译运行。 +**opencli-java-sdk** 将 Java 应用与 [OpenCLI](https://github.com/partme-ai/opencli) 多适配器 CLI 生态对接。它通过 Commons Exec 执行 `opencli ...` 子进程,提供类型化结果(`OpenCliResult` / `OpenCliTypedResult`)与统一异常语义,并支持远程 HTTP Agent(Apache HttpClient)与中心 WebSocket 反向 Agent 客户端(Java-WebSocket)。可在 JDK 8 线编译运行。 ### 1.2 不是什么 @@ -72,7 +72,7 @@ | JDK | 8+ | 1.0.x 线基线 | | Maven | 3.9.16 | 仓库 Maven Wrapper 版本 | | commons-exec | 1.6.0 | 本地子进程执行 | -| Unirest Java | 3.14.5 | 远程 Agent HTTP | +| Apache HttpClient | 由 Unirest Java 3.14.5 提供 | 远程 Agent HTTP | | Java-WebSocket | 1.6.0 | 中心 WebSocket | | `com.fasterxml.jackson.core:jackson-databind` | 2.18.9 | JSON 解析 | | SLF4J | 2.0.18 | 日志门面 | @@ -101,7 +101,7 @@ | 强类型封装(codex、npm...) | | meta list / validate / plugin / ... | | browser 会话 API(wait、extract...) | -| remote POST {base}/collect(Unirest) | +| remote POST {base}/collect(Apache HttpClient) | | center WebSocket 反向 Agent | +------------------------------------------+ | @@ -176,7 +176,7 @@ cli.gemini().deepResearch("topic", | `executionTarget` | `LOCAL_PROCESS` | `LOCAL_PROCESS` 或 `REMOTE_AGENT_HTTP` | | `executable` | `opencli` | 可执行文件名或绝对路径 | | `workingDirectory` | — | 子进程工作目录 | -| `commandTimeoutMillis` | `300000` | 命令超时(毫秒;远程模式复用为 HTTP 超时) | +| `commandTimeoutMillis` | `300000` | 命令超时(毫秒)。远程连接池等待、建连和读取响应共享调用预算。 | | `maxConcurrentExecutions` | `0` | 最大并发子进程数(0 = 不限) | | `startupProbeTimeoutMillis` | `30000` | 可用性探测超时 | | `environment` | `{}` | 额外环境变量(如 `OPENCLI_CDP_ENDPOINT`) | @@ -192,6 +192,7 @@ cli.gemini().deepResearch("topic", - 远程模式下 `stdout` 为 Agent 返回的 `items` 的 JSON(已按 `format` 解析为行列表),与本地原始子进程文本可能不同;`leadingArguments` 等仅影响本地进程拼装,**远程路径不注入**。 - 旧版 HTTP `/collect` 响应须包含 JSON 布尔字段 `success`。无效响应抛出 `OpenCliRemoteProtocolException`,它继承 `OpenCliExecutableFailureException`。当 `success: true` 且 `items` 缺失或为 null 时,仍返回 `[]`。 - 旧版 HTTP argv 调用仅接收 SDK 清单中的适配器及其子命令。根命令、Browser 会话、外部程序透传、重复选项、`--` 以及无法保留边界空格或前导短横的参数会在发请求前被拒绝。位置参数应在选项前。需要原样传递 argv 时使用本地执行,已有自定义 Agent 契约时可用显式 `OpenCliCollectRequest` API。 +- 远程调用超时抛出 `OpenCliRemoteTimeoutException`。请求提交给 HTTP 传输后,`isRemoteOutcomeUnknown()` 为 true。客户端不会自动重试或跟随重定向。 - `execution-target=REMOTE_AGENT_HTTP` 时可用性探测报告 `SKIPPED_REMOTE_MODE`(视为可启动)。 diff --git a/openspec/changes/harden-opencli-remote-collect/tasks.md b/openspec/changes/harden-opencli-remote-collect/tasks.md index 6061024..c8c7f83 100644 --- a/openspec/changes/harden-opencli-remote-collect/tasks.md +++ b/openspec/changes/harden-opencli-remote-collect/tasks.md @@ -8,7 +8,7 @@ - [x] 1.1 固定可控的 legacy `POST /collect` fixture,记录本地桩与上游 CLI 的范围差异。见下方 OC-REMOTE-004 证据。 - [x] 1.2 验证 Browser、根命令、外部透传和旧 DTO 无法保真的输入均在发送前拒绝。见下方 OC-REMOTE-001/002 证据。 -- [ ] 1.3 编写 success=false、503、malformed、null、超大body与超时结果未知用例。 +- [x] 1.3 验证业务失败、HTTP 503、畸形或 null 响应、响应超限及超时后远端结果未知。见下方 OC-REMOTE-004/005 证据。 ## 2. 最小适配修复 @@ -48,3 +48,10 @@ JDK 17 基线 `5ac4bb1` 的 20 项用例实际执行,7 项失败。缺少或 JDK 17 基线在 42 项 HTTP 用例中有 4 项失败,覆盖多字节响应超出一字节、HTTP 200 和 503 的分块响应,以及 gzip 解压超限。修改复用现有 Unirest 的原始响应流,从解压后的流读取至上限。读取超限检测只需额外一个字节,超限后由 Unirest 释放响应连接。既有整包读取 API 无法在流尚未结束时执行这一限制。分块桩在收到结果前保持响应开启,验证客户端不等待 EOF。 默认上限为 10 MiB,可通过 `maxRemoteResponseBytes` 配置正数。异常保留 HTTP 状态、上限和相关 ID。启用原文捕获的客户端也无法取得超限内容。补充验证恰好满足预算、声明字符集、无效配置零请求以及超限后同一客户端继续执行。总超时、结果不确定性和认证 header 仍待相应场景验收。 + + +## OC-REMOTE-005 持续分块与总预算 + +JDK 17 基线中,chunked 响应每 125 ms 持续发送数据,900 ms 的原套接字超时未能终止调用,测试在 3 秒断言窗口失败。使用现有 Apache HttpClient 的可取消请求后,连接池等待、建连、HTTP 头及有界读取共享一个单调时钟预算。超时只中止当前请求,已提交传输的调用返回远端结果未知,无自动重试。原始预算耗尽且尚未提交时返回未发送。当前响应池可继续处理后续调用,并保留 JVM 信任配置。另有 307 回归验证不会转发采集请求。 + +本轮验证的是 SDK 侧 HTTP 传输与回环 HTTP 桩。真实部署、系统 DNS 解析器或本地解析处理的执行时延,以及认证 header 仍需独立验收。 diff --git a/src/main/java/io/github/easy4j/opencli/OpenCliClient.java b/src/main/java/io/github/easy4j/opencli/OpenCliClient.java index 4e238e3..d919b86 100644 --- a/src/main/java/io/github/easy4j/opencli/OpenCliClient.java +++ b/src/main/java/io/github/easy4j/opencli/OpenCliClient.java @@ -120,7 +120,7 @@ public JimengOpenCliClient jimeng() { /** @return DeepSeek 浏览器适配器客户端 */ /** * 释放底层资源:本地模式为空操作;REMOTE_AGENT_HTTP 模式下关闭 - * 远程传输(实例级 shutdown,不影响 JVM 其它 Unirest 使用方)。 + * 远程 HTTP 连接池(仅释放该实例持有的资源)。 * close 之后远程调用抛 IllegalStateException,本地调用不受影响。 */ @Override diff --git a/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java b/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java index 0566c1b..480e480 100644 --- a/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java +++ b/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java @@ -15,7 +15,7 @@ *

*

* {@link #commandTimeoutMillis} 在本地模式下用于子进程 Watchdog;在 - * {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP} 模式下用作 HTTP 客户端超时上限。 + * {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP} 模式下为连接池等待、建连和读取响应共享的总预算。 *

*/ @Data/** @@ -86,7 +86,7 @@ public class OpenCliProperties { private String workingDirectory; /** - * 单次调用超时(毫秒):本地模式用于子进程 Watchdog;远程模式用于 Agent HTTP 请求。 + * 单次调用超时(毫秒):本地模式用于子进程 Watchdog;远程模式下覆盖 Agent HTTP 传输全过程。 */ private long commandTimeoutMillis = 300_000L; diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java index ad603f7..59c0cfc 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java @@ -106,7 +106,7 @@ private OpenCliResult invokeInternal(List adapterAndRest, } OpenCliCollectRequest req = OpenCliArgvToCollectParser.parse(tokens, properties.getRemoteOutputFormat(), properties.getRemoteCollectMode(), properties.getRemoteCdpEndpoint()); - return remoteAgent().collect(req); + return remoteAgent().collect(req, submittedAtNanos); } CommandLine commandLine = buildCommandLine(tokens); return run(commandLine, timeoutMillis, submittedAtNanos, cancellationToken); diff --git a/src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteTimeoutException.java b/src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteTimeoutException.java new file mode 100644 index 0000000..dcd61b4 --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteTimeoutException.java @@ -0,0 +1,24 @@ +package io.github.easy4j.opencli.exception; + +import lombok.Getter; + +/** Legacy HTTP collect exhausted its time budget before receiving a verified response. */ +@Getter +public final class OpenCliRemoteTimeoutException extends OpenCliExecutableFailureException { + + private final int timeoutMillis; + private final boolean remoteOutcomeUnknown; + + /** + * @param timeoutMillis original HTTP invocation budget + * @param remoteOutcomeUnknown whether the request was submitted to the transport + * @param correlationId SDK request correlation identifier + */ + public OpenCliRemoteTimeoutException(int timeoutMillis, boolean remoteOutcomeUnknown, String correlationId) { + super("Agent HTTP deadline exceeded after " + timeoutMillis + " ms, " + + (remoteOutcomeUnknown ? "remote outcome unknown" : "request not dispatched") + + " correlationId=" + correlationId, null); + this.timeoutMillis = timeoutMillis; + this.remoteOutcomeUnknown = remoteOutcomeUnknown; + } +} diff --git a/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java index ead42a6..4fdef37 100644 --- a/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java +++ b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java @@ -11,43 +11,34 @@ import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; import io.github.easy4j.opencli.exception.OpenCliRemoteProtocolException; import io.github.easy4j.opencli.exception.OpenCliRemoteResponseLimitException; +import io.github.easy4j.opencli.exception.OpenCliRemoteTimeoutException; import io.github.easy4j.opencli.parser.OpenCliParsedFields; import io.github.easy4j.opencli.util.OpenCliStrings; import java.io.ByteArrayOutputStream; import java.io.IOException; import java.io.InputStream; +import java.net.SocketTimeoutException; import java.nio.charset.Charset; +import java.nio.charset.StandardCharsets; import java.util.Objects; import java.util.Optional; import java.util.UUID; -import kong.unirest.HttpResponse; -import kong.unirest.RawResponse; -import kong.unirest.UnrecoverableException; -import kong.unirest.UnirestException; +import java.util.concurrent.ScheduledFuture; +import java.util.concurrent.ScheduledThreadPoolExecutor; +import java.util.concurrent.TimeUnit; import lombok.extern.slf4j.Slf4j; +import org.apache.http.HttpEntity; +import org.apache.http.client.config.RequestConfig; +import org.apache.http.client.methods.CloseableHttpResponse; +import org.apache.http.client.methods.HttpPost; +import org.apache.http.conn.ConnectTimeoutException; import org.apache.http.entity.ContentType; +import org.apache.http.entity.StringEntity; +import org.apache.http.impl.client.CloseableHttpClient; +import org.apache.http.impl.client.HttpClients; -/** - * 调用 opencli-admin 边缘 Agent 的 HTTP {@code POST /collect}。 - *

- * 使用 {@code com.konghq:unirest-java} 3.x(与 openclaw-java-sdk 同系列,且兼容 JDK 8 的 2.3.x 线)。 - *

- */ -@Slf4j/** - - * HTTP client that calls the opencli-admin edge Agent's {@code POST /collect} endpoint. - * - *

Uses {@code com.konghq:unirest-java} 3.x (same series as openclaw-java-sdk, - * compatible with JDK 8 via the 2.3.x line).

- - * - - * @author Loong Wan - - * @since 3.0.0 - - */ - +/** HTTP client for the opencli-admin legacy {@code POST /collect} contract. */ +@Slf4j public final class OpenCliRemoteAgentHttpClient implements AutoCloseable { private static final JsonMapper MAPPER = new JsonMapper(); @@ -55,11 +46,21 @@ public final class OpenCliRemoteAgentHttpClient implements AutoCloseable { DeserializationFeature.FAIL_ON_TRAILING_TOKENS, DeserializationFeature.FAIL_ON_READING_DUP_TREE_KEY); + private static final ScheduledThreadPoolExecutor DEADLINES = new ScheduledThreadPoolExecutor(1, task -> { + Thread thread = new Thread(task, "opencli-http-deadline"); + thread.setDaemon(true); + return thread; + }); + + static { + DEADLINES.setRemoveOnCancelPolicy(true); + } + private final OpenCliProperties properties; private final Object transportLock = new Object(); - private volatile kong.unirest.UnirestInstance transport; - private volatile boolean closed; + private CloseableHttpClient transport; + private boolean closed; /** * @param properties 含 {@code remoteAgentBaseUrl} 等配置 @@ -75,13 +76,24 @@ public OpenCliRemoteAgentHttpClient(OpenCliProperties properties) { * @return 与本地执行语义尽量一致的 {@link OpenCliResult} */ public OpenCliResult collect(OpenCliCollectRequest request) { + return collect(request, System.nanoTime()); + } + + /** + * Collects within the budget of an invocation that has already performed local preparation. + * + * @param request legacy collect request + * @param submittedAtNanos invocation start sampled from this JVM's {@link System#nanoTime()} + * @return the legacy collect result + */ + public OpenCliResult collect(OpenCliCollectRequest request, long submittedAtNanos) { Objects.requireNonNull(request, "request"); String base = properties.getRemoteAgentBaseUrl(); if (OpenCliStrings.isBlank(base)) { throw new IllegalStateException("opencli.remote-agent-base-url must be set for REMOTE_AGENT_HTTP"); } - String url = base.trim().replaceAll("/+$", "") + "/collect"; int timeout = resolveTimeoutMillis(); + long deadline = submittedAtNanos + TimeUnit.MILLISECONDS.toNanos(timeout); int maxResponseBytes = properties.getMaxRemoteResponseBytes(); if (maxResponseBytes <= 0) { throw new IllegalArgumentException("maxRemoteResponseBytes must be positive"); @@ -94,21 +106,34 @@ public OpenCliResult collect(OpenCliCollectRequest request) { log.warn("Agent request serialization failed correlationId={}", correlationId); throw failure("Failed to serialize collect request", correlationId); } + + HttpPost post; try { - HttpResponse> response = - transport() - .post(url) - .connectTimeout(timeout) - .socketTimeout(timeout) - .header("Content-Type", "application/json; charset=UTF-8") - .body(bodyJson) - .asObject(raw -> readBoundedBody(raw, maxResponseBytes)); - int status = response.getStatus(); - if (response.getParsingError().isPresent()) { - log.warn("Agent HTTP body read failed correlationId={} status={}", correlationId, status); - throw failure("Agent HTTP I/O error", correlationId); + post = new HttpPost(base.trim().replaceAll("/+$", "") + "/collect"); + } catch (IllegalArgumentException exception) { + throw failure("Invalid agent HTTP endpoint", correlationId); + } + post.setEntity(new StringEntity(bodyJson, ContentType.APPLICATION_JSON)); + CloseableHttpClient client = transport(); + long remainingNanos = deadline - System.nanoTime(); + if (remainingNanos <= 0) { + throw new OpenCliRemoteTimeoutException(timeout, false, correlationId); + } + int remainingMillis = (int) Math.max(1, TimeUnit.NANOSECONDS.toMillis(remainingNanos)); + post.setConfig(RequestConfig.custom() + .setConnectionRequestTimeout(remainingMillis) + .setConnectTimeout(remainingMillis) + .setSocketTimeout(remainingMillis) + .build()); + + ScheduledFuture abort = DEADLINES.schedule(post::abort, deadline - System.nanoTime(), TimeUnit.NANOSECONDS); + try (CloseableHttpResponse response = client.execute(post)) { + int status = response.getStatusLine().getStatusCode(); + Optional body = readBoundedBody(response.getEntity(), maxResponseBytes); + if (post.isAborted() || deadline - System.nanoTime() <= 0) { + throw new OpenCliRemoteTimeoutException(timeout, true, correlationId); } - String respBody = response.getBody().orElseThrow( + String respBody = body.orElseThrow( () -> new OpenCliRemoteResponseLimitException(status, maxResponseBytes, correlationId)); if (status < 200 || status >= 300) { log.warn("Agent HTTP non-2xx correlationId={} status={} responseChars={}", @@ -116,81 +141,82 @@ public OpenCliResult collect(OpenCliCollectRequest request) { throw failure("Agent HTTP " + status, correlationId); } return mapResponse(respBody, correlationId); - } catch (OpenCliNonZeroExitException e) { - throw e; } catch (com.fasterxml.jackson.core.JsonProcessingException e) { log.warn("Agent response parse failed correlationId={}", correlationId); throw failure("Failed to parse agent response", correlationId); - } catch (UnirestException e) { + } catch (SocketTimeoutException | ConnectTimeoutException e) { + throw new OpenCliRemoteTimeoutException(timeout, true, correlationId); + } catch (IOException | IllegalArgumentException e) { + if (post.isAborted() || deadline - System.nanoTime() <= 0) { + throw new OpenCliRemoteTimeoutException(timeout, true, correlationId); + } log.warn("Agent HTTP I/O failed correlationId={}", correlationId); throw failure("Agent HTTP I/O error", correlationId); + } finally { + abort.cancel(false); } } - /** - * 懒加载本客户端私有的 Unirest 实例({@code Unirest.spawn})—— - * shutdown 只影响自身,不触碰 JVM 全局主实例。 - */ - private kong.unirest.UnirestInstance transport() { - if (closed) { - throw new IllegalStateException("OpenCLI remote agent HTTP transport is closed"); - } - kong.unirest.UnirestInstance instance = transport; - if (Objects.isNull(instance)) { - synchronized (transportLock) { - if (Objects.isNull(transport)) { - transport = kong.unirest.Unirest.spawnInstance(); - } - instance = transport; + private CloseableHttpClient transport() { + synchronized (transportLock) { + if (closed) { + throw new IllegalStateException("OpenCLI remote agent HTTP transport is closed"); + } + if (Objects.isNull(transport)) { + transport = HttpClients.custom() + .useSystemProperties() + .disableAutomaticRetries() + .disableRedirectHandling() + .setMaxConnTotal(200) + .setMaxConnPerRoute(20) + .evictIdleConnections(30, TimeUnit.SECONDS) + .build(); } + return transport; } - return instance; } - /** - * 关闭本客户端的 Unirest 实例(幂等)。close 之后远程调用抛 - * {@link IllegalStateException};JVM 全局主实例不受影响。 - */ + /** Closes this client's HTTP pool and aborts its outstanding requests. */ @Override public void close() { - closed = true; - kong.unirest.UnirestInstance instance = transport; - if (Objects.nonNull(instance)) { - synchronized (transportLock) { - instance = transport; - } + CloseableHttpClient client; + synchronized (transportLock) { + closed = true; + client = transport; + transport = null; } - if (Objects.nonNull(instance)) { - instance.shutDown(); + if (Objects.nonNull(client)) { + try { + client.close(); + } catch (IOException e) { + log.warn("Agent HTTP transport close failed"); + } } } - private static Optional readBoundedBody(RawResponse response, int limit) { - try { - // Unirest owns the response stream. Closing it here can drain an oversized HTTP entity. - InputStream input = response.getContent(); - byte[] buffer = new byte[Math.min(8192, limit)]; - ByteArrayOutputStream body = new ByteArrayOutputStream(buffer.length); - while (true) { - int remaining = limit - body.size(); - int length = (int) Math.min(buffer.length, (long) remaining + 1); - int read = input.read(buffer, 0, length); - if (read < 0) { - break; - } - if (read > remaining) { - return Optional.empty(); - } - body.write(buffer, 0, read); + private static Optional readBoundedBody(HttpEntity entity, int limit) throws IOException { + if (Objects.isNull(entity)) { + return Optional.of(""); + } + // The response owns the stream. Closing the stream itself can drain an oversized entity. + InputStream input = entity.getContent(); + byte[] buffer = new byte[Math.min(8192, limit)]; + ByteArrayOutputStream body = new ByteArrayOutputStream(buffer.length); + while (true) { + int remaining = limit - body.size(); + int length = (int) Math.min(buffer.length, (long) remaining + 1); + int read = input.read(buffer, 0, length); + if (read < 0) { + break; + } + if (read > remaining) { + return Optional.empty(); } - String contentType = response.getContentType(); - Charset charset = OpenCliStrings.isBlank(contentType) ? null : ContentType.parse(contentType).getCharset(); - String encoding = Objects.nonNull(charset) ? charset.name() : response.getConfig().getDefaultResponseEncoding(); - return Optional.of(body.toString(encoding)); - } catch (IOException | RuntimeException exception) { - // Avoid Unirest's fallback, which otherwise retries by reading the full body for diagnostics. - throw new UnrecoverableException(exception); + body.write(buffer, 0, read); } + ContentType type = ContentType.get(entity); + Charset charset = Objects.nonNull(type) ? type.getCharset() : null; + return Optional.of(body.toString(Objects.nonNull(charset) ? charset.name() : StandardCharsets.UTF_8.name())); } private int resolveTimeoutMillis() { diff --git a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java index 6fcb455..f87bbf1 100644 --- a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java +++ b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java @@ -11,6 +11,7 @@ import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; import io.github.easy4j.opencli.exception.OpenCliRemoteProtocolException; import io.github.easy4j.opencli.exception.OpenCliRemoteResponseLimitException; +import io.github.easy4j.opencli.exception.OpenCliRemoteTimeoutException; import io.github.easy4j.opencli.meta.OpenCliExternalClient; import java.io.ByteArrayOutputStream; import java.io.IOException; @@ -100,6 +101,86 @@ void collectFailureIncludesRawBodyWhenEnabled() throws IOException { } } + @Test + void totalDeadlineStopsAnActiveChunkedResponseAndDoesNotRetry() throws IOException { + AtomicInteger writes = new AtomicInteger(); + AtomicInteger requests = new AtomicInteger(); + try (JsonCollectStub stub = JsonCollectStub.start(exchange -> { + if (requests.incrementAndGet() > 1) { + byte[] reply = "{\"success\":true}".getBytes(StandardCharsets.UTF_8); + exchange.sendResponseHeaders(200, reply.length); + try (OutputStream output = exchange.getResponseBody()) { + output.write(reply); + } + return; + } + exchange.sendResponseHeaders(200, 0); + try (OutputStream output = exchange.getResponseBody()) { + for (int index = 0; index < 50; index++) { + output.write(' '); + output.flush(); + writes.incrementAndGet(); + try { + Thread.sleep(125); + } catch (InterruptedException interrupted) { + Thread.currentThread().interrupt(); + return; + } + } + } + })) { + OpenCliProperties props = baseProps(stub.port()); + props.setCommandTimeoutMillis(900); + try (OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(props)) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("npm").command("search").build(); + OpenCliRemoteTimeoutException timeout = Assertions.assertTimeoutPreemptively( + Duration.ofSeconds(3), () -> Assertions.assertThrows( + OpenCliRemoteTimeoutException.class, () -> client.collect(request))); + Assertions.assertEquals(900, timeout.getTimeoutMillis()); + Assertions.assertTrue(timeout.isRemoteOutcomeUnknown()); + Assertions.assertNull(timeout.getCause()); + Assertions.assertTrue(writes.get() > 1); + Assertions.assertNull(timeout.getPartialResult()); + Assertions.assertEquals(1, stub.requests()); + props.setCommandTimeoutMillis(4_000); + Assertions.assertTrue(client.collect(request).isSuccess()); + Assertions.assertEquals(2, stub.requests()); + } + } + } + + @Test + void refusesAnExpiredInvocationBudgetBeforeDispatch() throws IOException { + try (JsonCollectStub stub = JsonCollectStub.start("{\"success\":true}")) { + OpenCliProperties props = baseProps(stub.port()); + props.setCommandTimeoutMillis(100); + try (OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(props)) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("npm").command("search").build(); + long submittedAt = System.nanoTime() - TimeUnit.SECONDS.toNanos(1); + OpenCliRemoteTimeoutException timeout = Assertions.assertThrows( + OpenCliRemoteTimeoutException.class, () -> client.collect(request, submittedAt)); + Assertions.assertFalse(timeout.isRemoteOutcomeUnknown()); + Assertions.assertEquals(0, stub.requests()); + } + } + } + + @Test + void doesNotReplayCollectAtARedirectLocation() throws IOException { + try (JsonCollectStub stub = JsonCollectStub.start(exchange -> { + exchange.getResponseHeaders().set("Location", "/collect?retry=true"); + exchange.sendResponseHeaders(307, -1); + exchange.close(); + }); + OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(baseProps(stub.port()))) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("npm").command("search").build(); + OpenCliExecutableFailureException failure = Assertions.assertThrows( + OpenCliExecutableFailureException.class, () -> client.collect(request)); + Assertions.assertTrue(failure.getMessage().contains("307")); + Assertions.assertEquals(1, stub.requests()); + } + } + @Test void permitsABodyAtTheByteLimitAndRejectsOneByteLess() throws IOException { String body = "{\"success\":true,\"items\":[\"你好\"]}"; From eb9e951728324b88d19c9442ab02d12adbe018c5 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:40:25 +0800 Subject: [PATCH 035/105] Retain status and exit provenance for legacy collect Refs #5 (cherry picked from commit 106585e16ea67c6bfde5fc827b1913e4bc73cec9) --- README.md | 1 + README.zh-CN.md | 1 + .../harden-opencli-remote-collect/tasks.md | 9 ++- .../opencli/core/OpenCliDiagnosticExport.java | 3 + .../core/OpenCliRemoteExecutionDetails.java | 37 +++++++++ .../easy4j/opencli/core/OpenCliResult.java | 2 + .../OpenCliRemoteProtocolException.java | 13 +++- .../remote/OpenCliRemoteAgentHttpClient.java | 76 +++++++++++-------- .../OpenCliRemoteAgentHttpClientTest.java | 61 +++++++++++++++ 9 files changed, 171 insertions(+), 32 deletions(-) create mode 100644 src/main/java/io/github/easy4j/opencli/core/OpenCliRemoteExecutionDetails.java diff --git a/README.md b/README.md index 827a4a7..a21824e 100644 --- a/README.md +++ b/README.md @@ -194,6 +194,7 @@ Notes: - A legacy HTTP `/collect` reply must contain a JSON boolean `success`. Invalid envelopes raise `OpenCliRemoteProtocolException`, which extends `OpenCliExecutableFailureException`. A valid reply with `success: true` and omitted or null `items` still returns `[]`. - Legacy HTTP argv dispatch accepts SDK-listed adapters and one subcommand. Root metadata, Browser sessions, external passthrough, repeated options, `--`, and tokens whose spacing or leading dash cannot be preserved are rejected before HTTP. Place positionals before options. Use local execution for commands that need the original argv. A deployment with its own adapter contract can use the explicit `OpenCliCollectRequest` API. - A collect timeout raises `OpenCliRemoteTimeoutException`. After dispatch to the HTTP transport, `isRemoteOutcomeUnknown()` is true. Collect does not automatically retry or follow redirects. +- Inspect `getRemoteExecutionDetails()` on the result or on an exception’s `getPartialResult()` to distinguish HTTP status, Agent business status and the source of `items`. The legacy 0/1 returned by `getExitCode()` is synthetic. HTTP and protocol failure snapshots have no exit code. Accepted response text is available in those snapshots only when raw capture is enabled. - `execution-target=REMOTE_AGENT_HTTP` makes the availability probe report `SKIPPED_REMOTE_MODE` (treated as startable). diff --git a/README.zh-CN.md b/README.zh-CN.md index e44c56b..9994f9a 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -193,6 +193,7 @@ cli.gemini().deepResearch("topic", - 旧版 HTTP `/collect` 响应须包含 JSON 布尔字段 `success`。无效响应抛出 `OpenCliRemoteProtocolException`,它继承 `OpenCliExecutableFailureException`。当 `success: true` 且 `items` 缺失或为 null 时,仍返回 `[]`。 - 旧版 HTTP argv 调用仅接收 SDK 清单中的适配器及其子命令。根命令、Browser 会话、外部程序透传、重复选项、`--` 以及无法保留边界空格或前导短横的参数会在发请求前被拒绝。位置参数应在选项前。需要原样传递 argv 时使用本地执行,已有自定义 Agent 契约时可用显式 `OpenCliCollectRequest` API。 - 远程调用超时抛出 `OpenCliRemoteTimeoutException`。请求提交给 HTTP 传输后,`isRemoteOutcomeUnknown()` 为 true。客户端不会自动重试或跟随重定向。 +- 通过结果或异常的 `getPartialResult()` 调用 `getRemoteExecutionDetails()`,查看 HTTP 状态、Agent 业务状态和 `items` 的来源。`getExitCode()` 的 0/1 是兼容映射。HTTP 或协议失败快照没有退出码。仅在开启原文捕获时,失败快照才携带已通过字节上限检查的响应正文。 - `execution-target=REMOTE_AGENT_HTTP` 时可用性探测报告 `SKIPPED_REMOTE_MODE`(视为可启动)。 diff --git a/openspec/changes/harden-opencli-remote-collect/tasks.md b/openspec/changes/harden-opencli-remote-collect/tasks.md index c8c7f83..144a985 100644 --- a/openspec/changes/harden-opencli-remote-collect/tasks.md +++ b/openspec/changes/harden-opencli-remote-collect/tasks.md @@ -13,7 +13,7 @@ ## 2. 最小适配修复 - [ ] 2.1 引入显式 legacy capability guard 和保真转换子集,避免无条件解析任意 argv。 -- [ ] 2.2 区分 HTTP/协议/命令失败、synthetic exit 与未观察的退出码。 +- [x] 2.2 区分 HTTP、协议与命令失败,保留兼容退出码及其来源。见 OC-REMOTE-003/004 验证。 - [ ] 2.3 使 body/timeout 有界并实现可测试的显式 header 配置,保持 TLS。 ## 3. 三线与安全 @@ -55,3 +55,10 @@ JDK 17 基线在 42 项 HTTP 用例中有 4 项失败,覆盖多字节响应超 JDK 17 基线中,chunked 响应每 125 ms 持续发送数据,900 ms 的原套接字超时未能终止调用,测试在 3 秒断言窗口失败。使用现有 Apache HttpClient 的可取消请求后,连接池等待、建连、HTTP 头及有界读取共享一个单调时钟预算。超时只中止当前请求,已提交传输的调用返回远端结果未知,无自动重试。原始预算耗尽且尚未提交时返回未发送。当前响应池可继续处理后续调用,并保留 JVM 信任配置。另有 307 回归验证不会转发采集请求。 本轮验证的是 SDK 侧 HTTP 传输与回环 HTTP 桩。真实部署、系统 DNS 解析器或本地解析处理的执行时延,以及认证 header 仍需独立验收。 + + +## OC-REMOTE-003/004 状态与退出码来源 + +对基线加入结果证据断言后,HTTP 200 业务失败、HTTP 503、缺省 `items` 和十种畸形响应共 13 项未能提供所需证据。修改后,`getRemoteExecutionDetails()` 保留 HTTP 状态、Agent 业务状态、失败层级和 `items` 来源。兼容退出值标记为 `SYNTHETIC_COMPATIBILITY`,观测到的远端退出码为空。HTTP 或协议失败快照保留真实状态且退出值为空,按原文捕获开关提供通过字节上限检查的完整响应。超限和超时沿用原有异常及保留策略。 + +验证覆盖 503 的 HTML 响应、可选原文与安全诊断、合法业务失败和协议失败。显式诊断导出先输出退出码来源,再输出兼容退出值,避免截断产生缺少来源的数字。 diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliDiagnosticExport.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliDiagnosticExport.java index 4a0e94f..e71cd7b 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliDiagnosticExport.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliDiagnosticExport.java @@ -34,9 +34,12 @@ public static String export(OpenCliResult result, int maxBytes) { } Integer exitCode = result.getExitCode(); + OpenCliRemoteExecutionDetails remote = result.getRemoteExecutionDetails(); String[] fields = { "success=" + result.isSuccess() + "\n", + Objects.isNull(remote) ? "" : "exitCodeSource=" + remote.getExitCodeSource() + "\n", Objects.isNull(exitCode) ? "" : "exitCode=" + exitCode + "\n", + Objects.isNull(remote) ? "" : "httpStatus=" + remote.getHttpStatus() + "\n", characterCount("stdoutChars", result.getStdout()), characterCount("stderrChars", result.getStderr()), characterCount("rawHttpChars", result.getRemoteRawHttpBody()) diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliRemoteExecutionDetails.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliRemoteExecutionDetails.java new file mode 100644 index 0000000..42e596e --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliRemoteExecutionDetails.java @@ -0,0 +1,37 @@ +package io.github.easy4j.opencli.core; + +import java.util.Objects; +import java.util.OptionalInt; +import lombok.Builder; +import lombok.Getter; + +/** Observable evidence from an HTTP response to a legacy collect request. */ +@Getter +@Builder +public final class OpenCliRemoteExecutionDetails { + + /** The layer that supplied the failed or successful result. */ + public enum Outcome { SUCCESS, COMMAND_FAILURE, HTTP_FAILURE, PROTOCOL_FAILURE } + + /** Origin of the compatibility exit code on the associated result. */ + public enum ExitCodeSource { SYNTHETIC_COMPATIBILITY, UNAVAILABLE } + + /** Origin of the items projected to stdout. */ + public enum ItemsSource { RESPONSE, ABSENT_DEFAULT, NULL_DEFAULT, UNAVAILABLE } + + private final int httpStatus; + private final Outcome outcome; + /** Null when a business status was unavailable or its envelope failed validation. */ + private final Boolean legacySuccess; + private final ItemsSource itemsSource; + + /** @return whether the associated 0/1 exit code is a mapping of the business status */ + public ExitCodeSource getExitCodeSource() { + return Objects.isNull(legacySuccess) ? ExitCodeSource.UNAVAILABLE : ExitCodeSource.SYNTHETIC_COMPATIBILITY; + } + + /** @return empty because the legacy collect response does not report a process exit */ + public OptionalInt getObservedRemoteExitCode() { + return OptionalInt.empty(); + } +} diff --git a/src/main/java/io/github/easy4j/opencli/core/OpenCliResult.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliResult.java index 23d4631..e6603ad 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliResult.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliResult.java @@ -49,4 +49,6 @@ public class OpenCliResult { /** Bounded local execution evidence, when available. */ private final OpenCliExecutionDetails executionDetails; + /** Evidence from a legacy HTTP collect response, if available. */ + private final OpenCliRemoteExecutionDetails remoteExecutionDetails; } diff --git a/src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteProtocolException.java b/src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteProtocolException.java index 78a0f0e..2b7fc48 100644 --- a/src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteProtocolException.java +++ b/src/main/java/io/github/easy4j/opencli/exception/OpenCliRemoteProtocolException.java @@ -1,9 +1,20 @@ package io.github.easy4j.opencli.exception; +import io.github.easy4j.opencli.core.OpenCliResult; + /** 远端 /collect 响应不符合协议,保留既有远程异常捕获类型。 */ public final class OpenCliRemoteProtocolException extends OpenCliExecutableFailureException { public OpenCliRemoteProtocolException(String message, String correlationId) { - super(message + " correlationId=" + correlationId, null); + this(message, correlationId, null); + } + + /** + * @param message safe summary of the protocol failure + * @param correlationId SDK request correlation identifier + * @param partialResult bounded HTTP response evidence + */ + public OpenCliRemoteProtocolException(String message, String correlationId, OpenCliResult partialResult) { + super(message + " correlationId=" + correlationId, null, partialResult); } } diff --git a/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java index 4fdef37..dd3d4a3 100644 --- a/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java +++ b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java @@ -6,6 +6,9 @@ import com.fasterxml.jackson.databind.json.JsonMapper; import io.github.easy4j.opencli.OpenCliProperties; import io.github.easy4j.opencli.core.OpenCliOutputParser; +import io.github.easy4j.opencli.core.OpenCliRemoteExecutionDetails; +import io.github.easy4j.opencli.core.OpenCliRemoteExecutionDetails.ItemsSource; +import io.github.easy4j.opencli.core.OpenCliRemoteExecutionDetails.Outcome; import io.github.easy4j.opencli.core.OpenCliResult; import io.github.easy4j.opencli.exception.OpenCliExecutableFailureException; import io.github.easy4j.opencli.exception.OpenCliNonZeroExitException; @@ -138,9 +141,10 @@ public OpenCliResult collect(OpenCliCollectRequest request, long submittedAtNano if (status < 200 || status >= 300) { log.warn("Agent HTTP non-2xx correlationId={} status={} responseChars={}", correlationId, status, respBody.length()); - throw failure("Agent HTTP " + status, correlationId); + throw new OpenCliExecutableFailureException("Agent HTTP " + status + " correlationId=" + correlationId, + null, failureSnapshot(status, Outcome.HTTP_FAILURE, respBody)); } - return mapResponse(respBody, correlationId); + return mapResponse(status, respBody, correlationId); } catch (com.fasterxml.jackson.core.JsonProcessingException e) { log.warn("Agent response parse failed correlationId={}", correlationId); throw failure("Failed to parse agent response", correlationId); @@ -231,7 +235,7 @@ private static OpenCliExecutableFailureException failure(String message, String return new OpenCliExecutableFailureException(message + " correlationId=" + correlationId, null); } - private OpenCliResult mapResponse(String respBody, String correlationId) + private OpenCliResult mapResponse(int status, String respBody, String correlationId) throws com.fasterxml.jackson.core.JsonProcessingException { String rawCapture = captureRawIfEnabled(respBody); JsonNode envelope; @@ -240,55 +244,67 @@ private OpenCliResult mapResponse(String respBody, String correlationId) } catch (com.fasterxml.jackson.core.JsonProcessingException e) { log.warn("Agent response envelope parse failed correlationId={} responseChars={}", correlationId, respBody.length()); - throw new OpenCliRemoteProtocolException("Failed to parse agent response envelope", correlationId); + throw new OpenCliRemoteProtocolException("Failed to parse agent response envelope", correlationId, + failureSnapshot(status, Outcome.PROTOCOL_FAILURE, respBody)); } if (Objects.isNull(envelope) || !envelope.isObject() || !envelope.path("success").isBoolean()) { log.warn("Agent response envelope status invalid correlationId={} responseChars={}", correlationId, respBody.length()); - throw new OpenCliRemoteProtocolException("Invalid agent response envelope status", correlationId); + throw new OpenCliRemoteProtocolException("Invalid agent response envelope status", correlationId, + failureSnapshot(status, Outcome.PROTOCOL_FAILURE, respBody)); } JsonNode error = envelope.path("error"); if (!error.isMissingNode() && !error.isNull() && !error.isTextual()) { log.warn("Agent response envelope error field invalid correlationId={} responseChars={}", correlationId, respBody.length()); - throw new OpenCliRemoteProtocolException("Invalid agent response envelope error field", correlationId); + throw new OpenCliRemoteProtocolException("Invalid agent response envelope error field", correlationId, + failureSnapshot(status, Outcome.PROTOCOL_FAILURE, respBody)); } boolean success = envelope.path("success").booleanValue(); String err = error.isTextual() ? error.asText() : ""; JsonNode items = envelope.path("items"); String stdout; + ItemsSource itemsSource; if (items.isMissingNode() || items.isNull()) { stdout = "[]"; - } else if (items.isArray()) { - stdout = MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(items); + itemsSource = items.isMissingNode() ? ItemsSource.ABSENT_DEFAULT : ItemsSource.NULL_DEFAULT; } else { - stdout = items.toPrettyString(); + stdout = items.isArray() ? MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(items) + : items.toPrettyString(); + itemsSource = ItemsSource.RESPONSE; } OpenCliParsedFields parsed = OpenCliOutputParser.parseBestEffort(stdout, err); - if (!success) { - log.warn( - "Agent collect reported failure correlationId={} errorChars={} stdoutLength={}", - correlationId, - err.length(), - stdout.length()); - OpenCliResult failed = - OpenCliResult.builder() - .stdout(stdout) - .stderr(err) - .exitCode(1) - .success(false) - .parsed(parsed) - .remoteRawHttpBody(rawCapture) - .build(); - throw new OpenCliNonZeroExitException("OpenCLI agent reported failure correlationId=" + correlationId, failed); - } - return OpenCliResult.builder() + OpenCliResult result = OpenCliResult.builder() .stdout(stdout) - .stderr(err.isEmpty() ? "" : err) - .exitCode(0) - .success(true) + .stderr(err) + .exitCode(success ? 0 : 1) + .success(success) .parsed(parsed) .remoteRawHttpBody(rawCapture) + .remoteExecutionDetails(OpenCliRemoteExecutionDetails.builder() + .httpStatus(status) + .legacySuccess(success) + .outcome(success ? Outcome.SUCCESS : Outcome.COMMAND_FAILURE) + .itemsSource(itemsSource) + .build()) + .build(); + if (!success) { + log.warn("Agent collect reported failure correlationId={} errorChars={} stdoutLength={}", + correlationId, err.length(), stdout.length()); + throw new OpenCliNonZeroExitException("OpenCLI agent reported failure correlationId=" + correlationId, result); + } + return result; + } + + private OpenCliResult failureSnapshot(int status, Outcome outcome, String respBody) { + return OpenCliResult.builder() + .success(false) + .remoteRawHttpBody(captureRawIfEnabled(respBody)) + .remoteExecutionDetails(OpenCliRemoteExecutionDetails.builder() + .httpStatus(status) + .outcome(outcome) + .itemsSource(ItemsSource.UNAVAILABLE) + .build()) .build(); } diff --git a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java index f87bbf1..9eacd55 100644 --- a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java +++ b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java @@ -5,6 +5,11 @@ import com.sun.net.httpserver.HttpServer; import io.github.easy4j.opencli.OpenCliExecutionTarget; import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.core.OpenCliDiagnosticExport; +import io.github.easy4j.opencli.core.OpenCliRemoteExecutionDetails; +import io.github.easy4j.opencli.core.OpenCliRemoteExecutionDetails.ExitCodeSource; +import io.github.easy4j.opencli.core.OpenCliRemoteExecutionDetails.ItemsSource; +import io.github.easy4j.opencli.core.OpenCliRemoteExecutionDetails.Outcome; import io.github.easy4j.opencli.core.OpenCliResult; import io.github.easy4j.opencli.core.OpenCliExecutor; import io.github.easy4j.opencli.exception.OpenCliExecutableFailureException; @@ -98,6 +103,20 @@ void collectFailureIncludesRawBodyWhenEnabled() throws IOException { OpenCliCollectRequest.builder().site("x").command("y").build())); Assertions.assertNotNull(ex.getPartialResult()); Assertions.assertEquals(json, ex.getPartialResult().getRemoteRawHttpBody()); + OpenCliResult result = ex.getPartialResult(); + OpenCliRemoteExecutionDetails details = result.getRemoteExecutionDetails(); + Assertions.assertNotNull(details); + Assertions.assertEquals(200, details.getHttpStatus()); + Assertions.assertEquals(Boolean.FALSE, details.getLegacySuccess()); + Assertions.assertEquals(Outcome.COMMAND_FAILURE, details.getOutcome()); + Assertions.assertEquals(ItemsSource.NULL_DEFAULT, details.getItemsSource()); + Assertions.assertEquals(Integer.valueOf(1), result.getExitCode()); + Assertions.assertEquals(ExitCodeSource.SYNTHETIC_COMPATIBILITY, details.getExitCodeSource()); + Assertions.assertFalse(details.getObservedRemoteExitCode().isPresent()); + Assertions.assertNull(result.getExecutionDetails()); + String exported = OpenCliDiagnosticExport.export(result, 250); + Assertions.assertTrue(exported.contains("exitCodeSource=SYNTHETIC_COMPATIBILITY")); + Assertions.assertFalse(exported.contains("agent-error")); } } @@ -307,6 +326,36 @@ void keepsDeclaredCharsetWithinTheResponseLimit() throws IOException { } } + @Test + void httpFailureRetainsItsStatusWithoutCreatingAProcessExit() throws IOException { + String body = "fixture-proxy-error"; + try (JsonCollectStub stub = JsonCollectStub.start(body, 503)) { + OpenCliProperties props = baseProps(stub.port()); + try (OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(props)) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("npm").command("search").build(); + OpenCliExecutableFailureException failure = Assertions.assertThrows( + OpenCliExecutableFailureException.class, () -> client.collect(request)); + OpenCliResult partial = failure.getPartialResult(); + Assertions.assertNotNull(partial); + Assertions.assertNull(partial.getRemoteRawHttpBody()); + Assertions.assertNull(partial.getExitCode()); + OpenCliRemoteExecutionDetails details = partial.getRemoteExecutionDetails(); + Assertions.assertNotNull(details); + Assertions.assertEquals(503, details.getHttpStatus()); + Assertions.assertNull(details.getLegacySuccess()); + Assertions.assertEquals(Outcome.HTTP_FAILURE, details.getOutcome()); + Assertions.assertEquals(ExitCodeSource.UNAVAILABLE, details.getExitCodeSource()); + Assertions.assertFalse(details.getObservedRemoteExitCode().isPresent()); + + props.setRemoteCaptureRawHttpResponse(true); + OpenCliExecutableFailureException withCapture = Assertions.assertThrows( + OpenCliExecutableFailureException.class, () -> client.collect(request)); + Assertions.assertEquals(body, withCapture.getPartialResult().getRemoteRawHttpBody()); + Assertions.assertFalse(withCapture.getMessage().contains("fixture-proxy-error")); + } + } + } + @Test void nonSuccessHttpResponseDoesNotExposeBodyCanaryInException() throws IOException { String canary = "body-secret-" + UUID.randomUUID(); @@ -425,6 +474,13 @@ void explicitSuccessfulReplyCanOmitItems() throws IOException { OpenCliResult result = client.collect(request); Assertions.assertTrue(result.isSuccess()); Assertions.assertEquals("[]", result.getStdout()); + OpenCliRemoteExecutionDetails details = result.getRemoteExecutionDetails(); + Assertions.assertNotNull(details); + Assertions.assertEquals(Outcome.SUCCESS, details.getOutcome()); + Assertions.assertEquals(Boolean.TRUE, details.getLegacySuccess()); + Assertions.assertEquals(ItemsSource.ABSENT_DEFAULT, details.getItemsSource()); + Assertions.assertEquals(Integer.valueOf(0), result.getExitCode()); + Assertions.assertFalse(details.getObservedRemoteExitCode().isPresent()); } } @@ -447,6 +503,11 @@ void invalidLegacyEnvelopeIsAProtocolFailure(String body) throws IOException { OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("x").command("y").build(); OpenCliRemoteProtocolException failure = Assertions.assertThrows( OpenCliRemoteProtocolException.class, () -> client.collect(request)); + OpenCliResult partial = failure.getPartialResult(); + Assertions.assertNotNull(partial); + Assertions.assertNull(partial.getExitCode()); + Assertions.assertEquals(200, partial.getRemoteExecutionDetails().getHttpStatus()); + Assertions.assertEquals(Outcome.PROTOCOL_FAILURE, partial.getRemoteExecutionDetails().getOutcome()); Assertions.assertTrue(failure.getMessage().contains("response envelope")); Assertions.assertTrue(failure.getMessage().contains("correlationId=")); Assertions.assertNull(failure.getCause()); From c03aac008df9b7868530b73ab9d60bf969afd858 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:48:34 +0800 Subject: [PATCH 036/105] Send explicit collect credentials only over verified HTTPS Refs #5 (cherry picked from commit b40ed5a91ed357478fe0f05b4936e4ac3508ec31) --- README.md | 1 + README.zh-CN.md | 1 + .../harden-opencli-remote-collect/tasks.md | 9 +- .../easy4j/opencli/OpenCliProperties.java | 6 + .../opencli/OpenCliRemoteAuthentication.java | 38 +++++ .../remote/OpenCliRemoteAgentHttpClient.java | 31 +++- .../ws/OpenCliWsReverseAgentSessionTest.java | 40 +---- .../OpenCliRemoteAgentHttpClientTest.java | 152 +++++++++++++++++- .../testsupport/OpenCliTlsFixture.java | 59 +++++++ 9 files changed, 289 insertions(+), 48 deletions(-) create mode 100644 src/main/java/io/github/easy4j/opencli/OpenCliRemoteAuthentication.java create mode 100644 src/test/java/io/github/easy4j/opencli/testsupport/OpenCliTlsFixture.java diff --git a/README.md b/README.md index a21824e..9b1dfca 100644 --- a/README.md +++ b/README.md @@ -195,6 +195,7 @@ Notes: - Legacy HTTP argv dispatch accepts SDK-listed adapters and one subcommand. Root metadata, Browser sessions, external passthrough, repeated options, `--`, and tokens whose spacing or leading dash cannot be preserved are rejected before HTTP. Place positionals before options. Use local execution for commands that need the original argv. A deployment with its own adapter contract can use the explicit `OpenCliCollectRequest` API. - A collect timeout raises `OpenCliRemoteTimeoutException`. After dispatch to the HTTP transport, `isRemoteOutcomeUnknown()` is true. Collect does not automatically retry or follow redirects. - Inspect `getRemoteExecutionDetails()` on the result or on an exception’s `getPartialResult()` to distinguish HTTP status, Agent business status and the source of `items`. The legacy 0/1 returned by `getExitCode()` is synthetic. HTTP and protocol failure snapshots have no exit code. Accepted response text is available in those snapshots only when raw capture is enabled. +- If your Agent accepts a credential header, configure `setRemoteAuthentication(new OpenCliRemoteAuthentication("Authorization", System.getenv("OPENCLI_AGENT_AUTHORIZATION")))`. Supply the complete header value. The Agent base URL must use HTTPS for credentials and contain no user info, query or fragment. The SDK sends the configured header on `/collect`. OAuth discovery and request signing are unsupported. - `execution-target=REMOTE_AGENT_HTTP` makes the availability probe report `SKIPPED_REMOTE_MODE` (treated as startable). diff --git a/README.zh-CN.md b/README.zh-CN.md index 9994f9a..774ab1e 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -194,6 +194,7 @@ cli.gemini().deepResearch("topic", - 旧版 HTTP argv 调用仅接收 SDK 清单中的适配器及其子命令。根命令、Browser 会话、外部程序透传、重复选项、`--` 以及无法保留边界空格或前导短横的参数会在发请求前被拒绝。位置参数应在选项前。需要原样传递 argv 时使用本地执行,已有自定义 Agent 契约时可用显式 `OpenCliCollectRequest` API。 - 远程调用超时抛出 `OpenCliRemoteTimeoutException`。请求提交给 HTTP 传输后,`isRemoteOutcomeUnknown()` 为 true。客户端不会自动重试或跟随重定向。 - 通过结果或异常的 `getPartialResult()` 调用 `getRemoteExecutionDetails()`,查看 HTTP 状态、Agent 业务状态和 `items` 的来源。`getExitCode()` 的 0/1 是兼容映射。HTTP 或协议失败快照没有退出码。仅在开启原文捕获时,失败快照才携带已通过字节上限检查的响应正文。 +- Agent 支持认证请求头时,可调用 `setRemoteAuthentication(new OpenCliRemoteAuthentication("Authorization", System.getenv("OPENCLI_AGENT_AUTHORIZATION")))`,传入完整请求头值。认证须使用 HTTPS,Agent 基础地址须省略用户信息、查询参数和片段。SDK 只在 `/collect` 请求上发送已配置的认证头。OAuth 发现和请求签名尚不支持。 - `execution-target=REMOTE_AGENT_HTTP` 时可用性探测报告 `SKIPPED_REMOTE_MODE`(视为可启动)。 diff --git a/openspec/changes/harden-opencli-remote-collect/tasks.md b/openspec/changes/harden-opencli-remote-collect/tasks.md index 144a985..5f6f2b0 100644 --- a/openspec/changes/harden-opencli-remote-collect/tasks.md +++ b/openspec/changes/harden-opencli-remote-collect/tasks.md @@ -18,7 +18,7 @@ ## 3. 三线与安全 -- [ ] 3.1 对照 C09 测试凭据、URL query、body preview 和异常 cause 的默认脱敏边界。 +- [x] 3.1 验证凭据、URL query、正文和异常 cause 的默认诊断边界。见 OC-REMOTE-006 验证。 - [ ] 3.2 在三分支分别跑本地 HTTP fixture;记录旧 API 的行为收紧与迁移例子。 - [ ] 3.3 未取得服务端契约的扩展仍标记 unsupported,不借此宣称远程全量兼容。 @@ -62,3 +62,10 @@ JDK 17 基线中,chunked 响应每 125 ms 持续发送数据,900 ms 的原 对基线加入结果证据断言后,HTTP 200 业务失败、HTTP 503、缺省 `items` 和十种畸形响应共 13 项未能提供所需证据。修改后,`getRemoteExecutionDetails()` 保留 HTTP 状态、Agent 业务状态、失败层级和 `items` 来源。兼容退出值标记为 `SYNTHETIC_COMPATIBILITY`,观测到的远端退出码为空。HTTP 或协议失败快照保留真实状态且退出值为空,按原文捕获开关提供通过字节上限检查的完整响应。超限和超时沿用原有异常及保留策略。 验证覆盖 503 的 HTML 响应、可选原文与安全诊断、合法业务失败和协议失败。显式诊断导出先输出退出码来源,再输出兼容退出值,避免截断产生缺少来源的数字。 + + +## OC-REMOTE-006 显式认证与 TLS + +基线先增加配置和夹具,尚未接入传输。HTTPS 认证成功、明文认证拒绝及三类 URL 凭据输入共 5 项验收失败。接入后,回环 HTTPS 服务使用独立测试证书和显式信任。未信任的证书在请求转交应用处理器前被拒绝。信任证书后,桩仅在明确收到正确的指定请求头时返回成功。去除配置后按 401 处理,不自动生成认证数据。错误凭据的 401 回显未出现在默认日志、异常栈或原文捕获关闭时的失败快照中。 + +显式认证采用 SDK 已有 Apache HttpClient 的 HTTPS 校验。明文认证、URL 用户信息、查询参数和片段均在发送前拒绝。测试复用了 WebSocket 的回环证书生成方式。真实 Agent 可接受的请求头和生产认证流程仍待部署契约验证。 diff --git a/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java b/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java index 480e480..a9927b7 100644 --- a/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java +++ b/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java @@ -5,6 +5,7 @@ import java.util.List; import java.util.Map; import lombok.Data; +import lombok.ToString; /** * OpenCLI runtime configuration POJO with no Spring dependency. @@ -49,8 +50,13 @@ public class OpenCliProperties { * 远端 Agent 根 URL(不含尾斜杠),例如 {@code http://192.168.1.10:19823}。 *

仅当 {@link #executionTarget} 为 {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP} 时必填。

*/ + @ToString.Exclude private String remoteAgentBaseUrl; + /** Explicit credential header for the configured HTTPS Agent. */ + @ToString.Exclude + private OpenCliRemoteAuthentication remoteAuthentication; + /** * 传给 Agent collect 的 {@code mode}:{@code bridge} 或 {@code cdp}(与 Agent 环境一致)。 */ diff --git a/src/main/java/io/github/easy4j/opencli/OpenCliRemoteAuthentication.java b/src/main/java/io/github/easy4j/opencli/OpenCliRemoteAuthentication.java new file mode 100644 index 0000000..37d54f9 --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/OpenCliRemoteAuthentication.java @@ -0,0 +1,38 @@ +package io.github.easy4j.opencli; + +import java.util.Objects; +import java.util.regex.Pattern; +import lombok.AccessLevel; +import lombok.Getter; + +/** A caller-supplied credential for an Agent's explicitly supported HTTP header. */ +@Getter +public final class OpenCliRemoteAuthentication { + + private static final Pattern HEADER_NAME = + Pattern.compile("(?:Authorization|Api-Key|X-[A-Za-z0-9][A-Za-z0-9-]*)", Pattern.CASE_INSENSITIVE); + private static final Pattern HEADER_VALUE = Pattern.compile("[!-~](?:[ -~]*[!-~])?"); + + private final String headerName; + @Getter(AccessLevel.NONE) + private final String headerValue; + + /** + * @param headerName Authorization, Api-Key or a custom X- header + * @param headerValue complete printable ASCII credential value, including any scheme + */ + public OpenCliRemoteAuthentication(String headerName, String headerValue) { + if (Objects.isNull(headerName) || !HEADER_NAME.matcher(headerName).matches()) { + throw new IllegalArgumentException("Unsupported remote authentication header name"); + } + if (Objects.isNull(headerValue) || !HEADER_VALUE.matcher(headerValue).matches()) { + throw new IllegalArgumentException("Invalid remote authentication header value"); + } + this.headerName = headerName; + this.headerValue = headerValue; + } + /** @return the raw credential for the explicitly configured HTTP request */ + public String headerValue() { + return headerValue; + } +} diff --git a/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java index dd3d4a3..a5419d8 100644 --- a/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java +++ b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java @@ -5,6 +5,7 @@ import com.fasterxml.jackson.databind.ObjectReader; import com.fasterxml.jackson.databind.json.JsonMapper; import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.OpenCliRemoteAuthentication; import io.github.easy4j.opencli.core.OpenCliOutputParser; import io.github.easy4j.opencli.core.OpenCliRemoteExecutionDetails; import io.github.easy4j.opencli.core.OpenCliRemoteExecutionDetails.ItemsSource; @@ -21,6 +22,7 @@ import java.io.IOException; import java.io.InputStream; import java.net.SocketTimeoutException; +import java.net.URI; import java.nio.charset.Charset; import java.nio.charset.StandardCharsets; import java.util.Objects; @@ -110,11 +112,14 @@ public OpenCliResult collect(OpenCliCollectRequest request, long submittedAtNano throw failure("Failed to serialize collect request", correlationId); } - HttpPost post; - try { - post = new HttpPost(base.trim().replaceAll("/+$", "") + "/collect"); - } catch (IllegalArgumentException exception) { - throw failure("Invalid agent HTTP endpoint", correlationId); + URI endpoint = parseEndpoint(base, correlationId); + OpenCliRemoteAuthentication authentication = properties.getRemoteAuthentication(); + HttpPost post = new HttpPost(endpoint); + if (Objects.nonNull(authentication)) { + if (!"https".equalsIgnoreCase(endpoint.getScheme())) { + throw failure("Remote authentication requires an HTTPS Agent", correlationId); + } + post.setHeader(authentication.getHeaderName(), authentication.headerValue()); } post.setEntity(new StringEntity(bodyJson, ContentType.APPLICATION_JSON)); CloseableHttpClient client = transport(); @@ -124,6 +129,7 @@ public OpenCliResult collect(OpenCliCollectRequest request, long submittedAtNano } int remainingMillis = (int) Math.max(1, TimeUnit.NANOSECONDS.toMillis(remainingNanos)); post.setConfig(RequestConfig.custom() + .setAuthenticationEnabled(false) .setConnectionRequestTimeout(remainingMillis) .setConnectTimeout(remainingMillis) .setSocketTimeout(remainingMillis) @@ -161,6 +167,21 @@ public OpenCliResult collect(OpenCliCollectRequest request, long submittedAtNano } } + private static URI parseEndpoint(String base, String correlationId) { + URI endpoint; + try { + endpoint = URI.create(base.trim()); + } catch (IllegalArgumentException exception) { + throw failure("Invalid agent HTTP endpoint", correlationId); + } + if ((!"http".equalsIgnoreCase(endpoint.getScheme()) && !"https".equalsIgnoreCase(endpoint.getScheme())) + || Objects.isNull(endpoint.getHost()) || Objects.nonNull(endpoint.getRawUserInfo()) + || Objects.nonNull(endpoint.getRawQuery()) || Objects.nonNull(endpoint.getRawFragment())) { + throw failure("Agent endpoint must be an HTTP base URL without user info, query or fragment", correlationId); + } + return URI.create(endpoint.toASCIIString().replaceAll("/+$", "") + "/collect"); + } + private CloseableHttpClient transport() { synchronized (transportLock) { if (closed) { diff --git a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java index 4f308ce..393da98 100644 --- a/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java +++ b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java @@ -1,5 +1,6 @@ package io.github.easy4j.opencli.center.ws; +import io.github.easy4j.opencli.testsupport.OpenCliTlsFixture; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; @@ -10,14 +11,11 @@ import java.io.PrintStream; import java.io.File; import java.io.IOException; -import java.io.InputStream; import java.net.InetSocketAddress; import java.nio.ByteBuffer; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; -import java.nio.file.Paths; -import java.security.KeyStore; import java.util.Arrays; import java.util.Base64; import java.util.Collections; @@ -32,9 +30,7 @@ import java.util.concurrent.atomic.AtomicBoolean; import java.util.concurrent.atomic.AtomicReference; import java.util.stream.Collectors; -import javax.net.ssl.KeyManagerFactory; import javax.net.ssl.SSLContext; -import javax.net.ssl.TrustManagerFactory; import org.java_websocket.WebSocket; import org.java_websocket.enums.Opcode; import org.java_websocket.handshake.ClientHandshake; @@ -560,40 +556,14 @@ void plainWebSocketReconnectDoesNotExposePreviousSessionCache(@TempDir Path temp @ParameterizedTest @ValueSource(booleans = {false, true}) void verifiedTlsReconnectReplaysOnlyAfterAnExplicitRetry(boolean failDelivery, @TempDir Path temporary) throws Exception { - Path storePath = temporary.resolve("center.p12"); - String keytool = System.getProperty("os.name").startsWith("Windows") ? "keytool.exe" : "keytool"; - Path tool = Paths.get(System.getProperty("java.home"), "bin", keytool); - Process keygen = new ProcessBuilder(tool.toString(), "-genkeypair", "-alias", "center", "-keyalg", "RSA", - "-keysize", "2048", "-dname", "CN=localhost", "-ext", "SAN=IP:127.0.0.1", "-validity", "1", - "-storetype", "PKCS12", "-keystore", storePath.toString(), "-storepass", "test-password") - .redirectErrorStream(true).redirectOutput(temporary.resolve("keytool.log").toFile()).start(); - try { - assertTrue(keygen.waitFor(10, TimeUnit.SECONDS)); - assertEquals(0, keygen.exitValue()); - } finally { - if (keygen.isAlive()) { - keygen.destroyForcibly(); - } - } - KeyStore store = KeyStore.getInstance("PKCS12"); - try (InputStream input = Files.newInputStream(storePath)) { - store.load(input, "test-password".toCharArray()); - } - KeyManagerFactory keys = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm()); - keys.init(store, "test-password".toCharArray()); - SSLContext server = SSLContext.getInstance("TLS"); - server.init(keys.getKeyManagers(), null, null); - TrustManagerFactory trust = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()); - trust.init(store); - SSLContext trustedClient = SSLContext.getInstance("TLS"); - trustedClient.init(null, trust.getTrustManagers(), null); + OpenCliTlsFixture tls = OpenCliTlsFixture.create(temporary); SSLContext previous = SSLContext.getDefault(); try { - SSLContext.setDefault(trustedClient); + SSLContext.setDefault(tls.getTrustedClient()); if (failDelivery) { - verifyFailedDeliveryReplay(temporary, server); + verifyFailedDeliveryReplay(temporary, tls.getServer()); } else { - verifyReconnectReplay(temporary, server, true); + verifyReconnectReplay(temporary, tls.getServer(), true); } } finally { SSLContext.setDefault(previous); diff --git a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java index 9eacd55..6775946 100644 --- a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java +++ b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java @@ -3,8 +3,11 @@ import com.sun.net.httpserver.HttpExchange; import com.sun.net.httpserver.HttpHandler; import com.sun.net.httpserver.HttpServer; +import com.sun.net.httpserver.HttpsConfigurator; +import com.sun.net.httpserver.HttpsServer; import io.github.easy4j.opencli.OpenCliExecutionTarget; import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.OpenCliRemoteAuthentication; import io.github.easy4j.opencli.core.OpenCliDiagnosticExport; import io.github.easy4j.opencli.core.OpenCliRemoteExecutionDetails; import io.github.easy4j.opencli.core.OpenCliRemoteExecutionDetails.ExitCodeSource; @@ -18,6 +21,7 @@ import io.github.easy4j.opencli.exception.OpenCliRemoteResponseLimitException; import io.github.easy4j.opencli.exception.OpenCliRemoteTimeoutException; import io.github.easy4j.opencli.meta.OpenCliExternalClient; +import io.github.easy4j.opencli.testsupport.OpenCliTlsFixture; import java.io.ByteArrayOutputStream; import java.io.IOException; import java.io.OutputStream; @@ -26,18 +30,23 @@ import java.io.StringWriter; import java.net.InetSocketAddress; import java.nio.charset.StandardCharsets; +import java.nio.file.Path; import java.time.Duration; import java.util.Arrays; +import java.util.Objects; import java.util.Scanner; import java.util.UUID; import java.util.concurrent.CountDownLatch; import java.util.concurrent.TimeUnit; import java.util.concurrent.atomic.AtomicInteger; +import java.util.concurrent.atomic.AtomicReference; import java.util.regex.Matcher; import java.util.regex.Pattern; import java.util.zip.GZIPOutputStream; +import javax.net.ssl.SSLContext; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; import org.junit.jupiter.params.ParameterizedTest; import org.junit.jupiter.params.provider.ValueSource; @@ -356,14 +365,134 @@ void httpFailureRetainsItsStatusWithoutCreatingAProcessExit() throws IOException } } + @Test + void authenticationHeaderIsSentOnlyOverVerifiedTls(@TempDir Path temporary) throws Exception { + String credential = "sdk-credential-" + UUID.randomUUID(); + String header = "X-OpenCLI-Test-Key"; + AtomicReference receivedCredential = new AtomicReference<>(); + AtomicReference receivedUri = new AtomicReference<>(); + OpenCliTlsFixture tls = OpenCliTlsFixture.create(temporary); + SSLContext previous = SSLContext.getDefault(); + try (JsonCollectStub stub = JsonCollectStub.start(tls.getServer(), exchange -> { + receivedCredential.set(exchange.getRequestHeaders().getFirst(header)); + receivedUri.set(exchange.getRequestURI().toASCIIString()); + // The synthetic fixture supports only this explicit header. + boolean accepted = credential.equals(receivedCredential.get()); + byte[] response = (accepted ? "{\"success\":true}" : "credential required " + receivedCredential.get()) + .getBytes(StandardCharsets.UTF_8); + if (!accepted) { + exchange.getResponseHeaders().set("WWW-Authenticate", "Basic realm=fixture"); + } + exchange.sendResponseHeaders(accepted ? 200 : 401, response.length); + try (OutputStream output = exchange.getResponseBody()) { + output.write(response); + } + })) { + OpenCliProperties props = baseProps(stub.port()); + props.setRemoteAgentBaseUrl("https://127.0.0.1:" + stub.port()); + props.setRemoteAuthentication(new OpenCliRemoteAuthentication(header, credential)); + Assertions.assertFalse(props.toString().contains(credential)); + Assertions.assertNull(props.copyForLocalCliExecution().getRemoteAuthentication()); + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("npm").command("search").build(); + try (OpenCliRemoteAgentHttpClient untrusted = new OpenCliRemoteAgentHttpClient(props)) { + OpenCliExecutableFailureException failure = Assertions.assertThrows( + OpenCliExecutableFailureException.class, () -> untrusted.collect(request)); + Assertions.assertFalse(failure.toString().contains(credential)); + Assertions.assertEquals(0, stub.requests()); + } + + SSLContext.setDefault(tls.getTrustedClient()); + try (OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(props)) { + Assertions.assertTrue(client.collect(request).isSuccess()); + Assertions.assertEquals(credential, receivedCredential.get()); + Assertions.assertEquals("/collect", receivedUri.get()); + Assertions.assertFalse(stub.requestBody.contains(credential)); + props.setRemoteAuthentication(new OpenCliRemoteAuthentication(header, "rejected-" + credential)); + ByteArrayOutputStream diagnostics = new ByteArrayOutputStream(); + PrintStream originalError = System.err; + try (PrintStream capture = new PrintStream(diagnostics, true, StandardCharsets.UTF_8.name())) { + System.setErr(capture); + OpenCliExecutableFailureException denied = Assertions.assertThrows( + OpenCliExecutableFailureException.class, () -> client.collect(request)); + StringWriter stack = new StringWriter(); + denied.printStackTrace(new PrintWriter(stack)); + Assertions.assertFalse(stack.toString().contains(credential)); + Assertions.assertNull(denied.getPartialResult().getRemoteRawHttpBody()); + } finally { + System.setErr(originalError); + } + String log = diagnostics.toString(StandardCharsets.UTF_8.name()); + Assertions.assertTrue(log.contains("status=401")); + Assertions.assertFalse(log.contains(credential)); + Assertions.assertEquals(2, stub.requests()); + + props.setRemoteAuthentication(null); + OpenCliExecutableFailureException failure = Assertions.assertThrows( + OpenCliExecutableFailureException.class, () -> client.collect(request)); + Assertions.assertEquals(401, failure.getPartialResult().getRemoteExecutionDetails().getHttpStatus()); + Assertions.assertNull(receivedCredential.get()); + Assertions.assertEquals(3, stub.requests()); + } + } finally { + SSLContext.setDefault(previous); + } + } + + @Test + void rejectsConfiguredAuthenticationOnPlainHttpBeforeDispatch() throws IOException { + String credential = "private-token"; + try (JsonCollectStub stub = JsonCollectStub.start("{\"success\":true}")) { + OpenCliProperties props = baseProps(stub.port()); + props.setRemoteAuthentication(new OpenCliRemoteAuthentication("Authorization", "Bearer " + credential)); + try (OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(props)) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("npm").command("search").build(); + OpenCliExecutableFailureException failure = Assertions.assertThrows( + OpenCliExecutableFailureException.class, () -> client.collect(request)); + Assertions.assertFalse(failure.toString().contains(credential)); + Assertions.assertEquals(0, stub.requests()); + } + } + } + + @ParameterizedTest + @ValueSource(strings = {"user-info", "query", "fragment"}) + void rejectsSecretsInAnAgentBaseUrlBeforeDispatch(String input) throws IOException { + String credential = "url-secret-" + UUID.randomUUID(); + try (JsonCollectStub stub = JsonCollectStub.start("{\"success\":true}")) { + OpenCliProperties props = baseProps(stub.port()); + String authority = "127.0.0.1:" + stub.port(); + if ("user-info".equals(input)) { + props.setRemoteAgentBaseUrl("http://operator:" + credential + "@" + authority); + } else { + props.setRemoteAgentBaseUrl("http://" + authority + "/collect" + + ("query".equals(input) ? "?key=" : "#") + credential); + } + try (OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(props)) { + OpenCliCollectRequest request = OpenCliCollectRequest.builder().site("npm").command("search").build(); + OpenCliExecutableFailureException failure = Assertions.assertThrows( + OpenCliExecutableFailureException.class, () -> client.collect(request)); + Assertions.assertFalse(failure.toString().contains(credential)); + Assertions.assertNull(failure.getCause()); + Assertions.assertEquals(0, stub.requests()); + } + } + } + + @Test + void rejectsMalformedAuthenticationHeaderWithoutRevealingItsValue() { + String secret = "fixture-injection-canary"; + IllegalArgumentException failure = Assertions.assertThrows(IllegalArgumentException.class, + () -> new OpenCliRemoteAuthentication("Authorization", "Bearer " + secret + "\r\nX-Injected: yes")); + Assertions.assertFalse(failure.toString().contains(secret)); + Assertions.assertThrows(IllegalArgumentException.class, + () -> new OpenCliRemoteAuthentication("Host", secret)); + } + @Test void nonSuccessHttpResponseDoesNotExposeBodyCanaryInException() throws IOException { String canary = "body-secret-" + UUID.randomUUID(); - String urlCanary = "url-secret-" + UUID.randomUUID(); try (JsonCollectStub stub = JsonCollectStub.start(canary, 503)) { OpenCliProperties props = baseProps(stub.port()); - props.setRemoteAgentBaseUrl("http://127.0.0.1:" + stub.port() - + "/collect?token=" + urlCanary); OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(props); ByteArrayOutputStream diagnostics = new ByteArrayOutputStream(); PrintStream previousErr = System.err; @@ -379,7 +508,6 @@ void nonSuccessHttpResponseDoesNotExposeBodyCanaryInException() throws IOExcepti } Assertions.assertTrue(ex.getMessage().contains("503")); Assertions.assertFalse(ex.toString().contains(canary)); - Assertions.assertFalse(ex.toString().contains(urlCanary)); String logText = diagnostics.toString(StandardCharsets.UTF_8.name()); Assertions.assertTrue(logText.contains("Agent HTTP non-2xx")); Matcher correlation = Pattern.compile("correlationId=([0-9a-f-]{36})") @@ -388,10 +516,8 @@ void nonSuccessHttpResponseDoesNotExposeBodyCanaryInException() throws IOExcepti Assertions.assertDoesNotThrow(() -> UUID.fromString(correlation.group(1))); Assertions.assertTrue(logText.contains(correlation.group(0))); Assertions.assertFalse(logText.contains(canary)); - Assertions.assertFalse(logText.contains(urlCanary)); for (Throwable cause = ex.getCause(); cause != null; cause = cause.getCause()) { Assertions.assertFalse(cause.toString().contains(canary)); - Assertions.assertFalse(cause.toString().contains(urlCanary)); } } } @@ -589,7 +715,19 @@ static JsonCollectStub start(String jsonBody, int status) throws IOException { } static JsonCollectStub start(HttpHandler response) throws IOException { - HttpServer server = HttpServer.create(new InetSocketAddress(0), 0); + return start(null, response); + } + + static JsonCollectStub start(SSLContext tls, HttpHandler response) throws IOException { + InetSocketAddress address = new InetSocketAddress("127.0.0.1", 0); + HttpServer server; + if (Objects.isNull(tls)) { + server = HttpServer.create(address, 0); + } else { + HttpsServer https = HttpsServer.create(address, 0); + https.setHttpsConfigurator(new HttpsConfigurator(tls)); + server = https; + } JsonCollectStub stub = new JsonCollectStub(server, server.getAddress().getPort()); server.createContext( "/collect", diff --git a/src/test/java/io/github/easy4j/opencli/testsupport/OpenCliTlsFixture.java b/src/test/java/io/github/easy4j/opencli/testsupport/OpenCliTlsFixture.java new file mode 100644 index 0000000..3df96fa --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/testsupport/OpenCliTlsFixture.java @@ -0,0 +1,59 @@ +package io.github.easy4j.opencli.testsupport; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.io.InputStream; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.security.KeyStore; +import java.util.concurrent.TimeUnit; +import javax.net.ssl.KeyManagerFactory; +import javax.net.ssl.SSLContext; +import javax.net.ssl.TrustManagerFactory; +import lombok.Getter; + +/** A loopback TLS certificate and explicit client trust for integration tests. */ +@Getter +public final class OpenCliTlsFixture { + + private final SSLContext server; + private final SSLContext trustedClient; + + private OpenCliTlsFixture(SSLContext server, SSLContext trustedClient) { + this.server = server; + this.trustedClient = trustedClient; + } + + public static OpenCliTlsFixture create(Path temporary) throws Exception { + Path storePath = temporary.resolve("opencli-fixture.p12"); + String keytool = System.getProperty("os.name").startsWith("Windows") ? "keytool.exe" : "keytool"; + Path tool = Paths.get(System.getProperty("java.home"), "bin", keytool); + Process keygen = new ProcessBuilder(tool.toString(), "-genkeypair", "-alias", "center", "-keyalg", "RSA", + "-keysize", "2048", "-dname", "CN=localhost", "-ext", "SAN=IP:127.0.0.1", "-validity", "1", + "-storetype", "PKCS12", "-keystore", storePath.toString(), "-storepass", "test-password") + .redirectErrorStream(true).redirectOutput(temporary.resolve("keytool.log").toFile()).start(); + try { + assertTrue(keygen.waitFor(10, TimeUnit.SECONDS)); + assertEquals(0, keygen.exitValue()); + } finally { + if (keygen.isAlive()) { + keygen.destroyForcibly(); + } + } + KeyStore store = KeyStore.getInstance("PKCS12"); + try (InputStream input = Files.newInputStream(storePath)) { + store.load(input, "test-password".toCharArray()); + } + KeyManagerFactory keys = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm()); + keys.init(store, "test-password".toCharArray()); + SSLContext server = SSLContext.getInstance("TLS"); + server.init(keys.getKeyManagers(), null, null); + TrustManagerFactory trust = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()); + trust.init(store); + SSLContext trustedClient = SSLContext.getInstance("TLS"); + trustedClient.init(null, trust.getTrustManagers(), null); + return new OpenCliTlsFixture(server, trustedClient); + } +} From f0286587c9caa98aa50fa4d4ab0045d23776b453 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:53:10 +0800 Subject: [PATCH 037/105] Verify HTTPS collect under an Agent path prefix --- README.md | 2 +- README.zh-CN.md | 2 +- .../remote/OpenCliRemoteAgentHttpClientTest.java | 12 ++++++++---- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 9b1dfca..268f418 100644 --- a/README.md +++ b/README.md @@ -181,7 +181,7 @@ Configuration is object-based via `OpenCliProperties`: | `maxConcurrentExecutions` | `0` | Max concurrent subprocesses (0 = unlimited) | | `startupProbeTimeoutMillis` | `30000` | Availability-probe timeout | | `environment` | `{}` | Extra environment variables (e.g. `OPENCLI_CDP_ENDPOINT`) | -| `remoteAgentBaseUrl` | — | Remote agent base URL | +| `remoteAgentBaseUrl` | — | Remote Agent HTTP(S) base URL. Keep any deployment path prefix and omit user info, queries and fragments. | | `remoteCollectMode` | `cdp` | `bridge` or `cdp` (must match the agent side) | | `remoteOutputFormat` | `json` | Output format requested from the agent | | `remoteCdpEndpoint` | — | Optional CDP endpoint overriding the agent default | diff --git a/README.zh-CN.md b/README.zh-CN.md index 774ab1e..5dce7ac 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -180,7 +180,7 @@ cli.gemini().deepResearch("topic", | `maxConcurrentExecutions` | `0` | 最大并发子进程数(0 = 不限) | | `startupProbeTimeoutMillis` | `30000` | 可用性探测超时 | | `environment` | `{}` | 额外环境变量(如 `OPENCLI_CDP_ENDPOINT`) | -| `remoteAgentBaseUrl` | — | 远程 Agent 根地址 | +| `remoteAgentBaseUrl` | — | 远程 Agent 的 HTTP(S) 基址,可以保留部署路径前缀。省略用户信息、查询参数和片段。 | | `remoteCollectMode` | `cdp` | `bridge` 或 `cdp`(须与 Agent 侧一致) | | `remoteOutputFormat` | `json` | 向 Agent 请求的输出格式 | | `remoteCdpEndpoint` | — | 可选,覆盖 Agent 默认 CDP 端点 | diff --git a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java index 6775946..499a7bd 100644 --- a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java +++ b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java @@ -373,7 +373,7 @@ void authenticationHeaderIsSentOnlyOverVerifiedTls(@TempDir Path temporary) thro AtomicReference receivedUri = new AtomicReference<>(); OpenCliTlsFixture tls = OpenCliTlsFixture.create(temporary); SSLContext previous = SSLContext.getDefault(); - try (JsonCollectStub stub = JsonCollectStub.start(tls.getServer(), exchange -> { + try (JsonCollectStub stub = JsonCollectStub.start(tls.getServer(), "/agent/collect", exchange -> { receivedCredential.set(exchange.getRequestHeaders().getFirst(header)); receivedUri.set(exchange.getRequestURI().toASCIIString()); // The synthetic fixture supports only this explicit header. @@ -389,7 +389,7 @@ void authenticationHeaderIsSentOnlyOverVerifiedTls(@TempDir Path temporary) thro } })) { OpenCliProperties props = baseProps(stub.port()); - props.setRemoteAgentBaseUrl("https://127.0.0.1:" + stub.port()); + props.setRemoteAgentBaseUrl("https://127.0.0.1:" + stub.port() + "/agent///"); props.setRemoteAuthentication(new OpenCliRemoteAuthentication(header, credential)); Assertions.assertFalse(props.toString().contains(credential)); Assertions.assertNull(props.copyForLocalCliExecution().getRemoteAuthentication()); @@ -405,7 +405,7 @@ void authenticationHeaderIsSentOnlyOverVerifiedTls(@TempDir Path temporary) thro try (OpenCliRemoteAgentHttpClient client = new OpenCliRemoteAgentHttpClient(props)) { Assertions.assertTrue(client.collect(request).isSuccess()); Assertions.assertEquals(credential, receivedCredential.get()); - Assertions.assertEquals("/collect", receivedUri.get()); + Assertions.assertEquals("/agent/collect", receivedUri.get()); Assertions.assertFalse(stub.requestBody.contains(credential)); props.setRemoteAuthentication(new OpenCliRemoteAuthentication(header, "rejected-" + credential)); ByteArrayOutputStream diagnostics = new ByteArrayOutputStream(); @@ -719,6 +719,10 @@ static JsonCollectStub start(HttpHandler response) throws IOException { } static JsonCollectStub start(SSLContext tls, HttpHandler response) throws IOException { + return start(tls, "/collect", response); + } + + static JsonCollectStub start(SSLContext tls, String path, HttpHandler response) throws IOException { InetSocketAddress address = new InetSocketAddress("127.0.0.1", 0); HttpServer server; if (Objects.isNull(tls)) { @@ -730,7 +734,7 @@ static JsonCollectStub start(SSLContext tls, HttpHandler response) throws IOExce } JsonCollectStub stub = new JsonCollectStub(server, server.getAddress().getPort()); server.createContext( - "/collect", + path, new HttpHandler() { @Override public void handle(HttpExchange exchange) throws IOException { From bc630bb166dada9a45971c4bd6f818aab24f4807 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:56:14 +0800 Subject: [PATCH 038/105] Capture OpenCLI 1.8.8 structured help contracts Refs #5 (cherry picked from commit fb766c66dab133b11ec6d68abc4e51c8df35654f) --- .../evidence/2026-11-19-structured-help.md | 21 + .../add-opencli-capability-discovery/tasks.md | 4 +- .../OpenCliStructuredHelpFixtureTest.java | 86 + .../v1/structured-help-1.8.8/.gitattributes | 2 + .../v1/structured-help-1.8.8/SHA256SUMS | 9 + .../v1/structured-help-1.8.8/browser-get.json | 292 +++ .../structured-help-1.8.8/browser-state.json | 57 + .../v1/structured-help-1.8.8/browser-tab.json | 99 + .../v1/structured-help-1.8.8/browser.stdout | 1624 +++++++++++++++++ .../v1/structured-help-1.8.8/meta-auth.json | 124 ++ .../v1/structured-help-1.8.8/meta-list.txt | 8 + .../v1/structured-help-1.8.8/root.json | 289 +++ .../site-npm-search.json | 86 + .../v1/structured-help-1.8.8/site-npm.json | 154 ++ 14 files changed, 2853 insertions(+), 2 deletions(-) create mode 100644 openspec/changes/add-opencli-capability-discovery/evidence/2026-11-19-structured-help.md create mode 100644 src/test/java/io/github/easy4j/opencli/contract/OpenCliStructuredHelpFixtureTest.java create mode 100644 src/test/resources/opencli-contracts/v1/structured-help-1.8.8/.gitattributes create mode 100644 src/test/resources/opencli-contracts/v1/structured-help-1.8.8/SHA256SUMS create mode 100644 src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser-get.json create mode 100644 src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser-state.json create mode 100644 src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser-tab.json create mode 100644 src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser.stdout create mode 100644 src/test/resources/opencli-contracts/v1/structured-help-1.8.8/meta-auth.json create mode 100644 src/test/resources/opencli-contracts/v1/structured-help-1.8.8/meta-list.txt create mode 100644 src/test/resources/opencli-contracts/v1/structured-help-1.8.8/root.json create mode 100644 src/test/resources/opencli-contracts/v1/structured-help-1.8.8/site-npm-search.json create mode 100644 src/test/resources/opencli-contracts/v1/structured-help-1.8.8/site-npm.json diff --git a/openspec/changes/add-opencli-capability-discovery/evidence/2026-11-19-structured-help.md b/openspec/changes/add-opencli-capability-discovery/evidence/2026-11-19-structured-help.md new file mode 100644 index 0000000..0570ffc --- /dev/null +++ b/openspec/changes/add-opencli-capability-discovery/evidence/2026-11-19-structured-help.md @@ -0,0 +1,21 @@ +# OpenCLI 1.8.8 帮助协议采集 + +使用 Node 24.18.0 和 npm 发布包 `@jackwener/opencli@1.8.8`,运行包声明的入口 `dist/src/main.js`。上游 `v1.8.8` tag 指向 `8271afc67e8504bda94c147f446ee29775d08274`,与本项目 U02/U03 锁定一致。[上游帮助实现](https://github.com/jackwener/OpenCLI/blob/8271afc67e8504bda94c147f446ee29775d08274/src/help.ts) + +[原始样本及 SHA-256](../../../../src/test/resources/opencli-contracts/v1/structured-help-1.8.8/) 按 stdout 字节保存。两轮分别使用独立临时用户目录,禁止自动更新检查,不加载用户已有的配置或插件。只运行 `--version` 和下表的帮助参数。两轮版本均为 1.8.8,9 个样本均退出 0、stderr 为空,对应 stdout 逐字节一致。样本来自 Apache-2.0 发布包。 + +| 样本 | 入口参数 | 实际输出 | +|---|---|---| +| `root.json` | `--help -f json` | 单一 JSON。根命令为简要列表,`site_adapters` 为含 `count`、`sites` 的对象。 | +| `browser.stdout` | `browser --help -f json` | JSON 后附加示例说明,共 472 个非首尾空白后缀字符,严格 JSON 读取失败。 | +| `browser-tab.json` | `browser fixture tab --help -f json` | `tab` 分组 JSON。命令路径保留 ``,包括 `tab list`、`tab select`。 | +| `browser-get.json` | `browser fixture get --help -f json` | `get` 分组 JSON。包含 `get text`、`get attributes` 等叶子。该版本把 `tab` 和 `get` 分为两组。 | +| `browser-state.json` | `browser fixture state --help -f json` | 单个叶子,带 session 占位符和独立的三类 options。 | +| `meta-auth.json` | `auth --help -f json` | meta 命名空间 JSON,保留 namespace 与 global options。 | +| `meta-list.txt` | `list --help -f json` | 纯文本 Commander 帮助,严格 JSON 读取失败。 | +| `site-npm.json` | `npm --help -f json` | 站点目录 JSON,公共参数字段为 `common_options`。 | +| `site-npm-search.json` | `npm search --help -f json` | 叶子 JSON,含必填位置参数 `query` 和命令参数 `limit`。 | + +采集时通过 `node --import` 预加载脚本,将进程的 `os.homedir()` 指向临时目录,并同步 Node 内置模块导出。为两轮分别配置 `OPENCLI_CACHE_DIR`、`OPENCLI_CONFIG_DIR`,设置 `CI=1`、`NO_COLOR=1`。浏览器参数 `fixture` 是帮助查询的字面会话名,未创建会话或执行叶子命令。 + +`OpenCliStructuredHelpFixtureTest` 验证真实的作用域、占位符、根命令目录与两种负例,报告位于 `target/surefire-reports`。这些输出约束后续 C06 模型设计。两种负例仍需发现服务给出明确状态。远端 Agent、运行时插件、本地 override 及其他站点尚无本轮采集证据。 diff --git a/openspec/changes/add-opencli-capability-discovery/tasks.md b/openspec/changes/add-opencli-capability-discovery/tasks.md index c0e8f0a..313a578 100644 --- a/openspec/changes/add-opencli-capability-discovery/tasks.md +++ b/openspec/changes/add-opencli-capability-discovery/tasks.md @@ -1,12 +1,12 @@ # C06 Tasks · 结构化能力发现与可追溯快照 -> 全部为待执行实现任务。文档/格式检查通过不允许提前勾选。 +> 勾选项有对应的执行证据。 关联规范:[spec](specs/opencli-capability-discovery/spec.md)。 ## 1. schema基线 -- [ ] 1.1 从锁定OpenCLI采集root/browser/meta/site结构化help,记录真实来源与hash,清楚标注不能采集的部分。 +- [x] 1.1 从锁定 OpenCLI 采集 root、browser、meta 和 site 帮助,保存原文与 SHA-256。不能读取为单一 JSON 文档的输出单列为负例。见 [1.8.8 采集证据](evidence/2026-11-19-structured-help.md)。 - [ ] 1.2 为scope、optionalvalue、negate、false、aliases、session占位和旧格式编写失败测试。 ## 2. 服务实现 diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliStructuredHelpFixtureTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliStructuredHelpFixtureTest.java new file mode 100644 index 0000000..282d70f --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliStructuredHelpFixtureTest.java @@ -0,0 +1,86 @@ +package io.github.easy4j.opencli.contract; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import com.fasterxml.jackson.core.JsonProcessingException; +import com.fasterxml.jackson.databind.DeserializationFeature; +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectReader; +import com.fasterxml.jackson.databind.json.JsonMapper; +import java.io.IOException; +import java.io.InputStream; +import org.junit.jupiter.api.Test; + +class OpenCliStructuredHelpFixtureTest { + + private static final String FIXTURES = "/opencli-contracts/v1/structured-help-1.8.8/"; + private static final ObjectReader STRICT_JSON = new JsonMapper().reader() + .with(DeserializationFeature.FAIL_ON_TRAILING_TOKENS); + + @Test + void preservesTheRootMetaAndSiteShapes() throws IOException { + JsonNode root = read("root.json"); + assertEquals("opencli", root.path("name").asText()); + assertTrue(includesNamed(root.path("commands"), "list")); + assertTrue(root.path("site_adapters").isObject()); + assertTrue(root.path("site_adapters").path("sites").isArray()); + + JsonNode auth = read("meta-auth.json"); + assertEquals("opencli auth", auth.path("command").asText()); + assertTrue(auth.path("namespace_options").isArray()); + assertTrue(auth.path("global_options").isArray()); + + JsonNode site = read("site-npm.json"); + assertEquals("npm", site.path("site").asText()); + assertTrue(includesNamed(site.path("commands"), "search")); + assertTrue(site.path("common_options").isArray()); + + JsonNode leaf = read("site-npm-search.json"); + assertEquals("opencli npm search", leaf.path("command").asText()); + assertEquals("query", leaf.path("positionals").get(0).path("name").asText()); + assertTrue(leaf.path("positionals").get(0).path("required").booleanValue()); + assertTrue(includesNamed(leaf.path("command_options"), "limit")); + } + + @Test + void preservesBrowserSessionPlaceholdersAndOptionScopes() throws IOException { + JsonNode tabs = read("browser-tab.json"); + assertEquals("opencli browser tab", tabs.path("command").asText()); + assertTrue(includesNamed(tabs.path("commands"), "tab list")); + assertTrue(includesNamed(tabs.path("namespace_options"), "window")); + assertTrue(includesNamed(tabs.path("global_options"), "profile")); + assertTrue(includesNamed(tabs.path("commands").get(0).path("command_options"), "tab")); + + JsonNode get = read("browser-get.json"); + assertEquals("opencli browser get", get.path("command").asText()); + assertTrue(includesNamed(get.path("commands"), "get text")); + + JsonNode state = read("browser-state.json"); + assertEquals("opencli browser state", state.path("command").asText()); + } + + @Test + void identifiesRealOutputsThatAreNotSingleJsonDocuments() { + assertThrows(JsonProcessingException.class, () -> read("browser.stdout")); + assertThrows(JsonProcessingException.class, () -> read("meta-list.txt")); + } + + private static boolean includesNamed(JsonNode entries, String name) { + for (JsonNode entry : entries) { + if (name.equals(entry.path("name").asText())) { + return true; + } + } + return false; + } + + private static JsonNode read(String name) throws IOException { + try (InputStream stream = OpenCliStructuredHelpFixtureTest.class.getResourceAsStream(FIXTURES + name)) { + assertNotNull(stream, name); + return STRICT_JSON.readTree(stream); + } + } +} diff --git a/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/.gitattributes b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/.gitattributes new file mode 100644 index 0000000..540f0b2 --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/.gitattributes @@ -0,0 +1,2 @@ +# Preserve upstream stdout for SHA-256 verification. +* -text whitespace=-blank-at-eof diff --git a/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/SHA256SUMS b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/SHA256SUMS new file mode 100644 index 0000000..2ebbadb --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/SHA256SUMS @@ -0,0 +1,9 @@ +98b36d2411e80ae141b4b6e6af51ab3cbe0a095031f790657ded3a8249893ea7 browser-get.json +e7c82f5f94cf299047bf276c7dfa3403e8850da1aaf0ae85f9f823e32a3ae8a0 browser-state.json +fc97ce18949e2d0ca59ed721f3ca8e8414bd4ad8404e1b860dc4f83f8ecd9195 browser-tab.json +611c4b4ab1b9f9c065c7fed5a571137fd85c64eb41912d17c26d66bf5f2f458e meta-auth.json +a2c5736472fc773da7c7c34a913192374672c7afcc2111bf01854c5f72979b7f root.json +0d6d9acae8fdb8075028308c353451f07791dce6d05d9724cd831ecd7605413c site-npm-search.json +cb0269d83a27d46a8fe25e0450d843f5e97027d0bce3e38fb73ea7993c1bd6ef site-npm.json +b96af9d8664871d83a4fb3efb27ea65fbc9ee9e71e676267930ecb66c73edf71 browser.stdout +b2d96c9154c61f18cf4eed5099db5bc31a12f4199cffcd50f8242eed852dacf2 meta-list.txt diff --git a/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser-get.json b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser-get.json new file mode 100644 index 0000000..63469c5 --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser-get.json @@ -0,0 +1,292 @@ +{ + "namespace": "browser", + "group": "get", + "command": "opencli browser get", + "usage": "opencli browser get [args] [options]", + "description": "Get page properties", + "command_count": 6, + "commands": [ + { + "name": "get attributes", + "command": "opencli browser get attributes", + "usage": "opencli browser get attributes [target] [options]", + "description": "Element attributes — JSON envelope {value, matches_n}", + "positionals": [ + { + "name": "target", + "help": "Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc." + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "Pick the nth match (0-based) when is a multi-match CSS selector", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "get html", + "command": "opencli browser get html", + "usage": "opencli browser get html [options]", + "description": "Page HTML (or scoped); use --as json for a {tag, attrs, text, children} tree", + "positionals": [], + "command_options": [ + { + "name": "selector", + "flags": "--selector ", + "help": "CSS selector scope (first match)", + "takes_value": "required" + }, + { + "name": "as", + "flags": "--as ", + "help": "Output format: \"html\" (default) or \"json\" for structured tree", + "takes_value": "required", + "default": "html" + }, + { + "name": "max", + "flags": "--max ", + "help": "Max characters of raw HTML to return (0 = unlimited)", + "takes_value": "required", + "default": "0" + }, + { + "name": "depth", + "flags": "--depth ", + "help": "(--as json) Max tree depth below root (0 = root only, 0 disables = unlimited via empty)", + "takes_value": "required", + "default": "" + }, + { + "name": "childrenMax", + "flags": "--children-max ", + "help": "(--as json) Max element children kept per node (empty = unlimited)", + "takes_value": "required", + "default": "" + }, + { + "name": "textMax", + "flags": "--text-max ", + "help": "(--as json) Max chars of direct text kept per node (empty = unlimited)", + "takes_value": "required", + "default": "" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "get text", + "command": "opencli browser get text", + "usage": "opencli browser get text [target] [options]", + "description": "Element text content — JSON envelope {value, matches_n}", + "positionals": [ + { + "name": "target", + "help": "Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc." + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "Pick the nth match (0-based) when is a multi-match CSS selector", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "get title", + "command": "opencli browser get title", + "usage": "opencli browser get title [options]", + "description": "Page title", + "positionals": [], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "get url", + "command": "opencli browser get url", + "usage": "opencli browser get url [options]", + "description": "Current page URL", + "positionals": [], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "get value", + "command": "opencli browser get value", + "usage": "opencli browser get value [target] [options]", + "description": "Input/textarea value — JSON envelope {value, matches_n}", + "positionals": [ + { + "name": "target", + "help": "Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc." + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "Pick the nth match (0-based) when is a multi-match CSS selector", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + } + ], + "namespace_options": [ + { + "name": "window", + "flags": "--window ", + "help": "Browser window mode: foreground or background", + "takes_value": "required" + } + ], + "global_options": [ + { + "name": "version", + "flags": "-V, --version", + "help": "output the version number" + }, + { + "name": "profile", + "flags": "--profile ", + "help": "Chrome profile/context alias for Browser Bridge commands", + "takes_value": "required" + } + ], + "structured_help": { + "formats": [ + "yaml", + "json" + ], + "usage": "opencli browser get --help -f yaml" + } +} diff --git a/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser-state.json b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser-state.json new file mode 100644 index 0000000..87e42bb --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser-state.json @@ -0,0 +1,57 @@ +{ + "namespace": "browser", + "name": "state", + "command": "opencli browser state", + "usage": "opencli browser state [options]", + "description": "Page state: URL, title, interactive elements with [N] indices", + "positionals": [], + "command_options": [ + { + "name": "source", + "flags": "--source ", + "help": "Snapshot backend: dom (default) or ax prototype", + "takes_value": "required", + "default": "dom" + }, + { + "name": "compareSources", + "flags": "--compare-sources", + "help": "Print DOM vs AX snapshot metrics for observation promotion decisions", + "default": false + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ], + "namespace_options": [ + { + "name": "window", + "flags": "--window ", + "help": "Browser window mode: foreground or background", + "takes_value": "required" + } + ], + "global_options": [ + { + "name": "version", + "flags": "-V, --version", + "help": "output the version number" + }, + { + "name": "profile", + "flags": "--profile ", + "help": "Chrome profile/context alias for Browser Bridge commands", + "takes_value": "required" + } + ], + "structured_help": { + "formats": [ + "yaml", + "json" + ], + "usage": "opencli browser state --help -f yaml" + } +} diff --git a/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser-tab.json b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser-tab.json new file mode 100644 index 0000000..e9eadb9 --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser-tab.json @@ -0,0 +1,99 @@ +{ + "namespace": "browser", + "group": "tab", + "command": "opencli browser tab", + "usage": "opencli browser tab [args] [options]", + "description": "Tab management — list, create, and close tabs in the browser session", + "command_count": 4, + "commands": [ + { + "name": "tab close", + "command": "opencli browser tab close", + "usage": "opencli browser tab close [targetId] [options]", + "description": "Close a tab by target ID", + "positionals": [ + { + "name": "targetId", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"" + } + ], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "tab list", + "command": "opencli browser tab list", + "usage": "opencli browser tab list [options]", + "description": "List tabs in the browser session with target IDs", + "positionals": [], + "command_options": [] + }, + { + "name": "tab new", + "command": "opencli browser tab new", + "usage": "opencli browser tab new [url] [options]", + "description": "Create a new tab and print its target ID", + "positionals": [ + { + "name": "url", + "help": "Optional URL to open in the new tab" + } + ], + "command_options": [] + }, + { + "name": "tab select", + "command": "opencli browser tab select", + "usage": "opencli browser tab select [targetId] [options]", + "description": "Select a tab by target ID and make it the default browser tab", + "positionals": [ + { + "name": "targetId", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"" + } + ], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + } + ], + "namespace_options": [ + { + "name": "window", + "flags": "--window ", + "help": "Browser window mode: foreground or background", + "takes_value": "required" + } + ], + "global_options": [ + { + "name": "version", + "flags": "-V, --version", + "help": "output the version number" + }, + { + "name": "profile", + "flags": "--profile ", + "help": "Chrome profile/context alias for Browser Bridge commands", + "takes_value": "required" + } + ], + "structured_help": { + "formats": [ + "yaml", + "json" + ], + "usage": "opencli browser tab --help -f yaml" + } +} diff --git a/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser.stdout b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser.stdout new file mode 100644 index 0000000..9c131ae --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/browser.stdout @@ -0,0 +1,1624 @@ +{ + "namespace": "browser", + "command": "opencli browser", + "usage": "opencli browser [options]", + "description": "Browser control — navigate, click, type, extract, wait (no LLM needed)", + "command_count": 42, + "commands": [ + { + "name": "analyze", + "command": "opencli browser analyze", + "usage": "opencli browser analyze [options]", + "description": "Classify site: anti-bot vendor, real-data API candidates, pattern (A/B/C/D), nearest adapter, next step", + "positionals": [ + { + "name": "url", + "required": true + } + ], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "back", + "command": "opencli browser back", + "usage": "opencli browser back [options]", + "description": "Go back in browser history", + "positionals": [], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "bind", + "command": "opencli browser bind", + "usage": "opencli browser bind [options]", + "description": "Bind the current Chrome tab/window to the browser session named by ", + "positionals": [], + "command_options": [] + }, + { + "name": "check", + "command": "opencli browser check", + "usage": "opencli browser check [target] [options]", + "description": "Ensure a checkbox/radio/aria-checked control is checked — JSON envelope {checked, changed, target, matches_n}", + "positionals": [ + { + "name": "target", + "help": "Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc." + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "When is a multi-match CSS selector, pick the nth match (0-based)", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "click", + "command": "opencli browser click", + "usage": "opencli browser click [target] [options]", + "description": "Click element — JSON envelope {clicked, target, matches_n}", + "positionals": [ + { + "name": "target", + "help": "Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc." + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "When is a multi-match CSS selector, pick the nth match (0-based)", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "close", + "command": "opencli browser close", + "usage": "opencli browser close [options]", + "description": "Release the current browser session tab lease", + "positionals": [], + "command_options": [] + }, + { + "name": "console", + "command": "opencli browser console", + "usage": "opencli browser console [options]", + "description": "Read recent browser console messages", + "positionals": [], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + }, + { + "name": "level", + "flags": "--level ", + "help": "Console level: all, error, warning, log, info, debug", + "takes_value": "required", + "default": "all" + }, + { + "name": "since", + "flags": "--since ", + "help": "Only include messages from the last duration (for example: 30s, 2m)", + "takes_value": "required" + }, + { + "name": "until", + "flags": "--until ", + "help": "Only include messages older than the duration from now", + "takes_value": "required" + }, + { + "name": "follow", + "flags": "--follow", + "help": "Continuously print new console messages as JSON lines", + "default": false + } + ] + }, + { + "name": "dblclick", + "command": "opencli browser dblclick", + "usage": "opencli browser dblclick [target] [options]", + "description": "Double-click element — JSON envelope {dblclicked, target, matches_n}", + "positionals": [ + { + "name": "target", + "help": "Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc." + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "When is a multi-match CSS selector, pick the nth match (0-based)", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "dialog accept", + "command": "opencli browser dialog accept", + "usage": "opencli browser dialog accept [options]", + "description": "Accept the currently open JavaScript dialog", + "positionals": [], + "command_options": [ + { + "name": "text", + "flags": "--text ", + "help": "Prompt text to submit for prompt() dialogs", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "dialog dismiss", + "command": "opencli browser dialog dismiss", + "usage": "opencli browser dialog dismiss [options]", + "description": "Dismiss the currently open JavaScript dialog", + "positionals": [], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "drag", + "command": "opencli browser drag", + "usage": "opencli browser drag [source] [target] [options]", + "description": "Drag one element to another — JSON envelope {dragged, source, target, source_matches_n, target_matches_n}", + "positionals": [ + { + "name": "source", + "help": "Numeric ref/CSS selector to drag from, or omit with --from-role/--from-name/etc." + }, + { + "name": "target", + "help": "Numeric ref/CSS selector to drop onto, or omit with --to-role/--to-name/etc." + } + ], + "command_options": [ + { + "name": "fromRole", + "flags": "--from-role ", + "help": "from semantic role", + "takes_value": "required" + }, + { + "name": "fromName", + "flags": "--from-name ", + "help": "from accessible name contains text", + "takes_value": "required" + }, + { + "name": "fromLabel", + "flags": "--from-label ", + "help": "from associated label contains text", + "takes_value": "required" + }, + { + "name": "fromText", + "flags": "--from-text ", + "help": "from visible text contains text", + "takes_value": "required" + }, + { + "name": "fromTestid", + "flags": "--from-testid ", + "help": "from data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "toRole", + "flags": "--to-role ", + "help": "to semantic role", + "takes_value": "required" + }, + { + "name": "toName", + "flags": "--to-name ", + "help": "to accessible name contains text", + "takes_value": "required" + }, + { + "name": "toLabel", + "flags": "--to-label ", + "help": "to associated label contains text", + "takes_value": "required" + }, + { + "name": "toText", + "flags": "--to-text ", + "help": "to visible text contains text", + "takes_value": "required" + }, + { + "name": "toTestid", + "flags": "--to-testid ", + "help": "to data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "fromNth", + "flags": "--from-nth ", + "help": "When is a multi-match CSS selector, pick the nth match (0-based)", + "takes_value": "required" + }, + { + "name": "toNth", + "flags": "--to-nth ", + "help": "When is a multi-match CSS selector, pick the nth match (0-based)", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "eval", + "command": "opencli browser eval", + "usage": "opencli browser eval [options]", + "description": "Execute JS in page context, return result", + "positionals": [ + { + "name": "js", + "required": true, + "help": "JavaScript code" + } + ], + "command_options": [ + { + "name": "frame", + "flags": "--frame ", + "help": "Cross-origin iframe index from \"browser frames\"", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "extract", + "command": "opencli browser extract", + "usage": "opencli browser extract [options]", + "description": "Extract page content as markdown, paragraph-aware chunks for long pages", + "positionals": [], + "command_options": [ + { + "name": "selector", + "flags": "--selector ", + "help": "CSS selector scope; defaults to
/
/", + "takes_value": "required" + }, + { + "name": "chunkSize", + "flags": "--chunk-size ", + "help": "Target chunk size in chars", + "takes_value": "required", + "default": "20000" + }, + { + "name": "start", + "flags": "--start ", + "help": "Start offset (use next_start_char from a previous extract)", + "takes_value": "required", + "default": "0" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "fill", + "command": "opencli browser fill", + "usage": "opencli browser fill [targetOrText] [text] [options]", + "description": "Set input/textarea/contenteditable text exactly and verify the value — JSON envelope {filled, verified, text, actual}", + "positionals": [ + { + "name": "targetOrText", + "help": "Numeric ref/CSS target, or text when using --role/--name/etc." + }, + { + "name": "text", + "help": "Text to set exactly" + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "When is a multi-match CSS selector, pick the nth match (0-based)", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "find", + "command": "opencli browser find", + "usage": "opencli browser find [options]", + "description": "Find DOM elements by CSS or semantic locator — returns JSON {matches_n, entries[]}", + "positionals": [], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "css", + "flags": "--css ", + "help": "CSS selector (required)", + "takes_value": "required" + }, + { + "name": "limit", + "flags": "--limit ", + "help": "Max entries returned", + "takes_value": "required", + "default": "50" + }, + { + "name": "textMax", + "flags": "--text-max ", + "help": "Max chars of trimmed text per entry", + "takes_value": "required", + "default": "120" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "focus", + "command": "opencli browser focus", + "usage": "opencli browser focus [target] [options]", + "description": "Focus an element — JSON envelope {focused, target, matches_n}", + "positionals": [ + { + "name": "target", + "help": "Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc." + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "When is a multi-match CSS selector, pick the nth match (0-based)", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "frames", + "command": "opencli browser frames", + "usage": "opencli browser frames [options]", + "description": "List cross-origin iframe targets in snapshot order", + "positionals": [], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "get attributes", + "command": "opencli browser get attributes", + "usage": "opencli browser get attributes [target] [options]", + "description": "Element attributes — JSON envelope {value, matches_n}", + "positionals": [ + { + "name": "target", + "help": "Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc." + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "Pick the nth match (0-based) when is a multi-match CSS selector", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "get html", + "command": "opencli browser get html", + "usage": "opencli browser get html [options]", + "description": "Page HTML (or scoped); use --as json for a {tag, attrs, text, children} tree", + "positionals": [], + "command_options": [ + { + "name": "selector", + "flags": "--selector ", + "help": "CSS selector scope (first match)", + "takes_value": "required" + }, + { + "name": "as", + "flags": "--as ", + "help": "Output format: \"html\" (default) or \"json\" for structured tree", + "takes_value": "required", + "default": "html" + }, + { + "name": "max", + "flags": "--max ", + "help": "Max characters of raw HTML to return (0 = unlimited)", + "takes_value": "required", + "default": "0" + }, + { + "name": "depth", + "flags": "--depth ", + "help": "(--as json) Max tree depth below root (0 = root only, 0 disables = unlimited via empty)", + "takes_value": "required", + "default": "" + }, + { + "name": "childrenMax", + "flags": "--children-max ", + "help": "(--as json) Max element children kept per node (empty = unlimited)", + "takes_value": "required", + "default": "" + }, + { + "name": "textMax", + "flags": "--text-max ", + "help": "(--as json) Max chars of direct text kept per node (empty = unlimited)", + "takes_value": "required", + "default": "" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "get text", + "command": "opencli browser get text", + "usage": "opencli browser get text [target] [options]", + "description": "Element text content — JSON envelope {value, matches_n}", + "positionals": [ + { + "name": "target", + "help": "Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc." + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "Pick the nth match (0-based) when is a multi-match CSS selector", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "get title", + "command": "opencli browser get title", + "usage": "opencli browser get title [options]", + "description": "Page title", + "positionals": [], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "get url", + "command": "opencli browser get url", + "usage": "opencli browser get url [options]", + "description": "Current page URL", + "positionals": [], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "get value", + "command": "opencli browser get value", + "usage": "opencli browser get value [target] [options]", + "description": "Input/textarea value — JSON envelope {value, matches_n}", + "positionals": [ + { + "name": "target", + "help": "Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc." + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "Pick the nth match (0-based) when is a multi-match CSS selector", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "hover", + "command": "opencli browser hover", + "usage": "opencli browser hover [target] [options]", + "description": "Move the mouse over an element — JSON envelope {hovered, target, matches_n}", + "positionals": [ + { + "name": "target", + "help": "Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc." + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "When is a multi-match CSS selector, pick the nth match (0-based)", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "init", + "command": "opencli browser init", + "usage": "opencli browser init [options]", + "description": "Generate adapter scaffold in ~/.opencli/clis/", + "positionals": [ + { + "name": "name", + "required": true, + "help": "Adapter name in site/command format (e.g. hn/top)" + } + ], + "command_options": [] + }, + { + "name": "keys", + "command": "opencli browser keys", + "usage": "opencli browser keys [options]", + "description": "Press keyboard key", + "positionals": [ + { + "name": "key", + "required": true, + "help": "Key to press (Enter, Escape, Tab, Control+a)" + } + ], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "network", + "command": "opencli browser network", + "usage": "opencli browser network [options]", + "description": "Capture network requests as shape previews; retrieve full bodies by key", + "positionals": [], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + }, + { + "name": "detail", + "flags": "--detail ", + "help": "Emit full body for the entry with this key", + "takes_value": "required" + }, + { + "name": "all", + "flags": "--all", + "help": "Include static resources (js/css/images/telemetry)" + }, + { + "name": "raw", + "flags": "--raw", + "help": "Emit full bodies for every entry (skip shape preview)" + }, + { + "name": "filter", + "flags": "--filter ", + "help": "Comma-separated field names; keep only entries whose body shape has ALL names as path segments", + "takes_value": "required" + }, + { + "name": "since", + "flags": "--since ", + "help": "Only include entries from the last duration (for example: 30s, 2m)", + "takes_value": "required" + }, + { + "name": "until", + "flags": "--until ", + "help": "Only include entries older than the duration from now", + "takes_value": "required" + }, + { + "name": "follow", + "flags": "--follow", + "help": "Continuously print new matching entries as JSON lines", + "default": false + }, + { + "name": "failed", + "flags": "--failed", + "help": "Only include failed HTTP requests (status 0 or >= 400)", + "default": false + }, + { + "name": "maxBody", + "flags": "--max-body ", + "help": "With --detail: cap the emitted body at N chars (0 = unlimited, default)", + "takes_value": "required", + "default": "0" + }, + { + "name": "ttl", + "flags": "--ttl ", + "help": "Cache TTL in ms for --detail lookups", + "takes_value": "required", + "default": "86400000" + } + ] + }, + { + "name": "open", + "command": "opencli browser open", + "usage": "opencli browser open [options]", + "description": "Open URL in the browser session", + "positionals": [ + { + "name": "url", + "required": true + } + ], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "screenshot", + "command": "opencli browser screenshot", + "usage": "opencli browser screenshot [path] [options]", + "description": "Take screenshot", + "positionals": [ + { + "name": "path", + "help": "Save to file (base64 if omitted)" + } + ], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + }, + { + "name": "fullPage", + "flags": "--full-page", + "help": "Capture the full scrollable page, not just the viewport", + "default": false + }, + { + "name": "annotate", + "flags": "--annotate", + "help": "Overlay visible browser state ref labels on the screenshot", + "default": false + }, + { + "name": "width", + "flags": "--width ", + "help": "Override viewport width in CSS pixels for this screenshot only", + "takes_value": "required" + }, + { + "name": "height", + "flags": "--height ", + "help": "Override viewport height in CSS pixels for this screenshot only (ignored with --full-page)", + "takes_value": "required" + } + ] + }, + { + "name": "scroll", + "command": "opencli browser scroll", + "usage": "opencli browser scroll [options]", + "description": "Scroll page", + "positionals": [ + { + "name": "direction", + "required": true, + "help": "up or down" + } + ], + "command_options": [ + { + "name": "amount", + "flags": "--amount ", + "help": "Pixels to scroll", + "takes_value": "required", + "default": "500" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "select", + "command": "opencli browser select", + "usage": "opencli browser select [targetOrOption] [option] [options]", + "description": "Select dropdown option — JSON envelope {selected, target, matches_n}", + "positionals": [ + { + "name": "targetOrOption", + "help": "Numeric ref/CSS target, or option text when using --role/--name/etc." + }, + { + "name": "option", + "help": "Option text (or value) to select" + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "When is a multi-match CSS selector, pick the nth match (0-based)", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "state", + "command": "opencli browser state", + "usage": "opencli browser state [options]", + "description": "Page state: URL, title, interactive elements with [N] indices", + "positionals": [], + "command_options": [ + { + "name": "source", + "flags": "--source ", + "help": "Snapshot backend: dom (default) or ax prototype", + "takes_value": "required", + "default": "dom" + }, + { + "name": "compareSources", + "flags": "--compare-sources", + "help": "Print DOM vs AX snapshot metrics for observation promotion decisions", + "default": false + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "tab close", + "command": "opencli browser tab close", + "usage": "opencli browser tab close [targetId] [options]", + "description": "Close a tab by target ID", + "positionals": [ + { + "name": "targetId", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"" + } + ], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "tab list", + "command": "opencli browser tab list", + "usage": "opencli browser tab list [options]", + "description": "List tabs in the browser session with target IDs", + "positionals": [], + "command_options": [] + }, + { + "name": "tab new", + "command": "opencli browser tab new", + "usage": "opencli browser tab new [url] [options]", + "description": "Create a new tab and print its target ID", + "positionals": [ + { + "name": "url", + "help": "Optional URL to open in the new tab" + } + ], + "command_options": [] + }, + { + "name": "tab select", + "command": "opencli browser tab select", + "usage": "opencli browser tab select [targetId] [options]", + "description": "Select a tab by target ID and make it the default browser tab", + "positionals": [ + { + "name": "targetId", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"" + } + ], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "type", + "command": "opencli browser type", + "usage": "opencli browser type [targetOrText] [text] [options]", + "description": "Click element, then type text — JSON envelope {typed, text, target, matches_n, autocomplete}", + "positionals": [ + { + "name": "targetOrText", + "help": "Numeric ref/CSS target, or text when using --role/--name/etc." + }, + { + "name": "text", + "help": "Text to type" + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "When is a multi-match CSS selector, pick the nth match (0-based)", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "unbind", + "command": "opencli browser unbind", + "usage": "opencli browser unbind [options]", + "description": "Detach the bound browser session named by without closing the user tab/window", + "positionals": [], + "command_options": [] + }, + { + "name": "uncheck", + "command": "opencli browser uncheck", + "usage": "opencli browser uncheck [target] [options]", + "description": "Ensure a checkbox/aria-checked control is unchecked — JSON envelope {checked, changed, target, matches_n}", + "positionals": [ + { + "name": "target", + "help": "Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc." + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "When is a multi-match CSS selector, pick the nth match (0-based)", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "upload", + "command": "opencli browser upload", + "usage": "opencli browser upload [targetOrFile] [files...] [options]", + "description": "Attach local files to a file input — JSON envelope {uploaded, files, file_names, target, matches_n}", + "positionals": [ + { + "name": "targetOrFile", + "help": "Numeric ref/CSS target, or first file when using --role/--name/etc." + }, + { + "name": "files", + "variadic": true, + "help": "Local file path(s) to attach" + } + ], + "command_options": [ + { + "name": "role", + "flags": "--role ", + "help": "Semantic role (button, link, textbox, option, etc.)", + "takes_value": "required" + }, + { + "name": "name", + "flags": "--name ", + "help": "Accessible name contains text (aria-label, label, title, placeholder, or visible text)", + "takes_value": "required" + }, + { + "name": "label", + "flags": "--label ", + "help": "Associated label contains text", + "takes_value": "required" + }, + { + "name": "text", + "flags": "--text ", + "help": "Visible text contains text", + "takes_value": "required" + }, + { + "name": "testid", + "flags": "--testid ", + "help": "data-testid / data-test / test-id contains id", + "takes_value": "required" + }, + { + "name": "nth", + "flags": "--nth ", + "help": "When is a multi-match CSS selector, pick the nth match (0-based)", + "takes_value": "required" + }, + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + } + ] + }, + { + "name": "verify", + "command": "opencli browser verify", + "usage": "opencli browser verify [options]", + "description": "Execute an adapter and validate output; uses fixture at ~/.opencli/sites//verify/.json when present", + "positionals": [ + { + "name": "name", + "required": true, + "help": "Adapter name in site/command format (e.g. hn/top)" + } + ], + "command_options": [ + { + "name": "writeFixture", + "flags": "--write-fixture", + "help": "Write a starter fixture to ~/.opencli/sites//verify/.json if none exists" + }, + { + "name": "updateFixture", + "flags": "--update-fixture", + "help": "Overwrite an existing fixture with one derived from current output" + }, + { + "name": "fixture", + "flags": "--no-fixture", + "help": "Ignore any fixture file for this run (no value-level validation)", + "negate": true + }, + { + "name": "strictMemory", + "flags": "--strict-memory", + "help": "Fail (not just warn) when ~/.opencli/sites//endpoints.json or notes.md is missing" + }, + { + "name": "seedArgs", + "flags": "--seed-args ", + "help": "Seed args when no fixture exists; use JSON array/object for multiple args or flags", + "takes_value": "required" + }, + { + "name": "trace", + "flags": "--trace ", + "help": "Trace capture for the adapter subprocess: off, on, retain-on-failure", + "takes_value": "required", + "default": "off" + } + ] + }, + { + "name": "wait", + "command": "opencli browser wait", + "usage": "opencli browser wait [value] [options]", + "description": "Wait for selector, text, time, matching XHR, or browser download (e.g. wait selector \".loaded\", wait text \"Success\", wait time 3, wait xhr \"/api/search\", wait download receipt.pdf)", + "positionals": [ + { + "name": "type", + "required": true, + "help": "selector, text, time, xhr, or download" + }, + { + "name": "value", + "help": "CSS selector, text string, seconds, XHR URL regex, or download filename/URL pattern" + } + ], + "command_options": [ + { + "name": "tab", + "flags": "--tab ", + "help": "Target tab/page identity returned by \"browser open\", \"browser tab new\", or \"browser tab list\"", + "takes_value": "required" + }, + { + "name": "timeout", + "flags": "--timeout ", + "help": "Timeout in milliseconds", + "takes_value": "required", + "default": "10000" + } + ] + } + ], + "namespace_options": [ + { + "name": "window", + "flags": "--window ", + "help": "Browser window mode: foreground or background", + "takes_value": "required" + } + ], + "global_options": [ + { + "name": "version", + "flags": "-V, --version", + "help": "output the version number" + }, + { + "name": "profile", + "flags": "--profile ", + "help": "Chrome profile/context alias for Browser Bridge commands", + "takes_value": "required" + } + ], + "structured_help": { + "formats": [ + "yaml", + "json" + ], + "usage": "opencli browser --help -f yaml" + } +} + + is a required positional: pass the name of the browser session every subcommand should operate on. Reuse the same name across calls to keep the tab/state alive; pick a different name to isolate parallel browser work. + +Examples: + $ opencli browser work open https://x.com + $ opencli browser work open https://x.com --window background + $ opencli browser work click 12 + $ opencli browser work state + $ opencli browser work bind + $ opencli browser work unbind + diff --git a/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/meta-auth.json b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/meta-auth.json new file mode 100644 index 0000000..92e3df6 --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/meta-auth.json @@ -0,0 +1,124 @@ +{ + "namespace": "auth", + "command": "opencli auth", + "usage": "opencli auth [args] [options]", + "description": "Inspect website login status", + "command_count": 2, + "commands": [ + { + "name": "refresh", + "command": "opencli auth refresh", + "usage": "opencli auth refresh [options]", + "description": "Touch logged-in site sessions to keep browser auth fresh", + "positionals": [], + "command_options": [ + { + "name": "site", + "flags": "--site ", + "help": "Comma-separated site names to refresh, e.g. github,claude", + "takes_value": "required" + }, + { + "name": "all", + "flags": "--all", + "help": "Ignore the 24h refresh throttle and force every selected site", + "default": false + }, + { + "name": "concurrency", + "flags": "--concurrency ", + "help": "Maximum sites to refresh at once", + "takes_value": "required" + }, + { + "name": "timeout", + "flags": "--timeout ", + "help": "Per-site timeout in seconds", + "takes_value": "required" + }, + { + "name": "format", + "flags": "-f, --format ", + "help": "Output format: table, plain, json, yaml, md, csv", + "takes_value": "required", + "default": "table" + } + ] + }, + { + "name": "status", + "command": "opencli auth status", + "usage": "opencli auth status [options]", + "description": "Show login status for sites with auth adapters", + "positionals": [], + "command_options": [ + { + "name": "site", + "flags": "--site ", + "help": "Comma-separated site names to check, e.g. github,chatgpt", + "takes_value": "required" + }, + { + "name": "full", + "flags": "--full", + "help": "Run full per-site whoami probes instead of quick no-navigation checks", + "default": false + }, + { + "name": "concurrency", + "flags": "--concurrency ", + "help": "Maximum sites to check at once", + "takes_value": "required" + }, + { + "name": "timeout", + "flags": "--timeout ", + "help": "Per-site timeout in seconds", + "takes_value": "required" + }, + { + "name": "only", + "flags": "--only ", + "help": "Filter rows by status", + "takes_value": "required", + "default": "all", + "choices": [ + "all", + "logged-in", + "not-logged-in", + "unknown", + "error" + ] + }, + { + "name": "format", + "flags": "-f, --format ", + "help": "Output format: table, plain, json, yaml, md, csv", + "takes_value": "required", + "default": "table" + } + ] + } + ], + "namespace_options": [], + "global_options": [ + { + "name": "version", + "flags": "-V, --version", + "help": "output the version number" + }, + { + "name": "profile", + "flags": "--profile ", + "help": "Chrome profile/context alias for Browser Bridge commands", + "takes_value": "required" + } + ], + "structured_help": { + "formats": [ + "yaml", + "json" + ], + "usage": "opencli auth --help -f yaml" + } +} diff --git a/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/meta-list.txt b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/meta-list.txt new file mode 100644 index 0000000..9f074b9 --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/meta-list.txt @@ -0,0 +1,8 @@ +Usage: opencli list [options] + +List all available CLI commands + +Options: + -f, --format Output format: table, json, yaml, md, csv (default: + "table") + -h, --help display help for command diff --git a/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/root.json b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/root.json new file mode 100644 index 0000000..5041c41 --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/root.json @@ -0,0 +1,289 @@ +{ + "name": "opencli", + "description": "Make any website your CLI. Zero setup. AI-powered.", + "commands": [ + { + "name": "list", + "description": "List all available CLI commands" + }, + { + "name": "validate", + "description": "Validate CLI definitions" + }, + { + "name": "verify", + "description": "Validate + smoke test" + }, + { + "name": "skills", + "description": "list, read" + }, + { + "name": "auth", + "description": "refresh, status" + }, + { + "name": "convention-audit", + "description": "Scan adapters for agent-native convention violations" + }, + { + "name": "browser", + "description": "analyze, back, bind, check, click, close, console, dblclick, dialog, drag, eval, extract, fill, find, focus, frames, get, hover, init, keys, network, open, screenshot, scroll, select, state, tab, type, unbind, uncheck, upload, verify, wait" + }, + { + "name": "doctor", + "description": "Diagnose opencli browser bridge connectivity" + }, + { + "name": "completion", + "description": "Output shell completion script" + }, + { + "name": "plugin", + "description": "create, install, list, uninstall, update" + }, + { + "name": "adapter", + "description": "eject, reset, status" + }, + { + "name": "profile", + "description": "list, rename, use" + }, + { + "name": "daemon", + "description": "restart, status, stop" + }, + { + "name": "external", + "description": "install, list, register" + } + ], + "external_clis": { + "count": 13, + "clis": [ + "discord", + "docker", + "dws", + "gh", + "lark-cli", + "longbridge", + "ntn", + "obsidian", + "tg", + "vercel", + "wecom-cli", + "wrangler", + "wx" + ], + "display": [ + "discord(discord-cli)", + "docker", + "dws(DingTalk Workspace)", + "gh", + "lark-cli", + "longbridge", + "ntn(notion)", + "obsidian", + "tg(tg-cli)", + "vercel", + "wecom-cli(企业微信)", + "wrangler", + "wx(wx-cli)" + ] + }, + "app_adapters": { + "count": 10, + "apps": [ + "antigravity", + "chatgpt-app", + "chatwise", + "codex", + "cursor", + "discord-app", + "doubao-app", + "qoder", + "trae-cn", + "trae-solo" + ] + }, + "site_adapters": { + "count": 169, + "sites": [ + "12306", + "1688", + "1point3acres", + "36kr", + "51job", + "aibase", + "amazon", + "apple-podcasts", + "archive", + "arxiv", + "autohome", + "baidu-scholar", + "band", + "barchart", + "bbc", + "bilibili", + "binance", + "bloomberg", + "bluesky", + "booking", + "boss", + "brave", + "chaoxing", + "chatgpt", + "chess", + "claude", + "cnki", + "coingecko", + "confluence", + "coupang", + "crates", + "ctrip", + "dblp", + "deepseek", + "defillama", + "devto", + "dianping", + "dictionary", + "dockerhub", + "dongchedi", + "douban", + "doubao", + "douyin", + "dribbble", + "duckduckgo", + "eastmoney", + "endoflife", + "facebook", + "flathub", + "flomo", + "gemini", + "geogebra", + "gitee", + "github", + "github-trending", + "gmail", + "google", + "google-scholar", + "goproxy", + "gov-law", + "gov-policy", + "grok", + "guazi", + "hackernews", + "hf", + "hltv", + "homebrew", + "huodongxing", + "hupu", + "imdb", + "indeed", + "instagram", + "jd", + "jianyu", + "jike", + "jimeng", + "jira", + "juejin", + "ke", + "kimi", + "lesswrong", + "lichess", + "linkedin", + "linkedin-learning", + "linux-do", + "lobsters", + "maimai", + "manus", + "maven", + "mdn", + "medium", + "mercury", + "midjourney", + "minimax", + "mubu", + "notebooklm", + "nowcoder", + "npm", + "nuget", + "nvd", + "oeis", + "ones", + "openalex", + "openfda", + "openreview", + "osv", + "packagist", + "paperreview", + "pinterest", + "pixiv", + "powerchina", + "producthunt", + "pubmed", + "pypi", + "quark", + "qwen", + "reddit", + "rednote", + "rest-countries", + "reuters", + "rfc", + "rubygems", + "semanticscholar", + "sinablog", + "sinafinance", + "slock", + "smzdm", + "spotify", + "stackoverflow", + "steam", + "substack", + "suno", + "taobao", + "tdx", + "ths", + "tieba", + "tiktok", + "toutiao", + "trip", + "tvmaze", + "twitter", + "uisdc", + "uiverse", + "upwork", + "v2ex", + "wanfang", + "web", + "wechat-channels", + "weibo", + "weixin", + "weread", + "weread-official", + "wikidata", + "wikipedia", + "wttr", + "xianyu", + "xiaoe", + "xiaohongshu", + "xiaoyuzhou", + "xueqiu", + "yahoo", + "yahoo-finance", + "yollomi", + "youdao", + "youtube", + "yuanbao", + "zhihu", + "zlibrary", + "zsxq" + ] + }, + "next": [ + "opencli --help -f yaml", + "opencli list -f yaml", + "opencli -f yaml" + ] +} diff --git a/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/site-npm-search.json b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/site-npm-search.json new file mode 100644 index 0000000..f9c12ac --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/site-npm-search.json @@ -0,0 +1,86 @@ +{ + "site": "npm", + "name": "search", + "command": "opencli npm search", + "usage": "opencli npm search [options]", + "access": "read", + "description": "Search the public npm registry by keyword", + "browser": false, + "domain": "registry.npmjs.org", + "positionals": [ + { + "name": "query", + "type": "str", + "positional": true, + "required": true, + "help": "Search keyword (e.g. \"react\", \"graphql client\")" + } + ], + "command_options": [ + { + "name": "limit", + "type": "int", + "default": 20, + "help": "Max results (1-250)" + } + ], + "example": "opencli npm search -f yaml", + "columns": [ + "rank", + "name", + "version", + "description", + "weeklyDownloads", + "dependents", + "license", + "publisher", + "updated", + "url" + ], + "common_options": [ + { + "name": "format", + "flags": "-f, --format ", + "help": "Output format: table, plain, json, yaml, md, csv", + "default": "table", + "choices": [ + "table", + "plain", + "json", + "yaml", + "md", + "csv" + ] + }, + { + "name": "trace", + "flags": "--trace ", + "help": "Trace capture: off, on, retain-on-failure", + "default": "off", + "choices": [ + "off", + "on", + "retain-on-failure" + ] + }, + { + "name": "verbose", + "flags": "-v, --verbose", + "help": "Debug output", + "default": false + }, + { + "name": "help", + "flags": "-h, --help", + "help": "display help for command" + } + ], + "output_formats": [ + "table", + "plain", + "yaml", + "json", + "md", + "csv" + ] +} diff --git a/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/site-npm.json b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/site-npm.json new file mode 100644 index 0000000..0f0f48f --- /dev/null +++ b/src/test/resources/opencli-contracts/v1/structured-help-1.8.8/site-npm.json @@ -0,0 +1,154 @@ +{ + "site": "npm", + "command_count": 3, + "commands": [ + { + "name": "downloads", + "command": "opencli npm downloads", + "usage": "opencli npm downloads [options]", + "access": "read", + "description": "Daily download counts for an npm package over a window", + "browser": false, + "domain": "api.npmjs.org", + "positionals": [ + { + "name": "name", + "type": "str", + "positional": true, + "required": true, + "help": "npm package name (e.g. \"react\", \"@vercel/og\")" + } + ], + "command_options": [ + { + "name": "period", + "type": "str", + "default": "last-week", + "help": "last-day / last-week / last-month / last-year, or YYYY-MM-DD:YYYY-MM-DD" + } + ], + "example": "opencli npm downloads -f yaml", + "columns": [ + "rank", + "package", + "day", + "downloads" + ] + }, + { + "name": "package", + "command": "opencli npm package", + "usage": "opencli npm package [options]", + "access": "read", + "description": "Single npm package metadata (latest version, license, homepage, repository). Use `npm downloads` for stats.", + "browser": false, + "domain": "registry.npmjs.org", + "positionals": [ + { + "name": "name", + "type": "str", + "positional": true, + "required": true, + "help": "npm package name (e.g. \"react\", \"@vercel/og\")" + } + ], + "command_options": [], + "example": "opencli npm package -f yaml", + "columns": [ + "name", + "latestVersion", + "description", + "license", + "homepage", + "repository", + "bugs", + "maintainers", + "keywords", + "created", + "modified", + "url" + ] + }, + { + "name": "search", + "command": "opencli npm search", + "usage": "opencli npm search [options]", + "access": "read", + "description": "Search the public npm registry by keyword", + "browser": false, + "domain": "registry.npmjs.org", + "positionals": [ + { + "name": "query", + "type": "str", + "positional": true, + "required": true, + "help": "Search keyword (e.g. \"react\", \"graphql client\")" + } + ], + "command_options": [ + { + "name": "limit", + "type": "int", + "default": 20, + "help": "Max results (1-250)" + } + ], + "example": "opencli npm search -f yaml", + "columns": [ + "rank", + "name", + "version", + "description", + "weeklyDownloads", + "dependents", + "license", + "publisher", + "updated", + "url" + ] + } + ], + "common_options": [ + { + "name": "format", + "flags": "-f, --format ", + "help": "Output format: table, plain, json, yaml, md, csv", + "default": "table", + "choices": [ + "table", + "plain", + "json", + "yaml", + "md", + "csv" + ] + }, + { + "name": "trace", + "flags": "--trace ", + "help": "Trace capture: off, on, retain-on-failure", + "default": "off", + "choices": [ + "off", + "on", + "retain-on-failure" + ] + }, + { + "name": "verbose", + "flags": "-v, --verbose", + "help": "Debug output", + "default": false + }, + { + "name": "help", + "flags": "-h, --help", + "help": "display help for command" + } + ], + "next": [ + "opencli npm --help -f yaml", + "opencli npm -f yaml" + ] +} From 49250f97cb6618502b40e5989b8521fc733d7fab Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:59:22 +0800 Subject: [PATCH 039/105] Keep raw availability details out of startup diagnostics --- README.md | 2 ++ README.zh-CN.md | 2 ++ .../availability/OpenCliAvailabilityReport.java | 17 ++--------------- .../OpenCliAvailabilityReportTest.java | 13 ++++++++----- 4 files changed, 14 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 268f418..5867fb0 100644 --- a/README.md +++ b/README.md @@ -245,6 +245,8 @@ Call `OpenCliDiagnosticExport.export(result, 512)` explicitly with an `OpenCliRe The SDK returns the text in memory. Your application controls the destination and retention. SDK diagnostics omit argv values, raw content, URLs and filesystem paths. Applications that use or log raw results should protect that data. `remoteCaptureRawHttpResponse` is still opt-in. +`OpenCliAvailabilityReport.toDiagnosticMessage()` is suitable for startup logs and reports readiness and status. Read the executable paths or probe message through their dedicated getters when needed. + At the low-level process boundary, `RunSession.getHandler().getException()` returns a safe I/O summary. `RunSession.getIoFailure()` is the explicit raw diagnostic accessor. Handle that exception as sensitive data because it can include local paths. diff --git a/README.zh-CN.md b/README.zh-CN.md index 5dce7ac..f5407dd 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -244,6 +244,8 @@ collect 请求 ID 必须为非空白字符串,长度上限 128 个 UTF-8 字 SDK 在内存中返回文本,由应用决定目的地和保留时间。SDK 诊断会排除命令参数、原始内容、URL 和文件路径。应用读取或记录原始结果时应自行保护这些数据。`remoteCaptureRawHttpResponse` 仍需显式开启。 +`OpenCliAvailabilityReport.toDiagnosticMessage()` 可用于启动日志,只输出就绪状态和状态码。需要查看可执行文件路径或原始探测消息时,调用对应的 getter。 + 低层进程接口的 `RunSession.getHandler().getException()` 返回安全的 I/O 摘要。`RunSession.getIoFailure()` 是显式读取原始诊断的入口,异常可能包含本地路径,应按敏感数据处理。 diff --git a/src/main/java/io/github/easy4j/opencli/core/availability/OpenCliAvailabilityReport.java b/src/main/java/io/github/easy4j/opencli/core/availability/OpenCliAvailabilityReport.java index 24f34ab..1c5e65f 100644 --- a/src/main/java/io/github/easy4j/opencli/core/availability/OpenCliAvailabilityReport.java +++ b/src/main/java/io/github/easy4j/opencli/core/availability/OpenCliAvailabilityReport.java @@ -40,24 +40,11 @@ public boolean isAvailable() { } /** - * 构造面向日志/异常的诊断文本。 + * 构造可写入日志的就绪状态摘要。可执行文件和原始探测消息可通过各自的 getter 读取。 * * @return 说明字符串 */ public String toDiagnosticMessage() { - StringBuilder sb = new StringBuilder(); - sb.append("OpenCLI "); - sb.append(available ? "ready" : "unavailable"); - sb.append(" [").append(status).append(']'); - if (configuredExecutable != null) { - sb.append(" executable=").append(configuredExecutable); - } - if (resolvedExecutablePath != null) { - sb.append(" resolved=").append(resolvedExecutablePath); - } - if (message != null && !message.isEmpty()) { - sb.append(" — ").append(message); - } - return sb.toString(); + return "OpenCLI " + (available ? "ready" : "unavailable") + " [" + status + "]"; } } diff --git a/src/test/java/io/github/easy4j/opencli/core/availability/OpenCliAvailabilityReportTest.java b/src/test/java/io/github/easy4j/opencli/core/availability/OpenCliAvailabilityReportTest.java index a99b5f8..395de57 100644 --- a/src/test/java/io/github/easy4j/opencli/core/availability/OpenCliAvailabilityReportTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/availability/OpenCliAvailabilityReportTest.java @@ -23,18 +23,21 @@ void shouldBuildReport() { } @Test - void shouldGenerateDiagnosticMessage() { + void shouldKeepPathsAndProviderDetailsOutOfDiagnosticMessage() { OpenCliAvailabilityReport report = OpenCliAvailabilityReport.builder() .status(OpenCliAvailabilityStatus.EXECUTABLE_NOT_FOUND) .available(false) - .configuredExecutable("opencli") - .message("not found on PATH") + .configuredExecutable("private-configured-executable") + .resolvedExecutablePath("/private/resolved-executable") + .message("private-probe-detail") .build(); String diag = report.toDiagnosticMessage(); assertTrue(diag.contains("unavailable")); assertTrue(diag.contains("EXECUTABLE_NOT_FOUND")); - assertTrue(diag.contains("opencli")); - assertTrue(diag.contains("not found on PATH")); + assertFalse(diag.contains("private")); + assertEquals("private-configured-executable", report.getConfiguredExecutable()); + assertEquals("/private/resolved-executable", report.getResolvedExecutablePath()); + assertEquals("private-probe-detail", report.getMessage()); } @Test From cca3dbbdde27e07f975d1a82e27f99fab75b09ca Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:05:14 +0800 Subject: [PATCH 040/105] Require pinned structured help evidence in OpenCLI CI --- .github/workflows/ci.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fec360b..d34526a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -34,6 +34,10 @@ jobs: java-version: '8' cache: maven + - name: Verify pinned structured help samples + working-directory: src/test/resources/opencli-contracts/v1/structured-help-1.8.8 + run: sha256sum --strict -c SHA256SUMS + - name: Build and verify with JaCoCo coverage run: ./mvnw -B --no-transfer-progress clean verify From af62b295c3166c32951ea2dd3238b6290a0dd3b3 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:04:17 +0800 Subject: [PATCH 041/105] Decode versioned OpenCLI structured help with explicit unknown states Refs #5 (cherry picked from commit 02e9358e7f792b4949916cda69e34689a305d408) --- README.md | 1 + README.zh-CN.md | 1 + .../add-opencli-capability-discovery/tasks.md | 7 + .../opencli/parser/OpenCliHelpParser.java | 167 ++++++++++++++++++ .../opencli/parser/OpenCliHelpResult.java | 27 +++ .../opencli/parser/OpenCliHelpSchema.java | 45 +++++ .../contract/OpenCliHelpParserTest.java | 104 +++++++++++ 7 files changed, 352 insertions(+) create mode 100644 src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpParser.java create mode 100644 src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpResult.java create mode 100644 src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpSchema.java create mode 100644 src/test/java/io/github/easy4j/opencli/contract/OpenCliHelpParserTest.java diff --git a/README.md b/README.md index 5867fb0..898aea1 100644 --- a/README.md +++ b/README.md @@ -196,6 +196,7 @@ Notes: - A collect timeout raises `OpenCliRemoteTimeoutException`. After dispatch to the HTTP transport, `isRemoteOutcomeUnknown()` is true. Collect does not automatically retry or follow redirects. - Inspect `getRemoteExecutionDetails()` on the result or on an exception’s `getPartialResult()` to distinguish HTTP status, Agent business status and the source of `items`. The legacy 0/1 returned by `getExitCode()` is synthetic. HTTP and protocol failure snapshots have no exit code. Accepted response text is available in those snapshots only when raw capture is enabled. - If your Agent accepts a credential header, configure `setRemoteAuthentication(new OpenCliRemoteAuthentication("Authorization", System.getenv("OPENCLI_AGENT_AUTHORIZATION")))`. Supply the complete header value. The Agent base URL must use HTTPS for credentials and contain no user info, query or fragment. The SDK sends the configured header on `/collect`. OAuth discovery and request signing are unsupported. +- Parse previously captured CLI help with `OpenCliHelpParser.parse(stdout)`. The result retains the original text and reports whether the schema is available. Structured commands preserve placeholders and separate command, namespace, global and common options. - `execution-target=REMOTE_AGENT_HTTP` makes the availability probe report `SKIPPED_REMOTE_MODE` (treated as startable). diff --git a/README.zh-CN.md b/README.zh-CN.md index f5407dd..995d0d6 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -195,6 +195,7 @@ cli.gemini().deepResearch("topic", - 远程调用超时抛出 `OpenCliRemoteTimeoutException`。请求提交给 HTTP 传输后,`isRemoteOutcomeUnknown()` 为 true。客户端不会自动重试或跟随重定向。 - 通过结果或异常的 `getPartialResult()` 调用 `getRemoteExecutionDetails()`,查看 HTTP 状态、Agent 业务状态和 `items` 的来源。`getExitCode()` 的 0/1 是兼容映射。HTTP 或协议失败快照没有退出码。仅在开启原文捕获时,失败快照才携带已通过字节上限检查的响应正文。 - Agent 支持认证请求头时,可调用 `setRemoteAuthentication(new OpenCliRemoteAuthentication("Authorization", System.getenv("OPENCLI_AGENT_AUTHORIZATION")))`,传入完整请求头值。认证须使用 HTTPS,Agent 基础地址须省略用户信息、查询参数和片段。SDK 只在 `/collect` 请求上发送已配置的认证头。OAuth 发现和请求签名尚不支持。 +- 对已采集的 CLI 帮助调用 `OpenCliHelpParser.parse(stdout)`,可读取结构化命令、占位符、不同作用域的选项和原文。纯文本、混合输出或无效结构会返回未知状态及原因。 - `execution-target=REMOTE_AGENT_HTTP` 时可用性探测报告 `SKIPPED_REMOTE_MODE`(视为可启动)。 diff --git a/openspec/changes/add-opencli-capability-discovery/tasks.md b/openspec/changes/add-opencli-capability-discovery/tasks.md index 313a578..975b8fa 100644 --- a/openspec/changes/add-opencli-capability-discovery/tasks.md +++ b/openspec/changes/add-opencli-capability-discovery/tasks.md @@ -24,3 +24,10 @@ ## 证据交付模板(实施时填写) 每项任务的完成记录包含:Requirement/Scenario、分支HEAD、测试命令、失败→通过证据、测试数/跳过数、退出码、报告位置。没有记录的任务保持未完成。 + + +## OC-CAP-001/002/005 结构化帮助解析 + +`OpenCliHelpParser` 在 Java 8 API 范围内提供帮助解析结果。根目录、站点、命名空间和叶子按真实 1.8.8 结构识别。Schema 保留命令显示路径、会话占位符、命令层级、位置参数、别名和分作用域选项。缺失字段、显式 false、可选取值、否定和默认值分别保留。原文和各节点的来源 JSON 可以追溯未解释字段。纯文本、JSON 后缀、重复字段或无效结构返回 `UNKNOWN` 及对应原因。 + +基线的 API 验收先因缺少解析入口而无法编译。加入实现后,以 1.8.8 的七个 JSON 样本、两个原始负例和合成扩展验证,详见 `OpenCliHelpParserTest`。当前验证范围为原文解码,运行时探测、快照来源与失效、类型化会话绑定仍由其余任务验收。 diff --git a/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpParser.java b/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpParser.java new file mode 100644 index 0000000..91f119c --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpParser.java @@ -0,0 +1,167 @@ +package io.github.easy4j.opencli.parser; + +import com.fasterxml.jackson.core.JsonProcessingException; +import com.fasterxml.jackson.databind.DeserializationFeature; +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectReader; +import com.fasterxml.jackson.databind.json.JsonMapper; +import io.github.easy4j.opencli.parser.OpenCliHelpResult.Reason; +import io.github.easy4j.opencli.parser.OpenCliHelpResult.Status; +import io.github.easy4j.opencli.util.OpenCliStrings; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; +import java.util.Objects; +import java.util.function.Function; + +/** Decodes the OpenCLI structured-help response shapes without executing their contents. */ +public final class OpenCliHelpParser { + + private static final ObjectReader READER = new JsonMapper().reader().with( + DeserializationFeature.FAIL_ON_TRAILING_TOKENS, + DeserializationFeature.FAIL_ON_READING_DUP_TREE_KEY, + DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS); + + private OpenCliHelpParser() { + } + + /** + * @param rawHelp stdout from a bounded help probe or a previously collected sample + * @return a structured schema or a reason it could not be recognized + */ + public static OpenCliHelpResult parse(String rawHelp) { + if (OpenCliStrings.isBlank(rawHelp)) { + return unknown(rawHelp, Reason.EMPTY); + } + String input = rawHelp.trim(); + if (input.charAt(0) != '{') { + return unknown(rawHelp, Reason.UNSUPPORTED_FORMAT); + } + + JsonNode root; + try { + root = READER.readTree(input); + } catch (JsonProcessingException ex) { + return unknown(rawHelp, Reason.INVALID_JSON); + } + try { + if (!isHelpRoot(root)) { + return unknown(rawHelp, Reason.INVALID_SCHEMA); + } + return new OpenCliHelpResult(Status.AVAILABLE, null, rawHelp, schema(root)); + } catch (IllegalArgumentException ex) { + return unknown(rawHelp, Reason.INVALID_SCHEMA); + } + } + + private static OpenCliHelpResult unknown(String rawHelp, Reason reason) { + return new OpenCliHelpResult(Status.UNKNOWN, reason, rawHelp, null); + } + + private static boolean isHelpRoot(JsonNode root) { + if (!root.isObject()) { + return false; + } + boolean directory = root.path("commands").isArray(); + if (directory && "opencli".equals(text(root.path("name"))) && root.path("site_adapters").isObject()) { + return true; + } + if (directory && OpenCliStrings.isNotBlank(text(root.path("site")))) { + return true; + } + return (OpenCliStrings.isNotBlank(text(root.path("namespace"))) + || OpenCliStrings.isNotBlank(text(root.path("site")))) + && OpenCliStrings.isNotBlank(text(root.path("command"))) + && (directory || (OpenCliStrings.isNotBlank(text(root.path("name"))) + && (root.path("positionals").isArray() || root.path("command_options").isArray()))); + } + + private static OpenCliHelpSchema schema(JsonNode node) { + String name = text(node.path("name")); + String command = text(node.path("command")); + String site = text(node.path("site")); + if (!node.isObject() || (OpenCliStrings.isBlank(name) + && OpenCliStrings.isBlank(command) && OpenCliStrings.isBlank(site))) { + throw invalidSchema(); + } + return OpenCliHelpSchema.builder() + .name(name) + .command(command) + .namespace(text(node.path("namespace"))) + .site(site) + .aliases(array(node.path("aliases"), OpenCliHelpParser::requiredText)) + .commands(array(node.path("commands"), OpenCliHelpParser::schema)) + .positionals(array(node.path("positionals"), OpenCliHelpParser::argument)) + .commandOptions(array(node.path("command_options"), OpenCliHelpParser::argument)) + .namespaceOptions(array(node.path("namespace_options"), OpenCliHelpParser::argument)) + .globalOptions(array(node.path("global_options"), OpenCliHelpParser::argument)) + .commonOptions(array(node.path("common_options"), OpenCliHelpParser::argument)) + .sourceJson(node.toString()) + .build(); + } + + private static OpenCliHelpSchema.Argument argument(JsonNode node) { + if (!node.isObject()) { + throw invalidSchema(); + } + JsonNode defaultValue = node.path("default"); + return OpenCliHelpSchema.Argument.builder() + .name(requiredText(node.path("name"))) + .flags(text(node.path("flags"))) + .type(text(node.path("type"))) + .takesValue(text(node.path("takes_value"))) + .required(bool(node.path("required"))) + .negate(bool(node.path("negate"))) + .variadic(bool(node.path("variadic"))) + .choices(array(node.path("choices"), OpenCliHelpParser::requiredText)) + .defaultJson(defaultValue.isMissingNode() ? null : defaultValue.toString()) + .sourceJson(node.toString()) + .build(); + } + + private static List array(JsonNode node, Function decode) { + if (node.isMissingNode()) { + return Collections.emptyList(); + } + if (!node.isArray()) { + throw invalidSchema(); + } + List values = new ArrayList<>(node.size()); + for (JsonNode value : node) { + values.add(decode.apply(value)); + } + return Collections.unmodifiableList(values); + } + + private static String text(JsonNode node) { + if (node.isMissingNode()) { + return null; + } + if (!node.isTextual()) { + throw invalidSchema(); + } + return node.asText(); + } + + private static String requiredText(JsonNode node) { + String value = text(node); + if (Objects.isNull(value)) { + throw invalidSchema(); + } + return value; + } + + private static Boolean bool(JsonNode node) { + if (node.isMissingNode()) { + return null; + } + if (!node.isBoolean()) { + throw invalidSchema(); + } + return node.booleanValue(); + } + + private static IllegalArgumentException invalidSchema() { + return new IllegalArgumentException("Invalid OpenCLI help schema"); + } +} diff --git a/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpResult.java b/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpResult.java new file mode 100644 index 0000000..26942fc --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpResult.java @@ -0,0 +1,27 @@ +package io.github.easy4j.opencli.parser; + +import lombok.Getter; + +/** Result of interpreting one supplied OpenCLI help document. */ +@Getter +public final class OpenCliHelpResult { + + public enum Status { AVAILABLE, UNKNOWN } + + public enum Reason { EMPTY, UNSUPPORTED_FORMAT, INVALID_JSON, INVALID_SCHEMA } + + private final Status status; + /** Null for recognized help. */ + private final Reason reason; + /** Exact text passed to the parser, including any trailing output. */ + private final String rawHelp; + /** Available only for recognized structured help. */ + private final OpenCliHelpSchema schema; + + OpenCliHelpResult(Status status, Reason reason, String rawHelp, OpenCliHelpSchema schema) { + this.status = status; + this.reason = reason; + this.rawHelp = rawHelp; + this.schema = schema; + } +} diff --git a/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpSchema.java b/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpSchema.java new file mode 100644 index 0000000..73f5e0b --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpSchema.java @@ -0,0 +1,45 @@ +package io.github.easy4j.opencli.parser; + +import java.util.List; +import lombok.AccessLevel; +import lombok.Builder; +import lombok.Getter; + +/** Read-only projection of a recognized help document or command entry. */ +@Getter +@Builder(access = AccessLevel.PACKAGE) +public final class OpenCliHelpSchema { + + private final String name; + /** Upstream display path, including any unbound placeholders. */ + private final String command; + private final String namespace; + private final String site; + private final List aliases; + private final List commands; + private final List positionals; + private final List commandOptions; + private final List namespaceOptions; + private final List globalOptions; + private final List commonOptions; + /** Source JSON for this entry, including fields the SDK does not interpret. */ + private final String sourceJson; + + /** Option or positional metadata as reported by OpenCLI. Missing scalar fields are null. */ + @Getter + @Builder(access = AccessLevel.PACKAGE) + public static final class Argument { + + private final String name; + private final String flags; + private final String type; + private final String takesValue; + private final Boolean required; + private final Boolean negate; + private final Boolean variadic; + private final List choices; + /** JSON representation of the reported default. Explicit null is the literal "null". */ + private final String defaultJson; + private final String sourceJson; + } +} diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliHelpParserTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliHelpParserTest.java new file mode 100644 index 0000000..7e55cdf --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliHelpParserTest.java @@ -0,0 +1,104 @@ +package io.github.easy4j.opencli.contract; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import io.github.easy4j.opencli.parser.OpenCliHelpParser; +import io.github.easy4j.opencli.parser.OpenCliHelpResult; +import io.github.easy4j.opencli.parser.OpenCliHelpSchema; +import java.io.InputStream; +import java.nio.charset.StandardCharsets; +import java.util.Scanner; +import org.junit.jupiter.api.Test; + +class OpenCliHelpParserTest { + + @Test + void decodesRealSnapshotsWithoutMergingScopes() { + String raw = sample("browser-tab.json"); + OpenCliHelpResult result = OpenCliHelpParser.parse(raw); + assertEquals(OpenCliHelpResult.Status.AVAILABLE, result.getStatus()); + assertEquals(raw, result.getRawHelp()); + OpenCliHelpSchema schema = result.getSchema(); + assertEquals("opencli browser tab", schema.getCommand()); + assertEquals("tab close", schema.getCommands().get(0).getName()); + assertEquals("tab", schema.getCommands().get(0).getCommandOptions().get(0).getName()); + assertEquals("window", schema.getNamespaceOptions().get(0).getName()); + assertTrue(schema.getGlobalOptions().stream().anyMatch(option -> "profile".equals(option.getName()))); + assertTrue(schema.getSourceJson().contains("\"structured_help\"")); + } + + @Test + void decodesRealCatalogAndRetainsAbsentMetadata() { + OpenCliHelpSchema root = OpenCliHelpParser.parse(sample("root.json")).getSchema(); + assertEquals("opencli", root.getName()); + assertNull(root.getCommands().get(0).getCommand()); + OpenCliHelpSchema npm = OpenCliHelpParser.parse(sample("site-npm-search.json")).getSchema(); + assertEquals("npm", npm.getSite()); + assertEquals("opencli npm search", npm.getCommand()); + assertEquals(Boolean.TRUE, npm.getPositionals().get(0).getRequired()); + assertEquals("false", npm.getCommonOptions().get(2).getDefaultJson()); + assertNull(npm.getCommonOptions().get(3).getDefaultJson()); + assertEquals("required", OpenCliHelpParser.parse(sample("browser-state.json")).getSchema() + .getNamespaceOptions().get(0).getTakesValue()); + assertEquals("npm", OpenCliHelpParser.parse(sample("site-npm.json")).getSchema().getSite()); + assertEquals("opencli auth", OpenCliHelpParser.parse(sample("meta-auth.json")).getSchema().getCommand()); + assertEquals("opencli browser get", + OpenCliHelpParser.parse(sample("browser-get.json")).getSchema().getCommand()); + } + + @Test + void preservesFutureFieldsOptionalValuesAndExplicitFalse() { + String raw = "{\"namespace\":\"browser\",\"name\":\"probe\",\"command\":\"opencli browser probe\"," + + "\"aliases\":[\"inspect\"],\"future\":{\"version\":2,\"large\":1e400}," + + "\"positionals\":[{\"name\":\"target\",\"variadic\":true}]," + + "\"command_options\":[{\"name\":\"sample\",\"takes_value\":\"optional\"," + + "\"required\":false,\"negate\":true,\"default\":false,\"choices\":[\"a\",\"b\"],\"extra\":42}]}"; + OpenCliHelpResult result = OpenCliHelpParser.parse(raw); + assertEquals(OpenCliHelpResult.Status.AVAILABLE, result.getStatus(), String.valueOf(result.getReason())); + OpenCliHelpSchema schema = result.getSchema(); + assertEquals("inspect", schema.getAliases().get(0)); + assertThrows(UnsupportedOperationException.class, () -> schema.getAliases().add("changed")); + assertEquals(Boolean.TRUE, schema.getPositionals().get(0).getVariadic()); + assertEquals("optional", schema.getCommandOptions().get(0).getTakesValue()); + assertEquals(Boolean.TRUE, schema.getCommandOptions().get(0).getNegate()); + assertFalse(schema.getCommandOptions().get(0).getRequired()); + assertEquals("false", schema.getCommandOptions().get(0).getDefaultJson()); + assertEquals("b", schema.getCommandOptions().get(0).getChoices().get(1)); + assertTrue(schema.getSourceJson().contains("\"future\"")); + assertTrue(schema.getSourceJson().contains("1E+400")); + assertTrue(schema.getCommandOptions().get(0).getSourceJson().contains("\"extra\":42")); + } + + @Test + void returnsUnknownForNonJsonOrInvalidHelpShapes() { + assertUnknown(sample("meta-list.txt"), OpenCliHelpResult.Reason.UNSUPPORTED_FORMAT); + assertUnknown(sample("browser.stdout"), OpenCliHelpResult.Reason.INVALID_JSON); + assertUnknown("{\"latest\":true}", OpenCliHelpResult.Reason.INVALID_SCHEMA); + assertUnknown("{\"site\":\"npm\",\"site\":\"other\",\"commands\":[]}", OpenCliHelpResult.Reason.INVALID_JSON); + assertUnknown("{\"namespace\":\"browser\",\"command\":\"opencli browser\",\"commands\":{}}", + OpenCliHelpResult.Reason.INVALID_SCHEMA); + assertUnknown("{\"site\":\"npm\",\"commands\":[{\"name\":17}]}", + OpenCliHelpResult.Reason.INVALID_SCHEMA); + assertUnknown(" ", OpenCliHelpResult.Reason.EMPTY); + } + + private static void assertUnknown(String raw, OpenCliHelpResult.Reason reason) { + OpenCliHelpResult result = OpenCliHelpParser.parse(raw); + assertEquals(OpenCliHelpResult.Status.UNKNOWN, result.getStatus()); + assertEquals(reason, result.getReason()); + assertEquals(raw, result.getRawHelp()); + assertNull(result.getSchema()); + } + + private static String sample(String name) { + InputStream stream = OpenCliHelpParserTest.class + .getResourceAsStream("/opencli-contracts/v1/structured-help-1.8.8/" + name); + try (Scanner scanner = new Scanner(stream, StandardCharsets.UTF_8.name())) { + return scanner.useDelimiter("\\A").next(); + } + } +} From 490a195018eac6e56a2940ba942b7279590451fd Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:11:04 +0800 Subject: [PATCH 042/105] Validate complete OpenCLI structured help output --- .../opencli/parser/OpenCliHelpParser.java | 18 ++++++++++++++---- .../contract/OpenCliHelpParserTest.java | 10 ++++++++++ 2 files changed, 24 insertions(+), 4 deletions(-) diff --git a/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpParser.java b/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpParser.java index 91f119c..f68e6d8 100644 --- a/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpParser.java +++ b/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpParser.java @@ -30,17 +30,27 @@ private OpenCliHelpParser() { * @return a structured schema or a reason it could not be recognized */ public static OpenCliHelpResult parse(String rawHelp) { - if (OpenCliStrings.isBlank(rawHelp)) { + if (Objects.isNull(rawHelp)) { return unknown(rawHelp, Reason.EMPTY); } - String input = rawHelp.trim(); - if (input.charAt(0) != '{') { + int start = 0; + while (start < rawHelp.length() && " \t\r\n".indexOf(rawHelp.charAt(start)) >= 0) { + start++; + } + if (start == rawHelp.length()) { + return unknown(rawHelp, Reason.EMPTY); + } + char first = rawHelp.charAt(start); + if (first < ' ') { + return unknown(rawHelp, Reason.INVALID_JSON); + } + if (first != '{') { return unknown(rawHelp, Reason.UNSUPPORTED_FORMAT); } JsonNode root; try { - root = READER.readTree(input); + root = READER.readTree(rawHelp); } catch (JsonProcessingException ex) { return unknown(rawHelp, Reason.INVALID_JSON); } diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliHelpParserTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliHelpParserTest.java index 7e55cdf..792b983 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/OpenCliHelpParserTest.java +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliHelpParserTest.java @@ -86,6 +86,16 @@ void returnsUnknownForNonJsonOrInvalidHelpShapes() { assertUnknown(" ", OpenCliHelpResult.Reason.EMPTY); } + @Test + void rejectsControlBytesOutsideAJsonHelpDocument() { + String control = String.valueOf((char) 0); + String valid = "{\"site\":\"npm\",\"commands\":[]}"; + assertUnknown(valid + control, OpenCliHelpResult.Reason.INVALID_JSON); + assertUnknown(control + valid, OpenCliHelpResult.Reason.INVALID_JSON); + assertUnknown(control, OpenCliHelpResult.Reason.INVALID_JSON); + assertEquals(OpenCliHelpResult.Status.AVAILABLE, OpenCliHelpParser.parse(" \t" + valid + "\r\n").getStatus()); + } + private static void assertUnknown(String raw, OpenCliHelpResult.Reason reason) { OpenCliHelpResult result = OpenCliHelpParser.parse(raw); assertEquals(OpenCliHelpResult.Status.UNKNOWN, result.getStatus()); From ad77458d80f16992319d5bde49230b62adfa0d6b Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:11:54 +0800 Subject: [PATCH 043/105] Probe trusted local OpenCLI root capabilities with bounded execution --- .../add-opencli-capability-discovery/tasks.md | 6 + .../github/easy4j/opencli/OpenCliClient.java | 10 ++ .../OpenCliCapabilityDiscovery.java | 167 ++++++++++++++++++ .../capability/OpenCliCapabilitySnapshot.java | 32 ++++ .../OpenCliCapabilityDiscoveryTest.java | 131 ++++++++++++++ 5 files changed, 346 insertions(+) create mode 100644 src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java create mode 100644 src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilitySnapshot.java create mode 100644 src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java diff --git a/openspec/changes/add-opencli-capability-discovery/tasks.md b/openspec/changes/add-opencli-capability-discovery/tasks.md index 975b8fa..e6704b3 100644 --- a/openspec/changes/add-opencli-capability-discovery/tasks.md +++ b/openspec/changes/add-opencli-capability-discovery/tasks.md @@ -31,3 +31,9 @@ `OpenCliHelpParser` 在 Java 8 API 范围内提供帮助解析结果。根目录、站点、命名空间和叶子按真实 1.8.8 结构识别。Schema 保留命令显示路径、会话占位符、命令层级、位置参数、别名和分作用域选项。缺失字段、显式 false、可选取值、否定和默认值分别保留。原文和各节点的来源 JSON 可以追溯未解释字段。纯文本、JSON 后缀、重复字段或无效结构返回 `UNKNOWN` 及对应原因。 基线的 API 验收先因缺少解析入口而无法编译。加入实现后,以 1.8.8 的七个 JSON 样本、两个原始负例和合成扩展验证,详见 `OpenCliHelpParserTest`。当前验证范围为原文解码,运行时探测、快照来源与失效、类型化会话绑定仍由其余任务验收。 + +## OC-CAP-004/005/006 本地根发现 + +`OpenCliClient.discoverCapabilities()` 接受调用者信任的绝对本地可执行文件配置,记录规范路径、观测版本、采集时刻、配置指纹及完整帮助文本的 SHA-256。探测固定为 `--version` 和 `--help -f json`,复用客户端执行器的本地并发容量、队列和进程清理。每次探测的队列与运行合计最多 10 秒,清理最多 1 秒,每路最多保留 1 MiB,调用者设置的更小预算优先。命令来源为 `UNKNOWN`,观察范围为 `ROOT_HELP`。采用按需重新观测,同版本改动可形成不同帮助摘要;缓存和 STALE 仍待实现。远端和 PATH 查找的发现请求返回 `UNSUPPORTED`,原有显式本地调用仍可使用。 + +`OpenCliCapabilityDiscoveryTest` 先因缺少公开发现 API 无法编译。真实 JVM 子进程验收固定参数、同版本变更、无来源推断、文本降级、输出超限、非零退出、超时及 local raw。Maven 定向测试同时验证原有帮助解析。范围仍为根级目录,细粒度帮助探测及类型化执行仍未验收。 diff --git a/src/main/java/io/github/easy4j/opencli/OpenCliClient.java b/src/main/java/io/github/easy4j/opencli/OpenCliClient.java index d919b86..28d8011 100644 --- a/src/main/java/io/github/easy4j/opencli/OpenCliClient.java +++ b/src/main/java/io/github/easy4j/opencli/OpenCliClient.java @@ -18,6 +18,8 @@ import io.github.easy4j.opencli.adapter.publicapi.pypi.PypiOpenCliClient; import io.github.easy4j.opencli.adapter.publicapi.wikipedia.WikipediaOpenCliClient; import io.github.easy4j.opencli.browser.OpenCliBrowserClient; +import io.github.easy4j.opencli.capability.OpenCliCapabilityDiscovery; +import io.github.easy4j.opencli.capability.OpenCliCapabilitySnapshot; import io.github.easy4j.opencli.core.OpenCliAdapterChannel; import io.github.easy4j.opencli.meta.OpenCliMetaClient; import io.github.easy4j.opencli.core.OpenCliExecutor; @@ -83,6 +85,14 @@ public OpenCliAdapterChannel adapter(String adapterId) { return new OpenCliAdapterChannel(executor, adapterId); } + /** + * Probes version and root structured help on the configured absolute local executable. + * @return a fresh observation with help, provenance and failure status + */ + public OpenCliCapabilitySnapshot discoverCapabilities() { + return OpenCliCapabilityDiscovery.discover(executor); + } + // ----- 参考强类型门面(Desktop) ----- /** @return Codex 桌面适配器客户端 */ diff --git a/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java new file mode 100644 index 0000000..3014705 --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java @@ -0,0 +1,167 @@ +package io.github.easy4j.opencli.capability; + +import io.github.easy4j.opencli.OpenCliExecutionTarget; +import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.capability.OpenCliCapabilitySnapshot.Status; +import io.github.easy4j.opencli.core.OpenCliExecutionDetails.TerminationReason; +import io.github.easy4j.opencli.core.OpenCliExecutor; +import io.github.easy4j.opencli.core.OpenCliResult; +import io.github.easy4j.opencli.exception.OpenCliException; +import io.github.easy4j.opencli.exception.OpenCliTimeoutException; +import io.github.easy4j.opencli.parser.OpenCliHelpParser; +import io.github.easy4j.opencli.parser.OpenCliHelpResult; +import io.github.easy4j.opencli.util.OpenCliStrings; +import java.io.IOException; +import java.nio.ByteBuffer; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.InvalidPathException; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; +import java.time.Instant; +import java.util.Arrays; +import java.util.Collections; +import java.util.Map; +import java.util.Objects; +import java.util.TreeMap; +import java.util.regex.Pattern; + +/** Fixed, bounded metadata probes through the existing local subprocess runtime. */ +public final class OpenCliCapabilityDiscovery { + private static final int MAX_PROBE_OUTPUT_BYTES = 1024 * 1024; + private static final long MAX_PROBE_MILLIS = 10_000; + private static final long MAX_CLEANUP_MILLIS = 1_000; + private static final Pattern VERSION = Pattern.compile( + "[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?"); + + private OpenCliCapabilityDiscovery() { + } + + /** + * Observes version and root help on a configured, trusted absolute executable. + * Installation, launcher arguments and environment are supplied by the trusted caller. + * + * @param executor client executor whose local process capacity is shared + * @return the root observation or an explicit reason it could not be made + */ + public static OpenCliCapabilitySnapshot discover(OpenCliExecutor executor) { + OpenCliProperties configured = executor.getProperties(); + OpenCliCapabilitySnapshot.OpenCliCapabilitySnapshotBuilder snapshot = + OpenCliCapabilitySnapshot.builder().observedAt(Instant.now()); + if (configured.getExecutionTarget() != OpenCliExecutionTarget.LOCAL_PROCESS) { + return snapshot.status(Status.UNSUPPORTED).reason("LOCAL_DISCOVERY_ONLY").build(); + } + if (OpenCliStrings.isBlank(configured.getExecutable())) { + return snapshot.status(Status.UNSUPPORTED).reason("ABSOLUTE_EXECUTABLE_REQUIRED").build(); + } + + OpenCliProperties probe = configured.copyForLocalCliExecution(); + Path executable; + try { + Path configuredPath = Paths.get(probe.getExecutable().trim()); + if (!configuredPath.isAbsolute()) { + return snapshot.status(Status.UNSUPPORTED).reason("ABSOLUTE_EXECUTABLE_REQUIRED").build(); + } + executable = configuredPath.toRealPath(); + if (!Files.isRegularFile(executable) || !Files.isExecutable(executable)) { + return snapshot.status(Status.UNKNOWN).reason("EXECUTABLE_UNAVAILABLE").build(); + } + } catch (IOException | InvalidPathException | SecurityException ex) { + return snapshot.status(Status.UNKNOWN).reason("EXECUTABLE_UNAVAILABLE").build(); + } + + probe.setExecutable(executable.toString()); + probe.setCommandTimeoutMillis(Math.min(MAX_PROBE_MILLIS, + Math.min(probe.getStartupProbeTimeoutMillis(), probe.getCommandTimeoutMillis()))); + probe.setCleanupGraceMillis(Math.min(MAX_CLEANUP_MILLIS, probe.getCleanupGraceMillis())); + probe.setMaxStdoutBytes(Math.min(MAX_PROBE_OUTPUT_BYTES, probe.getMaxStdoutBytes())); + probe.setMaxStderrBytes(Math.min(MAX_PROBE_OUTPUT_BYTES, probe.getMaxStderrBytes())); + snapshot.executable(probe.getExecutable()).configurationSha256(configurationDigest(probe)); + try (OpenCliExecutor local = new OpenCliExecutor(probe, executor.getProcessRuntime())) { + String phase = "VERSION"; + try { + OpenCliResult versionResult = local.invokeLocalOnly(Collections.singletonList("--version")); + String version = versionResult.getStdout().trim(); + if (versionResult.getExecutionDetails().isStdoutTruncated() || !VERSION.matcher(version).matches()) { + return snapshot.status(Status.UNKNOWN).reason("INVALID_VERSION_OUTPUT").build(); + } + snapshot.observedVersion(version); + phase = "HELP"; + OpenCliResult helpResult = local.invokeLocalOnly(Arrays.asList("--help", "-f", "json")); + if (helpResult.getExecutionDetails().isStdoutTruncated()) { + return snapshot.status(Status.UNKNOWN).reason("HELP_TRUNCATED").build(); + } + String stdout = helpResult.getStdout(); + OpenCliHelpResult help = OpenCliHelpParser.parse(stdout); + snapshot.help(help).helpSha256(hex(sha256().digest(stdout.getBytes(StandardCharsets.UTF_8)))); + if (help.getStatus() == OpenCliHelpResult.Status.AVAILABLE) { + return snapshot.status(Status.AVAILABLE).build(); + } + return snapshot.status(Status.UNKNOWN).reason(help.getReason().name()).build(); + } catch (OpenCliTimeoutException ex) { + return snapshot.status(Status.UNKNOWN).reason(phase + "_TIMEOUT").build(); + } catch (OpenCliException ex) { + OpenCliResult partial = ex.getPartialResult(); + if (Objects.nonNull(partial) && partial.getExecutionDetails().getTerminationReason() == TerminationReason.OUTPUT_LIMIT) { + return snapshot.status(Status.UNKNOWN).reason(phase + "_TRUNCATED").build(); + } + return snapshot.status(Status.UNKNOWN).reason(phase + "_PROBE_FAILED").build(); + } catch (IllegalArgumentException | IllegalStateException | UnsupportedOperationException ex) { + return snapshot.status(Status.UNKNOWN).reason(phase + "_PROBE_FAILED").build(); + } + } + } + + private static String configurationDigest(OpenCliProperties probe) { + MessageDigest digest = sha256(); + add(digest, probe.getExecutable()); + String directory = probe.getWorkingDirectory(); + add(digest, OpenCliStrings.isBlank(directory) ? System.getProperty("user.dir") : directory.trim()); + add(digest, Integer.toString(probe.getLeadingArguments().size())); + for (String argument : probe.getLeadingArguments()) { + add(digest, argument); + } + Map environment = new TreeMap<>(System.getenv()); + probe.getEnvironment().forEach((key, value) -> { + if (Objects.nonNull(key) && Objects.nonNull(value)) { + environment.put(key, value); + } + }); + environment.forEach((key, value) -> { + add(digest, key); + add(digest, value); + }); + return hex(digest.digest()); + } + + private static void add(MessageDigest digest, String value) { + if (Objects.isNull(value)) { + digest.update(ByteBuffer.allocate(Integer.BYTES).putInt(-1).array()); + return; + } + byte[] bytes = value.getBytes(StandardCharsets.UTF_8); + digest.update(ByteBuffer.allocate(Integer.BYTES).putInt(bytes.length).array()); + digest.update(bytes); + } + + private static MessageDigest sha256() { + try { + return MessageDigest.getInstance("SHA-256"); + } catch (NoSuchAlgorithmException ex) { + throw new IllegalStateException("The Java runtime must provide SHA-256", ex); + } + } + + private static String hex(byte[] digest) { + char[] digits = "0123456789abcdef".toCharArray(); + char[] result = new char[digest.length * 2]; + for (int index = 0; index < digest.length; index++) { + int value = digest[index] & 0xff; + result[index * 2] = digits[value >>> 4]; + result[index * 2 + 1] = digits[value & 0xf]; + } + return new String(result); + } +} diff --git a/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilitySnapshot.java b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilitySnapshot.java new file mode 100644 index 0000000..589d09b --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilitySnapshot.java @@ -0,0 +1,32 @@ +package io.github.easy4j.opencli.capability; + +import io.github.easy4j.opencli.parser.OpenCliHelpResult; +import java.time.Instant; +import lombok.Builder; +import lombok.Getter; + +/** Immutable observation of the configured local CLI's root help. */ +@Getter +@Builder +public final class OpenCliCapabilitySnapshot { + public enum Status { AVAILABLE, UNKNOWN, UNSUPPORTED } + + private final Status status; + private final String reason; + private final String executable; + private final String observedVersion; + private final Instant observedAt; + private final String configurationSha256; + private final String helpSha256; + private final OpenCliHelpResult help; + + /** @return scope of the metadata probe */ + public String getScope() { + return "ROOT_HELP"; + } + + /** @return unresolved origin, since help does not attribute overrides or plugins */ + public String getCommandOrigin() { + return "UNKNOWN"; + } +} diff --git a/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java b/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java new file mode 100644 index 0000000..f5cd9e4 --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java @@ -0,0 +1,131 @@ +package io.github.easy4j.opencli.capability; + +import io.github.easy4j.opencli.OpenCliClient; +import io.github.easy4j.opencli.OpenCliExecutionTarget; +import io.github.easy4j.opencli.OpenCliProperties; +import java.io.File; +import java.io.InputStream; +import java.util.Arrays; +import java.util.Scanner; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.*; + +class OpenCliCapabilityDiscoveryTest { + @Test + void rootProbePreservesUnknownSourceAndUsesOnlyDescriptiveCommands() { + OpenCliProperties properties = properties("structured"); + try (OpenCliClient client = new OpenCliClient(properties)) { + OpenCliCapabilitySnapshot result = client.discoverCapabilities(); + assertEquals(OpenCliCapabilitySnapshot.Status.AVAILABLE, result.getStatus()); + assertEquals("1.8.8", result.getObservedVersion()); + assertEquals("UNKNOWN", result.getCommandOrigin()); + assertEquals("ROOT_HELP", result.getScope()); + assertNotNull(result.getObservedAt()); + assertTrue(new File(result.getExecutable()).isAbsolute()); + assertEquals(64, result.getConfigurationSha256().length()); + assertEquals(64, result.getHelpSha256().length()); + assertTrue(result.getHelp().getRawHelp().contains("do not run this example")); + String structuredHash = result.getHelpSha256(); + properties.getEnvironment().put("OPENCLI_TEST_HELP_MODE", "revised"); + OpenCliCapabilitySnapshot revised = client.discoverCapabilities(); + assertEquals("1.8.8", revised.getObservedVersion()); + assertNotEquals(structuredHash, revised.getHelpSha256()); + assertNotEquals(result.getConfigurationSha256(), revised.getConfigurationSha256()); + } + } + + @Test + void plainHelpLeavesLocalInvocationAvailable() { + try (OpenCliClient client = new OpenCliClient(properties("plain"))) { + OpenCliCapabilitySnapshot result = client.discoverCapabilities(); + assertEquals(OpenCliCapabilitySnapshot.Status.UNKNOWN, result.getStatus()); + assertEquals("UNSUPPORTED_FORMAT", result.getReason()); + assertEquals("Usage: opencli\n", result.getHelp().getRawHelp()); + assertEquals("raw available", client.getExecutor().invoke("npm", "search").getStdout()); + } + } + + @Test + void pathLookupAndRemoteModeAreUnsupported() { + try (OpenCliClient client = new OpenCliClient()) { + assertEquals("ABSOLUTE_EXECUTABLE_REQUIRED", client.discoverCapabilities().getReason()); + } + OpenCliProperties props = properties("structured"); + props.setExecutionTarget(OpenCliExecutionTarget.REMOTE_AGENT_HTTP); + try (OpenCliClient client = new OpenCliClient(props)) { + assertEquals("LOCAL_DISCOVERY_ONLY", client.discoverCapabilities().getReason()); + } + } + + @Test + void truncatedHelpAndNonzeroOutputAreDiscoveryFailures() { + OpenCliProperties limited = properties("structured"); + limited.setMaxStdoutBytes(16); + try (OpenCliClient client = new OpenCliClient(limited)) { + OpenCliCapabilitySnapshot result = client.discoverCapabilities(); + assertEquals(OpenCliCapabilitySnapshot.Status.UNKNOWN, result.getStatus()); + assertEquals("HELP_TRUNCATED", result.getReason()); + } + try (OpenCliClient client = new OpenCliClient(properties("error"))) { + assertEquals("HELP_PROBE_FAILED", client.discoverCapabilities().getReason()); + } + } + + @Test + void slowHelpReturnsTimeoutWithinTheConfiguredProbeBudget() { + OpenCliProperties limited = properties("slow"); + limited.setStartupProbeTimeoutMillis(2_000); + try (OpenCliClient client = new OpenCliClient(limited)) { + OpenCliCapabilitySnapshot result = client.discoverCapabilities(); + assertEquals(OpenCliCapabilitySnapshot.Status.UNKNOWN, result.getStatus()); + assertEquals("HELP_TIMEOUT", result.getReason()); + assertEquals("1.8.8", result.getObservedVersion()); + } + } + + private static OpenCliProperties properties(String mode) { + OpenCliProperties props = new OpenCliProperties(); + String binary = System.getProperty("os.name").startsWith("Windows") ? "java.exe" : "java"; + props.setExecutable(new File(new File(System.getProperty("java.home"), "bin"), binary).getAbsolutePath()); + props.setLeadingArguments(Arrays.asList("-cp", + System.getProperty("surefire.test.class.path", System.getProperty("java.class.path")), + DiscoveryFixture.class.getName())); + props.getEnvironment().put("OPENCLI_TEST_HELP_MODE", mode); + return props; + } + + public static class DiscoveryFixture { + public static void main(String[] args) throws Exception { + if (Arrays.equals(args, new String[]{"--version"})) { + System.out.println("1.8.8"); + return; + } + if (Arrays.equals(args, new String[]{"npm", "search"})) { + System.out.print("raw available"); + return; + } + if (!Arrays.equals(args, new String[]{"--help", "-f", "json"})) { + System.exit(2); + } + String mode = System.getenv("OPENCLI_TEST_HELP_MODE"); + if ("error".equals(mode)) { + System.exit(3); + } + if ("slow".equals(mode)) { + Thread.sleep(30_000); + } + if ("plain".equals(mode)) { + System.out.print("Usage: opencli\n"); + return; + } + try (InputStream input = DiscoveryFixture.class.getResourceAsStream( + "/opencli-contracts/v1/structured-help-1.8.8/root.json"); + Scanner scan = new Scanner(input, "UTF-8").useDelimiter("\\A")) { + String root = scan.next().trim(); + System.out.print(root.substring(0, root.length() - 1) + + ",\"description_fixture\":\"do not run this example " + mode + "\"}"); + } + } + } +} From e28be302fc3c53c7b362c12a7df370b7c0a1f1ef Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:17:36 +0800 Subject: [PATCH 044/105] Reject malformed structured help catalogs --- .../opencli/parser/OpenCliHelpParser.java | 21 ++++++++++++++++--- .../OpenCliCapabilityDiscoveryTest.java | 15 +++++++++++++ .../contract/OpenCliHelpParserTest.java | 21 +++++++++++++++++++ 3 files changed, 54 insertions(+), 3 deletions(-) diff --git a/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpParser.java b/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpParser.java index f68e6d8..fd3b9ff 100644 --- a/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpParser.java +++ b/src/main/java/io/github/easy4j/opencli/parser/OpenCliHelpParser.java @@ -73,7 +73,14 @@ private static boolean isHelpRoot(JsonNode root) { return false; } boolean directory = root.path("commands").isArray(); - if (directory && "opencli".equals(text(root.path("name"))) && root.path("site_adapters").isObject()) { + if (directory && "opencli".equals(text(root.path("name"))) && root.has("site_adapters")) { + JsonNode sites = root.path("site_adapters").path("sites"); + if (!sites.isArray()) { + return false; + } + for (JsonNode site : sites) { + requiredName(site); + } return true; } if (directory && OpenCliStrings.isNotBlank(text(root.path("site")))) { @@ -99,7 +106,7 @@ private static OpenCliHelpSchema schema(JsonNode node) { .command(command) .namespace(text(node.path("namespace"))) .site(site) - .aliases(array(node.path("aliases"), OpenCliHelpParser::requiredText)) + .aliases(array(node.path("aliases"), OpenCliHelpParser::requiredName)) .commands(array(node.path("commands"), OpenCliHelpParser::schema)) .positionals(array(node.path("positionals"), OpenCliHelpParser::argument)) .commandOptions(array(node.path("command_options"), OpenCliHelpParser::argument)) @@ -116,7 +123,7 @@ private static OpenCliHelpSchema.Argument argument(JsonNode node) { } JsonNode defaultValue = node.path("default"); return OpenCliHelpSchema.Argument.builder() - .name(requiredText(node.path("name"))) + .name(requiredName(node.path("name"))) .flags(text(node.path("flags"))) .type(text(node.path("type"))) .takesValue(text(node.path("takes_value"))) @@ -161,6 +168,14 @@ private static String requiredText(JsonNode node) { return value; } + private static String requiredName(JsonNode node) { + String value = text(node); + if (OpenCliStrings.isBlank(value)) { + throw invalidSchema(); + } + return value; + } + private static Boolean bool(JsonNode node) { if (node.isMissingNode()) { return null; diff --git a/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java b/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java index f5cd9e4..277a982 100644 --- a/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java +++ b/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java @@ -46,6 +46,17 @@ void plainHelpLeavesLocalInvocationAvailable() { } } + @Test + void malformedRootRegistryLeavesLocalInvocationAvailable() { + try (OpenCliClient client = new OpenCliClient(properties("malformed-root"))) { + OpenCliCapabilitySnapshot result = client.discoverCapabilities(); + assertEquals(OpenCliCapabilitySnapshot.Status.UNKNOWN, result.getStatus()); + assertEquals("INVALID_SCHEMA", result.getReason()); + assertEquals("1.8.8", result.getObservedVersion()); + assertEquals("raw available", client.getExecutor().invoke("npm", "search").getStdout()); + } + } + @Test void pathLookupAndRemoteModeAreUnsupported() { try (OpenCliClient client = new OpenCliClient()) { @@ -119,6 +130,10 @@ public static void main(String[] args) throws Exception { System.out.print("Usage: opencli\n"); return; } + if ("malformed-root".equals(mode)) { + System.out.print("{\"name\":\"opencli\",\"commands\":[],\"site_adapters\":{}}"); + return; + } try (InputStream input = DiscoveryFixture.class.getResourceAsStream( "/opencli-contracts/v1/structured-help-1.8.8/root.json"); Scanner scan = new Scanner(input, "UTF-8").useDelimiter("\\A")) { diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliHelpParserTest.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliHelpParserTest.java index 792b983..1d75879 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/OpenCliHelpParserTest.java +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliHelpParserTest.java @@ -96,6 +96,27 @@ void rejectsControlBytesOutsideAJsonHelpDocument() { assertEquals(OpenCliHelpResult.Status.AVAILABLE, OpenCliHelpParser.parse(" \t" + valid + "\r\n").getStatus()); } + @Test + void distinguishesAnExplicitlyEmptyRootCatalogFromAMalformedRegistry() { + String root = "{\"name\":\"opencli\",\"commands\":[],\"site_adapters\":"; + assertUnknown(root + "{}}", OpenCliHelpResult.Reason.INVALID_SCHEMA); + assertUnknown(root + "{\"sites\":{}}}", OpenCliHelpResult.Reason.INVALID_SCHEMA); + assertUnknown(root + "{\"sites\":[\u0020null]}}", OpenCliHelpResult.Reason.INVALID_SCHEMA); + assertEquals(OpenCliHelpResult.Status.AVAILABLE, + OpenCliHelpParser.parse(root + "{\"count\":0,\"sites\":[]}}").getStatus()); + } + + @Test + void requiresArgumentAndAliasNamesWhilePreservingAnEmptyChoice() { + String command = "{\"site\":\"npm\",\"name\":\"search\",\"command\":\"opencli npm search\","; + assertUnknown(command + "\"positionals\":[{\"name\":\" \"}]}", OpenCliHelpResult.Reason.INVALID_SCHEMA); + assertUnknown(command + "\"positionals\":[],\"aliases\":[\"\"]}", OpenCliHelpResult.Reason.INVALID_SCHEMA); + OpenCliHelpResult result = OpenCliHelpParser.parse(command + + "\"command_options\":[{\"name\":\"query\",\"choices\":[\"\",\"all\"]}]}"); + assertEquals(OpenCliHelpResult.Status.AVAILABLE, result.getStatus()); + assertEquals("", result.getSchema().getCommandOptions().get(0).getChoices().get(0)); + } + private static void assertUnknown(String raw, OpenCliHelpResult.Reason reason) { OpenCliHelpResult result = OpenCliHelpParser.parse(raw); assertEquals(OpenCliHelpResult.Status.UNKNOWN, result.getStatus()); From 57ddf453068991c88b5078a868bf51c6adc6b9a6 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:17:27 +0800 Subject: [PATCH 045/105] Retain matching OpenCLI help snapshots on failed refresh --- .../add-opencli-capability-discovery/tasks.md | 6 + .../github/easy4j/opencli/OpenCliClient.java | 10 +- .../OpenCliCapabilityDiscovery.java | 46 ++++++- .../capability/OpenCliCapabilitySnapshot.java | 6 +- .../OpenCliCapabilityDiscoveryTest.java | 128 +++++++++++++++++- 5 files changed, 186 insertions(+), 10 deletions(-) diff --git a/openspec/changes/add-opencli-capability-discovery/tasks.md b/openspec/changes/add-opencli-capability-discovery/tasks.md index e6704b3..2987709 100644 --- a/openspec/changes/add-opencli-capability-discovery/tasks.md +++ b/openspec/changes/add-opencli-capability-discovery/tasks.md @@ -37,3 +37,9 @@ `OpenCliClient.discoverCapabilities()` 接受调用者信任的绝对本地可执行文件配置,记录规范路径、观测版本、采集时刻、配置指纹及完整帮助文本的 SHA-256。探测固定为 `--version` 和 `--help -f json`,复用客户端执行器的本地并发容量、队列和进程清理。每次探测的队列与运行合计最多 10 秒,清理最多 1 秒,每路最多保留 1 MiB,调用者设置的更小预算优先。命令来源为 `UNKNOWN`,观察范围为 `ROOT_HELP`。采用按需重新观测,同版本改动可形成不同帮助摘要;缓存和 STALE 仍待实现。远端和 PATH 查找的发现请求返回 `UNSUPPORTED`,原有显式本地调用仍可使用。 `OpenCliCapabilityDiscoveryTest` 先因缺少公开发现 API 无法编译。真实 JVM 子进程验收固定参数、同版本变更、无来源推断、文本降级、输出超限、非零退出、超时及 local raw。Maven 定向测试同时验证原有帮助解析。范围仍为根级目录,细粒度帮助探测及类型化执行仍未验收。 + +## OC-CAP-004/005 根帮助快照失效 + +客户端保存一个最近成功的根帮助快照,每次显式发现均重新探测。刷新失败且配置指纹一致、未观测到不同版本时,返回 `STALE`,保留成功时的采集时间、schema 和帮助摘要。失败的刷新另存于 `failedRefresh`,包括失败原因、尝试时间和可取得的原始帮助。配置或已观测版本改变会清除旧快照;成功刷新以新内容更新摘要。同一客户端并发探测时,较早发起但较晚完成的探测不会覆盖已发布的新结果。 + +`OpenCliCapabilityDiscoveryTest` 的定向红灯为预期 `STALE`、实际 `UNKNOWN`。实现后验证同配置降级、失败原文、同版本帮助变化、配置与版本失效、并发完成顺序。当前缓存范围为根帮助。 diff --git a/src/main/java/io/github/easy4j/opencli/OpenCliClient.java b/src/main/java/io/github/easy4j/opencli/OpenCliClient.java index 28d8011..949b78d 100644 --- a/src/main/java/io/github/easy4j/opencli/OpenCliClient.java +++ b/src/main/java/io/github/easy4j/opencli/OpenCliClient.java @@ -49,6 +49,8 @@ @Getter private final OpenCliExecutor executor; + private final OpenCliCapabilityDiscovery capabilityDiscovery; + /** * Constructs with default configuration (executable assumed to be {@code opencli} on PATH). */ @@ -60,8 +62,7 @@ public OpenCliClient() { * @param properties 运行配置,不得为 null */ public OpenCliClient(OpenCliProperties properties) { - this.properties = Objects.requireNonNull(properties, "properties"); - this.executor = new OpenCliExecutor(properties); + this(properties, new OpenCliExecutor(properties)); } /** @@ -73,6 +74,7 @@ public OpenCliClient(OpenCliProperties properties) { public OpenCliClient(OpenCliProperties properties, OpenCliExecutor executor) { this.properties = Objects.requireNonNull(properties, "properties"); this.executor = Objects.requireNonNull(executor, "executor"); + this.capabilityDiscovery = new OpenCliCapabilityDiscovery(executor); } /** @@ -87,10 +89,10 @@ public OpenCliAdapterChannel adapter(String adapterId) { /** * Probes version and root structured help on the configured absolute local executable. - * @return a fresh observation with help, provenance and failure status + * @return a current observation or a stale matching snapshot with the refresh failure */ public OpenCliCapabilitySnapshot discoverCapabilities() { - return OpenCliCapabilityDiscovery.discover(executor); + return capabilityDiscovery.refresh(); } // ----- 参考强类型门面(Desktop) ----- diff --git a/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java index 3014705..07ebe94 100644 --- a/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java +++ b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java @@ -36,7 +36,14 @@ public final class OpenCliCapabilityDiscovery { private static final Pattern VERSION = Pattern.compile( "[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?"); - private OpenCliCapabilityDiscovery() { + private final OpenCliExecutor executor; + private long nextAttempt; + private long lastPublishedAttempt; + private OpenCliCapabilitySnapshot lastAvailable; + + /** @param executor client executor whose local process capacity is shared */ + public OpenCliCapabilityDiscovery(OpenCliExecutor executor) { + this.executor = Objects.requireNonNull(executor, "executor"); } /** @@ -47,6 +54,43 @@ private OpenCliCapabilityDiscovery() { * @return the root observation or an explicit reason it could not be made */ public static OpenCliCapabilitySnapshot discover(OpenCliExecutor executor) { + return new OpenCliCapabilityDiscovery(executor).refresh(); + } + + /** + * Runs a fresh probe and can attach the previous matching observation if it fails. + * @return current observation, or a clearly marked stale snapshot or failure + */ + public OpenCliCapabilitySnapshot refresh() { + long attempt; + synchronized (this) { + attempt = ++nextAttempt; + } + return publish(attempt, observe()); + } + + private synchronized OpenCliCapabilitySnapshot publish(long attempt, OpenCliCapabilitySnapshot current) { + if (attempt < lastPublishedAttempt) { + return current; + } + lastPublishedAttempt = attempt; + if (current.getStatus() == Status.AVAILABLE) { + lastAvailable = current; + return current; + } + if (current.getStatus() == Status.UNKNOWN + && Objects.nonNull(lastAvailable) + && lastAvailable.getConfigurationSha256().equals(current.getConfigurationSha256()) + && (Objects.isNull(current.getObservedVersion()) + || lastAvailable.getObservedVersion().equals(current.getObservedVersion()))) { + return lastAvailable.toBuilder().status(Status.STALE).reason(current.getReason()) + .failedRefresh(current).build(); + } + lastAvailable = null; + return current; + } + + private OpenCliCapabilitySnapshot observe() { OpenCliProperties configured = executor.getProperties(); OpenCliCapabilitySnapshot.OpenCliCapabilitySnapshotBuilder snapshot = OpenCliCapabilitySnapshot.builder().observedAt(Instant.now()); diff --git a/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilitySnapshot.java b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilitySnapshot.java index 589d09b..498399c 100644 --- a/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilitySnapshot.java +++ b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilitySnapshot.java @@ -7,9 +7,9 @@ /** Immutable observation of the configured local CLI's root help. */ @Getter -@Builder +@Builder(toBuilder = true) public final class OpenCliCapabilitySnapshot { - public enum Status { AVAILABLE, UNKNOWN, UNSUPPORTED } + public enum Status { AVAILABLE, STALE, UNKNOWN, UNSUPPORTED } private final Status status; private final String reason; @@ -19,6 +19,8 @@ public enum Status { AVAILABLE, UNKNOWN, UNSUPPORTED } private final String configurationSha256; private final String helpSha256; private final OpenCliHelpResult help; + /** Latest failed observation when this result serves an earlier snapshot. */ + private final OpenCliCapabilitySnapshot failedRefresh; /** @return scope of the metadata probe */ public String getScope() { diff --git a/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java b/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java index 277a982..f2cc5b8 100644 --- a/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java +++ b/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java @@ -5,9 +5,19 @@ import io.github.easy4j.opencli.OpenCliProperties; import java.io.File; import java.io.InputStream; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; import java.util.Arrays; +import java.util.Objects; import java.util.Scanner; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.Future; +import java.util.concurrent.TimeUnit; import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; import static org.junit.jupiter.api.Assertions.*; @@ -95,6 +105,107 @@ void slowHelpReturnsTimeoutWithinTheConfiguredProbeBudget() { } } + @Test + void staleFallbackRetainsObservationAndRefreshEvidence(@TempDir Path directory) throws Exception { + Path control = directory.resolve("mode"); + writeMode(control, "first"); + OpenCliProperties props = controlledProperties(control); + try (OpenCliClient client = new OpenCliClient(props)) { + OpenCliCapabilitySnapshot first = client.discoverCapabilities(); + assertEquals(OpenCliCapabilitySnapshot.Status.AVAILABLE, first.getStatus()); + + writeMode(control, "plain"); + OpenCliCapabilitySnapshot stale = client.discoverCapabilities(); + assertEquals("STALE", stale.getStatus().name()); + assertEquals("UNSUPPORTED_FORMAT", stale.getReason()); + assertEquals(first.getObservedAt(), stale.getObservedAt()); + assertEquals(first.getHelpSha256(), stale.getHelpSha256()); + assertEquals(first.getHelp().getRawHelp(), stale.getHelp().getRawHelp()); + assertEquals("Usage: opencli\n", stale.getFailedRefresh().getHelp().getRawHelp()); + assertEquals(OpenCliCapabilitySnapshot.Status.UNKNOWN, stale.getFailedRefresh().getStatus()); + assertFalse(stale.getFailedRefresh().getObservedAt().isBefore(first.getObservedAt())); + + writeMode(control, "second"); + OpenCliCapabilitySnapshot current = client.discoverCapabilities(); + assertEquals(OpenCliCapabilitySnapshot.Status.AVAILABLE, current.getStatus()); + assertEquals(first.getConfigurationSha256(), current.getConfigurationSha256()); + assertNotEquals(first.getHelpSha256(), current.getHelpSha256()); + + writeMode(control, "error"); + OpenCliCapabilitySnapshot staleAfterChange = client.discoverCapabilities(); + assertEquals("STALE", staleAfterChange.getStatus().name()); + assertEquals(current.getHelpSha256(), staleAfterChange.getHelpSha256()); + } + } + + @Test + void configAndVersionChangesInvalidateCachedHelp(@TempDir Path directory) throws Exception { + Path control = directory.resolve("mode"); + writeMode(control, "baseline"); + OpenCliProperties props = controlledProperties(control); + try (OpenCliClient client = new OpenCliClient(props)) { + assertEquals(OpenCliCapabilitySnapshot.Status.AVAILABLE, client.discoverCapabilities().getStatus()); + writeMode(control, "new-version-error"); + OpenCliCapabilitySnapshot upgraded = client.discoverCapabilities(); + assertEquals(OpenCliCapabilitySnapshot.Status.UNKNOWN, upgraded.getStatus()); + assertEquals("1.8.9", upgraded.getObservedVersion()); + assertNull(upgraded.getHelp()); + + writeMode(control, "error"); + assertEquals(OpenCliCapabilitySnapshot.Status.UNKNOWN, client.discoverCapabilities().getStatus()); + writeMode(control, "baseline"); + assertEquals(OpenCliCapabilitySnapshot.Status.AVAILABLE, client.discoverCapabilities().getStatus()); + writeMode(control, "error"); + props.getEnvironment().put("OPENCLI_TEST_CHANGED_CONFIG", "true"); + assertEquals(OpenCliCapabilitySnapshot.Status.UNKNOWN, client.discoverCapabilities().getStatus()); + props.getEnvironment().remove("OPENCLI_TEST_CHANGED_CONFIG"); + assertEquals(OpenCliCapabilitySnapshot.Status.UNKNOWN, client.discoverCapabilities().getStatus()); + } + } + + @Test + void lateRefreshCannotOverwriteNewerSnapshot(@TempDir Path directory) throws Exception { + Path control = directory.resolve("mode"); + Path entered = directory.resolve("entered"); + Path release = directory.resolve("release"); + writeMode(control, "hold-old"); + OpenCliProperties props = controlledProperties(control); + props.setMaxConcurrentExecutions(2); + ExecutorService callers = Executors.newSingleThreadExecutor(); + try (OpenCliClient client = new OpenCliClient(props)) { + Future older = callers.submit(client::discoverCapabilities); + long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(5); + while (!Files.exists(entered) && System.nanoTime() < deadline) { + Thread.sleep(10); + } + assertTrue(Files.exists(entered), "older probe must be held after it reads the old help mode"); + writeMode(control, "newer"); + OpenCliCapabilitySnapshot newest = client.discoverCapabilities(); + assertEquals(OpenCliCapabilitySnapshot.Status.AVAILABLE, newest.getStatus()); + + Files.createFile(release); + OpenCliCapabilitySnapshot olderObservation = older.get(5, TimeUnit.SECONDS); + assertEquals(OpenCliCapabilitySnapshot.Status.AVAILABLE, olderObservation.getStatus()); + assertNotEquals(newest.getHelpSha256(), olderObservation.getHelpSha256()); + writeMode(control, "error"); + OpenCliCapabilitySnapshot stale = client.discoverCapabilities(); + assertEquals(OpenCliCapabilitySnapshot.Status.STALE, stale.getStatus()); + assertEquals(newest.getHelpSha256(), stale.getHelpSha256()); + } finally { + callers.shutdownNow(); + } + } + + private static OpenCliProperties controlledProperties(Path control) { + OpenCliProperties props = properties("unused"); + props.getEnvironment().put("OPENCLI_TEST_HELP_CONTROL", control.toString()); + return props; + } + + private static void writeMode(Path control, String mode) throws Exception { + Files.write(control, mode.getBytes(StandardCharsets.UTF_8)); + } + private static OpenCliProperties properties(String mode) { OpenCliProperties props = new OpenCliProperties(); String binary = System.getProperty("os.name").startsWith("Windows") ? "java.exe" : "java"; @@ -108,8 +219,13 @@ private static OpenCliProperties properties(String mode) { public static class DiscoveryFixture { public static void main(String[] args) throws Exception { + String mode = System.getenv("OPENCLI_TEST_HELP_MODE"); + String control = System.getenv("OPENCLI_TEST_HELP_CONTROL"); + if (Objects.nonNull(control)) { + mode = new String(Files.readAllBytes(Paths.get(control)), StandardCharsets.UTF_8); + } if (Arrays.equals(args, new String[]{"--version"})) { - System.out.println("1.8.8"); + System.out.println("new-version-error".equals(mode) ? "1.8.9" : "1.8.8"); return; } if (Arrays.equals(args, new String[]{"npm", "search"})) { @@ -119,8 +235,14 @@ public static void main(String[] args) throws Exception { if (!Arrays.equals(args, new String[]{"--help", "-f", "json"})) { System.exit(2); } - String mode = System.getenv("OPENCLI_TEST_HELP_MODE"); - if ("error".equals(mode)) { + if ("hold-old".equals(mode)) { + Path path = Paths.get(control).getParent(); + Files.createFile(path.resolve("entered")); + while (!Files.exists(path.resolve("release"))) { + Thread.sleep(10); + } + } + if ("error".equals(mode) || "new-version-error".equals(mode)) { System.exit(3); } if ("slow".equals(mode)) { From 8d1ccb6bd416ad16eea7d67fa0331a95c5f0c141 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:23:01 +0800 Subject: [PATCH 046/105] Discover pinned OpenCLI help scopes without executing commands --- .../add-opencli-capability-discovery/tasks.md | 6 ++ .../github/easy4j/opencli/OpenCliClient.java | 10 +++ .../OpenCliCapabilityDiscovery.java | 47 +++++++---- .../capability/OpenCliCapabilitySnapshot.java | 6 +- .../opencli/capability/OpenCliHelpScope.java | 48 +++++++++++ .../OpenCliCapabilityDiscoveryTest.java | 81 +++++++++++++++++-- 6 files changed, 176 insertions(+), 22 deletions(-) create mode 100644 src/main/java/io/github/easy4j/opencli/capability/OpenCliHelpScope.java diff --git a/openspec/changes/add-opencli-capability-discovery/tasks.md b/openspec/changes/add-opencli-capability-discovery/tasks.md index 2987709..25ce793 100644 --- a/openspec/changes/add-opencli-capability-discovery/tasks.md +++ b/openspec/changes/add-opencli-capability-discovery/tasks.md @@ -43,3 +43,9 @@ 客户端保存一个最近成功的根帮助快照,每次显式发现均重新探测。刷新失败且配置指纹一致、未观测到不同版本时,返回 `STALE`,保留成功时的采集时间、schema 和帮助摘要。失败的刷新另存于 `failedRefresh`,包括失败原因、尝试时间和可取得的原始帮助。配置或已观测版本改变会清除旧快照;成功刷新以新内容更新摘要。同一客户端并发探测时,较早发起但较晚完成的探测不会覆盖已发布的新结果。 `OpenCliCapabilityDiscoveryTest` 的定向红灯为预期 `STALE`、实际 `UNKNOWN`。实现后验证同配置降级、失败原文、同版本帮助变化、配置与版本失效、并发完成顺序。当前缓存范围为根帮助。 + +## OC-CAP-001/003/004/005/006 固定范围帮助探测 + +`discoverCapabilities(OpenCliHelpScope)` 提供根目录、浏览器、浏览器 tab/get/state、auth、list 及 npm 站点和 search 的九个固定查询。细粒度参数只在已验证的 OpenCLI 1.8.8 启用。浏览器查询使用固定的帮助会话占位,不接受调用者提供的命令路径,也不执行帮助描述中的内容。结构化结果需匹配请求范围;纯文本和混合输出维持原有失败原因。 + +每个范围只保存其最近成功的观察,且配置或已观测版本变化使其他不匹配的范围一并失效。OpenCLI 能力仍按请求观察,并保留来源未知标记。增加 `OpenCliCapabilityDiscoveryTest` 的进程验收后,缺少范围 API 时失败,加入实现后定向测试通过。类型化会话绑定及执行前参数校验仍待验收。 diff --git a/src/main/java/io/github/easy4j/opencli/OpenCliClient.java b/src/main/java/io/github/easy4j/opencli/OpenCliClient.java index 949b78d..798f514 100644 --- a/src/main/java/io/github/easy4j/opencli/OpenCliClient.java +++ b/src/main/java/io/github/easy4j/opencli/OpenCliClient.java @@ -20,6 +20,7 @@ import io.github.easy4j.opencli.browser.OpenCliBrowserClient; import io.github.easy4j.opencli.capability.OpenCliCapabilityDiscovery; import io.github.easy4j.opencli.capability.OpenCliCapabilitySnapshot; +import io.github.easy4j.opencli.capability.OpenCliHelpScope; import io.github.easy4j.opencli.core.OpenCliAdapterChannel; import io.github.easy4j.opencli.meta.OpenCliMetaClient; import io.github.easy4j.opencli.core.OpenCliExecutor; @@ -95,6 +96,15 @@ public OpenCliCapabilitySnapshot discoverCapabilities() { return capabilityDiscovery.refresh(); } + /** + * Probes a fixed help query from the verified OpenCLI protocol fixture set. + * @param scope versioned local help query + * @return scoped observation or explicit failure status + */ + public OpenCliCapabilitySnapshot discoverCapabilities(OpenCliHelpScope scope) { + return capabilityDiscovery.refresh(scope); + } + // ----- 参考强类型门面(Desktop) ----- /** @return Codex 桌面适配器客户端 */ diff --git a/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java index 07ebe94..391e57e 100644 --- a/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java +++ b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java @@ -21,8 +21,8 @@ import java.security.MessageDigest; import java.security.NoSuchAlgorithmException; import java.time.Instant; -import java.util.Arrays; import java.util.Collections; +import java.util.EnumMap; import java.util.Map; import java.util.Objects; import java.util.TreeMap; @@ -39,7 +39,8 @@ public final class OpenCliCapabilityDiscovery { private final OpenCliExecutor executor; private long nextAttempt; private long lastPublishedAttempt; - private OpenCliCapabilitySnapshot lastAvailable; + private final Map lastAvailable = + new EnumMap<>(OpenCliHelpScope.class); /** @param executor client executor whose local process capacity is shared */ public OpenCliCapabilityDiscovery(OpenCliExecutor executor) { @@ -62,11 +63,21 @@ public static OpenCliCapabilitySnapshot discover(OpenCliExecutor executor) { * @return current observation, or a clearly marked stale snapshot or failure */ public OpenCliCapabilitySnapshot refresh() { + return refresh(OpenCliHelpScope.ROOT_HELP); + } + + /** + * Queries a fixed help scope on the pinned protocol version and tracks its snapshot. + * @param scope help query from the locked protocol fixture set + * @return current scoped observation or the explicit stale or failure status + */ + public OpenCliCapabilitySnapshot refresh(OpenCliHelpScope scope) { + Objects.requireNonNull(scope, "scope"); long attempt; synchronized (this) { attempt = ++nextAttempt; } - return publish(attempt, observe()); + return publish(attempt, observe(scope)); } private synchronized OpenCliCapabilitySnapshot publish(long attempt, OpenCliCapabilitySnapshot current) { @@ -74,26 +85,28 @@ private synchronized OpenCliCapabilitySnapshot publish(long attempt, OpenCliCapa return current; } lastPublishedAttempt = attempt; + lastAvailable.values().removeIf(old -> + !old.getConfigurationSha256().equals(current.getConfigurationSha256()) + || (Objects.nonNull(current.getObservedVersion()) + && !old.getObservedVersion().equals(current.getObservedVersion()))); + OpenCliHelpScope scope = current.getHelpScope(); if (current.getStatus() == Status.AVAILABLE) { - lastAvailable = current; + lastAvailable.put(scope, current); return current; } - if (current.getStatus() == Status.UNKNOWN - && Objects.nonNull(lastAvailable) - && lastAvailable.getConfigurationSha256().equals(current.getConfigurationSha256()) - && (Objects.isNull(current.getObservedVersion()) - || lastAvailable.getObservedVersion().equals(current.getObservedVersion()))) { - return lastAvailable.toBuilder().status(Status.STALE).reason(current.getReason()) + OpenCliCapabilitySnapshot previous = lastAvailable.get(scope); + if (current.getStatus() == Status.UNKNOWN && Objects.nonNull(previous)) { + return previous.toBuilder().status(Status.STALE).reason(current.getReason()) .failedRefresh(current).build(); } - lastAvailable = null; + lastAvailable.remove(scope); return current; } - private OpenCliCapabilitySnapshot observe() { + private OpenCliCapabilitySnapshot observe(OpenCliHelpScope scope) { OpenCliProperties configured = executor.getProperties(); OpenCliCapabilitySnapshot.OpenCliCapabilitySnapshotBuilder snapshot = - OpenCliCapabilitySnapshot.builder().observedAt(Instant.now()); + OpenCliCapabilitySnapshot.builder().helpScope(scope).observedAt(Instant.now()); if (configured.getExecutionTarget() != OpenCliExecutionTarget.LOCAL_PROCESS) { return snapshot.status(Status.UNSUPPORTED).reason("LOCAL_DISCOVERY_ONLY").build(); } @@ -132,8 +145,11 @@ private OpenCliCapabilitySnapshot observe() { return snapshot.status(Status.UNKNOWN).reason("INVALID_VERSION_OUTPUT").build(); } snapshot.observedVersion(version); + if (scope != OpenCliHelpScope.ROOT_HELP && !"1.8.8".equals(version)) { + return snapshot.status(Status.UNSUPPORTED).reason("UNVERIFIED_HELP_VERSION").build(); + } phase = "HELP"; - OpenCliResult helpResult = local.invokeLocalOnly(Arrays.asList("--help", "-f", "json")); + OpenCliResult helpResult = local.invokeLocalOnly(scope.arguments()); if (helpResult.getExecutionDetails().isStdoutTruncated()) { return snapshot.status(Status.UNKNOWN).reason("HELP_TRUNCATED").build(); } @@ -141,7 +157,8 @@ private OpenCliCapabilitySnapshot observe() { OpenCliHelpResult help = OpenCliHelpParser.parse(stdout); snapshot.help(help).helpSha256(hex(sha256().digest(stdout.getBytes(StandardCharsets.UTF_8)))); if (help.getStatus() == OpenCliHelpResult.Status.AVAILABLE) { - return snapshot.status(Status.AVAILABLE).build(); + return scope.matches(help.getSchema()) ? snapshot.status(Status.AVAILABLE).build() + : snapshot.status(Status.UNKNOWN).reason("UNEXPECTED_HELP_SCOPE").build(); } return snapshot.status(Status.UNKNOWN).reason(help.getReason().name()).build(); } catch (OpenCliTimeoutException ex) { diff --git a/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilitySnapshot.java b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilitySnapshot.java index 498399c..bb0c298 100644 --- a/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilitySnapshot.java +++ b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilitySnapshot.java @@ -5,12 +5,14 @@ import lombok.Builder; import lombok.Getter; -/** Immutable observation of the configured local CLI's root help. */ +/** Immutable observation of the configured local CLI's help for one query. */ @Getter @Builder(toBuilder = true) public final class OpenCliCapabilitySnapshot { public enum Status { AVAILABLE, STALE, UNKNOWN, UNSUPPORTED } + @Builder.Default + private final OpenCliHelpScope helpScope = OpenCliHelpScope.ROOT_HELP; private final Status status; private final String reason; private final String executable; @@ -24,7 +26,7 @@ public enum Status { AVAILABLE, STALE, UNKNOWN, UNSUPPORTED } /** @return scope of the metadata probe */ public String getScope() { - return "ROOT_HELP"; + return helpScope.name(); } /** @return unresolved origin, since help does not attribute overrides or plugins */ diff --git a/src/main/java/io/github/easy4j/opencli/capability/OpenCliHelpScope.java b/src/main/java/io/github/easy4j/opencli/capability/OpenCliHelpScope.java new file mode 100644 index 0000000..431f69b --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/capability/OpenCliHelpScope.java @@ -0,0 +1,48 @@ +package io.github.easy4j.opencli.capability; + +import io.github.easy4j.opencli.parser.OpenCliHelpSchema; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.List; +import java.util.Objects; + +/** Local help queries verified against OpenCLI 1.8.8. Browser queries use a fixed help-only session token. */ +public enum OpenCliHelpScope { + ROOT_HELP(null, "opencli", null, null), + BROWSER("opencli browser", null, null, "browser", "browser"), + BROWSER_TAB("opencli browser tab", null, null, "browser", "browser", "fixture", "tab"), + BROWSER_GET("opencli browser get", null, null, "browser", "browser", "fixture", "get"), + BROWSER_STATE("opencli browser state", "state", null, "browser", "browser", "fixture", "state"), + META_AUTH("opencli auth", null, null, "auth", "auth"), + META_LIST("opencli list", "list", null, null, "list"), + SITE_NPM(null, null, "npm", null, "npm"), + SITE_NPM_SEARCH("opencli npm search", "search", "npm", null, "npm", "search"); + + private final String command; + private final String name; + private final String site; + private final String namespace; + private final List arguments; + + OpenCliHelpScope(String command, String name, String site, String namespace, String... path) { + this.command = command; + this.name = name; + this.site = site; + this.namespace = namespace; + List argv = new ArrayList<>(Arrays.asList(path)); + argv.addAll(Arrays.asList("--help", "-f", "json")); + this.arguments = Collections.unmodifiableList(argv); + } + + List arguments() { + return arguments; + } + + boolean matches(OpenCliHelpSchema schema) { + return Objects.equals(command, schema.getCommand()) + && Objects.equals(name, schema.getName()) + && Objects.equals(site, schema.getSite()) + && Objects.equals(namespace, schema.getNamespace()); + } +} diff --git a/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java b/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java index f2cc5b8..34027a3 100644 --- a/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java +++ b/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java @@ -173,7 +173,7 @@ void lateRefreshCannotOverwriteNewerSnapshot(@TempDir Path directory) throws Exc props.setMaxConcurrentExecutions(2); ExecutorService callers = Executors.newSingleThreadExecutor(); try (OpenCliClient client = new OpenCliClient(props)) { - Future older = callers.submit(client::discoverCapabilities); + Future older = callers.submit(() -> client.discoverCapabilities()); long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(5); while (!Files.exists(entered) && System.nanoTime() < deadline) { Thread.sleep(10); @@ -196,6 +196,50 @@ void lateRefreshCannotOverwriteNewerSnapshot(@TempDir Path directory) throws Exc } } + @Test + void fixedQueriesReturnTheirCapturedScopeAndKeepUnsupportedFormats() { + OpenCliHelpScope[] scopes = {OpenCliHelpScope.BROWSER_TAB, OpenCliHelpScope.BROWSER_GET, + OpenCliHelpScope.BROWSER_STATE, OpenCliHelpScope.META_AUTH, OpenCliHelpScope.SITE_NPM, + OpenCliHelpScope.SITE_NPM_SEARCH}; + try (OpenCliClient client = new OpenCliClient(properties("structured"))) { + for (OpenCliHelpScope scope : scopes) { + OpenCliCapabilitySnapshot snapshot = client.discoverCapabilities(scope); + assertEquals(OpenCliCapabilitySnapshot.Status.AVAILABLE, snapshot.getStatus(), scope.name()); + assertEquals(scope.name(), snapshot.getScope()); + assertEquals("UNKNOWN", snapshot.getCommandOrigin()); + } + assertEquals("opencli browser state", + client.discoverCapabilities(OpenCliHelpScope.BROWSER_STATE).getHelp().getSchema().getCommand()); + assertEquals("UNSUPPORTED_FORMAT", client.discoverCapabilities(OpenCliHelpScope.META_LIST).getReason()); + assertEquals("INVALID_JSON", client.discoverCapabilities(OpenCliHelpScope.BROWSER).getReason()); + } + } + + @Test + void freshnessIsScopedAndVersionChangesClearOldQueries(@TempDir Path directory) throws Exception { + Path control = directory.resolve("mode"); + writeMode(control, "structured"); + try (OpenCliClient client = new OpenCliClient(controlledProperties(control))) { + OpenCliCapabilitySnapshot root = client.discoverCapabilities(); + OpenCliCapabilitySnapshot state = client.discoverCapabilities(OpenCliHelpScope.BROWSER_STATE); + assertEquals(OpenCliCapabilitySnapshot.Status.AVAILABLE, state.getStatus()); + + writeMode(control, "wrong-help"); + OpenCliCapabilitySnapshot stale = client.discoverCapabilities(OpenCliHelpScope.BROWSER_STATE); + assertEquals(OpenCliCapabilitySnapshot.Status.STALE, stale.getStatus()); + assertEquals("UNEXPECTED_HELP_SCOPE", stale.getReason()); + assertEquals(state.getHelpSha256(), stale.getHelpSha256()); + assertNotEquals(root.getHelpSha256(), stale.getHelpSha256()); + + writeMode(control, "new-version-error"); + OpenCliCapabilitySnapshot upgraded = client.discoverCapabilities(OpenCliHelpScope.BROWSER_STATE); + assertEquals(OpenCliCapabilitySnapshot.Status.UNSUPPORTED, upgraded.getStatus()); + assertEquals("UNVERIFIED_HELP_VERSION", upgraded.getReason()); + writeMode(control, "error"); + assertEquals(OpenCliCapabilitySnapshot.Status.UNKNOWN, client.discoverCapabilities().getStatus()); + } + } + private static OpenCliProperties controlledProperties(Path control) { OpenCliProperties props = properties("unused"); props.getEnvironment().put("OPENCLI_TEST_HELP_CONTROL", control.toString()); @@ -232,6 +276,27 @@ public static void main(String[] args) throws Exception { System.out.print("raw available"); return; } + if (args.length > 3 && Arrays.asList("--help", "-f", "json") + .equals(Arrays.asList(args).subList(args.length - 3, args.length))) { + if ("new-version-error".equals(mode) || "error".equals(mode)) { + System.exit(3); + } + String path = String.join(" ", Arrays.asList(args).subList(0, args.length - 3)); + String fixture; + switch (path) { + case "browser": fixture = "browser.stdout"; break; + case "browser fixture tab": fixture = "browser-tab.json"; break; + case "browser fixture get": fixture = "browser-get.json"; break; + case "browser fixture state": fixture = "browser-state.json"; break; + case "auth": fixture = "meta-auth.json"; break; + case "list": fixture = "meta-list.txt"; break; + case "npm": fixture = "site-npm.json"; break; + case "npm search": fixture = "site-npm-search.json"; break; + default: throw new IllegalArgumentException("Unapproved fixture command"); + } + System.out.print(readFixture("wrong-help".equals(mode) ? "root.json" : fixture)); + return; + } if (!Arrays.equals(args, new String[]{"--help", "-f", "json"})) { System.exit(2); } @@ -256,12 +321,18 @@ public static void main(String[] args) throws Exception { System.out.print("{\"name\":\"opencli\",\"commands\":[],\"site_adapters\":{}}"); return; } + String root = readFixture("root.json").trim(); + System.out.print(root.substring(0, root.length() - 1) + + ",\"description_fixture\":\"do not run this example " + mode + "\"}"); + } + + private static String readFixture(String fixture) { try (InputStream input = DiscoveryFixture.class.getResourceAsStream( - "/opencli-contracts/v1/structured-help-1.8.8/root.json"); + "/opencli-contracts/v1/structured-help-1.8.8/" + fixture); Scanner scan = new Scanner(input, "UTF-8").useDelimiter("\\A")) { - String root = scan.next().trim(); - System.out.print(root.substring(0, root.length() - 1) - + ",\"description_fixture\":\"do not run this example " + mode + "\"}"); + return scan.next(); + } catch (java.io.IOException ex) { + throw new java.io.UncheckedIOException(ex); } } } From 2eab964a383e7613633af68ac8a9e147968cb3ad Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:25:46 +0800 Subject: [PATCH 047/105] Reject malformed version output before capability discovery --- .../OpenCliCapabilityDiscovery.java | 8 ++++--- .../OpenCliCapabilityDiscoveryTest.java | 23 +++++++++++++++++++ 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java index 391e57e..b804b12 100644 --- a/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java +++ b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscovery.java @@ -26,6 +26,7 @@ import java.util.Map; import java.util.Objects; import java.util.TreeMap; +import java.util.regex.Matcher; import java.util.regex.Pattern; /** Fixed, bounded metadata probes through the existing local subprocess runtime. */ @@ -34,7 +35,7 @@ public final class OpenCliCapabilityDiscovery { private static final long MAX_PROBE_MILLIS = 10_000; private static final long MAX_CLEANUP_MILLIS = 1_000; private static final Pattern VERSION = Pattern.compile( - "[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?"); + "[ \t\r\n]*([0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?)[ \t\r\n]*"); private final OpenCliExecutor executor; private long nextAttempt; @@ -140,10 +141,11 @@ private OpenCliCapabilitySnapshot observe(OpenCliHelpScope scope) { String phase = "VERSION"; try { OpenCliResult versionResult = local.invokeLocalOnly(Collections.singletonList("--version")); - String version = versionResult.getStdout().trim(); - if (versionResult.getExecutionDetails().isStdoutTruncated() || !VERSION.matcher(version).matches()) { + Matcher versionOutput = VERSION.matcher(versionResult.getStdout()); + if (versionResult.getExecutionDetails().isStdoutTruncated() || !versionOutput.matches()) { return snapshot.status(Status.UNKNOWN).reason("INVALID_VERSION_OUTPUT").build(); } + String version = versionOutput.group(1); snapshot.observedVersion(version); if (scope != OpenCliHelpScope.ROOT_HELP && !"1.8.8".equals(version)) { return snapshot.status(Status.UNSUPPORTED).reason("UNVERIFIED_HELP_VERSION").build(); diff --git a/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java b/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java index 34027a3..8cdbeca 100644 --- a/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java +++ b/src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityDiscoveryTest.java @@ -67,6 +67,21 @@ void malformedRootRegistryLeavesLocalInvocationAvailable() { } } + @Test + void invalidVersionOutputPreventsTheHelpProbe(@TempDir Path directory) { + Path marker = directory.resolve("help-started"); + OpenCliProperties props = properties("invalid-version"); + props.getEnvironment().put("OPENCLI_TEST_DISCOVERY_HELP_MARKER", marker.toString()); + try (OpenCliClient client = new OpenCliClient(props)) { + OpenCliCapabilitySnapshot result = client.discoverCapabilities(); + assertFalse(Files.exists(marker), "help was started after malformed version output"); + assertEquals(OpenCliCapabilitySnapshot.Status.UNKNOWN, result.getStatus()); + assertEquals("INVALID_VERSION_OUTPUT", result.getReason()); + assertNull(result.getObservedVersion()); + assertNull(result.getHelp()); + } + } + @Test void pathLookupAndRemoteModeAreUnsupported() { try (OpenCliClient client = new OpenCliClient()) { @@ -269,6 +284,10 @@ public static void main(String[] args) throws Exception { mode = new String(Files.readAllBytes(Paths.get(control)), StandardCharsets.UTF_8); } if (Arrays.equals(args, new String[]{"--version"})) { + if ("invalid-version".equals(mode)) { + System.out.println("1.8.8" + (char) 0); + return; + } System.out.println("new-version-error".equals(mode) ? "1.8.9" : "1.8.8"); return; } @@ -300,6 +319,10 @@ public static void main(String[] args) throws Exception { if (!Arrays.equals(args, new String[]{"--help", "-f", "json"})) { System.exit(2); } + String marker = System.getenv("OPENCLI_TEST_DISCOVERY_HELP_MARKER"); + if (Objects.nonNull(marker)) { + Files.createFile(Paths.get(marker)); + } if ("hold-old".equals(mode)) { Path path = Paths.get(control).getParent(); Files.createFile(path.resolve("entered")); From 3b97f2c4037aaa49cf0e992e2a9a695988cacd77 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:29:22 +0800 Subject: [PATCH 048/105] Bind and validate discovered OpenCLI commands before local execution --- .../add-opencli-capability-discovery/tasks.md | 6 + .../github/easy4j/opencli/OpenCliClient.java | 17 ++ .../capability/OpenCliCapabilityCommand.java | 225 ++++++++++++++++++ .../OpenCliCapabilityDiscovery.java | 40 +++- .../opencli/parser/OpenCliHelpParser.java | 1 + .../opencli/parser/OpenCliHelpSchema.java | 1 + .../OpenCliCapabilityCommandTest.java | 63 +++++ .../OpenCliCapabilityDiscoveryTest.java | 14 ++ 8 files changed, 363 insertions(+), 4 deletions(-) create mode 100644 src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityCommand.java create mode 100644 src/test/java/io/github/easy4j/opencli/capability/OpenCliCapabilityCommandTest.java diff --git a/openspec/changes/add-opencli-capability-discovery/tasks.md b/openspec/changes/add-opencli-capability-discovery/tasks.md index 25ce793..6821130 100644 --- a/openspec/changes/add-opencli-capability-discovery/tasks.md +++ b/openspec/changes/add-opencli-capability-discovery/tasks.md @@ -49,3 +49,9 @@ `discoverCapabilities(OpenCliHelpScope)` 提供根目录、浏览器、浏览器 tab/get/state、auth、list 及 npm 站点和 search 的九个固定查询。细粒度参数只在已验证的 OpenCLI 1.8.8 启用。浏览器查询使用固定的帮助会话占位,不接受调用者提供的命令路径,也不执行帮助描述中的内容。结构化结果需匹配请求范围;纯文本和混合输出维持原有失败原因。 每个范围只保存其最近成功的观察,且配置或已观测版本变化使其他不匹配的范围一并失效。OpenCLI 能力仍按请求观察,并保留来源未知标记。增加 `OpenCliCapabilityDiscoveryTest` 的进程验收后,缺少范围 API 时失败,加入实现后定向测试通过。类型化会话绑定及执行前参数校验仍待验收。 + +## OC-CAP-002/003 类型化本地调用 + +`OpenCliClient.invokeDiscovered` 对本地配置取快照,刷新指定范围,选择显式给定的叶子路径,校验后通过同一执行器运行时提交字面参数。需要提供浏览器会话时,必须填入合法会话标识。校验覆盖必选项和值、声明 choices、可选值 flag、显式 false、否定拼写和可变位置参数;用字面分隔符隔离可能像选项的位置参数。不可用或过期的帮助无法进入类型化执行。原有本地 raw 入口独立可用。 + +`OpenCliCapabilityCommandTest` 和 `OpenCliCapabilityDiscoveryTest` 以失败→通过验证新 API、字段级错误和真实 JVM 子进程收到的 argv。当前仅对已验证的 OpenCLI 1.8.8 执行发现绑定;测试不依赖浏览器账户。 diff --git a/src/main/java/io/github/easy4j/opencli/OpenCliClient.java b/src/main/java/io/github/easy4j/opencli/OpenCliClient.java index 798f514..edc780c 100644 --- a/src/main/java/io/github/easy4j/opencli/OpenCliClient.java +++ b/src/main/java/io/github/easy4j/opencli/OpenCliClient.java @@ -24,9 +24,12 @@ import io.github.easy4j.opencli.core.OpenCliAdapterChannel; import io.github.easy4j.opencli.meta.OpenCliMetaClient; import io.github.easy4j.opencli.core.OpenCliExecutor; +import io.github.easy4j.opencli.core.OpenCliResult; import io.github.easy4j.opencli.facade.BrowserClient; import io.github.easy4j.opencli.facade.DesktopClient; import io.github.easy4j.opencli.facade.PublicApiClient; +import java.util.List; +import java.util.Map; import java.util.Objects; import lombok.Getter; @@ -105,6 +108,20 @@ public OpenCliCapabilitySnapshot discoverCapabilities(OpenCliHelpScope scope) { return capabilityDiscovery.refresh(scope); } + /** + * Refreshes structured help and invokes an explicitly selected, validated local command. + * @param scope verified help query containing the leaf + * @param command exact leaf display path from help + * @param session browser session identifier, or null when the command has no session + * @param positionals user-supplied positionals in schema order, or null + * @param options option spellings and values, with null for bare flags + * @return local execution result + */ + public OpenCliResult invokeDiscovered(OpenCliHelpScope scope, String command, String session, + List positionals, Map options) { + return capabilityDiscovery.invoke(scope, command, session, positionals, options); + } + // ----- 参考强类型门面(Desktop) ----- /** @return Codex 桌面适配器客户端 */ diff --git a/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityCommand.java b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityCommand.java new file mode 100644 index 0000000..ebbe7b1 --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/capability/OpenCliCapabilityCommand.java @@ -0,0 +1,225 @@ +package io.github.easy4j.opencli.capability; + +import io.github.easy4j.opencli.core.OpenCliArgSupport; +import io.github.easy4j.opencli.parser.OpenCliHelpSchema; +import io.github.easy4j.opencli.parser.OpenCliHelpSchema.Argument; +import io.github.easy4j.opencli.util.OpenCliStrings; +import java.util.ArrayList; +import java.util.Collections; +import java.util.HashSet; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.Objects; +import java.util.Set; +import java.util.regex.Pattern; +import lombok.RequiredArgsConstructor; + +/** Converts one explicitly selected help leaf into validated literal CLI arguments. */ +public final class OpenCliCapabilityCommand { + private static final Pattern COMMAND_TOKEN = Pattern.compile("[A-Za-z0-9][A-Za-z0-9_-]*"); + private static final Pattern OPTION_TOKEN = Pattern.compile("--[A-Za-z0-9][A-Za-z0-9-]*|-[A-Za-z0-9]"); + + private OpenCliCapabilityCommand() { + } + + /** + * @param snapshot currently available structured help + * @param command exact leaf display path from help, including any placeholders + * @param session explicit browser session, or null for a non-browser leaf + * @param positionals literal values in declared order, or null + * @param options declared option spellings and values, with null values for bare flags + * @return immutable literal arguments excluding the executable + */ + public static List bind(OpenCliCapabilitySnapshot snapshot, String command, String session, + List positionals, Map options) { + Objects.requireNonNull(snapshot, "snapshot"); + Objects.requireNonNull(command, "command"); + if (snapshot.getStatus() != OpenCliCapabilitySnapshot.Status.AVAILABLE + || Objects.isNull(snapshot.getHelp()) || Objects.isNull(snapshot.getHelp().getSchema())) { + throw new IllegalStateException("Current structured help is unavailable"); + } + OpenCliHelpSchema scope = snapshot.getHelp().getSchema(); + OpenCliHelpSchema leaf = locateLeaf(scope, command); + String[] path = command.split(" ", -1); + if (path.length < 3 || !"opencli".equals(path[0])) { + throw new IllegalArgumentException("The help command path cannot be bound"); + } + + List prefixOptions = new ArrayList<>(); + List leafOptions = new ArrayList<>(); + appendOptions(scope, leaf, options, prefixOptions, leafOptions); + + List argv = new ArrayList<>(); + argv.add(path[1]); + argv.addAll(prefixOptions); + boolean sessionUsed = false; + for (int index = 2; index < path.length; index++) { + String token = path[index]; + if ("".equals(token) && index == 2 && "browser".equals(path[1])) { + if (OpenCliStrings.isBlank(session) || !COMMAND_TOKEN.matcher(session).matches()) { + throw new IllegalArgumentException("A literal browser session identifier is required"); + } + argv.add(session); + sessionUsed = true; + } else { + if (!COMMAND_TOKEN.matcher(token).matches()) { + throw new IllegalArgumentException("The help command path contains an unsupported token"); + } + argv.add(token); + } + } + if (!sessionUsed && Objects.nonNull(session)) { + throw new IllegalArgumentException("This command has no browser session binding"); + } + argv.addAll(leafOptions); + List values = OpenCliArgSupport.merge(null, positionals); + validatePositionals(leaf.getPositionals(), values); + if (!values.isEmpty()) { + argv.add("--"); + argv.addAll(values); + } + return Collections.unmodifiableList(argv); + } + + private static OpenCliHelpSchema locateLeaf(OpenCliHelpSchema scope, String command) { + if (command.equals(scope.getCommand()) && scope.getCommands().isEmpty()) { + return scope; + } + return scope.getCommands().stream() + .filter(child -> command.equals(child.getCommand()) && child.getCommands().isEmpty()) + .findFirst() + .orElseThrow(() -> new IllegalArgumentException("The requested command is not a leaf in this help scope")); + } + + private static void validatePositionals(List definitions, List values) { + int consumed = 0; + for (Argument definition : definitions) { + int count = Boolean.TRUE.equals(definition.getVariadic()) ? values.size() - consumed + : Math.min(1, values.size() - consumed); + if (count == 0 && Boolean.TRUE.equals(definition.getRequired())) { + throw invalid(definition, "is required"); + } + for (int index = 0; index < count; index++) { + validateValue(definition, values.get(consumed++)); + } + } + if (consumed != values.size()) { + throw new IllegalArgumentException("Too many positional arguments"); + } + } + + private static void appendOptions(OpenCliHelpSchema scope, OpenCliHelpSchema leaf, Map options, + List prefix, List local) { + Map definitions = new LinkedHashMap<>(); + index(definitions, inherited(leaf.getGlobalOptions(), scope.getGlobalOptions()), prefix); + index(definitions, inherited(leaf.getNamespaceOptions(), scope.getNamespaceOptions()), prefix); + index(definitions, inherited(leaf.getCommonOptions(), scope.getCommonOptions()), local); + index(definitions, leaf.getCommandOptions(), local); + Set