From cdc8b66e74730ab1ed99a9f24a077f9077d2dbf5 Mon Sep 17 00:00:00 2001 From: Loong Wan Date: Mon, 21 Sep 2026 12:45:05 +0800 Subject: [PATCH 001/146] test(contracts): establish C10 evidence foundation and C01 RED process tests Add shared, hash-locked synthetic argv vectors and a Java 8-compatible child probe. Add fail-closed layered Surefire reporting with 12 self-tests and pinned OpenSpec strict CI. This is the intentional C01 RED checkpoint; no product Java sources changed. Keep C10 integration and the remaining OpenSpec changes open. --- .github/workflows/contracts.yml | 126 +++++++++++++ docs/implementation/c10-c01-execution.md | 23 +++ scripts/contract_report.py | 111 ++++++++++++ scripts/tests/test_contract_report.py | 96 ++++++++++ .../opencli/contract/ContractProbe.java | 16 ++ .../contract/OpenCliArgvContractTest.java | 171 ++++++++++++++++++ .../resources/opencli-contracts/v1/SHA256SUMS | 2 + .../resources/opencli-contracts/v1/argv.tsv | 6 + .../opencli-contracts/v1/sources.lock.json | 58 ++++++ 9 files changed, 609 insertions(+) create mode 100644 .github/workflows/contracts.yml create mode 100644 docs/implementation/c10-c01-execution.md create mode 100644 scripts/contract_report.py create mode 100644 scripts/tests/test_contract_report.py create mode 100644 src/test/java/io/github/easy4j/opencli/contract/ContractProbe.java create mode 100644 src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.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/.github/workflows/contracts.yml b/.github/workflows/contracts.yml new file mode 100644 index 0000000..4c53c65 --- /dev/null +++ b/.github/workflows/contracts.yml @@ -0,0 +1,126 @@ +name: OpenCLI Contracts + +on: + push: + branches: + - 'feature/1.0.x' + - 'feature/2.0.x' + - 'feature/3.0.x' + - 'feature/*-contract-hardening' + workflow_dispatch: + +permissions: + contents: read + +jobs: + specification: + name: OpenSpec strict and evidence-runner tests + runs-on: ubuntu-latest + timeout-minutes: 10 + env: + OPENSPEC_TELEMETRY: '0' + DO_NOT_TRACK: '1' + CI: 'true' + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v4 + with: + node-version: '22' + - name: Verify report runner and shared fixture hashes + run: | + python3 -m unittest discover -s scripts/tests -v + (cd src/test/resources/opencli-contracts/v1 && sha256sum -c SHA256SUMS) + - name: Install pinned official OpenSpec + run: npm install --prefix "$RUNNER_TEMP/opencli-openspec" --ignore-scripts --no-audit --no-fund @fission-ai/openspec@1.13.1 + - name: Validate all proposals and each change with strict mode + shell: bash + run: | + export PATH="$RUNNER_TEMP/opencli-openspec/node_modules/.bin:$PATH" + mkdir -p .spec-evidence + openspec --version | tee .spec-evidence/version.txt + openspec list --json > .spec-evidence/list.json + failed=0 + for path in openspec/changes/*; do + [[ -d "$path" && "$(basename "$path")" != archive ]] || continue + change="$(basename "$path")" + if openspec validate "$change" --strict --no-interactive > ".spec-evidence/$change.log" 2>&1; then + printf '%s\tPASS\n' "$change" + else + cat ".spec-evidence/$change.log" + failed=1 + fi + done + if ! openspec validate --all --strict --no-interactive > .spec-evidence/all.log 2>&1; then + cat .spec-evidence/all.log + failed=1 + fi + exit "$failed" + - name: Upload specification evidence + if: always() + uses: actions/upload-artifact@v7 + with: + name: openspec-strict-${{ github.sha }} + path: .spec-evidence + if-no-files-found: error + + jvm: + name: Branch-specific JVM contract verification + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - uses: actions/checkout@v7 + - name: Select declared branch line + id: line + shell: bash + run: | + case "$GITHUB_REF_NAME" in + feature/1.0.x*) echo 'java=8' >> "$GITHUB_OUTPUT" ;; + feature/2.0.x*) echo 'java=17' >> "$GITHUB_OUTPUT" ;; + feature/3.0.x*) echo 'java=21' >> "$GITHUB_OUTPUT" ;; + *) echo 'Unsupported branch line' >&2; exit 1 ;; + esac + - uses: actions/setup-java@v5 + with: + distribution: temurin + java-version: ${{ steps.line.outputs.java }} + cache: maven + - name: Record exact source and actual tools + run: | + mkdir -p .contract-evidence + git rev-parse HEAD > .contract-evidence/head.txt + java -version > .contract-evidence/java.txt 2>&1 + bash ./mvnw -version > .contract-evidence/maven.txt 2>&1 + - name: Full clean verify using this branch wrapper + id: verify + shell: bash + run: | + set +e + bash ./mvnw -B --no-transfer-progress clean verify > .contract-evidence/maven.log 2>&1 + result=$? + printf '%s\n' "$result" > .contract-evidence/maven.exit + tail -100 .contract-evidence/maven.log + exit "$result" + - name: Require nonempty, non-skipped contract evidence + if: always() + shell: bash + run: | + test -f .contract-evidence/maven.exit + python3 scripts/contract_report.py \ + --reports target/surefire-reports \ + --head "$(cat .contract-evidence/head.txt)" \ + --branch "$GITHUB_REF_NAME" \ + --java-version-file .contract-evidence/java.txt \ + --maven-version-file .contract-evidence/maven.txt \ + --exit-code "$(cat .contract-evidence/maven.exit)" \ + --suite argv=io.github.easy4j.opencli.contract.OpenCliArgvContractTest \ + --output .contract-evidence/report.json + - name: Upload actual JVM evidence + if: always() + uses: actions/upload-artifact@v7 + with: + name: contracts-jdk-${{ steps.line.outputs.java }}-${{ github.sha }} + path: | + .contract-evidence + target/surefire-reports + target/site/jacoco + if-no-files-found: error diff --git a/docs/implementation/c10-c01-execution.md b/docs/implementation/c10-c01-execution.md new file mode 100644 index 0000000..dab1be4 --- /dev/null +++ b/docs/implementation/c10-c01-execution.md @@ -0,0 +1,23 @@ +# C10 foundation and C01 implementation ledger + +## Approved ordering and scope + +The user approved C10 foundation, then C01/C02/C03/C04/C05/C09, then C06/C07/C08, and only then C10 integration closure. `feature/2.0.x` is the canonical implementation line. This file records execution, not completion of the ten changes. + +An isolated implementation branch starts at `d0c8056990f7a47fcc202acffa387ba066bcfc67`. The 1.x/3.x baseline refs and permitted JDK/Jackson/Maven differences are recorded in `src/test/resources/opencli-contracts/v1/sources.lock.json`. No changes to `main`, dependency versions or coverage thresholds are part of this increment. + +## C10 foundation + +Shared synthetic UTF-8/base64 argv vectors preserve empty and trailing empty fields. They have content hashes and a specification ref, not an invented upstream capture provenance. A Java 8-compatible child prints each actual argument. The regression suite uses the real SDK executor, adapter and Browser paths; a Recording executor is not used to prove process behavior. + +The report runner separates enumeration, argv, protocol, typed-result and real-execution evidence. Only explicitly selected suites contribute; the real-execution layer remains NOT_RUN because a Java argv probe is not a live OpenCLI website test. Missing reports, zero tests, skipped required tests, nonzero Maven exit, malformed XML and inconsistent testcase counts fail closed. + +Local runner TDD: 12 failures before the runner existed, then 12 passing tests. The probe compiled with `javac --release 8` on JDK 21 and emitted an empty token unchanged. This does not constitute an actual JDK 8 runtime test. Full JVM evidence is produced by the branch-specific GitHub Actions workflow using each line's checked-in Maven wrapper. + +## C01 RED checkpoint + +The initial Java contract suite deliberately demands lossless values before any product source is changed. The first CI run must be inspected for assertion failures at the real child boundary, not treated as a completed fix. Compilation errors or tool setup failures are not valid RED proof. + +## Still open + +C01 schema-aware repeated/false option handling, C02/C03/C04/C05/C09 production fixes, discovery, Browser result models, context/diagnostics and three-branch integration closure are not complete. Official OpenSpec strict is configured but must be observed at the exact workflow run before claiming it passed. No OpenSpec implementation tasks are pre-checked. diff --git a/scripts/contract_report.py b/scripts/contract_report.py new file mode 100644 index 0000000..19fcbba --- /dev/null +++ b/scripts/contract_report.py @@ -0,0 +1,111 @@ +#!/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', '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): + # Do not copy testcase failure bodies or captured application output. + 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 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/scripts/tests/test_contract_report.py b/scripts/tests/test_contract_report.py new file mode 100644 index 0000000..f466e0a --- /dev/null +++ b/scripts/tests/test_contract_report.py @@ -0,0 +1,96 @@ +import importlib.util +import json +import pathlib +import tempfile +import unittest + +SCRIPT = pathlib.Path(__file__).resolve().parents[1] / 'contract_report.py' +HEAD = 'd0c8056990f7a47fcc202acffa387ba066bcfc67' +SUITE = 'io.github.easy4j.opencli.contract.OpenCliArgvContractTest' + + +class ContractReportTest(unittest.TestCase): + def setUp(self): + self.assertTrue(SCRIPT.is_file(), 'C10 contract report runner is not implemented') + spec = importlib.util.spec_from_file_location('contract_report', SCRIPT) + self.module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(self.module) + self.temp = tempfile.TemporaryDirectory() + self.addCleanup(self.temp.cleanup) + self.root = pathlib.Path(self.temp.name) + + def xml(self, tests=2, skipped=0, failures=0, errors=0): + executed = tests - skipped + cases = [] + for i in range(tests): + child = '' if i >= executed else ('' if i < failures else ('' if i < failures + errors else '')) + cases.append('' + child + '') + (self.root / ('TEST-' + SUITE + '.xml')).write_text( + '' + ''.join(cases) + '', encoding='utf-8') + + def report(self, **kwargs): + return self.module.build_report(self.root, head=kwargs.get('head', HEAD), + branch='feature/2.0.x', java_version='openjdk 17 (test fixture)', + maven_version='Apache Maven (test fixture)', exit_code=kwargs.get('exit_code', 0), + required_suites={'argv': [SUITE]}) + + def test_complete_argv_evidence_passes_but_live_is_not_run(self): + self.xml() + report = self.report() + self.assertEqual('PASS', report['status']) + self.assertEqual(2, report['layers']['argv']['executed']) + self.assertEqual('NOT_RUN', report['layers']['real-execution']['status']) + self.assertEqual(HEAD, report['head']) + json.dumps(report) + + def test_missing_report_fails(self): + self.assertEqual('FAIL', self.report()['status']) + + def test_zero_tests_fails(self): + self.xml(tests=0) + self.assertEqual('FAIL', self.report()['status']) + + def test_all_skipped_fails(self): + self.xml(tests=2, skipped=2) + self.assertEqual('FAIL', self.report()['status']) + + def test_partly_skipped_fails(self): + self.xml(tests=2, skipped=1) + self.assertEqual('FAIL', self.report()['status']) + + def test_failure_fails(self): + self.xml(failures=1) + self.assertEqual('FAIL', self.report()['status']) + + def test_error_fails(self): + self.xml(errors=1) + self.assertEqual('FAIL', self.report()['status']) + + def test_nonzero_command_exit_fails_despite_green_xml(self): + self.xml() + self.assertEqual('FAIL', self.report(exit_code=1)['status']) + + def test_malformed_xml_fails_closed(self): + (self.root / 'TEST-broken.xml').write_text('', '', 1), encoding='utf-8') + self.assertEqual('FAIL', self.report()['status']) + + +if __name__ == '__main__': + unittest.main() 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/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/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 94de053f4ae7a0912201c2bbeab81b8332f660b8 Mon Sep 17 00:00:00 2001 From: Loong Wan Date: Mon, 21 Sep 2026 12:47:42 +0800 Subject: [PATCH 002/146] fix(ci): restore wrapper launcher and preserve contract evidence artifacts The 2.x script invokes MavenWrapperMain but its launcher JAR was absent. Reuse the existing repository 3.x launcher blob; retain Maven 3.9.16 distribution. Use non-hidden scoped evidence directories so upload-artifact can find reports. No product-source changes; the C01 regression suite remains the RED checkpoint. --- .github/workflows/contracts.yml | 48 ++++++++++++++------------ .mvn/wrapper/maven-wrapper.jar | Bin 0 -> 50710 bytes .mvn/wrapper/maven-wrapper.properties | 2 +- 3 files changed, 27 insertions(+), 23 deletions(-) create mode 100644 .mvn/wrapper/maven-wrapper.jar mode change 100755 => 100644 .mvn/wrapper/maven-wrapper.properties diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index 4c53c65..5f9c448 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -36,22 +36,22 @@ jobs: shell: bash run: | export PATH="$RUNNER_TEMP/opencli-openspec/node_modules/.bin:$PATH" - mkdir -p .spec-evidence - openspec --version | tee .spec-evidence/version.txt - openspec list --json > .spec-evidence/list.json + mkdir -p spec-evidence + openspec --version | tee spec-evidence/version.txt + openspec list --json > spec-evidence/list.json failed=0 for path in openspec/changes/*; do [[ -d "$path" && "$(basename "$path")" != archive ]] || continue change="$(basename "$path")" - if openspec validate "$change" --strict --no-interactive > ".spec-evidence/$change.log" 2>&1; then + if openspec validate "$change" --strict --no-interactive > "spec-evidence/$change.log" 2>&1; then printf '%s\tPASS\n' "$change" else - cat ".spec-evidence/$change.log" + cat "spec-evidence/$change.log" failed=1 fi done - if ! openspec validate --all --strict --no-interactive > .spec-evidence/all.log 2>&1; then - cat .spec-evidence/all.log + if ! openspec validate --all --strict --no-interactive > spec-evidence/all.log 2>&1; then + cat spec-evidence/all.log failed=1 fi exit "$failed" @@ -60,7 +60,7 @@ jobs: uses: actions/upload-artifact@v7 with: name: openspec-strict-${{ github.sha }} - path: .spec-evidence + path: spec-evidence if-no-files-found: error jvm: @@ -86,41 +86,45 @@ jobs: cache: maven - name: Record exact source and actual tools run: | - mkdir -p .contract-evidence - git rev-parse HEAD > .contract-evidence/head.txt - java -version > .contract-evidence/java.txt 2>&1 - bash ./mvnw -version > .contract-evidence/maven.txt 2>&1 + mkdir -p contract-evidence + git rev-parse HEAD > contract-evidence/head.txt + java -version > contract-evidence/java.txt 2>&1 + if ! bash ./mvnw -version > contract-evidence/maven.txt 2>&1; then + cat contract-evidence/maven.txt + exit 1 + fi + cat contract-evidence/java.txt contract-evidence/maven.txt - name: Full clean verify using this branch wrapper id: verify shell: bash run: | set +e - bash ./mvnw -B --no-transfer-progress clean verify > .contract-evidence/maven.log 2>&1 + bash ./mvnw -B --no-transfer-progress clean verify > contract-evidence/maven.log 2>&1 result=$? - printf '%s\n' "$result" > .contract-evidence/maven.exit - tail -100 .contract-evidence/maven.log + printf '%s\n' "$result" > contract-evidence/maven.exit + tail -100 contract-evidence/maven.log exit "$result" - name: Require nonempty, non-skipped contract evidence if: always() shell: bash run: | - test -f .contract-evidence/maven.exit + test -f contract-evidence/maven.exit python3 scripts/contract_report.py \ --reports target/surefire-reports \ - --head "$(cat .contract-evidence/head.txt)" \ + --head "$(cat contract-evidence/head.txt)" \ --branch "$GITHUB_REF_NAME" \ - --java-version-file .contract-evidence/java.txt \ - --maven-version-file .contract-evidence/maven.txt \ - --exit-code "$(cat .contract-evidence/maven.exit)" \ + --java-version-file contract-evidence/java.txt \ + --maven-version-file contract-evidence/maven.txt \ + --exit-code "$(cat contract-evidence/maven.exit)" \ --suite argv=io.github.easy4j.opencli.contract.OpenCliArgvContractTest \ - --output .contract-evidence/report.json + --output contract-evidence/report.json - name: Upload actual JVM evidence if: always() uses: actions/upload-artifact@v7 with: name: contracts-jdk-${{ steps.line.outputs.java }}-${{ github.sha }} path: | - .contract-evidence + contract-evidence target/surefire-reports target/site/jacoco if-no-files-found: error diff --git a/.mvn/wrapper/maven-wrapper.jar b/.mvn/wrapper/maven-wrapper.jar new file mode 100644 index 0000000000000000000000000000000000000000..2cc7d4a55c0cd0092912bf49ae38b3a9e3fd0054 GIT binary patch literal 50710 zcmbTd1CVCTmM+|7+wQV$+qP}n>auOywyU~q+qUhh+uxis_~*a##hm*_WW?9E7Pb7N%LRFiwbEGCJ0XP=%-6oeT$XZcYgtzC2~q zk(K08IQL8oTl}>>+hE5YRgXTB@fZ4TH9>7=79e`%%tw*SQUa9~$xKD5rS!;ZG@ocK zQdcH}JX?W|0_Afv?y`-NgLum62B&WSD$-w;O6G0Sm;SMX65z)l%m1e-g8Q$QTI;(Q z+x$xth4KFvH@Bs6(zn!iF#nenk^Y^ce;XIItAoCsow38eq?Y-Auh!1in#Rt-_D>H^ z=EjbclGGGa6VnaMGmMLj`x3NcwA43Jb(0gzl;RUIRAUDcR1~99l2SAPkVhoRMMtN} zXvC<tOmX83grD8GSo_Lo?%lNfhD#EBgPo z*nf@ppMC#B!T)Ae0RG$mlJWmGl7CkuU~B8-==5i;rS;8i6rJ=PoQxf446XDX9g|c> zU64ePyMlsI^V5Jq5A+BPe#e73+kpc_r1tv#B)~EZ;7^67F0*QiYfrk0uVW;Qb=NsG zN>gsuCwvb?s-KQIppEaeXtEMdc9dy6Dfduz-tMTms+i01{eD9JE&h?Kht*$eOl#&L zJdM_-vXs(V#$Ed;5wyNWJdPNh+Z$+;$|%qR(t`4W@kDhd*{(7-33BOS6L$UPDeE_53j${QfKN-0v-HG z(QfyvFNbwPK%^!eIo4ac1;b>c0vyf9}Xby@YY!lkz-UvNp zwj#Gg|4B~?n?G^{;(W;|{SNoJbHTMpQJ*Wq5b{l9c8(%?Kd^1?H1om1de0Da9M;Q=n zUfn{f87iVb^>Exl*nZ0hs(Yt>&V9$Pg`zX`AI%`+0SWQ4Zc(8lUDcTluS z5a_KerZWe}a-MF9#Cd^fi!y3%@RFmg&~YnYZ6<=L`UJ0v={zr)>$A;x#MCHZy1st7 ztT+N07NR+vOwSV2pvWuN1%lO!K#Pj0Fr>Q~R40{bwdL%u9i`DSM4RdtEH#cW)6}+I-eE< z&tZs+(Ogu(H_;$a$!7w`MH0r%h&@KM+<>gJL@O~2K2?VrSYUBbhCn#yy?P)uF3qWU z0o09mIik+kvzV6w>vEZy@&Mr)SgxPzUiDA&%07m17udz9usD82afQEps3$pe!7fUf z0eiidkJ)m3qhOjVHC_M(RYCBO%CZKZXFb8}s0-+}@CIn&EF(rRWUX2g^yZCvl0bI} zbP;1S)iXnRC&}5-Tl(hASKqdSnO?ASGJ*MIhOXIblmEudj(M|W!+I3eDc}7t`^mtg z)PKlaXe(OH+q-)qcQ8a@!llRrpGI8DsjhoKvw9T;TEH&?s=LH0w$EzI>%u;oD@x83 zJL7+ncjI9nn!TlS_KYu5vn%f*@qa5F;| zEFxY&B?g=IVlaF3XNm_03PA)=3|{n-UCgJoTr;|;1AU9|kPE_if8!Zvb}0q$5okF$ zHaJdmO&gg!9oN|M{!qGE=tb|3pVQ8PbL$}e;NgXz<6ZEggI}wO@aBP**2Wo=yN#ZC z4G$m^yaM9g=|&!^ft8jOLuzc3Psca*;7`;gnHm}tS0%f4{|VGEwu45KptfNmwxlE~ z^=r30gi@?cOm8kAz!EylA4G~7kbEiRlRIzwrb~{_2(x^$-?|#e6Bi_**(vyr_~9Of z!n>Gqf+Qwiu!xhi9f53=PM3`3tNF}pCOiPU|H4;pzjcsqbwg*{{kyrTxk<;mx~(;; z1NMrpaQ`57yn34>Jo3b|HROE(UNcQash!0p2-!Cz;{IRv#Vp5!3o$P8!%SgV~k&Hnqhp`5eLjTcy93cK!3Hm-$`@yGnaE=?;*2uSpiZTs_dDd51U%i z{|Zd9ou-;laGS_x=O}a+ zB||za<795A?_~Q=r=coQ+ZK@@ zId~hWQL<%)fI_WDIX#=(WNl!Dm$a&ROfLTd&B$vatq!M-2Jcs;N2vps$b6P1(N}=oI3<3luMTmC|0*{ zm1w8bt7vgX($!0@V0A}XIK)w!AzUn7vH=pZEp0RU0p?}ch2XC-7r#LK&vyc2=-#Q2 z^L%8)JbbcZ%g0Du;|8=q8B>X=mIQirpE=&Ox{TiuNDnOPd-FLI^KfEF729!!0x#Es z@>3ursjFSpu%C-8WL^Zw!7a0O-#cnf`HjI+AjVCFitK}GXO`ME&on|^=~Zc}^LBp9 zj=-vlN;Uc;IDjtK38l7}5xxQF&sRtfn4^TNtnzXv4M{r&ek*(eNbIu!u$>Ed%` z5x7+&)2P&4>0J`N&ZP8$vcR+@FS0126s6+Jx_{{`3ZrIMwaJo6jdrRwE$>IU_JTZ} z(||hyyQ)4Z1@wSlT94(-QKqkAatMmkT7pCycEB1U8KQbFX&?%|4$yyxCtm3=W`$4fiG0WU3yI@c zx{wfmkZAYE_5M%4{J-ygbpH|(|GD$2f$3o_Vti#&zfSGZMQ5_f3xt6~+{RX=$H8at z?GFG1Tmp}}lmm-R->ve*Iv+XJ@58p|1_jRvfEgz$XozU8#iJS})UM6VNI!3RUU!{5 zXB(+Eqd-E;cHQ>)`h0(HO_zLmzR3Tu-UGp;08YntWwMY-9i^w_u#wR?JxR2bky5j9 z3Sl-dQQU$xrO0xa&>vsiK`QN<$Yd%YXXM7*WOhnRdSFt5$aJux8QceC?lA0_if|s> ze{ad*opH_kb%M&~(~&UcX0nFGq^MqjxW?HJIP462v9XG>j(5Gat_)#SiNfahq2Mz2 zU`4uV8m$S~o9(W>mu*=h%Gs(Wz+%>h;R9Sg)jZ$q8vT1HxX3iQnh6&2rJ1u|j>^Qf`A76K%_ubL`Zu?h4`b=IyL>1!=*%!_K)=XC z6d}4R5L+sI50Q4P3upXQ3Z!~1ZXLlh!^UNcK6#QpYt-YC=^H=EPg3)z*wXo*024Q4b2sBCG4I# zlTFFY=kQ>xvR+LsuDUAk)q%5pEcqr(O_|^spjhtpb1#aC& zghXzGkGDC_XDa%t(X`E+kvKQ4zrQ*uuQoj>7@@ykWvF332)RO?%AA&Fsn&MNzmFa$ zWk&&^=NNjxLjrli_8ESU)}U|N{%j&TQmvY~lk!~Jh}*=^INA~&QB9em!in_X%Rl1&Kd~Z(u z9mra#<@vZQlOY+JYUwCrgoea4C8^(xv4ceCXcejq84TQ#sF~IU2V}LKc~Xlr_P=ry zl&Hh0exdCbVd^NPCqNNlxM3vA13EI8XvZ1H9#bT7y*U8Y{H8nwGpOR!e!!}*g;mJ#}T{ekSb}5zIPmye*If(}}_=PcuAW#yidAa^9-`<8Gr0 z)Fz=NiZ{)HAvw{Pl5uu)?)&i&Us$Cx4gE}cIJ}B4Xz~-q7)R_%owbP!z_V2=Aq%Rj z{V;7#kV1dNT9-6R+H}}(ED*_!F=~uz>&nR3gb^Ce%+0s#u|vWl<~JD3MvS0T9thdF zioIG3c#Sdsv;LdtRv3ml7%o$6LTVL>(H`^@TNg`2KPIk*8-IB}X!MT0`hN9Ddf7yN z?J=GxPL!uJ7lqwowsl?iRrh@#5C$%E&h~Z>XQcvFC*5%0RN-Opq|=IwX(dq(*sjs+ zqy99+v~m|6T#zR*e1AVxZ8djd5>eIeCi(b8sUk)OGjAsKSOg^-ugwl2WSL@d#?mdl zib0v*{u-?cq}dDGyZ%$XRY=UkQwt2oGu`zQneZh$=^! zj;!pCBWQNtvAcwcWIBM2y9!*W|8LmQy$H~5BEx)78J`4Z0(FJO2P^!YyQU{*Al+fs z){!4JvT1iLrJ8aU3k0t|P}{RN)_^v%$$r;+p0DY7N8CXzmS*HB*=?qaaF9D@#_$SN zSz{moAK<*RH->%r7xX~9gVW$l7?b|_SYI)gcjf0VAUJ%FcQP(TpBs; zg$25D!Ry_`8xpS_OJdeo$qh#7U+cepZ??TII7_%AXsT$B z=e)Bx#v%J0j``00Zk5hsvv6%T^*xGNx%KN-=pocSoqE5_R)OK%-Pbu^1MNzfds)mL zxz^F4lDKV9D&lEY;I+A)ui{TznB*CE$=9(wgE{m}`^<--OzV-5V4X2w9j(_!+jpTr zJvD*y6;39&T+==$F&tsRKM_lqa1HC}aGL0o`%c9mO=fts?36@8MGm7Vi{Y z^<7m$(EtdSr#22<(rm_(l_(`j!*Pu~Y>>xc>I9M#DJYDJNHO&4=HM%YLIp?;iR&$m z#_$ZWYLfGLt5FJZhr3jpYb`*%9S!zCG6ivNHYzNHcI%khtgHBliM^Ou}ZVD7ehU9 zS+W@AV=?Ro!=%AJ>Kcy9aU3%VX3|XM_K0A+ZaknKDyIS3S-Hw1C7&BSW5)sqj5Ye_ z4OSW7Yu-;bCyYKHFUk}<*<(@TH?YZPHr~~Iy%9@GR2Yd}J2!N9K&CN7Eq{Ka!jdu; zQNB*Y;i(7)OxZK%IHGt#Rt?z`I|A{q_BmoF!f^G}XVeTbe1Wnzh%1g>j}>DqFf;Rp zz7>xIs12@Ke0gr+4-!pmFP84vCIaTjqFNg{V`5}Rdt~xE^I;Bxp4)|cs8=f)1YwHz zqI`G~s2~qqDV+h02b`PQpUE#^^Aq8l%y2|ByQeXSADg5*qMprEAE3WFg0Q39`O+i1 z!J@iV!`Y~C$wJ!5Z+j5$i<1`+@)tBG$JL=!*uk=2k;T<@{|s1$YL079FvK%mPhyHV zP8^KGZnp`(hVMZ;s=n~3r2y;LTwcJwoBW-(ndU-$03{RD zh+Qn$ja_Z^OuMf3Ub|JTY74s&Am*(n{J3~@#OJNYuEVVJd9*H%)oFoRBkySGm`hx! zT3tG|+aAkXcx-2Apy)h^BkOyFTWQVeZ%e2@;*0DtlG9I3Et=PKaPt&K zw?WI7S;P)TWED7aSH$3hL@Qde?H#tzo^<(o_sv_2ci<7M?F$|oCFWc?7@KBj-;N$P zB;q!8@bW-WJY9do&y|6~mEruZAVe$!?{)N9rZZxD-|oltkhW9~nR8bLBGXw<632!l z*TYQn^NnUy%Ds}$f^=yQ+BM-a5X4^GHF=%PDrRfm_uqC zh{sKwIu|O0&jWb27;wzg4w5uA@TO_j(1X?8E>5Zfma|Ly7Bklq|s z9)H`zoAGY3n-+&JPrT!>u^qg9Evx4y@GI4$n-Uk_5wttU1_t?6><>}cZ-U+&+~JE) zPlDbO_j;MoxdLzMd~Ew|1o^a5q_1R*JZ=#XXMzg?6Zy!^hop}qoLQlJ{(%!KYt`MK z8umEN@Z4w!2=q_oe=;QttPCQy3Nm4F@x>@v4sz_jo{4m*0r%J(w1cSo;D_hQtJs7W z><$QrmG^+<$4{d2bgGo&3-FV}avg9zI|Rr(k{wTyl3!M1q+a zD9W{pCd%il*j&Ft z5H$nENf>>k$;SONGW`qo6`&qKs*T z2^RS)pXk9b@(_Fw1bkb)-oqK|v}r$L!W&aXA>IpcdNZ_vWE#XO8X`#Yp1+?RshVcd zknG%rPd*4ECEI0wD#@d+3NbHKxl}n^Sgkx==Iu%}HvNliOqVBqG?P2va zQ;kRJ$J6j;+wP9cS za#m;#GUT!qAV%+rdWolk+)6kkz4@Yh5LXP+LSvo9_T+MmiaP-eq6_k;)i6_@WSJ zlT@wK$zqHu<83U2V*yJ|XJU4farT#pAA&@qu)(PO^8PxEmPD4;Txpio+2)#!9 z>&=i7*#tc0`?!==vk>s7V+PL#S1;PwSY?NIXN2=Gu89x(cToFm))7L;< z+bhAbVD*bD=}iU`+PU+SBobTQ%S!=VL!>q$rfWsaaV}Smz>lO9JXT#`CcH_mRCSf4%YQAw`$^yY z3Y*^Nzk_g$xn7a_NO(2Eb*I=^;4f!Ra#Oo~LLjlcjke*k*o$~U#0ZXOQ5@HQ&T46l z7504MUgZkz2gNP1QFN8Y?nSEnEai^Rgyvl}xZfMUV6QrJcXp;jKGqB=D*tj{8(_pV zqyB*DK$2lgYGejmJUW)*s_Cv65sFf&pb(Yz8oWgDtQ0~k^0-wdF|tj}MOXaN@ydF8 zNr={U?=;&Z?wr^VC+`)S2xl}QFagy;$mG=TUs7Vi2wws5zEke4hTa2)>O0U?$WYsZ z<8bN2bB_N4AWd%+kncgknZ&}bM~eDtj#C5uRkp21hWW5gxWvc6b*4+dn<{c?w9Rmf zIVZKsPl{W2vQAlYO3yh}-{Os=YBnL8?uN5(RqfQ=-1cOiUnJu>KcLA*tQK3FU`_bM zM^T28w;nAj5EdAXFi&Kk1Nnl2)D!M{@+D-}bIEe+Lc4{s;YJc-{F#``iS2uk;2!Zp zF9#myUmO!wCeJIoi^A+T^e~20c+c2C}XltaR!|U-HfDA=^xF97ev}$l6#oY z&-&T{egB)&aV$3_aVA51XGiU07$s9vubh_kQG?F$FycvS6|IO!6q zq^>9|3U^*!X_C~SxX&pqUkUjz%!j=VlXDo$!2VLH!rKj@61mDpSr~7B2yy{>X~_nc zRI+7g2V&k zd**H++P9dg!-AOs3;GM`(g<+GRV$+&DdMVpUxY9I1@uK28$az=6oaa+PutlO9?6#? zf-OsgT>^@8KK>ggkUQRPPgC7zjKFR5spqQb3ojCHzj^(UH~v+!y*`Smv)VpVoPwa6 zWG18WJaPKMi*F6Zdk*kU^`i~NNTfn3BkJniC`yN98L-Awd)Z&mY? zprBW$!qL-OL7h@O#kvYnLsfff@kDIegt~?{-*5A7JrA;#TmTe?jICJqhub-G@e??D zqiV#g{)M!kW1-4SDel7TO{;@*h2=_76g3NUD@|c*WO#>MfYq6_YVUP+&8e4|%4T`w zXzhmVNziAHazWO2qXcaOu@R1MrPP{t)`N)}-1&~mq=ZH=w=;-E$IOk=y$dOls{6sRR`I5>|X zpq~XYW4sd;J^6OwOf**J>a7u$S>WTFPRkjY;BfVgQst)u4aMLR1|6%)CB^18XCz+r ztkYQ}G43j~Q&1em(_EkMv0|WEiKu;z2zhb(L%$F&xWwzOmk;VLBYAZ8lOCziNoPw1 zv2BOyXA`A8z^WH!nXhKXM`t0;6D*-uGds3TYGrm8SPnJJOQ^fJU#}@aIy@MYWz**H zvkp?7I5PE{$$|~{-ZaFxr6ZolP^nL##mHOErB^AqJqn^hFA=)HWj!m3WDaHW$C)i^ z9@6G$SzB=>jbe>4kqr#sF7#K}W*Cg-5y6kun3u&0L7BpXF9=#7IN8FOjWrWwUBZiU zT_se3ih-GBKx+Uw0N|CwP3D@-C=5(9T#BH@M`F2!Goiqx+Js5xC92|Sy0%WWWp={$(am!#l~f^W_oz78HX<0X#7 zp)p1u~M*o9W@O8P{0Qkg@Wa# z2{Heb&oX^CQSZWSFBXKOfE|tsAm#^U-WkDnU;IowZ`Ok4!mwHwH=s|AqZ^YD4!5!@ zPxJj+Bd-q6w_YG`z_+r;S86zwXb+EO&qogOq8h-Ect5(M2+>(O7n7)^dP*ws_3U6v zVsh)sk^@*c>)3EML|0<-YROho{lz@Nd4;R9gL{9|64xVL`n!m$-Jjrx?-Bacp!=^5 z1^T^eB{_)Y<9)y{-4Rz@9_>;_7h;5D+@QcbF4Wv7hu)s0&==&6u)33 zHRj+&Woq-vDvjwJCYES@$C4{$?f$Ibi4G()UeN11rgjF+^;YE^5nYprYoJNoudNj= zm1pXSeG64dcWHObUetodRn1Fw|1nI$D9z}dVEYT0lQnsf_E1x2vBLql7NrHH!n&Sq z6lc*mvU=WS6=v9Lrl}&zRiu_6u;6g%_DU{9b+R z#YHqX7`m9eydf?KlKu6Sb%j$%_jmydig`B*TN`cZL-g!R)iE?+Q5oOqBFKhx z%MW>BC^(F_JuG(ayE(MT{S3eI{cKiwOtPwLc0XO*{*|(JOx;uQOfq@lp_^cZo=FZj z4#}@e@dJ>Bn%2`2_WPeSN7si^{U#H=7N4o%Dq3NdGybrZgEU$oSm$hC)uNDC_M9xc zGzwh5Sg?mpBIE8lT2XsqTt3j3?We8}3bzLBTQd639vyg^$0#1epq8snlDJP2(BF)K zSx30RM+{f+b$g{9usIL8H!hCO117Xgv}ttPJm9wVRjPk;ePH@zxv%j9k5`TzdXLeT zFgFX`V7cYIcBls5WN0Pf6SMBN+;CrQ(|EsFd*xtwr#$R{Z9FP`OWtyNsq#mCgZ7+P z^Yn$haBJ)r96{ZJd8vlMl?IBxrgh=fdq_NF!1{jARCVz>jNdC)H^wfy?R94#MPdUjcYX>#wEx+LB#P-#4S-%YH>t-j+w zOFTI8gX$ard6fAh&g=u&56%3^-6E2tpk*wx3HSCQ+t7+*iOs zPk5ysqE}i*cQocFvA68xHfL|iX(C4h*67@3|5Qwle(8wT&!&{8*{f%0(5gH+m>$tq zp;AqrP7?XTEooYG1Dzfxc>W%*CyL16q|fQ0_jp%%Bk^k!i#Nbi(N9&T>#M{gez_Ws zYK=l}adalV(nH}I_!hNeb;tQFk3BHX7N}}R8%pek^E`X}%ou=cx8InPU1EE0|Hen- zyw8MoJqB5=)Z%JXlrdTXAE)eqLAdVE-=>wGHrkRet}>3Yu^lt$Kzu%$3#(ioY}@Gu zjk3BZuQH&~7H+C*uX^4}F*|P89JX;Hg2U!pt>rDi(n(Qe-c}tzb0#6_ItoR0->LSt zR~UT<-|@TO%O`M+_e_J4wx7^)5_%%u+J=yF_S#2Xd?C;Ss3N7KY^#-vx+|;bJX&8r zD?|MetfhdC;^2WG`7MCgs>TKKN=^=!x&Q~BzmQio_^l~LboTNT=I zC5pme^P@ER``p$2md9>4!K#vV-Fc1an7pl>_|&>aqP}+zqR?+~Z;f2^`a+-!Te%V? z;H2SbF>jP^GE(R1@%C==XQ@J=G9lKX+Z<@5}PO(EYkJh=GCv#)Nj{DkWJM2}F&oAZ6xu8&g7pn1ps2U5srwQ7CAK zN&*~@t{`31lUf`O;2w^)M3B@o)_mbRu{-`PrfNpF!R^q>yTR&ETS7^-b2*{-tZAZz zw@q5x9B5V8Qd7dZ!Ai$9hk%Q!wqbE1F1c96&zwBBaRW}(^axoPpN^4Aw}&a5dMe+*Gomky_l^54*rzXro$ z>LL)U5Ry>~FJi=*{JDc)_**c)-&faPz`6v`YU3HQa}pLtb5K)u%K+BOqXP0)rj5Au$zB zW1?vr?mDv7Fsxtsr+S6ucp2l#(4dnr9sD*v+@*>g#M4b|U?~s93>Pg{{a5|rm2xfI z`>E}?9S@|IoUX{Q1zjm5YJT|3S>&09D}|2~BiMo=z4YEjXlWh)V&qs;*C{`UMxp$9 zX)QB?G$fPD6z5_pNs>Jeh{^&U^)Wbr?2D6-q?)`*1k@!UvwQgl8eG$r+)NnFoT)L6 zg7lEh+E6J17krfYJCSjWzm67hEth24pomhz71|Qodn#oAILN)*Vwu2qpJirG)4Wnv}9GWOFrQg%Je+gNrPl8mw7ykE8{ z=|B4+uwC&bpp%eFcRU6{mxRV32VeH8XxX>v$du<$(DfinaaWxP<+Y97Z#n#U~V zVEu-GoPD=9$}P;xv+S~Ob#mmi$JQmE;Iz4(){y*9pFyW-jjgdk#oG$fl4o9E8bo|L zWjo4l%n51@Kz-n%zeSCD`uB?T%FVk+KBI}=ve zvlcS#wt`U6wrJo}6I6Rwb=1GzZfwE=I&Ne@p7*pH84XShXYJRgvK)UjQL%R9Zbm(m zxzTQsLTON$WO7vM)*vl%Pc0JH7WhP;$z@j=y#avW4X8iqy6mEYr@-}PW?H)xfP6fQ z&tI$F{NNct4rRMSHhaelo<5kTYq+(?pY)Ieh8*sa83EQfMrFupMM@nfEV@EmdHUv9 z35uzIrIuo4#WnF^_jcpC@uNNaYTQ~uZWOE6P@LFT^1@$o&q+9Qr8YR+ObBkpP9=F+$s5+B!mX2~T zAuQ6RenX?O{IlLMl1%)OK{S7oL}X%;!XUxU~xJN8xk z`xywS*naF(J#?vOpB(K=o~lE;m$zhgPWDB@=p#dQIW>xe_p1OLoWInJRKbEuoncf; zmS1!u-ycc1qWnDg5Nk2D)BY%jmOwCLC+Ny>`f&UxFowIsHnOXfR^S;&F(KXd{ODlm z$6#1ccqt-HIH9)|@fHnrKudu!6B$_R{fbCIkSIb#aUN|3RM>zuO>dpMbROZ`^hvS@ z$FU-;e4W}!ubzKrU@R*dW*($tFZ>}dd*4_mv)#O>X{U@zSzQt*83l9mI zI$8O<5AIDx`wo0}f2fsPC_l>ONx_`E7kdXu{YIZbp1$(^oBAH({T~&oQ&1{X951QW zmhHUxd)t%GQ9#ak5fTjk-cahWC;>^Rg7(`TVlvy0W@Y!Jc%QL3Ozu# zDPIqBCy&T2PWBj+d-JA-pxZlM=9ja2ce|3B(^VCF+a*MMp`(rH>Rt6W1$;r{n1(VK zLs>UtkT43LR2G$AOYHVailiqk7naz2yZGLo*xQs!T9VN5Q>eE(w zw$4&)&6xIV$IO^>1N-jrEUg>O8G4^@y+-hQv6@OmF@gy^nL_n1P1-Rtyy$Bl;|VcV zF=p*&41-qI5gG9UhKmmnjs932!6hceXa#-qfK;3d*a{)BrwNFeKU|ge?N!;zk+kB! zMD_uHJR#%b54c2tr~uGPLTRLg$`fupo}cRJeTwK;~}A>(Acy4k-Xk&Aa1&eWYS1ULWUj@fhBiWY$pdfy+F z@G{OG{*v*mYtH3OdUjwEr6%_ZPZ3P{@rfbNPQG!BZ7lRyC^xlMpWH`@YRar`tr}d> z#wz87t?#2FsH-jM6m{U=gp6WPrZ%*w0bFm(T#7m#v^;f%Z!kCeB5oiF`W33W5Srdt zdU?YeOdPG@98H7NpI{(uN{FJdu14r(URPH^F6tOpXuhU7T9a{3G3_#Ldfx_nT(Hec zo<1dyhsVsTw;ZkVcJ_0-h-T3G1W@q)_Q30LNv)W?FbMH+XJ* zy=$@39Op|kZv`Rt>X`zg&at(?PO^I=X8d9&myFEx#S`dYTg1W+iE?vt#b47QwoHI9 zNP+|3WjtXo{u}VG(lLUaW0&@yD|O?4TS4dfJI`HC-^q;M(b3r2;7|FONXphw-%7~* z&;2!X17|05+kZOpQ3~3!Nb>O94b&ZSs%p)TK)n3m=4eiblVtSx@KNFgBY_xV6ts;NF;GcGxMP8OKV^h6LmSb2E#Qnw ze!6Mnz7>lE9u{AgQ~8u2zM8CYD5US8dMDX-5iMlgpE9m*s+Lh~A#P1er*rF}GHV3h z=`STo?kIXw8I<`W0^*@mB1$}pj60R{aJ7>C2m=oghKyxMbFNq#EVLgP0cH3q7H z%0?L93-z6|+jiN|@v>ix?tRBU(v-4RV`}cQH*fp|)vd3)8i9hJ3hkuh^8dz{F5-~_ zUUr1T3cP%cCaTooM8dj|4*M=e6flH0&8ve32Q)0dyisl))XkZ7Wg~N}6y`+Qi2l+e zUd#F!nJp{#KIjbQdI`%oZ`?h=5G^kZ_uN`<(`3;a!~EMsWV|j-o>c?x#;zR2ktiB! z);5rrHl?GPtr6-o!tYd|uK;Vbsp4P{v_4??=^a>>U4_aUXPWQ$FPLE4PK$T^3Gkf$ zHo&9$U&G`d(Os6xt1r?sg14n)G8HNyWa^q8#nf0lbr4A-Fi;q6t-`pAx1T*$eKM*$ z|CX|gDrk#&1}>5H+`EjV$9Bm)Njw&7-ZR{1!CJTaXuP!$Pcg69`{w5BRHysB$(tWUes@@6aM69kb|Lx$%BRY^-o6bjH#0!7b;5~{6J+jKxU!Kmi# zndh@+?}WKSRY2gZ?Q`{(Uj|kb1%VWmRryOH0T)f3cKtG4oIF=F7RaRnH0Rc_&372={_3lRNsr95%ZO{IX{p@YJ^EI%+gvvKes5cY+PE@unghjdY5#9A!G z70u6}?zmd?v+{`vCu-53_v5@z)X{oPC@P)iA3jK$`r zSA2a7&!^zmUiZ82R2=1cumBQwOJUPz5Ay`RLfY(EiwKkrx%@YN^^XuET;tE zmr-6~I7j!R!KrHu5CWGSChO6deaLWa*9LLJbcAJsFd%Dy>a!>J`N)Z&oiU4OEP-!Ti^_!p}O?7`}i7Lsf$-gBkuY*`Zb z7=!nTT;5z$_5$=J=Ko+Cp|Q0J=%oFr>hBgnL3!tvFoLNhf#D0O=X^h+x08iB;@8pXdRHxX}6R4k@i6%vmsQwu^5z zk1ip`#^N)^#Lg#HOW3sPI33xqFB4#bOPVnY%d6prwxf;Y-w9{ky4{O6&94Ra8VN@K zb-lY;&`HtxW@sF!doT5T$2&lIvJpbKGMuDAFM#!QPXW87>}=Q4J3JeXlwHys?!1^#37q_k?N@+u&Ns20pEoBeZC*np;i;M{2C0Z4_br2gsh6eL z#8`#sn41+$iD?^GL%5?cbRcaa-Nx0vE(D=*WY%rXy3B%gNz0l?#noGJGP728RMY#q z=2&aJf@DcR?QbMmN)ItUe+VM_U!ryqA@1VVt$^*xYt~-qvW!J4Tp<-3>jT=7Zow5M z8mSKp0v4b%a8bxFr>3MwZHSWD73D@+$5?nZAqGM#>H@`)mIeC#->B)P8T$zh-Pxnc z8)~Zx?TWF4(YfKuF3WN_ckpCe5;x4V4AA3(i$pm|78{%!q?|~*eH0f=?j6i)n~Hso zmTo>vqEtB)`%hP55INf7HM@taH)v`Fw40Ayc*R!T?O{ziUpYmP)AH`euTK!zg9*6Z z!>M=$3pd0!&TzU=hc_@@^Yd3eUQpX4-33}b{?~5t5lgW=ldJ@dUAH%`l5US1y_`40 zs(X`Qk}vvMDYYq+@Rm+~IyCX;iD~pMgq^KY)T*aBz@DYEB={PxA>)mI6tM*sx-DmGQHEaHwRrAmNjO!ZLHO4b;;5mf@zzlPhkP($JeZGE7 z?^XN}Gf_feGoG~BjUgVa*)O`>lX=$BSR2)uD<9 z>o^|nb1^oVDhQbfW>>!;8-7<}nL6L^V*4pB=>wwW+RXAeRvKED(n1;R`A6v$6gy0I(;Vf?!4;&sgn7F%LpM}6PQ?0%2Z@b{It<(G1CZ|>913E0nR2r^Pa*Bp z@tFGi*CQ~@Yc-?{cwu1 zsilf=k^+Qs>&WZG(3WDixisHpR>`+ihiRwkL(3T|=xsoNP*@XX3BU8hr57l3k;pni zI``=3Nl4xh4oDj<%>Q1zYXHr%Xg_xrK3Nq?vKX3|^Hb(Bj+lONTz>4yhU-UdXt2>j z<>S4NB&!iE+ao{0Tx^N*^|EZU;0kJkx@zh}S^P{ieQjGl468CbC`SWnwLRYYiStXm zOxt~Rb3D{dz=nHMcY)#r^kF8|q8KZHVb9FCX2m^X*(|L9FZg!5a7((!J8%MjT$#Fs)M1Pb zq6hBGp%O1A+&%2>l0mpaIzbo&jc^!oN^3zxap3V2dNj3x<=TwZ&0eKX5PIso9j1;e zwUg+C&}FJ`k(M|%%}p=6RPUq4sT3-Y;k-<68ciZ~_j|bt>&9ZLHNVrp#+pk}XvM{8 z`?k}o-!if>hVlCP9j%&WI2V`5SW)BCeR5>MQhF)po=p~AYN%cNa_BbV6EEh_kk^@a zD>4&>uCGCUmyA-c)%DIcF4R6!>?6T~Mj_m{Hpq`*(wj>foHL;;%;?(((YOxGt)Bhx zuS+K{{CUsaC++%}S6~CJ=|vr(iIs-je)e9uJEU8ZJAz)w166q)R^2XI?@E2vUQ!R% zn@dxS!JcOimXkWJBz8Y?2JKQr>`~SmE2F2SL38$SyR1^yqj8_mkBp)o$@+3BQ~Mid z9U$XVqxX3P=XCKj0*W>}L0~Em`(vG<>srF8+*kPrw z20{z(=^w+ybdGe~Oo_i|hYJ@kZl*(9sHw#Chi&OIc?w`nBODp?ia$uF%Hs(X>xm?j zqZQ`Ybf@g#wli`!-al~3GWiE$K+LCe=Ndi!#CVjzUZ z!sD2O*;d28zkl))m)YN7HDi^z5IuNo3^w(zy8 zszJG#mp#Cj)Q@E@r-=NP2FVxxEAeOI2e=|KshybNB6HgE^(r>HD{*}S}mO>LuRGJT{*tfTzw_#+er-0${}%YPe@CMJ1Ng#j#)i)SnY@ss3gL;g zg2D~#Kpdfu#G;q1qz_TwSz1VJT(b3zby$Vk&;Y#1(A)|xj`_?i5YQ;TR%jice5E;0 zYHg;`zS5{S*9xI6o^j>rE8Ua*XhIw{_-*&@(R|C(am8__>+Ws&Q^ymy*X4~hR2b5r zm^p3sw}yv=tdyncy_Ui7{BQS732et~Z_@{-IhHDXAV`(Wlay<#hb>%H%WDi+K$862nA@BDtM#UCKMu+kM`!JHyWSi?&)A7_ z3{cyNG%a~nnH_!+;g&JxEMAmh-Z}rC!o7>OVzW&PoMyTA_g{hqXG)SLraA^OP**<7 zjWbr7z!o2n3hnx7A=2O=WL;`@9N{vQIM@&|G-ljrPvIuJHYtss0Er0fT5cMXNUf1B z7FAwBDixt0X7C3S)mPe5g`YtME23wAnbU)+AtV}z+e8G;0BP=bI;?(#|Ep!vVfDbK zvx+|CKF>yt0hWQ3drchU#XBU+HiuG*V^snFAPUp-5<#R&BUAzoB!aZ+e*KIxa26V}s6?nBK(U-7REa573wg-jqCg>H8~>O{ z*C0JL-?X-k_y%hpUFL?I>0WV{oV`Nb)nZbJG01R~AG>flIJf)3O*oB2i8~;!P?Wo_ z0|QEB*fifiL6E6%>tlAYHm2cjTFE@*<);#>689Z6S#BySQ@VTMhf9vYQyLeDg1*F} zjq>i1*x>5|CGKN{l9br3kB0EHY|k4{%^t7-uhjd#NVipUZa=EUuE5kS1_~qYX?>hJ z$}!jc9$O$>J&wnu0SgfYods^z?J4X;X7c77Me0kS-dO_VUQ39T(Kv(Y#s}Qqz-0AH z^?WRL(4RzpkD+T5FG_0NyPq-a-B7A5LHOCqwObRJi&oRi(<;OuIN7SV5PeHU$<@Zh zPozEV`dYmu0Z&Tqd>t>8JVde9#Pt+l95iHe$4Xwfy1AhI zDM4XJ;bBTTvRFtW>E+GzkN)9k!hA5z;xUOL2 zq4}zn-DP{qc^i|Y%rvi|^5k-*8;JZ~9a;>-+q_EOX+p1Wz;>i7c}M6Nv`^NY&{J-> z`(mzDJDM}QPu5i44**2Qbo(XzZ-ZDu%6vm8w@DUarqXj41VqP~ zs&4Y8F^Waik3y1fQo`bVUH;b=!^QrWb)3Gl=QVKr+6sxc=ygauUG|cm?|X=;Q)kQ8 zM(xrICifa2p``I7>g2R~?a{hmw@{!NS5`VhH8+;cV(F>B94M*S;5#O`YzZH1Z%yD? zZ61w(M`#aS-*~Fj;x|J!KM|^o;MI#Xkh0ULJcA?o4u~f%Z^16ViA27FxU5GM*rKq( z7cS~MrZ=f>_OWx8j#-Q3%!aEU2hVuTu(7`TQk-Bi6*!<}0WQi;_FpO;fhpL4`DcWp zGOw9vx0N~6#}lz(r+dxIGZM3ah-8qrqMmeRh%{z@dbUD2w15*_4P?I~UZr^anP}DB zU9CCrNiy9I3~d#&!$DX9e?A});BjBtQ7oGAyoI$8YQrkLBIH@2;lt4E^)|d6Jwj}z z&2_E}Y;H#6I4<10d_&P0{4|EUacwFHauvrjAnAm6yeR#}f}Rk27CN)vhgRqEyPMMS7zvunj2?`f;%?alsJ+-K+IzjJx>h8 zu~m_y$!J5RWAh|C<6+uiCNsOKu)E72M3xKK(a9Okw3e_*O&}7llNV!=P87VM2DkAk zci!YXS2&=P0}Hx|wwSc9JP%m8dMJA*q&VFB0yMI@5vWoAGraygwn){R+Cj6B1a2Px z5)u(K5{+;z2n*_XD!+Auv#LJEM)(~Hx{$Yb^ldQmcYF2zNH1V30*)CN_|1$v2|`LnFUT$%-tO0Eg|c5$BB~yDfzS zcOXJ$wpzVK0MfTjBJ0b$r#_OvAJ3WRt+YOLlJPYMx~qp>^$$$h#bc|`g0pF-Ao43? z>*A+8lx>}L{p(Tni2Vvk)dtzg$hUKjSjXRagj)$h#8=KV>5s)J4vGtRn5kP|AXIz! zPgbbVxW{2o4s-UM;c#We8P&mPN|DW7_uLF!a|^0S=wr6Esx9Z$2|c1?GaupU6$tb| zY_KU`(_29O_%k(;>^|6*pZURH3`@%EuKS;Ns z1lujmf;r{qAN&Q0&m{wJSZ8MeE7RM5+Sq;ul_ z`+ADrd_Um+G37js6tKsArNB}n{p*zTUxQr>3@wA;{EUbjNjlNd6$Mx zg0|MyU)v`sa~tEY5$en7^PkC=S<2@!nEdG6L=h(vT__0F=S8Y&eM=hal#7eM(o^Lu z2?^;05&|CNliYrq6gUv;|i!(W{0N)LWd*@{2q*u)}u*> z7MQgk6t9OqqXMln?zoMAJcc zMKaof_Up})q#DzdF?w^%tTI7STI^@8=Wk#enR*)&%8yje>+tKvUYbW8UAPg55xb70 zEn5&Ba~NmOJlgI#iS8W3-@N%>V!#z-ZRwfPO1)dQdQkaHsiqG|~we2ALqG7Ruup(DqSOft2RFg_X%3w?6VqvV1uzX_@F(diNVp z4{I|}35=11u$;?|JFBEE*gb;T`dy+8gWJ9~pNsecrO`t#V9jW-6mnfO@ff9od}b(3s4>p0i30gbGIv~1@a^F2kl7YO;DxmF3? zWi-RoXhzRJV0&XE@ACc?+@6?)LQ2XNm4KfalMtsc%4!Fn0rl zpHTrHwR>t>7W?t!Yc{*-^xN%9P0cs0kr=`?bQ5T*oOo&VRRu+1chM!qj%2I!@+1XF z4GWJ=7ix9;Wa@xoZ0RP`NCWw0*8247Y4jIZ>GEW7zuoCFXl6xIvz$ezsWgKdVMBH> z{o!A7f;R-@eK9Vj7R40xx)T<2$?F2E<>Jy3F;;=Yt}WE59J!1WN367 zA^6pu_zLoZIf*x031CcwotS{L8bJE(<_F%j_KJ2P_IusaZXwN$&^t716W{M6X2r_~ zaiMwdISX7Y&Qi&Uh0upS3TyEIXNDICQlT5fHXC`aji-c{U(J@qh-mWl-uMN|T&435 z5)a1dvB|oe%b2mefc=Vpm0C%IUYYh7HI*;3UdgNIz}R##(#{(_>82|zB0L*1i4B5j-xi9O4x10rs_J6*gdRBX=@VJ+==sWb&_Qc6tSOowM{BX@(zawtjl zdU!F4OYw2@Tk1L^%~JCwb|e#3CC>srRHQ*(N%!7$Mu_sKh@|*XtR>)BmWw!;8-mq7 zBBnbjwx8Kyv|hd*`5}84flTHR1Y@@uqjG`UG+jN_YK&RYTt7DVwfEDXDW4U+iO{>K zw1hr{_XE*S*K9TzzUlJH2rh^hUm2v7_XjwTuYap|>zeEDY$HOq3X4Tz^X}E9z)x4F zs+T?Ed+Hj<#jY-`Va~fT2C$=qFT-5q$@p9~0{G&eeL~tiIAHXA!f6C(rAlS^)&k<- zXU|ZVs}XQ>s5iONo~t!XXZgtaP$Iau;JT%h)>}v54yut~pykaNye4axEK#5@?TSsQ zE;Jvf9I$GVb|S`7$pG)4vgo9NXsKr?u=F!GnA%VS2z$@Z(!MR9?EPcAqi5ft)Iz6sNl`%kj+_H-X`R<>BFrBW=fSlD|{`D%@Rcbu2?%>t7i34k?Ujb)2@J-`j#4 zLK<69qcUuniIan-$A1+fR=?@+thwDIXtF1Tks@Br-xY zfB+zblrR(ke`U;6U~-;p1Kg8Lh6v~LjW@9l2P6s+?$2!ZRPX`(ZkRGe7~q(4&gEi<$ch`5kQ?*1=GSqkeV z{SA1EaW_A!t{@^UY2D^YO0(H@+kFVzZaAh0_`A`f(}G~EP~?B|%gtxu&g%^x{EYSz zk+T;_c@d;+n@$<>V%P=nk36?L!}?*=vK4>nJSm+1%a}9UlmTJTrfX4{Lb7smNQn@T zw9p2%(Zjl^bWGo1;DuMHN(djsEm)P8mEC2sL@KyPjwD@d%QnZ$ zMJ3cnn!_!iP{MzWk%PI&D?m?C(y2d|2VChluN^yHya(b`h>~GkI1y;}O_E57zOs!{ zt2C@M$^PR2U#(dZmA-sNreB@z-yb0Bf7j*yONhZG=onhx>t4)RB`r6&TP$n zgmN*)eCqvgriBO-abHQ8ECN0bw?z5Bxpx z=jF@?zFdVn?@gD5egM4o$m`}lV(CWrOKKq(sv*`mNcHcvw&Xryfw<{ch{O&qc#WCTXX6=#{MV@q#iHYba!OUY+MGeNTjP%Fj!WgM&`&RlI^=AWTOqy-o zHo9YFt!gQ*p7{Fl86>#-JLZo(b^O`LdFK~OsZBRR@6P?ad^Ujbqm_j^XycM4ZHFyg ziUbIFW#2tj`65~#2V!4z7DM8Z;fG0|APaQ{a2VNYpNotB7eZ5kp+tPDz&Lqs0j%Y4tA*URpcfi z_M(FD=fRGdqf430j}1z`O0I=;tLu81bwJXdYiN7_&a-?ly|-j*+=--XGvCq#32Gh(=|qj5F?kmihk{%M&$}udW5)DHK zF_>}5R8&&API}o0osZJRL3n~>76nUZ&L&iy^s>PMnNcYZ|9*1$v-bzbT3rpWsJ+y{ zPrg>5Zlery96Um?lc6L|)}&{992{_$J&=4%nRp9BAC6!IB=A&=tF>r8S*O-=!G(_( zwXbX_rGZgeiK*&n5E;f=k{ktyA1(;x_kiMEt0*gpp_4&(twlS2e5C?NoD{n>X2AT# zY@Zp?#!b1zNq96MQqeO*M1MMBin5v#RH52&Xd~DO6-BZLnA6xO1$sou(YJ1Dlc{WF zVa%2DyYm`V#81jP@70IJ;DX@y*iUt$MLm)ByAD$eUuji|5{ptFYq(q)mE(5bOpxjM z^Q`AHWq44SG3`_LxC9fwR)XRVIp=B%<(-lOC3jI#bb@dK(*vjom!=t|#<@dZql%>O z15y^{4tQoeW9Lu%G&V$90x6F)xN6y_oIn;!Q zs)8jT$;&;u%Y>=T3hg34A-+Y*na=|glcStr5D;&5*t5*DmD~x;zQAV5{}Ya`?RRGa zT*t9@$a~!co;pD^!J5bo?lDOWFx%)Y=-fJ+PDGc0>;=q=s?P4aHForSB+)v0WY2JH z?*`O;RHum6j%#LG)Vu#ciO#+jRC3!>T(9fr+XE7T2B7Z|0nR5jw@WG)kDDzTJ=o4~ zUpeyt7}_nd`t}j9BKqryOha{34erm)RmST)_9Aw)@ zHbiyg5n&E{_CQR@h<}34d7WM{s{%5wdty1l+KX8*?+-YkNK2Be*6&jc>@{Fd;Ps|| z26LqdI3#9le?;}risDq$K5G3yoqK}C^@-8z^wj%tdgw-6@F#Ju{Sg7+y)L?)U$ez> zoOaP$UFZ?y5BiFycir*pnaAaY+|%1%8&|(@VB)zweR%?IidwJyK5J!STzw&2RFx zZV@qeaCB01Hu#U9|1#=Msc8Pgz5P*4Lrp!Q+~(G!OiNR{qa7|r^H?FC6gVhkk3y7=uW#Sh;&>78bZ}aK*C#NH$9rX@M3f{nckYI+5QG?Aj1DM)@~z_ zw!UAD@gedTlePB*%4+55naJ8ak_;))#S;4ji!LOqY5VRI){GMwHR~}6t4g>5C_#U# ztYC!tjKjrKvRy=GAsJVK++~$|+s!w9z3H4G^mACv=EErXNSmH7qN}%PKcN|8%9=i)qS5+$L zu&ya~HW%RMVJi4T^pv?>mw*Gf<)-7gf#Qj|e#w2|v4#t!%Jk{&xlf;$_?jW*n!Pyx zkG$<18kiLOAUPuFfyu-EfWX%4jYnjBYc~~*9JEz6oa)_R|8wjZA|RNrAp%}14L7fW zi7A5Wym*K+V8pkqqO-X#3ft{0qs?KVt^)?kS>AicmeO&q+~J~ zp0YJ_P~_a8j= zsAs~G=8F=M{4GZL{|B__UorX@MRNQLn?*_gym4aW(~+i13knnk1P=khoC-ViMZk+x zLW(l}oAg1H`dU+Fv**;qw|ANDSRs>cGqL!Yw^`; zv;{E&8CNJcc)GHzTYM}f&NPw<6j{C3gaeelU#y!M)w-utYEHOCCJo|Vgp7K6C_$14 zqIrLUB0bsgz^D%V%fbo2f9#yb#CntTX?55Xy|Kps&Xek*4_r=KDZ z+`TQuv|$l}MWLzA5Ay6Cvsa^7xvwXpy?`w(6vx4XJ zWuf1bVSb#U8{xlY4+wlZ$9jjPk)X_;NFMqdgq>m&W=!KtP+6NL57`AMljW+es zzqjUjgz;V*kktJI?!NOg^s_)ph45>4UDA!Vo0hn>KZ+h-3=?Y3*R=#!fOX zP$Y~+14$f66ix?UWB_6r#fMcC^~X4R-<&OD1CSDNuX~y^YwJ>sW0j`T<2+3F9>cLo z#!j57$ll2K9(%$4>eA7(>FJX5e)pR5&EZK!IMQzOfik#FU*o*LGz~7u(8}XzIQRy- z!U7AlMTIe|DgQFmc%cHy_9^{o`eD%ja_L>ckU6$O4*U**o5uR7`FzqkU8k4gxtI=o z^P^oGFPm5jwZMI{;nH}$?p@uV8FT4r=|#GziKXK07bHJLtK}X%I0TON$uj(iJ`SY^ zc$b2CoxCQ>7LH@nxcdW&_C#fMYBtTxcg46dL{vf%EFCZ~eErMvZq&Z%Lhumnkn^4A zsx$ay(FnN7kYah}tZ@0?-0Niroa~13`?hVi6`ndno`G+E8;$<6^gsE-K3)TxyoJ4M zb6pj5=I8^FD5H@`^V#Qb2^0cx7wUz&cruA5g>6>qR5)O^t1(-qqP&1g=qvY#s&{bx zq8Hc%LsbK1*%n|Y=FfojpE;w~)G0-X4i*K3{o|J7`krhIOd*c*$y{WIKz2n2*EXEH zT{oml3Th5k*vkswuFXdGDlcLj15Nec5pFfZ*0?XHaF_lVuiB%Pv&p7z)%38}%$Gup zVTa~C8=cw%6BKn_|4E?bPNW4PT7}jZQLhDJhvf4z;~L)506IE0 zX!tWXX(QOQPRj-p80QG79t8T2^az4Zp2hOHziQlvT!|H)jv{Ixodabzv6lBj)6WRB z{)Kg@$~~(7$-az?lw$4@L%I&DI0Lo)PEJJziWP33a3azb?jyXt1v0N>2kxwA6b%l> zZqRpAo)Npi&loWbjFWtEV)783BbeIAhqyuc+~>i7aQ8shIXt)bjCWT6$~ro^>99G} z2XfmT0(|l!)XJb^E!#3z4oEGIsL(xd; zYX1`1I(cG|u#4R4T&C|m*9KB1`UzKvho5R@1eYtUL9B72{i(ir&ls8g!pD ztR|25xGaF!4z5M+U@@lQf(12?xGy`!|3E}7pI$k`jOIFjiDr{tqf0va&3pOn6Pu)% z@xtG2zjYuJXrV)DUrIF*y<1O1<$#54kZ#2;=X51J^F#0nZ0(;S$OZDt_U2bx{RZ=Q zMMdd$fH|!s{ zXq#l;{`xfV`gp&C>A`WrQU?d{!Ey5(1u*VLJt>i27aZ-^&2IIk=zP5p+{$q(K?2(b z8?9h)kvj9SF!Dr zoyF}?V|9;6abHxWk2cEvGs$-}Pg}D+ZzgkaN&$Snp%;5m%zh1E#?Wac-}x?BYlGN#U#Mek*}kek#I9XaHt?mz3*fDrRTQ#&#~xyeqJk1QJ~E$7qsw6 z?sV;|?*=-{M<1+hXoj?@-$y+(^BJ1H~wQ9G8C0#^aEAyhDduNX@haoa=PuPp zYsGv8UBfQaRHgBgLjmP^eh>fLMeh{8ic)?xz?#3kX-D#Z{;W#cd_`9OMFIaJg-=t`_3*!YDgtNQ2+QUEAJB9M{~AvT$H`E)IKmCR21H532+ata8_i_MR@ z2Xj<3w<`isF~Ah$W{|9;51ub*f4#9ziKrOR&jM{x7I_7()O@`F*5o$KtZ?fxU~g`t zUovNEVKYn$U~VX8eR)qb`7;D8pn*Pp$(otYTqL)5KH$lUS-jf}PGBjy$weoceAcPp z&5ZYB$r&P$MN{0H0AxCe4Qmd3T%M*5d4i%#!nmBCN-WU-4m4Tjxn-%j3HagwTxCZ9 z)j5vO-C7%s%D!&UfO>bi2oXiCw<-w{vVTK^rVbv#W=WjdADJy8$khnU!`ZWCIU`># zyjc^1W~pcu>@lDZ{zr6gv%)2X4n27~Ve+cQqcND%0?IFSP4sH#yIaXXYAq^z3|cg` z`I3$m%jra>e2W-=DiD@84T!cb%||k)nPmEE09NC%@PS_OLhkrX*U!cgD*;;&gIaA(DyVT4QD+q_xu z>r`tg{hiGY&DvD-)B*h+YEd+Zn)WylQl}<4>(_NlsKXCRV;a)Rcw!wtelM2_rWX`j zTh5A|i6=2BA(iMCnj_fob@*eA;V?oa4Z1kRBGaU07O70fb6-qmA$Hg$ps@^ka1=RO zTbE_2#)1bndC3VuK@e!Sftxq4=Uux}fDxXE#Q5_x=E1h>T5`DPHz zbH<_OjWx$wy7=%0!mo*qH*7N4tySm+R0~(rbus`7;+wGh;C0O%x~fEMkt!eV>U$`i z5>Q(o z=t$gPjgGh0&I7KY#k50V7DJRX<%^X z>6+ebc9efB3@eE2Tr){;?_w`vhgF>`-GDY(YkR{9RH(MiCnyRtd!LxXJ75z+?2 zGi@m^+2hKJ5sB1@Xi@s_@p_Kwbc<*LQ_`mr^Y%j}(sV_$`J(?_FWP)4NW*BIL~sR>t6 zM;qTJZ~GoY36&{h-Pf}L#y2UtR}>ZaI%A6VkU>vG4~}9^i$5WP2Tj?Cc}5oQxe2=q z8BeLa$hwCg_psjZyC2+?yX4*hJ58Wu^w9}}7X*+i5Rjqu5^@GzXiw#SUir1G1`jY% zOL=GE_ENYxhcyUrEt9XlMNP6kx6h&%6^u3@zB8KUCAa18T(R2J`%JjWZ z!{7cXaEW+Qu*iJPu+m>QqW}Lo$4Z+!I)0JNzZ&_M%=|B1yejFRM04bGAvu{=lNPd+ zJRI^DRQ(?FcVUD+bgEcAi@o(msqys9RTCG#)TjI!9~3-dc`>gW;HSJuQvH~d`MQs86R$|SKXHh zqS9Qy)u;T`>>a!$LuaE2keJV%;8g)tr&Nnc;EkvA-RanHXsy)D@XN0a>h}z2j81R; zsUNJf&g&rKpuD0WD@=dDrPHdBoK42WoBU|nMo17o(5^;M|dB4?|FsAGVrSyWcI`+FVw^vTVC`y}f(BwJl zrw3Sp151^9=}B})6@H*i4-dIN_o^br+BkcLa^H56|^2XsT0dESw2 zMX>(KqNl=x2K5=zIKg}2JpGAZu{I_IO}0$EQ5P{4zol**PCt3F4`GX}2@vr8#Y)~J zKb)gJeHcFnR@4SSh%b;c%J`l=W*40UPjF#q{<}ywv-=vHRFmDjv)NtmC zQx9qm)d%0zH&qG7AFa3VAU1S^(n8VFTC~Hb+HjYMjX8r#&_0MzlNR*mnLH5hi}`@{ zK$8qiDDvS_(L9_2vHgzEQ${DYSE;DqB!g*jhJghE&=LTnbgl&Xepo<*uRtV{2wDHN z)l;Kg$TA>Y|K8Lc&LjWGj<+bp4Hiye_@BfU(y#nF{fpR&|Ltbye?e^j0}8JC4#xi% zv29ZR%8%hk=3ZDvO-@1u8KmQ@6p%E|dlHuy#H1&MiC<*$YdLkHmR#F3ae;bKd;@*i z2_VfELG=B}JMLCO-6UQy^>RDE%K4b>c%9ki`f~Z2Qu8hO7C#t%Aeg8E%+}6P7Twtg z-)dj(w}_zFK&86KR@q9MHicUAucLVshUdmz_2@32(V`y3`&Kf8Q2I)+!n0mR=rrDU zXvv^$ho;yh*kNqJ#r1}b0|i|xRUF6;lhx$M*uG3SNLUTC@|htC z-=fsw^F%$qqz4%QdjBrS+ov}Qv!z00E+JWas>p?z@=t!WWU3K*?Z(0meTuTOC7OTx zU|kFLE0bLZ+WGcL$u4E}5dB0g`h|uwv3=H6f+{5z9oLv-=Q45+n~V4WwgO=CabjM% zBAN+RjM65(-}>Q2V#i1Na@a0`08g&y;W#@sBiX6Tpy8r}*+{RnyGUT`?XeHSqo#|J z^ww~c;ou|iyzpErDtlVU=`8N7JSu>4M z_pr9=tX0edVn9B}YFO2y(88j#S{w%E8vVOpAboK*27a7e4Ekjt0)hIX99*1oE;vex z7#%jhY=bPijA=Ce@9rRO(Vl_vnd00!^TAc<+wVvRM9{;hP*rqEL_(RzfK$er_^SN; z)1a8vo8~Dr5?;0X0J62Cusw$A*c^Sx1)dom`-)Pl7hsW4i(r*^Mw`z5K>!2ixB_mu z*Ddqjh}zceRFdmuX1akM1$3>G=#~|y?eYv(e-`Qy?bRHIq=fMaN~fB zUa6I8Rt=)jnplP>yuS+P&PxeWpJ#1$F`iqRl|jF$WL_aZFZl@kLo&d$VJtu&w?Q0O zzuXK>6gmygq(yXJy0C1SL}T8AplK|AGNUOhzlGeK_oo|haD@)5PxF}rV+5`-w{Aag zus45t=FU*{LguJ11Sr-28EZkq;!mJO7AQGih1L4rEyUmp>B!%X0YemsrV3QFvlgt* z5kwlPzaiJ+kZ^PMd-RRbl(Y?F*m`4*UIhIuf#8q>H_M=fM*L_Op-<_r zBZagV=4B|EW+KTja?srADTZXCd3Yv%^Chfpi)cg{ED${SI>InNpRj5!euKv?=Xn92 zsS&FH(*w`qLIy$doc>RE&A5R?u zzkl1sxX|{*fLpXvIW>9d<$ePROttn3oc6R!sN{&Y+>Jr@yeQN$sFR z;w6A<2-0%UA?c8Qf;sX7>>uKRBv3Ni)E9pI{uVzX|6Bb0U)`lhLE3hK58ivfRs1}d zNjlGK0hdq0qjV@q1qI%ZFMLgcpWSY~mB^LK)4GZ^h_@H+3?dAe_a~k*;9P_d7%NEFP6+ zgV(oGr*?W(ql?6SQ~`lUsjLb%MbfC4V$)1E0Y_b|OIYxz4?O|!kRb?BGrgiH5+(>s zoqM}v*;OBfg-D1l`M6T6{K`LG+0dJ1)!??G5g(2*vlNkm%Q(MPABT$r13q?|+kL4- zf)Mi5r$sn;u41aK(K#!m+goyd$c!KPl~-&-({j#D4^7hQkV3W|&>l_b!}!z?4($OA z5IrkfuT#F&S1(`?modY&I40%gtroig{YMvF{K{>5u^I51k8RriGd${z)=5k2tG zM|&Bp5kDTfb#vfuTTd?)a=>bX=lokw^y9+2LS?kwHQIWI~pYgy7 zb?A-RKVm_vM5!9?C%qYdfRAw& zAU7`up~%g=p@}pg#b7E)BFYx3g%(J36Nw(Dij!b>cMl@CSNbrW!DBDbTD4OXk!G4x zi}JBKc8HBYx$J~31PXH+4^x|UxK~(<@I;^3pWN$E=sYma@JP|8YL`L(zI6Y#c%Q{6 z*APf`DU$S4pr#_!60BH$FGViP14iJmbrzSrOkR;f3YZa{#E7Wpd@^4E-zH8EgPc-# zKWFPvh%WbqU_%ZEt`=Q?odKHc7@SUmY{GK`?40VuL~o)bS|is$Hn=<=KGHOsEC5tB zFb|q}gGlL97NUf$G$>^1b^3E18PZ~Pm9kX%*ftnolljiEt@2#F2R5ah$zbXd%V_Ev zyDd{1o_uuoBga$fB@Fw!V5F3jIr=a-ykqrK?WWZ#a(bglI_-8pq74RK*KfQ z0~Dzus7_l;pMJYf>Bk`)`S8gF!To-BdMnVw5M-pyu+aCiC5dwNH|6fgRsIKZcF&)g zr}1|?VOp}I3)IR@m1&HX1~#wsS!4iYqES zK}4J{Ei>;e3>LB#Oly>EZkW14^@YmpbgxCDi#0RgdM${&wxR+LiX}B+iRioOB0(pDKpVEI;ND?wNx>%e|m{RsqR_{(nmQ z3ZS}@t!p4a(BKx_-CYwrcyJ5u1TO9bcXti$8sy>xcLKqKCc#~UOZYD{llKTSFEjJ~ zyNWt>tLU}*>^`TvPxtP%F`ZJQw@W0^>x;!^@?k_)9#bF$j0)S3;mH-IR5y82l|%=F z2lR8zhP?XNP-ucZZ6A+o$xOyF!w;RaLHGh57GZ|TCXhJqY~GCh)aXEV$1O&$c}La1 zjuJxkY9SM4av^Hb;i7efiYaMwI%jGy`3NdY)+mcJhF(3XEiSlU3c|jMBi|;m-c?~T z+x0_@;SxcoY=(6xNgO$bBt~Pj8`-<1S|;Bsjrzw3@zSjt^JC3X3*$HI79i~!$RmTz zsblZsLYs7L$|=1CB$8qS!tXrWs!F@BVuh?kN(PvE5Av-*r^iYu+L^j^m9JG^#=m>@ z=1soa)H*w6KzoR$B8mBCXoU;f5^bVuwQ3~2LKg!yxomG1#XPmn(?YH@E~_ED+W6mxs%x{%Z<$pW`~ON1~2XjP5v(0{C{+6Dm$00tsd3w=f=ZENy zOgb-=f}|Hb*LQ$YdWg<(u7x3`PKF)B7ZfZ6;1FrNM63 z?O6tE%EiU@6%rVuwIQjvGtOofZBGZT1Sh(xLIYt9c4VI8`!=UJd2BfLjdRI#SbVAX ziT(f*RI^T!IL5Ac>ql7uduF#nuCRJ1)2bdvAyMxp-5^Ww5p#X{rb5)(X|fEhDHHW{ zw(Lfc$g;+Q`B0AiPGtmK%*aWfQQ$d!*U<|-@n2HZvCWSiw^I>#vh+LyC;aaVWGbmkENr z&kl*8o^_FW$T?rDYLO1Pyi%>@&kJKQoH2E0F`HjcN}Zlnx1ddoDA>G4Xu_jyp6vuT zPvC}pT&Owx+qB`zUeR|4G;OH(<<^_bzkjln0k40t`PQxc$7h(T8Ya~X+9gDc8Z9{Z z&y0RAU}#_kQGrM;__MK9vwIwK^aoqFhk~dK!ARf1zJqHMxF2?7-8|~yoO@_~Ed;_wvT%Vs{9RK$6uUQ|&@#6vyBsFK9eZW1Ft#D2)VpQRwpR(;x^ zdoTgMqfF9iBl%{`QDv7B0~8{8`8k`C4@cbZAXBu00v#kYl!#_Wug{)2PwD5cNp?K^ z9+|d-4z|gZ!L{57>!Ogfbzchm>J1)Y%?NThxIS8frAw@z>Zb9v%3_3~F@<=LG%r*U zaTov}{{^z~SeX!qgSYow`_5)ij*QtGp4lvF`aIGQ>@3ZTkDmsl#@^5*NGjOuu82}o zzLF~Q9SW+mP=>88%eSA1W4_W7-Q>rdq^?t=m6}^tDPaBRGFLg%ak93W!kOp#EO{6& zP%}Iff5HZQ9VW$~+9r=|Quj#z*=YwcnssS~9|ub2>v|u1JXP47vZ1&L1O%Z1DsOrDfSIMHU{VT>&>H=9}G3i@2rP+rx@eU@uE8rJNec zij~#FmuEBj03F1~ct@C@$>y)zB+tVyjV3*n`mtAhIM0$58vM9jOQC}JJOem|EpwqeMuYPxu3sv}oMS?S#o6GGK@8PN59)m&K4Dc&X% z(;XL_kKeYkafzS3Wn5DD>Yiw{LACy_#jY4op(>9q>>-*9@C0M+=b#bknAWZ37^(Ij zq>H%<@>o4a#6NydoF{_M4i4zB_KG)#PSye9bk0Ou8h%1Dtl7Q_y#7*n%g)?m>xF~( zjqvOwC;*qvN_3(*a+w2|ao0D?@okOvg8JskUw(l7n`0fncglavwKd?~l_ryKJ^Ky! zKCHkIC-o7%fFvPa$)YNh022lakMar^dgL=t#@XLyNHHw!b?%WlM)R@^!)I!smZL@k zBi=6wE5)2v&!UNV(&)oOYW(6Qa!nUjDKKBf-~Da=#^HE4(@mWk)LPvhyN3i4goB$3K8iV7uh zsv+a?#c4&NWeK(3AH;ETrMOIFgu{_@%XRwCZ;L=^8Ts)hix4Pf3yJRQ<8xb^CkdmC z?c_gB)XmRsk`9ch#tx4*hO=#qS7={~Vb4*tTf<5P%*-XMfUUYkI9T1cEF;ObfxxI-yNuA=I$dCtz3ey znVkctYD*`fUuZ(57+^B*R=Q}~{1z#2!ca?)+YsRQb+lt^LmEvZt_`=j^wqig+wz@n@ z`LIMQJT3bxMzuKg8EGBU+Q-6cs5(@5W?N>JpZL{$9VF)veF`L5%DSYTNQEypW%6$u zm_~}T{HeHj1bAlKl8ii92l9~$dm=UM21kLemA&b$;^!wB7#IKWGnF$TVq!!lBlG4 z{?Rjz?P(uvid+|i$VH?`-C&Gcb3{(~Vpg`w+O);Wk1|Mrjxrht0GfRUnZqz2MhrXa zqgVC9nemD5)H$to=~hp)c=l9?#~Z_7i~=U-`FZxb-|TR9@YCxx;Zjo-WpMNOn2)z) zFPGGVl%3N$f`gp$gPnWC+f4(rmts%fidpo^BJx72zAd7|*Xi{2VXmbOm)1`w^tm9% znM=0Fg4bDxH5PxPEm{P3#A(mxqlM7SIARP?|2&+c7qmU8kP&iApzL|F>Dz)Ixp_`O zP%xrP1M6@oYhgo$ZWwrAsYLa4 z|I;DAvJxno9HkQrhLPQk-8}=De{9U3U%)dJ$955?_AOms!9gia%)0E$Mp}$+0er@< zq7J&_SzvShM?e%V?_zUu{niL@gt5UFOjFJUJ}L?$f%eU%jUSoujr{^O=?=^{19`ON zlRIy8Uo_nqcPa6@yyz`CM?pMJ^^SN^Fqtt`GQ8Q#W4kE7`V9^LT}j#pMChl!j#g#J zr-=CCaV%xyFeQ9SK+mG(cTwW*)xa(eK;_Z(jy)woZp~> zA(4}-&VH+TEeLzPTqw&FOoK(ZjD~m{KW05fiGLe@E3Z2`rLukIDahE*`u!ubU)9`o zn^-lyht#E#-dt~S>}4y$-mSbR8{T@}22cn^refuQ08NjLOv?JiEWjyOnzk<^R5%gO zhUH_B{oz~u#IYwVnUg8?3P*#DqD8#X;%q%HY**=I>>-S|!X*-!x1{^l#OnR56O>iD zc;i;KS+t$koh)E3)w0OjWJl_aW2;xF=9D9Kr>)(5}4FqUbk# zI#$N8o0w;IChL49m9CJTzoC!|u{Ljd%ECgBOf$}&jA^$(V#P#~)`&g`H8E{uv52pp zwto`xUL-L&WTAVREEm$0g_gYPL(^vHq(*t1WCH_6alhkeW&GCZ3hL)|{O-jiFOBrF z!EW=Jej|dqQitT6!B-7&io2K)WIm~Q)v@yq%U|VpV+I?{y0@Yd%n8~-NuuM*pM~KA z85YB};IS~M(c<}4Hxx>qRK0cdl&e?t253N%vefkgds>Ubn8X}j6Vpgs>a#nFq$osY z1ZRwLqFv=+BTb=i%D2Wv>_yE0z}+niZ4?rE|*a3d7^kndWGwnFqt+iZ(7+aln<}jzbAQ(#Z2SS}3S$%Bd}^ zc9ghB%O)Z_mTZMRC&H#)I#fiLuIkGa^`4e~9oM5zKPx?zjkC&Xy0~r{;S?FS%c7w< zWbMpzc(xSw?9tGxG~_l}Acq}zjt5ClaB7-!vzqnlrX;}$#+PyQ9oU)_DfePh2E1<7 ztok6g6K^k^DuHR*iJ?jw?bs_whk|bx`dxu^nC6#e{1*m~z1eq7m}Cf$*^Eua(oi_I zAL+3opNhJteu&mWQ@kQWPucmiP)4|nFG`b2tpC;h{-PI@`+h?9v=9mn|0R-n8#t=+Z*FD(c5 zjj79Jxkgck*DV=wpFgRZuwr%}KTm+dx?RT@aUHJdaX-ODh~gByS?WGx&czAkvkg;x zrf92l8$Or_zOwJVwh>5rB`Q5_5}ef6DjS*$x30nZbuO3dijS*wvNEqTY5p1_A0gWr znH<(Qvb!os14|R)n2Ost>jS2;d1zyLHu`Svm|&dZD+PpP{Bh>U&`Md;gRl64q;>{8MJJM$?UNUd`aC>BiLe>*{ zJY15->yW+<3rLgYeTruFDtk1ovU<$(_y7#HgUq>)r0{^}Xbth}V#6?%5jeFYt;SG^ z3qF)=uWRU;Jj)Q}cpY8-H+l_n$2$6{ZR?&*IGr{>ek!69ZH0ZoJ*Ji+ezzlJ^%qL3 zO5a`6gwFw(moEzqxh=yJ9M1FTn!eo&qD#y5AZXErHs%22?A+JmS&GIolml!)rZTnUDM3YgzYfT#;OXn)`PWv3Ta z!-i|-Wojv*k&bC}_JJDjiAK(Ba|YZgUI{f}TdEOFT2+}nPmttytw7j%@bQZDV1vvj z^rp{gRkCDmYJHGrE1~e~AE!-&6B6`7UxVQuvRrfdFkGX8H~SNP_X4EodVd;lXd^>eV1jN+Tt4}Rsn)R0LxBz0c=NXU|pUe!MQQFkGBWbR3&(jLm z%RSLc#p}5_dO{GD=DEFr=Fc% z85CBF>*t!6ugI?soX(*JNxBp+-DdZ4X0LldiK}+WWGvXV(C(Ht|!3$psR=&c*HIM=BmX;pRIpz@Ale{9dhGe(U2|Giv;# zOc|;?p67J=Q(kamB*aus=|XP|m{jN^6@V*Bpm?ye56Njh#vyJqE=DweC;?Rv7faX~ zde03n^I~0B2vUmr;w^X37tVxUK?4}ifsSH5_kpKZIzpYu0;Kv}SBGfI2AKNp+VN#z`nI{UNDRbo-wqa4NEls zICRJpu)??cj^*WcZ^MAv+;bDbh~gpN$1Cor<{Y2oyIDws^JsfW^5AL$azE(T0p&pP z1Mv~6Q44R&RHoH95&OuGx2srIr<@zYJTOMKiVs;Bx3py89I87LOb@%mr`0)#;7_~Z zzcZj8?w=)>%5@HoCHE_&hnu(n_yQ-L(~VjpjjkbT7e)Dk5??fApg(d>vwLRJ-x{um z*Nt?DqTSxh_MIyogY!vf1mU1`Gld-&L)*43f6dilz`Q@HEz;+>MDDYv9u!s;WXeao zUq=TaL$P*IFgJzrGc>j1dDOd zed+=ZBo?w4mr$2)Ya}?vedDopomhW1`#P<%YOJ_j=WwClX0xJH-f@s?^tmzs_j7t!k zK@j^zS0Q|mM4tVP5Ram$VbS6|YDY&y?Q1r1joe9dj08#CM{RSMTU}(RCh`hp_Rkl- zGd|Cv~G@F{DLhCizAm9AN!^{rNs8hu!G@8RpnGx7e`-+K$ffN<0qjR zGq^$dj_Tv!n*?zOSyk5skI7JVKJ)3jysnjIu-@VSzQiP8r6MzudCU=~?v-U8yzo^7 zGf~SUTvEp+S*!X9uX!sq=o}lH;r{pzk~M*VA(uyQ`3C8!{C;)&6)95fv(cK!%Cuz$ z_Zal57H6kPN>25KNiI6z6F)jzEkh#%OqU#-__Xzy)KyH};81#N6OfX$$IXWzOn`Q& z4f$Z1t>)8&8PcYfEwY5UadU1yg+U*(1m2ZlHoC-!2?gB!!fLhmTl))D@dhvkx#+Yj z1O=LV{(T%{^IeCuFK>%QR!VZ4GnO5tK8a+thWE zg4VytZrwcS?7^ zuZfhYnB8dwd%VLO?DK7pV5Wi<(`~DYqOXn8#jUIL^)12*Dbhk4GmL_E2`WX&iT16o zk(t|hok(Y|v-wzn?4x34T)|+SfZP>fiq!><*%vnxGN~ypST-FtC+@TPv*vYv@iU!_ z@2gf|PrgQ?Ktf*9^CnJ(x*CtZVB8!OBfg0%!wL;Z8(tYYre0vcnPGlyCc$V(Ipl*P z_(J!a=o@vp^%Efme!K74(Ke7A>Y}|sxV+JL^aYa{~m%5#$$+R1? zGaQhZTTX!#s#=Xtpegqero$RNt&`4xn3g$)=y*;=N=Qai)}~`xtxI_N*#MMCIq#HFifT zz(-*m;pVH&+4bixL&Bbg)W5FN^bH87pAHp)zPkWNMfTFqS=l~AC$3FX3kQUSh_C?-ZftyClgM)o_D7cX$RGlEYblux0jv5 zTr|i-I3@ZPCGheCl~BGhImF)K4!9@?pC(gi3ozX=a!|r1)LFxy_8c&wY0<^{2cm|P zv6Y`QktY*;I)IUd5y3ne1CqpVanlY45z8hf4&$EUBnucDj16pDa4&GI&TArYhf*xh zdj>*%APH8(h~c>o@l#%T>R$e>rwVx_WUB|~V`p^JHsg*y12lzj&zF}w6W09HwB2yb z%Q~`es&(;7#*DUC_w-Dmt7|$*?TA_m;zB+-u{2;Bg{O}nV7G_@7~<)Bv8fH^G$XG8$(&{A zwXJK5LRK%M34(t$&NI~MHT{UQ9qN-V_yn|%PqC81EIiSzmMM=2zb`mIwiP_b)x+2M z7Gd`83h79j#SItpQ}luuf2uOU`my_rY5T{6P#BNlb%h%<#MZb=m@y5aW;#o1^2Z)SWo+b`y0gV^iRcZtz5!-05vF z7wNo=hc6h4hc&s@uL^jqRvD6thVYtbErDK9k!;+a0xoE0WL7zLixjn5;$fXvT=O3I zT6jI&^A7k6R{&5#lVjz#8%_RiAa2{di{`kx79K+j72$H(!ass|B%@l%KeeKchYLe_ z>!(JC2fxsv>XVen+Y42GeYPxMWqm`6F$(E<6^s|g(slNk!lL*6v^W2>f6hh^mE$s= z3D$)}{V5(Qm&A6bp%2Q}*GZ5Qrf}n7*Hr51?bJOyA-?B4vg6y_EX<*-e20h{=0Mxs zbuQGZ$fLyO5v$nQ&^kuH+mNq9O#MWSfThtH|0q1i!NrWj^S}_P;Q1OkYLW6U^?_7G zx2wg?CULj7))QU(n{$0JE%1t2dWrMi2g-Os{v|8^wK{@qlj%+1b^?NI z$}l2tjp0g>K3O+p%yK<9!XqmQ?E9>z&(|^Pi~aSRwI5x$jaA62GFz9%fmO3t3a>cq zK8Xbv=5Ps~4mKN5+Eqw12(!PEyedFXv~VLxMB~HwT1Vfo51pQ#D8e$e4pFZ{&RC2P z5gTIzl{3!&(tor^BwZfR8j4k{7Rq#`riKXP2O-Bh66#WWK2w=z;iD9GLl+3 zpHIaI4#lQ&S-xBK8PiQ%dwOh?%BO~DCo06pN7<^dnZCN@NzY{_Z1>rrB0U|nC&+!2 z2y!oBcTd2;@lzyk(B=TkyZ)zy0deK05*Q0zk+o$@nun`VI1Er7pjq>8V zNmlW{p7S^Btgb(TA}jL(uR>`0w8gHP^T~Sh5Tkip^spk4SBAhC{TZU}_Z)UJw-}zm zPq{KBm!k)?P{`-(9?LFt&YN4s%SIZ-9lJ!Ws~B%exHOeVFk3~}HewnnH(d)qkLQ_d z6h>O)pEE{vbOVw}E+jdYC^wM+AAhaI(YAibUc@B#_mDss0Ji&BK{WG`4 zOk>vSNq(Bq2IB@s>>Rxm6Wv?h;ZXkpb1l8u|+_qXWdC*jjcPCixq;!%BVPSp#hP zqo`%cNf&YoQXHC$D=D45RiT|5ngPlh?0T~?lUf*O)){K@*Kbh?3RW1j9-T?%lDk@y z4+~?wKI%Y!-=O|_IuKz|=)F;V7ps=5@g)RrE;;tvM$gUhG>jHcw2Hr@fS+k^Zr~>G z^JvPrZc}_&d_kEsqAEMTMJw!!CBw)u&ZVzmq+ZworuaE&TT>$pYsd9|g9O^0orAe8 z221?Va!l1|Y5X1Y?{G7rt1sX#qFA^?RLG^VjoxPf63;AS=_mVDfGJKg73L zsGdnTUD40y(>S##2l|W2Cy!H(@@5KBa(#gs`vlz}Y~$ot5VsqPQ{{YtjYFvIumZzt zA{CcxZLJR|4#{j7k~Tu*jkwz8QA|5G1$Cl895R`Zyp;irp1{KN){kB30O8P1W5;@bG znvX74roeMmQlUi=v9Y%(wl$ZC#9tKNFpvi3!C}f1m6Ct|l2g%psc{TJp)@yu)*e2> z((p0Fg*8gJ!|3WZke9;Z{8}&NRkv7iP=#_y-F}x^y?2m%-D_aj^)f04%mneyjo_;) z6qc_Zu$q37d~X``*eP~Q>I2gg%rrV8v=kDfpp$=%Vj}hF)^dsSWygoN(A$g*E=Do6FX?&(@F#7pbiJ`;c0c@Ul zDqW_90Wm#5f2L<(Lf3)3TeXtI7nhYwRm(F;*r_G6K@OPW4H(Y3O5SjUzBC}u3d|eQ8*8d@?;zUPE+i#QNMn=r(ap?2SH@vo*m z3HJ%XuG_S6;QbWy-l%qU;8x;>z>4pMW7>R}J%QLf%@1BY(4f_1iixd-6GlO7Vp*yU zp{VU^3?s?90i=!#>H`lxT!q8rk>W_$2~kbpz7eV{3wR|8E=8**5?qn8#n`*(bt1xRQrdGxyx2y%B$qmw#>ZV$c7%cO#%JM1lY$Y0q?Yuo> ze9KdJoiM)RH*SB%^;TAdX-zEjA7@%y=!0=Zg%iWK7jVI9b&Dk}0$Af&08KHo+ zOwDhFvA(E|ER%a^cdh@^wLUlmIv6?_3=BvX8jKk92L=Y}7Jf5OGMfh` zBdR1wFCi-i5@`9km{isRb0O%TX+f~)KNaEz{rXQa89`YIF;EN&gN)cigu6mNh>?Cm zAO&Im2flv6D{jwm+y<%WsPe4!89n~KN|7}Cb{Z;XweER73r}Qp2 zz}WP4j}U0&(uD&9yGy6`!+_v-S(yG*iytsTR#x_Rc>=6u^vnRDnf1gP{#2>`ffrAC% zTZ5WQ@hAK;P;>kX{D)mIXe4%a5p=LO1xXH@8T?mz7Q@d)$3pL{{B!2{-v70L*o1AO+|n5beiw~ zk@(>m?T3{2k2c;NWc^`4@P&Z?BjxXJ@;x1qhn)9Mn*IFdt_J-dIqx5#d`NfyfX~m( zIS~5)MfZ2Uy?_4W`47i}u0ZgPh<{D|w_d#;D}Q&U$Q-G}xM1A@1f{#%A$jh6Qp&0hQ<0bPOM z-{1Wm&p%%#eb_?x7i;bol EfAhh=DF6Tf literal 0 HcmV?d00001 diff --git a/.mvn/wrapper/maven-wrapper.properties b/.mvn/wrapper/maven-wrapper.properties old mode 100755 new mode 100644 index 216df05..27e7135 --- 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 From c93a25c182f0b0acd15cdfa01089599b52601854 Mon Sep 17 00:00:00 2001 From: Loong Wan Date: Mon, 21 Sep 2026 12:54:22 +0800 Subject: [PATCH 003/146] fix(argv): preserve literal values across executor adapter and typed paths Observed RED at 94de053: 33 real-child contract tests, 21 failures, 0 errors and 0 skips; full suite 2027 tests. Snapshot submitted tokens, reject null elements without disclosing values, preserve empty/padded/newline arguments and validate blank command identifiers. Align two legacy filtering assertions with OC-ARGV-001 without removing tests. Ordered schema-aware options and remaining C01 closure are still pending. --- .../opencli/core/OpenCliAdapterChannel.java | 84 ++++--------- .../core/OpenCliAdapterCommandRequest.java | 62 +++------- .../opencli/core/OpenCliArgSupport.java | 80 ++++++------ .../easy4j/opencli/core/OpenCliExecutor.java | 116 ++++++------------ .../OpenCliAdapterCommandRequestTest.java | 4 +- .../opencli/core/OpenCliArgSupportTest.java | 12 +- 6 files changed, 135 insertions(+), 223 deletions(-) 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..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()); - } - } - log.debug("OpenCLI adapter invoke adapterId={} subcommandSummary={}", adapterId, summarizeSubcommand(tokens)); + 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,38 +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); - } - - 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(); + 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..6ea38da 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequest.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequest.java @@ -13,33 +13,18 @@ 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)}. - * - *

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

- + * Structured adapter request. Positional and valued-option contents are literal; + * command and option identifiers are validated separately. + * The legacy options map represents a single-valued subset: Boolean values + * retain their historical presence-only flag semantics. * - * @author Loong Wan - * @since 3.0.0 - */ - +@Getter +@Builder public final class OpenCliAdapterCommandRequest { - /** 子命令名(不含 adapter id)。 */ private final String subcommand; @Getter(AccessLevel.NONE) @@ -50,9 +35,7 @@ public final class OpenCliAdapterCommandRequest { @Builder.Default private final Map options = Collections.emptyMap(); - /** - * @return positional 参数副本 - */ + /** @return an immutable copy of positional values */ public List getPositionals() { if (Objects.isNull(positionals)) { return Collections.emptyList(); @@ -60,9 +43,7 @@ public List getPositionals() { return Collections.unmodifiableList(new ArrayList<>(positionals)); } - /** - * @return 命名选项副本 - */ + /** @return an immutable copy of named options */ public Map getOptions() { if (Objects.isNull(options)) { return Collections.emptyMap(); @@ -71,20 +52,17 @@ public Map getOptions() { } /** - * 将本请求转换为 {@link OpenCliAdapterChannel#invoke(List)} 所需的 token 列表。 - * - * @return 以 subcommand 开头、随后 positional、再 options 的 argv 片段 + * @return subcommand, then unchanged positional values and named options */ 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")); } if (Objects.nonNull(options)) { for (Map.Entry entry : options.entrySet()) { @@ -106,16 +84,14 @@ private static void appendOption(List target, String name, Object value) return; } target.add(flag); - target.add(String.valueOf(value).trim()); + target.add(String.valueOf(value)); } /** - * 从 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, 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..dc5cc9f 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,11 +84,11 @@ 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)) { @@ -91,11 +97,11 @@ public static void addOptionPairIfPresent(List target, String flag, Obje } /** - * 当 {@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/OpenCliExecutor.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java index f313578..edb7c6a 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java @@ -16,7 +16,7 @@ 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.Map; @@ -29,83 +29,64 @@ 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.

+ *

{@link #invoke(List)} accepts literal argv tokens following the executable name. + * Local invocation prepends {@link OpenCliProperties#getLeadingArguments()}. + * Empty and whitespace-only values are preserved; null tokens are rejected before + * transport selection. Command identifiers are validated separately.

* - *

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

- + *

When the execution target is {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP}, + * invocation uses the legacy opencli-admin {@code /collect} contract. That protocol's + * representation limits are separate from the local raw argv contract.

* - * @author Loong Wan - * @since 3.0.0 - */ - +@Slf4j +@Getter public class OpenCliExecutor { private final OpenCliProperties properties; - /** - * 懒加载,仅远程模式使用。 - */ + /** Lazily initialized for remote mode. */ private volatile OpenCliRemoteAgentHttpClient remoteAgentHttpClient; - /** - * @param properties 运行时配置,不得为 null - */ + /** @param properties runtime configuration */ public OpenCliExecutor(OpenCliProperties properties) { this.properties = Objects.requireNonNull(properties, "properties"); SubprocessExecutionSupport.configureMaxConcurrentExecutions(properties.getMaxConcurrentExecutions()); } /** - * 执行 {@code opencli ...} 完整 argv(不含可执行文件本身)。 + * Invoke a snapshot of the complete argv vector, excluding the executable. * - * @param adapterAndRest 至少包含 adapter 名,后续为子命令与 flag;不得为 null - * @return 包含成功标记的执行结果 + * @param adapterAndRest nonempty command and literal values + * @return execution result */ public OpenCliResult invoke(List adapterAndRest) { - Objects.requireNonNull(adapterAndRest, "adapterAndRest"); + 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) { - log.debug("OpenCLI invoke remote agent argvSize={}", adapterAndRest.size()); + log.debug("OpenCLI invoke remote agent argvSize={}", tokens.size()); OpenCliCollectRequest req = OpenCliArgvToCollectParser.parse( - adapterAndRest, + tokens, properties.getRemoteOutputFormat(), properties.getRemoteCollectMode(), properties.getRemoteCdpEndpoint()); return remoteAgent().collect(req); } - log.debug("OpenCLI invoke local argvSize={}", adapterAndRest.size()); - CommandLine cmd = buildCommandLine(adapterAndRest); + log.debug("OpenCLI invoke local argvSize={}", tokens.size()); + CommandLine cmd = buildCommandLine(tokens); return run(cmd); } - /** - * @return 远程 Agent HTTP 客户端(懒加载) - */ private OpenCliRemoteAgentHttpClient remoteAgent() { if (Objects.isNull(remoteAgentHttpClient)) { synchronized (this) { @@ -118,57 +99,40 @@ private OpenCliRemoteAgentHttpClient remoteAgent() { } /** - * 便捷重载:可变参数形式。 - * - * @param adapterAndRest adapter 及后续 CLI token - * @return 执行结果 + * @param adapterAndRest command and literal values + * @return execution result */ 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()); - } - } - } - return invoke(list); + Objects.requireNonNull(adapterAndRest, "adapterAndRest"); + return invoke(Arrays.asList(adapterAndRest)); } - /** - * 拼装 {@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)) { throw new IllegalStateException("opencli.executable must not be blank"); } CommandLine cmd = new CommandLine(exe.trim()); - appendCleanArgs(cmd, properties.getLeadingArguments()); - appendCleanArgs(cmd, adapterAndRest); + appendLiteralArgs(cmd, properties.getLeadingArguments(), "leadingArguments"); + appendLiteralArgs(cmd, adapterAndRest, "adapterAndRest"); return cmd; } - private static void appendCleanArgs(CommandLine cmd, List args) { - if (Objects.isNull(args) || args.isEmpty()) { + private static void appendLiteralArgs(CommandLine cmd, List args, String field) { + if (args == null) { return; } - for (String a : args) { - if (OpenCliStrings.isNotBlank(a)) { - cmd.addArgument(a.trim(), false); - } + for (String value : OpenCliArgSupport.snapshotValues(args, field)) { + cmd.addArgument(value, false); } } /** - * 将 {@code --key=value} 以句柄安全形式追加(含空格时由 Commons Exec 处理)。 + * Append a {@code --key=value} token using Commons Exec quoting. * - * @param cmd 命令行 - * @param key 必须以 {@code --} 开头 - * @param value 非空值 + * @param cmd command line + * @param key option name starting with {@code --} + * @param value non-null value */ public static void appendQuotedKeyValue(CommandLine cmd, String key, String value) { Objects.requireNonNull(key, "key"); 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..d98b0f5 100644 --- a/src/test/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequestTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequestTest.java @@ -116,7 +116,7 @@ void shouldReturnImmutableOptions() { } @Test - void shouldSkipNullPositionalInToSubcommandAndArgs() { + void shouldPreserveEmptyPositionalInToSubcommandAndArgs() { OpenCliAdapterCommandRequest req = OpenCliAdapterCommandRequest.builder() .subcommand("sub") .positional("a") @@ -124,7 +124,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..977ec52 100644 --- a/src/test/java/io/github/easy4j/opencli/core/OpenCliArgSupportTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/OpenCliArgSupportTest.java @@ -15,9 +15,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 From 6f830b4f2e5b87bb57eb6b3b669fd299ee48ee39 Mon Sep 17 00:00:00 2001 From: Loong Wan Date: Mon, 21 Sep 2026 12:57:47 +0800 Subject: [PATCH 004/146] fix(argv): bypass Commons Exec internal argument trimming The first repair left 11 real-child assertions failing because CommandLine.Argument trims its stored value even with handleQuoting=false. Preserve a separate literal vector at the native launch boundary; do not relax whitespace/newline assertions. No implicit shell parsing, quoting, or substitution is added. --- .../opencli/core/LiteralCommandLine.java | 46 +++++++++++++++++++ .../easy4j/opencli/core/OpenCliExecutor.java | 2 +- 2 files changed, 47 insertions(+), 1 deletion(-) create mode 100644 src/main/java/io/github/easy4j/opencli/core/LiteralCommandLine.java 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/OpenCliExecutor.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java index edb7c6a..99b1abe 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java @@ -112,7 +112,7 @@ private CommandLine buildCommandLine(List adapterAndRest) { if (OpenCliStrings.isBlank(exe)) { throw new IllegalStateException("opencli.executable must not be blank"); } - CommandLine cmd = new CommandLine(exe.trim()); + CommandLine cmd = new LiteralCommandLine(exe.trim()); appendLiteralArgs(cmd, properties.getLeadingArguments(), "leadingArguments"); appendLiteralArgs(cmd, adapterAndRest, "adapterAndRest"); return cmd; From d02b16ddc5e0fe7c1d98c6847f4b2999cf2f2566 Mon Sep 17 00:00:00 2001 From: Loong Wan Date: Mon, 21 Sep 2026 13:00:34 +0800 Subject: [PATCH 005/146] test(argv): add ordered option and immutable request RED contracts Cover repeatable option occurrences, explicit valued false, positive/negative flags, nonrepeatable and legacy collisions, malformed schemas, and captured mutable inputs. Use public API reflection so absent API is an assertion failure, not compile failure. The existing 33 real-child contracts remain enabled. --- .../OpenCliStructuredArgvContractTest.java | 180 ++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 src/test/java/io/github/easy4j/opencli/contract/OpenCliStructuredArgvContractTest.java 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)); + } +} From 48b14388bc1c86fcf1dff2705f0140a541a3fa75 Mon Sep 17 00:00:00 2001 From: Loong Wan Date: Mon, 21 Sep 2026 13:03:33 +0800 Subject: [PATCH 006/146] feat(argv): add schema-checked ordered options and immutable request inputs Observed second RED at d02b16d: 2038 tests, 10 assertion failures, 0 errors/skips. Add explicit flag/value/negatable schemas and immutable option occurrences. Preserve occurrence order and valued false; reject duplicate/mixed-schema ambiguity. Snapshot legacy maps and mutable values while retaining Boolean flag compatibility. Do not claim capability discovery or final three-branch integration is complete. --- .../core/OpenCliAdapterCommandRequest.java | 141 +++++++++++++----- .../easy4j/opencli/core/OpenCliOption.java | 73 +++++++++ .../opencli/core/OpenCliOptionSchema.java | 73 +++++++++ 3 files changed, 247 insertions(+), 40 deletions(-) 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 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 6ea38da..91e1dd2 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequest.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliAdapterCommandRequest.java @@ -1,22 +1,26 @@ 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; /** - * Structured adapter request. Positional and valued-option contents are literal; - * command and option identifiers are validated separately. - * The legacy options map represents a single-valued subset: Boolean values - * retain their historical presence-only flag semantics. + * 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. * * @author Loong Wan * @since 3.0.0 @@ -24,7 +28,6 @@ @Getter @Builder public final class OpenCliAdapterCommandRequest { - private final String subcommand; @Getter(AccessLevel.NONE) @@ -32,28 +35,45 @@ 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; + + /** + * Builder customisation snapshots legacy option values before they can be + * changed through the caller's Map or a mutable value object. + */ + 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 an immutable copy of positional values */ public List getPositionals() { - if (Objects.isNull(positionals)) { - return Collections.emptyList(); - } - return Collections.unmodifiableList(new ArrayList<>(positionals)); + return positionals == null ? Collections.emptyList() + : Collections.unmodifiableList(new ArrayList<>(positionals)); } - /** @return an immutable copy of named options */ + /** @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)); } - /** - * @return subcommand, then unchanged positional values and named options - */ + /** @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)) { @@ -64,27 +84,74 @@ public List toSubcommandAndArgs() { if (positionals != null) { tokens.addAll(OpenCliArgSupport.snapshotValues(positionals, "positionals")); } - if (Objects.nonNull(options)) { + Set legacyFlags = new HashSet<>(); + if (options != null) { for (Map.Entry entry : options.entrySet()) { - appendOption(tokens, entry.getKey(), entry.getValue()); + String flag = appendLegacyOption(tokens, entry.getKey(), entry.getValue()); + if (flag != null && !legacyFlags.add(flag)) { + throw new IllegalArgumentException("Ambiguous duplicate legacy option identifier"); + } + } + } + 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 = String.valueOf(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)); + if (!(value instanceof Boolean)) { + target.add(String.valueOf(value)); + } + return flag; } /** @@ -94,16 +161,10 @@ private static void appendOption(List target, String name, Object value) * @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/OpenCliOption.java b/src/main/java/io/github/easy4j/opencli/core/OpenCliOption.java new file mode 100644 index 0000000..5e5277e --- /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, String.valueOf(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); } +} From 31bde9cc4bda23519b6a81d66df7ddb781d94548 Mon Sep 17 00:00:00 2001 From: Loong Wan Date: Mon, 21 Sep 2026 13:12:35 +0800 Subject: [PATCH 007/146] test(process): add C02 bounded lifecycle RED contracts Use self-bounded offline child processes to expose limiter replacement, queue deadline bypass, unbounded stdout/stderr and interrupted-child leaks. Also require explicit shared runtime and pre-cancel semantics. No production lifecycle implementation changes in this RED checkpoint. --- .../opencli/contract/LifecycleProbe.java | 40 +++ .../contract/OpenCliProcessContractTest.java | 233 ++++++++++++++++++ 2 files changed, 273 insertions(+) create mode 100644 src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java create mode 100644 src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessContractTest.java 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..f6e6874 --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java @@ -0,0 +1,40 @@ +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 test cleanup even against broken SDKs. */ +public final class LifecycleProbe { + private LifecycleProbe() { } + + public static void main(String[] args) throws Exception { + String mode = args[0]; + 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/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)); + } +} From 98e3db1f8883b8485ec8a428238173dc1148dfb4 Mon Sep 17 00:00:00 2001 From: Loong Wan Date: Mon, 21 Sep 2026 13:19:31 +0800 Subject: [PATCH 008/146] fix(process): enforce stable capacity deadlines and bounded native capture C02 RED at 31bde9c: 2046 tests, 8 failures, 0 errors/skips. Use fixed per-client or explicit shared runtimes, monotonic queue/execution budgets, 8MiB stdout and 2MiB stderr caps, per-call cancellation and owned-root cleanup. Preserve lifecycle reasons, byte counts and unknown descendant status in results. Quarantine runtimes with unconfirmed owned root/reader cleanup; keep legacy API bridge. Remote cancellation and unverified descendant ownership are not claimed. --- .../easy4j/opencli/OpenCliProperties.java | 107 +---- .../core/OpenCliCancellationToken.java | 14 + .../opencli/core/OpenCliExecutionDetails.java | 33 ++ .../easy4j/opencli/core/OpenCliExecutor.java | 293 +++++-------- .../opencli/core/OpenCliProcessRuntime.java | 37 ++ .../easy4j/opencli/core/OpenCliResult.java | 38 +- .../support/SubprocessExecutionSupport.java | 409 ++++++++++++++---- .../OpenCliExecutableFailureException.java | 14 +- 8 files changed, 541 insertions(+), 404 deletions(-) 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/OpenCliProcessRuntime.java diff --git a/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java b/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java index 6c87513..e60a87a 100644 --- a/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java +++ b/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java @@ -7,112 +7,46 @@ import lombok.Data; /** - * OpenCLI runtime configuration POJO with no Spring dependency. - *

- * 描述可执行文件、工作目录、超时、全局 argv 前缀、远端 Agent 以及需要注入子进程的环境变量 - *(例如 {@code OPENCLI_CDP_ENDPOINT})。Spring Boot 可由上层以 - * {@code @ConfigurationProperties(prefix = "opencli")} 绑定同名字段。 - *

- *

- * {@link #commandTimeoutMillis} 在本地模式下用于子进程 Watchdog;在 - * {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP} 模式下用作 HTTP 客户端超时上限。 - *

- */ -@Data/** - - * OpenCLI runtime configuration POJO with no Spring dependency. - * - *

Describes the executable path, working directory, timeout, global argv prefix, - * remote Agent settings, and environment variables injected into the subprocess - * (e.g. {@code OPENCLI_CDP_ENDPOINT}). Spring Boot applications can bind these - * fields via {@code @ConfigurationProperties(prefix = "opencli")}.

+ * OpenCLI runtime configuration without Spring dependencies. + * Local execution uses a monotonic submission-to-exit deadline; cleanup has a + * separate finite grace. Remote HTTP retains its own transport timeout semantics. * - *

{@link #commandTimeoutMillis} is used as the subprocess watchdog timeout in local - * mode and as the HTTP client timeout in {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP} mode.

- - * - * @author Loong Wan - * @since 3.0.0 - */ - +@Data public class OpenCliProperties { - - /** - * 执行目标:本机进程或与 opencli-admin 兼容的远端 Agent。 - */ private OpenCliExecutionTarget executionTarget = OpenCliExecutionTarget.LOCAL_PROCESS; - - /** - * 远端 Agent 根 URL(不含尾斜杠),例如 {@code http://192.168.1.10:19823}。 - *

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

- */ + /** Root URL of an opencli-admin compatible Agent. */ private String remoteAgentBaseUrl; - - /** - * 传给 Agent collect 的 {@code mode}:{@code bridge} 或 {@code cdp}(与 Agent 环境一致)。 - */ private String remoteCollectMode = "cdp"; - - /** - * 传给 Agent collect 的默认 {@code format}(可被 argv 中的 {@code -f} 覆盖)。 - */ private String remoteOutputFormat = "json"; - - /** - * 对应 collect body 的 {@code cdp_endpoint};空表示由 Agent 使用自身 {@code OPENCLI_CDP_ENDPOINT}。 - */ private String remoteCdpEndpoint = ""; - - /** - * 为 true 时,远程模式下将 Agent HTTP 响应原文写入 {@link io.github.easy4j.opencli.core.OpenCliResult} 的 - * {@code remoteRawHttpBody} 字段; - * 本地模式无效果。大响应时请谨慎开启。 - */ + /** Raw HTTP capture is explicitly opt-in and may contain sensitive business data. */ private boolean remoteCaptureRawHttpResponse = false; - - /** - * OpenCLI 可执行文件名或绝对路径;默认假定已在 {@code PATH} 中。 - */ private String executable = "opencli"; - - /** - * 子进程工作目录;为空时使用 JVM 当前目录。 - */ private String workingDirectory; - - /** - * 单次调用超时(毫秒):本地模式用于子进程 Watchdog;远程模式用于 Agent HTTP 请求。 - */ + /** Total local queue plus execution budget; remote mode uses an HTTP timeout. */ private long commandTimeoutMillis = 300_000L; - - /** - * 本机 CLI 子进程最大并发数;小于等于 0 时使用 CPU 核心数与 2 的较大值。 - */ + /** Positive per-client capacity, zero for max(2, cores); negative is invalid. Captured at construction. */ private int maxConcurrentExecutions = 0; - - /** - * 启动探测({@code opencli list})专用超时(毫秒);小于等于 0 时探测使用 30 秒。 - */ + /** Maximum bytes retained from stdout for one local invocation. */ + private int maxStdoutBytes = 8 * 1024 * 1024; + /** Maximum bytes retained from stderr for one local invocation. */ + private int maxStderrBytes = 2 * 1024 * 1024; + /** Independent bounded cleanup grace, in milliseconds. */ + private long cleanupGraceMillis = 5_000L; private long startupProbeTimeoutMillis = 30_000L; - - /** - * 附加到 {@code opencli} 之后的最前参数(在 adapter 名之前),便于预留 profile 等扩展。 - */ + /** Literal prefix arguments placed before the command identifier. */ private List leadingArguments = new ArrayList<>(); - - /** - * 合并进子进程环境的键值;覆盖同名系统环境变量。 - */ + /** Variables overlaying the inherited process environment. */ private Map environment = new LinkedHashMap<>(); /** - * 复制为「仅本机子进程」配置,供边缘 WebSocket Agent 处理中心下发的 {@code collect} 时使用, - * 避免误将 collect 再次转发为 {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP} 而形成回路。 + * Copy into a local-only configuration for reverse-Agent execution without + * forwarding a received command back to a remote Agent. * - * @return 新实例,不会改变当前对象 + * @return an independent local configuration */ public OpenCliProperties copyForLocalCliExecution() { OpenCliProperties c = new OpenCliProperties(); @@ -120,6 +54,9 @@ 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)); 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..98530e3 --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutionDetails.java @@ -0,0 +1,33 @@ +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; + 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 99b1abe..ebb35af 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java @@ -2,69 +2,78 @@ 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.Arrays; import java.util.HashMap; import java.util.List; +import java.util.Locale; import java.util.Map; import java.util.Objects; 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; /** - * OpenCLI subprocess execution wrapper based on Apache Commons Exec. - * - *

{@link #invoke(List)} accepts literal argv tokens following the executable name. - * Local invocation prepends {@link OpenCliProperties#getLeadingArguments()}. - * Empty and whitespace-only values are preserved; null tokens are rejected before - * transport selection. Command identifiers are validated separately.

- * - *

When the execution target is {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP}, - * invocation uses the legacy opencli-admin {@code /collect} contract. That protocol's - * representation limits are separate from the local raw argv contract.

+ * 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 */ -@Slf4j @Getter public class OpenCliExecutor { - private final OpenCliProperties properties; - - /** Lazily initialized for remote mode. */ + private final OpenCliProcessRuntime processRuntime; private volatile OpenCliRemoteAgentHttpClient remoteAgentHttpClient; - /** @param properties runtime configuration */ + /** @param properties configuration; process capacity is captured once */ public OpenCliExecutor(OpenCliProperties properties) { + this(properties, new OpenCliProcessRuntime(Objects.requireNonNull(properties, "properties") + .getMaxConcurrentExecutions())); + } + + /** + * @param properties configuration + * @param processRuntime an explicitly shared, stable local capacity owner + */ + public OpenCliExecutor(OpenCliProperties properties, OpenCliProcessRuntime processRuntime) { this.properties = Objects.requireNonNull(properties, "properties"); - SubprocessExecutionSupport.configureMaxConcurrentExecutions(properties.getMaxConcurrentExecutions()); + this.processRuntime = Objects.requireNonNull(processRuntime, "processRuntime"); + } + + /** @param adapterAndRest command and literal values @return execution result */ + public OpenCliResult invoke(List adapterAndRest) { + return invokeInternal(adapterAndRest, new OpenCliCancellationToken(), false); } /** - * Invoke a snapshot of the complete argv vector, excluding the executable. + * Cancellable local invocation. The legacy HTTP protocol does not claim a + * cancellable remote process; explicit tokens are rejected in remote mode. * - * @param adapterAndRest nonempty command and literal values + * @param adapterAndRest command and literal values + * @param cancellationToken cancellation for this invocation only * @return execution result */ - public OpenCliResult invoke(List adapterAndRest) { + 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"); @@ -73,24 +82,21 @@ public OpenCliResult invoke(List adapterAndRest) { throw new IllegalArgumentException("adapterAndRest[0] command identifier must not be blank"); } if (properties.getExecutionTarget() == OpenCliExecutionTarget.REMOTE_AGENT_HTTP) { - log.debug("OpenCLI invoke remote agent argvSize={}", tokens.size()); - OpenCliCollectRequest req = - OpenCliArgvToCollectParser.parse( - tokens, - properties.getRemoteOutputFormat(), - properties.getRemoteCollectMode(), - properties.getRemoteCdpEndpoint()); + 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); } - log.debug("OpenCLI invoke local argvSize={}", tokens.size()); - CommandLine cmd = buildCommandLine(tokens); - return run(cmd); + 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); } } @@ -98,194 +104,107 @@ private OpenCliRemoteAgentHttpClient remoteAgent() { return remoteAgentHttpClient; } - /** - * @param adapterAndRest command and literal values - * @return execution result - */ + /** @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 adapterAndRest) { - String exe = properties.getExecutable(); - if (OpenCliStrings.isBlank(exe)) { + 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 LiteralCommandLine(exe.trim()); + 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, adapterAndRest, "adapterAndRest"); + appendLiteralArgs(cmd, tokens, "adapterAndRest"); return cmd; } - private static void appendLiteralArgs(CommandLine cmd, List args, String field) { - if (args == null) { - return; - } - for (String value : OpenCliArgSupport.snapshotValues(args, field)) { - cmd.addArgument(value, 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); } } - /** - * Append a {@code --key=value} token using Commons Exec quoting. - * - * @param cmd command line - * @param key option name starting with {@code --} - * @param value non-null 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"); 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); } - 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); - + SubprocessExecutionSupport.ExecutionRequest request = new SubprocessExecutionSupport.ExecutionRequest( + commandLine, resolveWorkingDirectory(), buildEnvironment(), timeoutMillis, + properties.getMaxStdoutBytes(), properties.getMaxStderrBytes(), properties.getCleanupGraceMillis(), + submittedAtNanos, cancellationToken); try { - SubprocessExecutionSupport.RunSession session = SubprocessExecutionSupport.execute(request); - return completeAfterWait( - commandLine, - timeoutMs, - session.getStdout(), - session.getStderr(), - session.getHandler(), - session.getWatchdog(), - session.isWaitTimedOut()); - } catch (IOException e) { - log.warn("OpenCLI spawn failed commandLine={}, message={}", commandLine, e.getMessage()); - throw new OpenCliExecutableFailureException( - "OpenCLI could not be started (check PATH or executable path): " + commandLine, e); - } catch (InterruptedException e) { + return complete(processRuntime.execute(request)); + } catch (IOException ex) { + throw new OpenCliExecutableFailureException("OpenCLI process could not be started", ex); + } catch (InterruptedException ex) { Thread.currentThread().interrupt(); - log.warn("OpenCLI interrupted commandLine={}", commandLine); - throw new OpenCliException("Interrupted while awaiting OpenCLI subprocess", e, null); + throw new OpenCliException("Interrupted while awaiting OpenCLI subprocess", ex, null); } } + 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", session.getIoFailure(), result); + } + if (reason == TerminationReason.PROCESS_EXIT && exit != null && exit != 0) { + throw new OpenCliNonZeroExitException("OpenCLI returned nonzero exitCode=" + exit, result); + } + throw new OpenCliException("OpenCLI execution ended: " + reason, session.getIoFailure(), result); + } + 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: " + wd.getAbsolutePath(), null); + 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 wd; + return directory; } return null; } - private OpenCliResult completeAfterWait( - CommandLine commandLine, - long timeoutMs, - ByteArrayOutputStream out, - ByteArrayOutputStream 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); - OpenCliParsedFields parsed = OpenCliOutputParser.parseBestEffort(stdoutStr, stderrStr); - - if (waitTimedOut || watchdog.killedProcess()) { - log.warn("OpenCLI timed out commandLine={} timeoutMs={}", commandLine, timeoutMs); - OpenCliResult partial = snapshot(stdoutStr, stderrStr, readExitQuietly(handler), parsed); - throw new OpenCliTimeoutException( - "OpenCLI timed out after " + timeoutMs + " ms: " + commandLine, partial); - } - - Exception asyncFailure = handler.getException(); - if (asyncFailure instanceof ExecuteException) { - ExecuteException ex = (ExecuteException) asyncFailure; - log.warn("OpenCLI failed exitCode={} commandLine={}", ex.getExitValue(), commandLine); - OpenCliResult failed = snapshot(stdoutStr, stderrStr, normalizeExitValue(ex.getExitValue()), parsed); - throw new OpenCliNonZeroExitException( - "OpenCLI failed (exitCode=" + ex.getExitValue() + "): " + commandLine, failed); - } - if (Objects.nonNull(asyncFailure)) { - log.error("OpenCLI async failure commandLine={}", commandLine, asyncFailure); - OpenCliResult snapshot = snapshot(stdoutStr, stderrStr, readExitQuietly(handler), parsed); - throw new OpenCliException( - "OpenCLI async failure: " + commandLine + " cause=" + asyncFailure.getMessage(), - asyncFailure, snapshot); - } - - final int exit; - try { - exit = handler.getExitValue(); - } catch (IllegalStateException e) { - throw new OpenCliException( - "OpenCLI completed without observable exit code: " + commandLine, - e, - snapshot(stdoutStr, stderrStr, null, parsed)); - } - - if (exit != 0) { - log.warn("OpenCLI non-zero exit exitCode={} commandLine={}", exit, commandLine); - OpenCliResult failed = snapshot(stdoutStr, stderrStr, exit, parsed); - throw new OpenCliNonZeroExitException( - "OpenCLI non-zero exit (exitCode=" + exit + "): " + commandLine, failed); - } - - return OpenCliResult.builder() - .stdout(stdoutStr) - .stderr(stderrStr) - .exitCode(exit) - .success(true) - .parsed(parsed) - .build(); - } - 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/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..b1fd2e4 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliResult.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliResult.java @@ -5,45 +5,23 @@ import lombok.Getter; /** - * 单次 OpenCLI 调用的原始结果载体。 - *

- * {@link #remoteRawHttpBody} 仅在 {@link io.github.easy4j.opencli.OpenCliExecutionTarget#REMOTE_AGENT_HTTP} - * 且 {@link io.github.easy4j.opencli.OpenCliProperties} 的 {@code remoteCaptureRawHttpResponse} 为 true 时填充, - * 为 Agent 返回的完整 HTTP 响应体,便于审计或与 {@code stdout}(由 {@code items} 重组)对照。 - *

- */ -@Getter -@Builder/** - - * Raw result carrier for a single OpenCLI invocation. - * - *

{@link #remoteRawHttpBody} is only populated when using - * {@link io.github.easy4j.opencli.OpenCliExecutionTarget#REMOTE_AGENT_HTTP} - * and {@link io.github.easy4j.opencli.OpenCliProperties#isRemoteCaptureRawHttpResponse()} - * is {@code true}.

- + * Raw result for one OpenCLI invocation. Raw output is business data, not a safe + * diagnostic string. Local execution adds bounded lifecycle evidence; legacy + * remote responses do not acquire an invented process exit or cleanup state. * - * @author Loong Wan - * @since 3.0.0 - */ - +@Getter +@Builder public class OpenCliResult { - private final String stdout; - private final String stderr; - private final Integer exitCode; - private final boolean success; - private final OpenCliParsedFields parsed; - - /** - * 远端 Agent HTTP 响应全文;本地子进程模式或非调试场景下为 null。 - */ + /** Only populated by explicit remote HTTP raw capture. */ private final String remoteRawHttpBody; + /** Observed local execution metadata; null for a legacy remote result. */ + 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 f6d77bb..5334915 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,167 +1,386 @@ 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.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 收尾等待的上限(毫秒)。 */ + * 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 { 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 static final int DEFAULT_MAX_CONCURRENT = Math.max(2, Runtime.getRuntime().availableProcessors()); - - private static final AtomicReference CONCURRENCY_LIMIT = - new AtomicReference<>(new Semaphore(DEFAULT_MAX_CONCURRENT)); - - 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--; } } } - private static RunSession executeWithinLimit(ExecutionRequest request) throws IOException, InterruptedException { - long timeoutMs = Math.max(1L, request.getTimeoutMillis()); - ByteArrayOutputStream out = new ByteArrayOutputStream(); - ByteArrayOutputStream err = new ByteArrayOutputStream(); + /** Internal capacity/cleanup owner exposed through OpenCliProcessRuntime. */ + public static final class Runtime { + private final int maxConcurrentExecutions; + private final Semaphore permits; + private volatile boolean quarantined; - DefaultExecutor.Builder builder = DefaultExecutor.builder(); - if (request.getWorkingDirectory() != null) { - builder.setWorkingDirectory(request.getWorkingDirectory()); + public Runtime(int maxConcurrent) { + if (maxConcurrent < 0) { + throw new IllegalArgumentException("maxConcurrentExecutions must not be negative"); + } + maxConcurrentExecutions = maxConcurrent == 0 ? DEFAULT_MAX_CONCURRENT : maxConcurrent; + permits = new Semaphore(maxConcurrentExecutions, true); } - DefaultExecutor executor = builder.get(); - executor.setStreamHandler(new PumpStreamHandler(out, err)); - - ExecuteWatchdog watchdog = - ExecuteWatchdog.builder().setTimeout(Duration.ofMillis(timeoutMs)).get(); - executor.setWatchdog(watchdog); - - DefaultExecuteResultHandler handler = new DefaultExecuteResultHandler(); - Map environment = request.getEnvironment(); - if (environment != null) { - executor.execute(request.getCommandLine(), environment, handler); - } else { - executor.execute(request.getCommandLine(), handler); + + 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 = ExecuteWatchdog.builder() + .setTimeout(Duration.ofMillis(request.timeoutMillis)).get(); + TerminationReason reason = null; + IOException ioFailure = null; + boolean acquired = false; + boolean interrupted = 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 = builder.start(); + 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); + watchdog = ExecuteWatchdog.builder().setTimeout(Duration.ofMillis( + Math.max(1L, TimeUnit.NANOSECONDS.toMillis(Math.max(0L, remaining))))).get(); + watchdog.start(process); + 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 (stdoutReader.failure != null || stderrReader.failure != null) { + 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; + } finally { + watchdog.stop(); + long cleanupStart = System.nanoTime(); + long cleanupBudget = nanos(request.cleanupGraceMillis, "cleanupGraceMillis"); + if (process != null) { + if (process.isAlive()) { process.destroy(); } + boolean forceSent = false; + 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)) { + process.destroyForcibly(); + forceSent = true; + } + try { + TimeUnit.NANOSECONDS.sleep(Math.min(POLL_NANOS, + Math.max(1L, remaining(cleanupStart, cleanupBudget)))); + } catch (InterruptedException ex) { + interrupted = true; + } + } + if (process.isAlive()) { process.destroyForcibly(); } + 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; } + } + } + 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)) + .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(); + return new RunSession(out, err, handler, watchdog, request.timeoutMillis, + reason == TerminationReason.QUEUE_TIMEOUT || reason == TerminationReason.EXECUTION_TIMEOUT, + details, exit, ioFailure); + } + } + + private static boolean alive(Thread thread) { return thread != null && thread.isAlive(); } + 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); } + + 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"); + } + return millis * 1_000_000L; + } + + private static final class BoundedCapture extends ByteArrayOutputStream { + private final int limit; + private long observed; + private boolean truncated; + private boolean frozen; + + 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 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) { + 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()); + } + + 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; + 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 ByteArrayOutputStream stdout; private final ByteArrayOutputStream stderr; private final DefaultExecuteResultHandler handler; private final ExecuteWatchdog watchdog; private final long timeoutMillis; private final 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) { + 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; } } } 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); + } } From 3bacc8d09b1eeeaa05d6137e2a7e9c350d6622ce Mon Sep 17 00:00:00 2001 From: Loong Wan Date: Mon, 21 Sep 2026 13:24:21 +0800 Subject: [PATCH 009/146] test(contracts): extend lifecycle boundaries and layered execution evidence Add UTF-8 byte-boundary, budget validation, running/queued cancellation, configuration copy and repeated timeout regression tests. Report both argv suites and process suites separately from live OpenCLI evidence. Runner extension observed local RED then GREEN: 13 self-tests pass. Archive only committed source alongside exact-head CI evidence for reproducible review. --- .github/workflows/contracts.yml | 5 + scripts/contract_report.py | 5 +- scripts/tests/test_contract_report.py | 9 + .../opencli/contract/LifecycleProbe.java | 6 +- .../contract/OpenCliProcessBoundaryTest.java | 162 ++++++++++++++++++ 5 files changed, 183 insertions(+), 4 deletions(-) create mode 100644 src/test/java/io/github/easy4j/opencli/contract/OpenCliProcessBoundaryTest.java diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index 5f9c448..58a9d9c 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -88,6 +88,8 @@ jobs: run: | mkdir -p contract-evidence git rev-parse HEAD > contract-evidence/head.txt + git archive -o contract-evidence/source.tar HEAD + sha256sum contract-evidence/source.tar > contract-evidence/source.sha256 java -version > contract-evidence/java.txt 2>&1 if ! bash ./mvnw -version > contract-evidence/maven.txt 2>&1; then cat contract-evidence/maven.txt @@ -117,6 +119,9 @@ jobs: --maven-version-file contract-evidence/maven.txt \ --exit-code "$(cat contract-evidence/maven.exit)" \ --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 \ --output contract-evidence/report.json - name: Upload actual JVM evidence if: always() diff --git a/scripts/contract_report.py b/scripts/contract_report.py index 19fcbba..b0c8c78 100644 --- a/scripts/contract_report.py +++ b/scripts/contract_report.py @@ -11,7 +11,7 @@ import sys import xml.etree.ElementTree as ET -LAYERS = ('enumeration', 'argv', 'protocol', 'typed-result', 'real-execution') +LAYERS = ('enumeration', 'argv', 'process', 'protocol', 'typed-result', 'real-execution') def _suite_summary(suite): @@ -50,7 +50,6 @@ def build_report(reports_dir, *, head, branch, java_version, maven_version, exit raise ValueError('duplicate testsuite') suites[name] = _suite_summary(suite) except (ET.ParseError, OSError, KeyError, ValueError): - # Do not copy testcase failure bodies or captured application output. problems.append('invalid or duplicate Surefire report: ' + path.name) layers = {} for layer in LAYERS: @@ -71,7 +70,7 @@ def build_report(reports_dir, *, head, branch, java_version, maven_version, exit 'head': head, 'branch': branch, 'javaVersion': java_version, 'mavenVersion': maven_version, 'commandExitCode': exit_code, 'layers': layers, 'problems': problems, - 'scope': 'Explicit Surefire suites only; synthetic argv probes are not live OpenCLI verification.'} + 'scope': 'Explicit Surefire suites only; synthetic argv/process probes are not live OpenCLI verification.'} def main(argv=None): diff --git a/scripts/tests/test_contract_report.py b/scripts/tests/test_contract_report.py index f466e0a..b9bfd2e 100644 --- a/scripts/tests/test_contract_report.py +++ b/scripts/tests/test_contract_report.py @@ -44,6 +44,15 @@ def test_complete_argv_evidence_passes_but_live_is_not_run(self): self.assertEqual(HEAD, report['head']) json.dumps(report) + def test_process_layer_is_separate_from_real_execution(self): + self.xml() + report = self.module.build_report(self.root, head=HEAD, branch='feature/2.0.x', + java_version='fixture-jdk', maven_version='fixture-maven', exit_code=0, + required_suites={'process': [SUITE]}) + self.assertEqual('PASS', report['status']) + self.assertEqual(2, report['layers']['process']['executed']) + self.assertEqual('NOT_RUN', report['layers']['real-execution']['status']) + def test_missing_report_fails(self): self.assertEqual('FAIL', self.report()['status']) 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 f6e6874..88247cf 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java +++ b/src/test/java/io/github/easy4j/opencli/contract/LifecycleProbe.java @@ -6,12 +6,16 @@ import java.nio.file.Paths; import java.util.Arrays; -/** Offline, self-bounded child fixture. Release files allow test cleanup even against broken SDKs. */ +/** 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'); 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()); + } + } +} From d2690ce76692d593044614e20f4dd2ae1e080176 Mon Sep 17 00:00:00 2001 From: Loong Wan Date: Mon, 21 Sep 2026 13:38:16 +0800 Subject: [PATCH 010/146] docs(implementation): record verified C10 C01 C02 progress and open review gates Record exact RED/GREEN commits, 2052-test evidence, 43 argv/14 process contracts, 13 evidence-runner self-tests and ten official OpenSpec strict validations. Keep remaining edge cases, independent review, platform/backport work and the three-branch integration gate explicitly open; no OpenSpec tasks are pre-closed. Preserve the intentional trailing TSV separator with a path-scoped attribute. No product Java or dependency changes in this documentation checkpoint. --- .gitattributes | 2 + docs/implementation/c10-c01-execution.md | 80 ++++++++++++++++++++---- openspec/implementation-status.json | 34 ++++++++++ 3 files changed, 104 insertions(+), 12 deletions(-) create mode 100644 .gitattributes create mode 100644 openspec/implementation-status.json diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..c9683ed --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +# The last TSV field intentionally encodes an empty argv token. Do not trim it. +src/test/resources/opencli-contracts/v1/argv.tsv whitespace=-blank-at-eol diff --git a/docs/implementation/c10-c01-execution.md b/docs/implementation/c10-c01-execution.md index dab1be4..679e197 100644 --- a/docs/implementation/c10-c01-execution.md +++ b/docs/implementation/c10-c01-execution.md @@ -1,23 +1,79 @@ -# C10 foundation and C01 implementation ledger +# C10 基础与 C01 / C02 第一批实施记录 -## Approved ordering and scope +> 2026-09-21。状态:IMPLEMENTATION_IN_PROGRESS / REVIEW_REQUIRED。 +> 本文记录实际实现和实际验证,不代表十个 Change 已完成,也不关闭三分支集成门禁。 -The user approved C10 foundation, then C01/C02/C03/C04/C05/C09, then C06/C07/C08, and only then C10 integration closure. `feature/2.0.x` is the canonical implementation line. This file records execution, not completion of the ten changes. +## 1. 执行顺序与分支边界 -An isolated implementation branch starts at `d0c8056990f7a47fcc202acffa387ba066bcfc67`. The 1.x/3.x baseline refs and permitted JDK/Jackson/Maven differences are recorded in `src/test/resources/opencli-contracts/v1/sources.lock.json`. No changes to `main`, dependency versions or coverage thresholds are part of this increment. +顺序保持:C10 共享测试基础 → C01/C02/C03/C04/C05/C09 → C06/C07/C08 → C10 最终集成。 -## C10 foundation +标准实现线为 `feature/2.0.x`。本批在隔离分支 `feature/2.0.x-contract-hardening` 实施,基点为 `d0c8056990f7a47fcc202acffa387ba066bcfc67`。1.x 基点 `abba809f11dae68437c39d2ea5a2f4cf8798c0ef`,3.x 基点 `6e38904bdfcae90ec617e8d29bf3d8cf2f002893`。共享 fixture 的 sources.lock.json 保存三线 Java/Jackson/Maven 允许差异。当前实施没有移动这三个原始 feature 分支,也没有修改 main。 -Shared synthetic UTF-8/base64 argv vectors preserve empty and trailing empty fields. They have content hashes and a specification ref, not an invented upstream capture provenance. A Java 8-compatible child prints each actual argument. The regression suite uses the real SDK executor, adapter and Browser paths; a Recording executor is not used to prove process behavior. +本批未开始 C03/C04/C05/C06/C07/C08 的新实现;移除本地 Executor/Adapter 默认参数日志只是 C09 的局部改进,不等于整个 SDK 的日志/异常隐私治理完成。 -The report runner separates enumeration, argv, protocol, typed-result and real-execution evidence. Only explicitly selected suites contribute; the real-execution layer remains NOT_RUN because a Java argv probe is not a live OpenCLI website test. Missing reports, zero tests, skipped required tests, nonzero Maven exit, malformed XML and inconsistent testcase counts fail closed. +## 2. 实际 RED → GREEN -Local runner TDD: 12 failures before the runner existed, then 12 passing tests. The probe compiled with `javac --release 8` on JDK 21 and emitted an empty token unchanged. This does not constitute an actual JDK 8 runtime test. Full JVM evidence is produced by the branch-specific GitHub Actions workflow using each line's checked-in Maven wrapper. +| 阶段 | 精确提交 | 验证结果 | GitHub Actions run | +|---|---|---|---| +| C01 原始参数 RED | `94de053f4ae7a0912201c2bbeab81b8332f660b8` | 全套 2027 项;21 failures、0 errors、0 skipped。新增 33 项参数契约中 21 项失败 | [35562286431](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/35562286431) | +| SDK 层修复后的剩余 RED | `c93a25c182f0b0acd15cdfa01089599b52601854` | 2028 项;仍有 11 项失败,原因在 Commons Exec 内部 trim | [35562634249](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/35562634249) | +| 原始参数 GREEN | `6f830b4f2e5b87bb57eb6b3b669fd299ee48ee39` | clean verify、参数契约门禁、官方 strict、报告上传通过 | [35562782412](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/35562782412) | +| 有序选项/快照 RED | `d02b16ddc5e0fe7c1d98c6847f4b2999cf2f2566` | 2038 项;10 failures、0 errors、0 skipped;原始 33 项参数契约仍通过 | [35562952517](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/35562952517) | +| 有序选项/快照 GREEN | `48b14388bc1c86fcf1dff2705f0140a541a3fa75` | 完整验证与官方 strict 通过 | [35563156619](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/35563156619) | +| C02 资源行为 RED | `31bde9cc4bda23519b6a81d66df7ddb781d94548` | 2046 项;新增八项全部失败;0 errors、0 skipped | [35563763025](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/35563763025) | +| 执行核 GREEN | `98e3db1f8883b8485ec8a428238173dc1148dfb4` | 完整验证、资源回归、官方 strict 通过 | [35564181728](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/35564181728) | +| 扩展边界 GREEN | `3bacc8d09b1eeeaa05d6137e2a7e9c350d6622ce` | Surefire XML 实际合计 2052 项,0 failures、0 errors、0 skipped;argv 43 项、process 14 项 | [35564455068](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/35564455068) | -## C01 RED checkpoint +初始 `cdc8b66` 的 CI 因 Wrapper JAR 缺失、隐藏证据目录未被上传而失败;它不是有效行为 RED。修复构建基础后才得到表中的真实失败证据。2.x Wrapper 复用仓库已有的 launcher JAR,保留 Maven 3.9.16 分发;未修改 POM 依赖版本或降低 JaCoCo 门槛。 -The initial Java contract suite deliberately demands lossless values before any product source is changed. The first CI run must be inspected for assertion failures at the real child boundary, not treated as a completed fix. Compilation errors or tool setup failures are not valid RED proof. +## 3. C10 已建立的基础 -## Still open +`src/test/resources/opencli-contracts/v1/` 包含版本化的 UTF-8/base64 参数向量、内容 hash、来源 lock、三线基点和允许差异。向量明确标为 synthetic offline,不伪装成上游或网站采集结果。TSV 最后一列可以为空;限定到该文件的 .gitattributes 保留末尾分隔符,不允许格式化器把空参数删除。 -C01 schema-aware repeated/false option handling, C02/C03/C04/C05/C09 production fixes, discovery, Browser result models, context/diagnostics and three-branch integration closure are not complete. Official OpenSpec strict is configured but must be observed at the exact workflow run before claiming it passed. No OpenSpec implementation tasks are pre-checked. +`ContractProbe` 输出真实 JVM 参数,覆盖 Executor List/varargs、Adapter List/varargs、结构化 request 与 Browser fill 路径。不是只断言 Recording executor 的前两项。 + +`scripts/contract_report.py` 分开记录 enumeration、argv、process、protocol、typed-result、real-execution。缺报告、零测试、required suite 被跳过、实际 Maven exit 非零、坏 XML、声明数量与实际 testcase 不一致均失败。13 项 Python 检查器测试经过本地 RED→GREEN,并在 CI 再次运行。 + +NOT_RUN 表示本轮没有为该层选择新的契约证据,不表示既有协议/解析测试被跳过;完整 Maven 套件仍运行全部既有测试。Java 子进程探针不等于 live OpenCLI/网站验证。 + +`.github/workflows/contracts.yml` 使用分支对应 JDK 与 checked-in Wrapper,记录精确 HEAD、实际 Java/Maven 版本、退出码、Surefire XML、JaCoCo 和分层报告。所有十个 Change 均使用官方 OpenSpec 1.13.1 逐项及 `--all --strict --no-interactive` 校验;在上述绿色 run 中均通过。 + +## 4. C01 的实现内容和兼容约束 + +参数值原样保留空字符串、空白、换行、Unicode、引号、`--` 和含 `=` 的内容。null 元素按字段和索引报错,不在错误中拼接其它参数值。命令标识符与值分开校验;输入在排队之前做快照。 + +Commons Exec 的 Argument 构造器在 handleQuoting=false 时仍 trim;先由 LiteralCommandLine 保留原始向量,当前执行核再把完整向量直接交给 ProcessBuilder。没有自动 shell 展开或拼接 shell 字符串。 + +OpenCliOptionSchema / OpenCliOption 增量支持带值选项、可重复有序 occurrences、显式 false 和否定 flag,拒绝 schema 冲突与 legacy/ordered 重叠。旧 Map 中 Boolean 仍保持历史 presence-only 行为;不能把旧 false 静默改成否定 flag。Map 和可变对象的常规值在构造时捕获。 + +Windows `.cmd/.bat` 被明确拒绝,调用方应使用原生 node 可执行文件及 JS 路径;Windows/macOS 实际执行尚未验证。legacy appendQuotedKeyValue 保留,不作为新的 literal 路径使用。 + +## 5. C02 的实现内容和边界 + +每个 Executor 默认持有稳定的容量 owner;显式共享 OpenCliProcessRuntime 才跨 Client 共用许可。0 使用 CPU 派生默认值,负数拒绝。旧静态 bridge 仅保留给兼容调用,且在存在提交时拒绝重配;构造新 Client 不再修改它。 + +System.nanoTime 驱动提交到执行的总预算。排队到期不创建子进程;启动前取消也不创建子进程。stdout 默认捕获 8 MiB,stderr 2 MiB;超过预算返回 OUTPUT_LIMIT 失败和有界部分输出。字段分别记录 retained/observed 字节数与截断标记;UTF-8 截断采用替换字符解码,字节计数不根据重新编码后的文本计算。 + +清理只有有限 grace,默认 5 秒;中断标记会恢复,许可在收尾后释放。主进程或读取线程未确认结束时,runtime 被隔离,不继续积累新的不确定资源。结果携带 terminationReason、cleanupState、processStarted、streamsDrained、字节计数和 elapsed/queue 时间。 + +主进程确认退出不等于所有后代退出。当前 portable backend 固定保留 descendantsExitConfirmed=false;不按进程名/PID 批量终止共享 daemon 或用户浏览器。同步 follow 仍受有限 timeout/capture 约束;没有实现无限流式 sink 或远端取消协议。 + +## 6. 尚未满足的关闭条件 + +C01/C02 的 Change 继续 IN_PROGRESS;不能因为上述测试通过就整体勾选或 archive。 + +- C01:自定义 Object.toString() 返回 null 的输入应补专门拒绝测试;Windows/macOS 和三版本线实际完整回归尚未完成。 +- C02:底层 stop/destroy 抛 unchecked 异常时的收尾保护需要故障注入验证和补强;未知清理、取消/自然退出竞争及未确认后代的验收仍需继续。 +- C09:HTTP、WS、诊断和异常 cause 链仍需独立隐私回归;本地参数日志减少不构成全域完成。 +- C03/C04/C05 尚未进入本轮新实现,C06/C07/C08 也尚未进入;不得跳过这些项关闭 C10。 +- 1.x/JDK8、3.x/JDK21、真实 OpenCLI 输出采集、CodeGraph 索引以及独立代码评审未完成。不能用本批 JDK17 证据代替它们。 + +## 7. 实际产物验证 + +扩展边界 run 35564455068 的 JDK artifact SHA-256:`86cc81f83792b5c65d648c04db1afee6970f46335583c7ad8ff2cdb34b6f4897`。 +其中 committed-source tar SHA-256:`c11fe761f44af076f29dffe8aa10f3000c9d1d421bcfc83aa2191da4afe08d35`。 +该 tar 在容器重建的 Git tree 精确等于 `f421af093023fb11683fcd4334806f12d9aa140c`,与 3bacc8d 的远端树一致;这是固定源码快照,不是声称已 clone 完整 Git 历史或同步用户 Mac。 + +官方 strict artifact SHA-256:`aac29fdd4c5c3f7c9c556e7a92036d4956c630609ad5a9f37ddd25dfc1c24a24`;all.log 实际为 10 passed / 0 failed,version.txt 为 1.13.1。 + +后续提交会使 HEAD 改变,最终状态应读取该精确 HEAD 的新 CI,而不是重复使用旧绿色结果。 diff --git a/openspec/implementation-status.json b/openspec/implementation-status.json new file mode 100644 index 0000000..2ecbb45 --- /dev/null +++ b/openspec/implementation-status.json @@ -0,0 +1,34 @@ +{ + "schemaVersion": 1, + "asOf": "2026-09-21", + "state": "IMPLEMENTATION_IN_PROGRESS", + "canonicalLine": "feature/2.0.x", + "implementationBranch": "feature/2.0.x-contract-hardening", + "verifiedCodeHead": "3bacc8d09b1eeeaa05d6137e2a7e9c350d6622ce", + "verifiedCodeTree": "f421af093023fb11683fcd4334806f12d9aa140c", + "runId": 35564455068, + "javaTests": {"tests": 2052, "failures": 0, "errors": 0, "skipped": 0}, + "selectedContracts": {"argv": 43, "process": 14}, + "pythonRunnerSelfTests": 13, + "officialOpenSpec": {"version": "1.13.1", "strictChangesPassed": 10, "failed": 0}, + "changes": { + "C10": "FOUNDATION_IMPLEMENTED_IN_CANONICAL_BRANCH; FINAL_GATE_OPEN", + "C01": "CORE_IMPLEMENTED; EDGE_CASES_AND_MULTIBRANCH_REVIEW_PENDING", + "C02": "CORE_IMPLEMENTED; CLEANUP_FAULT_INJECTION_AND_MULTIBRANCH_REVIEW_PENDING", + "C03": "NOT_STARTED", + "C04": "NOT_STARTED", + "C05": "NOT_STARTED", + "C06": "NOT_STARTED", + "C07": "NOT_STARTED", + "C08": "NOT_STARTED", + "C09": "LOCAL_LOG_REDUCTION_ONLY; FULL_PRIVACY_CONTRACT_NOT_IMPLEMENTED" + }, + "originalFeatureBranchesChanged": false, + "mainChanged": false, + "localMacSynchronized": false, + "threeBranchIntegrationGate": "OPEN", + "independentCodeReview": "PENDING", + "codeGraph": "NOT_RUN", + "liveOpenCliVerification": "NOT_RUN", + "ledger": "../docs/implementation/c10-c01-execution.md" +} From 41ffefd7d5f7052336edc0445490f20f64946fa7 Mon Sep 17 00:00:00 2001 From: Loong Wan Date: Mon, 21 Sep 2026 14:01:40 +0800 Subject: [PATCH 011/146] ci(contracts): provide scoped offline reproduction dependencies Resolve baseline build and the proposed safe YAML parser for C03. Export only public Maven artifacts and distribution, never credentials or settings. Bundle runs only when its workflow changes or is explicitly dispatched. --- .github/workflows/repro-bundle.yml | 42 ++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 .github/workflows/repro-bundle.yml diff --git a/.github/workflows/repro-bundle.yml b/.github/workflows/repro-bundle.yml new file mode 100644 index 0000000..7c4d9ed --- /dev/null +++ b/.github/workflows/repro-bundle.yml @@ -0,0 +1,42 @@ +name: Offline contract reproduction bundle +on: + push: + branches: ['feature/2.0.x-contract-hardening'] + paths: ['.github/workflows/repro-bundle.yml'] + workflow_dispatch: +permissions: + contents: read +jobs: + bundle: + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-java@v5 + with: + distribution: temurin + java-version: '17' + cache: maven + - name: Verify baseline and resolve the proposed safe YAML parser + run: | + bash ./mvnw -B --no-transfer-progress clean verify + bash ./mvnw -B --no-transfer-progress org.apache.maven.plugins:maven-dependency-plugin:3.8.1:get -Dartifact=org.yaml:snakeyaml:2.6 + - name: Package only public Maven artifacts and distribution + shell: bash + run: | + mkdir -p repro-bundle + git rev-parse HEAD > repro-bundle/source-head.txt + java -version > repro-bundle/java.txt 2>&1 + bash ./mvnw -version > repro-bundle/maven.txt 2>&1 + # Never include settings.xml, toolchains.xml, Git credentials or environment dumps. + tar -czf repro-bundle/maven-repository.tar.gz -C "$HOME/.m2" repository + distribution="$(find "$HOME/.m2/wrapper/dists" -type d -name apache-maven-3.9.16 -print -quit)" + test -n "$distribution" + tar -czf repro-bundle/maven-distribution.tar.gz -C "$(dirname "$distribution")" apache-maven-3.9.16 + (cd repro-bundle && sha256sum *.tar.gz > SHA256SUMS) + - uses: actions/upload-artifact@v7 + with: + name: opencli-offline-repro-${{ github.sha }} + path: repro-bundle + retention-days: 3 + if-no-files-found: error From 6c5c9b3aaa51665e8218311fd895ae48b4734781 Mon Sep 17 00:00:00 2001 From: Loong Wan Date: Mon, 21 Sep 2026 14:34:45 +0800 Subject: [PATCH 012/146] ci(contracts): capture pinned OpenCLI descriptive schemas in isolation Run only bounded version/help probes from npm OpenCLI 1.8.8 with lifecycle scripts disabled. Retain package provenance, hashes and descriptive artifacts; do not invoke website operations. --- .github/workflows/upstream-contracts.yml | 46 ++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 .github/workflows/upstream-contracts.yml diff --git a/.github/workflows/upstream-contracts.yml b/.github/workflows/upstream-contracts.yml new file mode 100644 index 0000000..1f1100d --- /dev/null +++ b/.github/workflows/upstream-contracts.yml @@ -0,0 +1,46 @@ +name: Pinned upstream descriptive contracts +on: + push: + branches: ['feature/2.0.x-contract-hardening'] + paths: ['.github/workflows/upstream-contracts.yml'] + workflow_dispatch: +permissions: + contents: read +jobs: + capture: + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v4 + with: + node-version: '22' + - name: Install pinned OpenCLI without lifecycle scripts + shell: bash + run: | + mkdir -p upstream-evidence "$RUNNER_TEMP/opencli-prefix" "$RUNNER_TEMP/opencli-isolated-home" + npm view @jackwener/opencli@1.8.8 version gitHead dist --json > upstream-evidence/npm-provenance.json + npm install --prefix "$RUNNER_TEMP/opencli-prefix" --ignore-scripts --no-audit --no-fund --save-exact @jackwener/opencli@1.8.8 + - name: Capture only bounded version and structured help + shell: bash + run: | + export HOME="$RUNNER_TEMP/opencli-isolated-home" + CLI="$RUNNER_TEMP/opencli-prefix/node_modules/@jackwener/opencli/dist/src/main.js" + timeout 20 node "$CLI" --version > upstream-evidence/version.txt + timeout 20 node "$CLI" --help -f json > upstream-evidence/root-help.json + for namespace in browser daemon auth skills plugin adapter profile; do + timeout 20 node "$CLI" "$namespace" --help -f json > "upstream-evidence/$namespace-help.json" + done + cp "$RUNNER_TEMP/opencli-prefix/node_modules/@jackwener/opencli/cli-manifest.json" upstream-evidence/cli-manifest.json + cp "$RUNNER_TEMP/opencli-prefix/node_modules/@jackwener/opencli/package.json" upstream-evidence/package.json + tar -czf upstream-evidence/opencli-package.tar.gz -C "$RUNNER_TEMP/opencli-prefix/node_modules/@jackwener/opencli" dist/src cli-manifest.json package.json + node --version > upstream-evidence/node-version.txt + date -u +%FT%TZ > upstream-evidence/captured-at.txt + (cd upstream-evidence && sha256sum *.json *.txt *.tar.gz > SHA256SUMS) + - uses: actions/upload-artifact@v7 + if: always() + with: + name: opencli-1.8.8-descriptive-${{ github.sha }} + path: upstream-evidence + retention-days: 14 + if-no-files-found: error From 80ebb3b4235761e3aca35db0a8e3c4fee2f6c007 Mon Sep 17 00:00:00 2001 From: Loong Wan Date: Mon, 21 Sep 2026 14:37:08 +0800 Subject: [PATCH 013/146] fix(contracts): build exact upstream ref when npm version is unpublished The registry returned E404 for @jackwener/opencli@1.8.8. Keep that evidence. Build the previously audited 8271afc commit and label descriptive captures as source-built. Do not silently substitute another upstream version. --- .github/workflows/upstream-contracts.yml | 26 ++++++++++++++++-------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/.github/workflows/upstream-contracts.yml b/.github/workflows/upstream-contracts.yml index 1f1100d..6a79916 100644 --- a/.github/workflows/upstream-contracts.yml +++ b/.github/workflows/upstream-contracts.yml @@ -15,32 +15,40 @@ jobs: - uses: actions/setup-node@v4 with: node-version: '22' - - name: Install pinned OpenCLI without lifecycle scripts + - name: Checkout exact upstream source, not an assumed npm publication + uses: actions/checkout@v7 + with: + repository: jackwener/OpenCLI + ref: 8271afc67e8504bda94c147f446ee29775d08274 + path: upstream-src + persist-credentials: false + - name: Build the locked source with dependency lifecycle scripts disabled shell: bash run: | - mkdir -p upstream-evidence "$RUNNER_TEMP/opencli-prefix" "$RUNNER_TEMP/opencli-isolated-home" - npm view @jackwener/opencli@1.8.8 version gitHead dist --json > upstream-evidence/npm-provenance.json - npm install --prefix "$RUNNER_TEMP/opencli-prefix" --ignore-scripts --no-audit --no-fund --save-exact @jackwener/opencli@1.8.8 + mkdir -p upstream-evidence "$RUNNER_TEMP/opencli-isolated-home" + git -C upstream-src rev-parse HEAD > upstream-evidence/upstream-head.txt + npm view @jackwener/opencli@1.8.8 version gitHead dist --json > upstream-evidence/npm-provenance.json 2> upstream-evidence/npm-provenance.stderr || printf 'UNAVAILABLE_IN_REGISTRY\n' > upstream-evidence/npm-status.txt + (cd upstream-src && npm ci --ignore-scripts --no-audit --no-fund && npm run build) - name: Capture only bounded version and structured help shell: bash run: | export HOME="$RUNNER_TEMP/opencli-isolated-home" - CLI="$RUNNER_TEMP/opencli-prefix/node_modules/@jackwener/opencli/dist/src/main.js" + CLI="$GITHUB_WORKSPACE/upstream-src/dist/src/main.js" timeout 20 node "$CLI" --version > upstream-evidence/version.txt timeout 20 node "$CLI" --help -f json > upstream-evidence/root-help.json for namespace in browser daemon auth skills plugin adapter profile; do timeout 20 node "$CLI" "$namespace" --help -f json > "upstream-evidence/$namespace-help.json" done - cp "$RUNNER_TEMP/opencli-prefix/node_modules/@jackwener/opencli/cli-manifest.json" upstream-evidence/cli-manifest.json - cp "$RUNNER_TEMP/opencli-prefix/node_modules/@jackwener/opencli/package.json" upstream-evidence/package.json - tar -czf upstream-evidence/opencli-package.tar.gz -C "$RUNNER_TEMP/opencli-prefix/node_modules/@jackwener/opencli" dist/src cli-manifest.json package.json + cp upstream-src/cli-manifest.json upstream-evidence/cli-manifest.json + cp upstream-src/package.json upstream-evidence/package.json + tar -czf upstream-evidence/opencli-source.tar.gz -C upstream-src src cli-manifest.json package.json package-lock.json node --version > upstream-evidence/node-version.txt date -u +%FT%TZ > upstream-evidence/captured-at.txt (cd upstream-evidence && sha256sum *.json *.txt *.tar.gz > SHA256SUMS) - uses: actions/upload-artifact@v7 if: always() with: - name: opencli-1.8.8-descriptive-${{ github.sha }} + name: opencli-source-8271afc-descriptive-${{ github.sha }} path: upstream-evidence retention-days: 14 if-no-files-found: error From f9c058bf15c2e2317e6ac032114b02a514826a92 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 10:30:41 +0800 Subject: [PATCH 014/146] ci(opencli): select JDK 17 for named 2.0 contract branch --- .github/workflows/contracts.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index e18eeca..4919a4f 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -75,6 +75,7 @@ jobs: shell: bash run: | case "$GITHUB_REF_NAME" in + feature/REQ-20261118-wandl-opencli-contracts-20) echo 'java=17' >> "$GITHUB_OUTPUT" ;; feature/1.0.x*) echo 'java=8' >> "$GITHUB_OUTPUT" ;; feature/2.0.x*) echo 'java=17' >> "$GITHUB_OUTPUT" ;; feature/3.0.x*) echo 'java=21' >> "$GITHUB_OUTPUT" ;; From 9717538fc642b21ef155552f7c025c81e5ec38e2 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 10:37:52 +0800 Subject: [PATCH 015/146] fix(opencli): retain cleanup evidence when stop operations throw --- docs/implementation/c10-c01-execution.md | 6 +- openspec/implementation-status.json | 6 +- .../opencli/core/OpenCliExecutionDetails.java | 2 + .../support/SubprocessExecutionSupport.java | 109 ++++++++---- .../support/SubprocessCleanupFaultTest.java | 163 ++++++++++++++++++ 5 files changed, 249 insertions(+), 37 deletions(-) create mode 100644 src/test/java/io/github/easy4j/opencli/core/support/SubprocessCleanupFaultTest.java diff --git a/docs/implementation/c10-c01-execution.md b/docs/implementation/c10-c01-execution.md index b2a8e8a..55bd05c 100644 --- a/docs/implementation/c10-c01-execution.md +++ b/docs/implementation/c10-c01-execution.md @@ -63,7 +63,7 @@ System.nanoTime 驱动提交到执行的总预算。排队到期不创建子进 C01/C02 的 Change 继续 IN_PROGRESS;不能因为上述测试通过就整体勾选或 archive。 - C01:自定义 Object.toString() 返回 null 的输入已补拒绝测试;Windows/macOS 和三版本线实际完整回归尚未完成。 -- C02:底层 stop/destroy 抛 unchecked 异常时的收尾保护需要故障注入验证和补强;未知清理、取消/自然退出竞争及未确认后代的验收仍需继续。 +- C02:底层 stop/destroy 抛 unchecked 异常的收尾保护已有故障注入验证;取消/自然退出竞争、其他清理异常及未确认后代的验收仍需继续。 - C09:HTTP、WS、诊断和异常 cause 链仍需独立隐私回归;本地参数日志减少不构成全域完成。 - C03/C04/C05 尚未进入本轮新实现,C06/C07/C08 也尚未进入;不得跳过这些项关闭 C10。 - 1.x/JDK8、3.x/JDK21、真实 OpenCLI 输出采集、CodeGraph 索引以及独立代码评审未完成。不能用本批 JDK17 证据代替它们。 @@ -83,3 +83,7 @@ C01/C02 的 Change 继续 IN_PROGRESS;不能因为上述测试通过就整体 从现行 `feature/2.0.x` 建立 `feature/REQ-20261118-wandl-opencli-contracts-20`,合并旧草稿的 C10/C01/C02 实现,并保留现行基线新增的远端传输关闭和 `maxOutputBytes` 配置入口。输出超限按 C02 规格返回 `OUTPUT_LIMIT` 与有界部分结果;旧版“截断但成功”测试已改为核验该已确定的行为。新增自定义 `Object.toString()` 返回 null 的拒绝回归。 本地 JDK 17 `clean verify` 实际执行 2059 项 Java 测试,0 失败、0 错误、0 跳过;13 项 Python evidence-runner 自测通过;OpenSpec 1.14.1 strict 验证 10/10。修正 Surefire 的 JaCoCo agent 参数后,实际覆盖为 2550/2989 行(85.31%),低于现有 90% 告警目标;门禁配置未降低。当前新分支仍需自身精确提交的远端 CI、覆盖补足、C02 故障注入、跨平台和跨版本验证,因此 Change 保持进行中。 + +## 9. C02 清理操作异常回归 + +新增可控进程和 watchdog 故障注入:`destroy()` 抛异常时仍尝试强制终止;`watchdog.stop()` 抛异常时仍清理所拥有的进程;两种已确认退出路径都保留 `cleanupOperationFailed` 证据并释放许可。强制终止也失败时不虚构退出码,结果标记 `UNCONFIRMED`,隔离该 Runtime,拒绝后续启动。目标测试先以 2 项错误复现异常逃出清理路径,修复后扩展为 3 项通过。本地 JDK 17 完整 `clean verify` 执行 2062 项测试,0 失败、0 错误、0 跳过;实际 JaCoCo 2572/3008 行(85.51%),仍低于现有 90% 告警目标。此新增提交的远端 CI 需单独验证。 diff --git a/openspec/implementation-status.json b/openspec/implementation-status.json index dc7ed9b..e4476ec 100644 --- a/openspec/implementation-status.json +++ b/openspec/implementation-status.json @@ -8,15 +8,15 @@ "verifiedCodeTree": null, "runId": null, "previousEvidence": {"head": "3bacc8d09b1eeeaa05d6137e2a7e9c350d6622ce", "tree": "f421af093023fb11683fcd4334806f12d9aa140c", "runId": 35564455068}, - "localValidation": {"javaTests": 2059, "failures": 0, "errors": 0, "skipped": 0, "jacocoCoveredLines": 2550, "jacocoTotalLines": 2989, "jacocoTarget": 0.90, "pythonRunnerSelfTests": 13, "openspecStrictChangesPassed": 10}, - "javaTests": {"tests": 2059, "failures": 0, "errors": 0, "skipped": 0}, + "localValidation": {"javaTests": 2062, "failures": 0, "errors": 0, "skipped": 0, "jacocoCoveredLines": 2572, "jacocoTotalLines": 3008, "jacocoTarget": 0.90, "pythonRunnerSelfTests": 13, "openspecStrictChangesPassed": 10}, + "javaTests": {"tests": 2062, "failures": 0, "errors": 0, "skipped": 0}, "selectedContracts": {"argv": 43, "process": 14}, "pythonRunnerSelfTests": 13, "officialOpenSpec": {"version": "1.14.1", "strictChangesPassed": 10, "failed": 0}, "changes": { "C10": "FOUNDATION_IMPLEMENTED_ON_NAMED_FEATURE; FINAL_GATE_OPEN", "C01": "CORE_AND_NULL_STRING_EDGE_IMPLEMENTED; MULTIBRANCH_REVIEW_PENDING", - "C02": "CORE_IMPLEMENTED; CLEANUP_FAULT_INJECTION_AND_MULTIBRANCH_REVIEW_PENDING", + "C02": "CORE_AND_STOP_DESTROY_FAULT_INJECTION_IMPLEMENTED; CANCEL_RACE_AND_MULTIBRANCH_REVIEW_PENDING", "C03": "NOT_STARTED", "C04": "NOT_STARTED", "C05": "NOT_STARTED", 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 98530e3..6da55ff 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutionDetails.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutionDetails.java @@ -20,6 +20,8 @@ public enum CleanupState { NOT_STARTED, ROOT_EXIT_CONFIRMED, UNCONFIRMED } 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; 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 7c9dff1..2030935 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 @@ -30,6 +30,16 @@ * compatibility with the earlier low-level RunSession API. */ public final class SubprocessExecutionSupport { + @FunctionalInterface + interface ProcessStarter { + Process start(ProcessBuilder builder) throws IOException; + } + + @FunctionalInterface + interface WatchdogFactory { + ExecuteWatchdog create(long timeoutMillis); + } + 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; @@ -80,14 +90,23 @@ public static RunSession execute(ExecutionRequest request) throws IOException, I 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, timeoutMillis -> ExecuteWatchdog.builder() + .setTimeout(Duration.ofMillis(timeoutMillis)).get()); + } + + 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; } @@ -101,12 +120,12 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup Process process = null; Reader stdoutReader = null; Reader stderrReader = null; - ExecuteWatchdog watchdog = ExecuteWatchdog.builder() - .setTimeout(Duration.ofMillis(request.timeoutMillis)).get(); + ExecuteWatchdog watchdog = watchdogFactory.create(request.timeoutMillis); TerminationReason reason = null; IOException ioFailure = null; boolean acquired = false; boolean interrupted = false; + boolean cleanupOperationFailed = false; long queueWaitMillis = 0L; try { while (!acquired && reason == null) { @@ -146,15 +165,15 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup builder.environment().clear(); builder.environment().putAll(request.environment); } - process = builder.start(); + 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); - watchdog = ExecuteWatchdog.builder().setTimeout(Duration.ofMillis( - Math.max(1L, TimeUnit.NANOSECONDS.toMillis(Math.max(0L, remaining))))).get(); + watchdog = watchdogFactory.create( + Math.max(1L, TimeUnit.NANOSECONDS.toMillis(Math.max(0L, remaining)))); watchdog.start(process); while (reason == null) { if (out.isTruncated() || err.isTruncated()) { @@ -183,38 +202,53 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup ioFailure = ex; reason = process == null ? TerminationReason.SPAWN_FAILED : TerminationReason.IO_FAILURE; } finally { - watchdog.stop(); - long cleanupStart = System.nanoTime(); - long cleanupBudget = nanos(request.cleanupGraceMillis, "cleanupGraceMillis"); - if (process != null) { - if (process.isAlive()) { process.destroy(); } - boolean forceSent = false; - 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)) { - process.destroyForcibly(); - forceSent = true; + try { + try { + 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; } + } } - try { - TimeUnit.NANOSECONDS.sleep(Math.min(POLL_NANOS, - Math.max(1L, remaining(cleanupStart, cleanupBudget)))); - } catch (InterruptedException ex) { - interrupted = 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; } } } - if (process.isAlive()) { process.destroyForcibly(); } - 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(); } } - 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; @@ -233,6 +267,7 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup .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) @@ -244,6 +279,14 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup } 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); } 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..71c8c3e --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCleanupFaultTest.java @@ -0,0 +1,163 @@ +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 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]); + } + + 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; + + FakeWatchdog(boolean failStop) { + super(1000L); + this.failStop = failStop; + } + + @Override + public synchronized void start(Process process) { } + + @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; + + FakeProcess(boolean failDestroy) { this(failDestroy, false); } + + FakeProcess(boolean failDestroy, boolean failForce) { + this.failDestroy = failDestroy; + this.failForce = failForce; + } + + @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() { + 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; } + } +} From 1d66f1b3681593cf7e66f4af0f8fb6223d219960 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 10:49:55 +0800 Subject: [PATCH 016/146] test(opencli): cover simultaneous C02 terminal signals --- .../support/SubprocessCompletionRaceTest.java | 96 +++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 src/test/java/io/github/easy4j/opencli/core/support/SubprocessCompletionRaceTest.java 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..bc62a5f --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCompletionRaceTest.java @@ -0,0 +1,96 @@ +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.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.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()); + } + + 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; } + } +} From 527faf0b76705ac26392a7a7717c099ba33cceea Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 10:53:28 +0800 Subject: [PATCH 017/146] fix(opencli): retain reader I/O cause in terminal evidence --- .../support/SubprocessExecutionSupport.java | 4 +- .../support/SubprocessStreamFailureTest.java | 93 +++++++++++++++++++ 2 files changed, 96 insertions(+), 1 deletion(-) create mode 100644 src/test/java/io/github/easy4j/opencli/core/support/SubprocessStreamFailureTest.java 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 2030935..6db8447 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 @@ -183,7 +183,9 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup reason = TerminationReason.CANCELLED; } else if (request.cancellationToken.isCancelled()) { reason = TerminationReason.CANCELLED; - } else if (stdoutReader.failure != null || stderrReader.failure != null) { + } 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; 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; } + } +} From 177d7823ac662d271136b98bade87bda017b2c29 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:17:14 +0800 Subject: [PATCH 018/146] fix: contain watchdog startup failure after process spawn --- .../support/SubprocessExecutionSupport.java | 7 +++- .../support/SubprocessCleanupFaultTest.java | 41 ++++++++++++++++++- 2 files changed, 46 insertions(+), 2 deletions(-) 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 6db8447..b091a1a 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 @@ -174,7 +174,12 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup long remaining = remaining(request.submittedAtNanos, budget); watchdog = watchdogFactory.create( Math.max(1L, TimeUnit.NANOSECONDS.toMillis(Math.max(0L, remaining)))); - watchdog.start(process); + try { + watchdog.start(process); + } catch (RuntimeException ex) { + ioFailure = new IOException("Failed to start execution watchdog", ex); + reason = TerminationReason.IO_FAILURE; + } while (reason == null) { if (out.isTruncated() || err.isTruncated()) { reason = TerminationReason.OUTPUT_LIMIT; 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 71c8c3e..664422a 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 @@ -27,6 +27,35 @@ void watchdogStopFailureStillCleansOwnedChildAndReleasesPermit() throws Exceptio 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 unconfirmedForcedStopQuarantinesRuntimeWithoutFabricatingExit() throws Exception { OpenCliCancellationToken token = new OpenCliCancellationToken(); @@ -93,14 +122,24 @@ private static void assertCleanupSurvives(boolean failStop, boolean failDestroy) 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) { } + public synchronized void start(Process process) { + if (failStart) { + throw new IllegalStateException("injected watchdog start failure"); + } + } @Override public synchronized void stop() { From 5e2cd13effa0467448df6011bafcdfc70887ee71 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:26:09 +0800 Subject: [PATCH 019/146] fix: contain process setup failures after spawn --- .../support/SubprocessExecutionSupport.java | 9 ++- .../support/SubprocessCleanupFaultTest.java | 79 ++++++++++++++++++- 2 files changed, 83 insertions(+), 5 deletions(-) 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 b091a1a..4cabcb8 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 @@ -172,12 +172,12 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup stdoutReader.start(); stderrReader.start(); long remaining = remaining(request.submittedAtNanos, budget); - watchdog = watchdogFactory.create( - Math.max(1L, TimeUnit.NANOSECONDS.toMillis(Math.max(0L, remaining)))); 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 start execution watchdog", ex); + ioFailure = new IOException("Failed to initialize execution watchdog", ex); reason = TerminationReason.IO_FAILURE; } while (reason == null) { @@ -208,6 +208,9 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup } 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 { 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 664422a..0940ffc 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 @@ -56,6 +56,70 @@ void watchdogStartFailureStillCleansOwnedChildAndReleasesPermit() throws Excepti assertEquals(2, starts[0]); } + @Test + void watchdogCreationFailureAfterSpawnStillCleansChildAndReleasesPermit() throws Exception { + int[] starts = new int[1]; + int[] watchdogCreations = 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 -> { + if (++watchdogCreations[0] % 2 == 0) { + throw new IllegalStateException("injected watchdog creation failure"); + } + return 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 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(); @@ -157,16 +221,27 @@ private static final class FakeProcess extends Process { private boolean alive = true; private final boolean failForce; + private final boolean failStreamSetup; - FakeProcess(boolean failDestroy) { this(failDestroy, false); } + 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() { return new ByteArrayOutputStream(); } + 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]); } From 8f0d20593eec6d7ae247f6dda0b67707bca3d2dd Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:36:41 +0800 Subject: [PATCH 020/146] test: verify interrupted process cleanup and permit reuse --- .../support/SubprocessCompletionRaceTest.java | 94 +++++++++++++++++++ 1 file changed, 94 insertions(+) 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 index bc62a5f..c52b42c 100644 --- a/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCompletionRaceTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/support/SubprocessCompletionRaceTest.java @@ -8,6 +8,9 @@ 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; @@ -17,6 +20,7 @@ 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. */ @@ -55,6 +59,68 @@ void simultaneousSignalsKeepOneResultAndReuseThePermit() throws Exception { 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); } @@ -93,4 +159,32 @@ 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; } + } } From 8278dd794aa38c358b1d542c412e865ef0748c20 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:42:30 +0800 Subject: [PATCH 021/146] fix: keep remote HTTP diagnostics free of payloads --- pom.xml | 5 ++ .../remote/OpenCliRemoteAgentHttpClient.java | 39 ++++------ .../OpenCliRemoteAgentHttpClientTest.java | 75 ++++++++++++++++++- 3 files changed, 93 insertions(+), 26 deletions(-) diff --git a/pom.xml b/pom.xml index b3aeee9..f6f1ca4 100644 --- a/pom.xml +++ b/pom.xml @@ -175,6 +175,11 @@ junit-jupiter test + + org.slf4j + slf4j-simple + test + 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 b5a0b86..fa16b15 100644 --- a/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java +++ b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java @@ -1,7 +1,6 @@ package io.github.easy4j.opencli.remote; import com.fasterxml.jackson.annotation.JsonIgnoreProperties; -import com.fasterxml.jackson.core.JacksonException; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.json.JsonMapper; import io.github.easy4j.opencli.OpenCliProperties; @@ -73,7 +72,7 @@ public OpenCliResult collect(OpenCliCollectRequest request) { try { bodyJson = MAPPER.writeValueAsString(request); } catch (com.fasterxml.jackson.core.JsonProcessingException e) { - throw new OpenCliExecutableFailureException("Failed to serialize collect request: " + e.getMessage(), e); + throw new OpenCliExecutableFailureException("Failed to serialize collect request", null); } try { HttpResponse response = @@ -87,26 +86,18 @@ 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 status={} responseChars={}", status, respBody.length()); + throw new OpenCliExecutableFailureException("Agent HTTP " + status, null); } - return mapResponse(respBody, url); + return mapResponse(respBody); } 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"); + throw new OpenCliExecutableFailureException("Failed to parse agent response", null); } 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"); + throw new OpenCliExecutableFailureException("Agent HTTP I/O error", null); } } @@ -156,16 +147,15 @@ private int resolveTimeoutMillis() { return (int) Math.min(timeoutMs, Integer.MAX_VALUE); } - private OpenCliResult mapResponse(String respBody, String url) + private OpenCliResult mapResponse(String respBody) 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 responseChars={}", respBody.length()); + throw new OpenCliExecutableFailureException("Failed to parse agent response envelope", null); } boolean success = Objects.nonNull(env.success) && env.success; String err = Objects.isNull(env.error) ? "" : env.error; @@ -180,9 +170,8 @@ 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 errorChars={} stdoutLength={}", + err.length(), stdout.length()); OpenCliResult failed = OpenCliResult.builder() @@ -193,7 +182,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", failed); } return OpenCliResult.builder() .stdout(stdout) 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..71966d5 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,16 @@ 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.net.InetSocketAddress; import java.nio.charset.StandardCharsets; +import java.util.UUID; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; @@ -80,6 +84,71 @@ 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")); + 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 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 +178,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 +198,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); } From 137919ed329f1aa08ea64c241466503d658a9ccd Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:46:23 +0800 Subject: [PATCH 022/146] fix: omit parser input from debug diagnostics --- .../opencli/parser/OpenCliStdoutJson.java | 2 +- .../opencli/parser/OpenCliStdoutJsonTest.java | 25 +++++++++++++++++++ src/test/resources/simplelogger.properties | 1 + 3 files changed, 27 insertions(+), 1 deletion(-) create mode 100644 src/test/resources/simplelogger.properties 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/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/resources/simplelogger.properties b/src/test/resources/simplelogger.properties new file mode 100644 index 0000000..5124b74 --- /dev/null +++ b/src/test/resources/simplelogger.properties @@ -0,0 +1 @@ +org.slf4j.simpleLogger.log.io.github.easy4j.opencli.parser.OpenCliStdoutJson=debug From 345306c3164e816dfbe48258d6784cc75ea8e1ad Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:50:56 +0800 Subject: [PATCH 023/146] fix: keep WebSocket diagnostics free of URL payloads --- .../center/ws/OpenCliCenterWsUrls.java | 2 +- .../ws/OpenCliWsReverseAgentClient.java | 20 +++++------ .../center/ws/OpenCliCenterWsUrlsTest.java | 10 ++++++ .../ws/OpenCliWsReverseAgentClientTest.java | 33 +++++++++++++++++++ 4 files changed, 53 insertions(+), 12 deletions(-) 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/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)); + } } From 6e23120b7ba021a49caa95e4ab56c0b84a380789 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:53:36 +0800 Subject: [PATCH 024/146] fix: omit native process paths from public exceptions --- .../easy4j/opencli/core/OpenCliExecutor.java | 7 ++++--- .../opencli/core/OpenCliExecutorTest.java | 21 +++++++++++++++++++ 2 files changed, 25 insertions(+), 3 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 e56befa..9b853ae 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliExecutor.java @@ -165,7 +165,7 @@ commandLine, resolveWorkingDirectory(), buildEnvironment(), timeoutMillis, try { return complete(processRuntime.execute(request)); } catch (IOException ex) { - throw new OpenCliExecutableFailureException("OpenCLI process could not be started", ex); + throw new OpenCliExecutableFailureException("OpenCLI process could not be started", null); } catch (InterruptedException ex) { Thread.currentThread().interrupt(); throw new OpenCliException("Interrupted while awaiting OpenCLI subprocess", ex, null); @@ -193,12 +193,13 @@ private OpenCliResult complete(SubprocessExecutionSupport.RunSession session) { throw new OpenCliTimeoutException("OpenCLI deadline exceeded: " + reason, result); } if (reason == TerminationReason.SPAWN_FAILED) { - throw new OpenCliExecutableFailureException("OpenCLI process could not be started", session.getIoFailure(), result); + 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); } - throw new OpenCliException("OpenCLI execution ended: " + reason, session.getIoFailure(), result); + // Native I/O errors may include executable paths or other invocation data. + throw new OpenCliException("OpenCLI execution ended: " + reason, result); } private File resolveWorkingDirectory() { diff --git a/src/test/java/io/github/easy4j/opencli/core/OpenCliExecutorTest.java b/src/test/java/io/github/easy4j/opencli/core/OpenCliExecutorTest.java index 4df6963..d89f0d2 100644 --- a/src/test/java/io/github/easy4j/opencli/core/OpenCliExecutorTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/OpenCliExecutorTest.java @@ -4,8 +4,12 @@ import io.github.easy4j.opencli.OpenCliExecutionTarget; import io.github.easy4j.opencli.OpenCliProperties; import io.github.easy4j.opencli.exception.OpenCliExecutableFailureException; +import java.io.PrintWriter; +import java.io.StringWriter; +import java.nio.file.Path; import org.apache.commons.exec.CommandLine; import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; class OpenCliExecutorTest { @@ -74,4 +78,21 @@ void shouldThrowWhenWorkingDirectoryDoesNotExist() { OpenCliExecutor executor = new OpenCliExecutor(props); assertThrows(OpenCliExecutableFailureException.class, () -> executor.invoke("list")); } + @Test + void spawnFailureStackTraceOmitsExecutablePath(@TempDir Path directory) { + String canary = "private-executable-path-canary"; + OpenCliProperties props = new OpenCliProperties(); + props.setExecutable(directory.resolve(canary).toString()); + + try (OpenCliExecutor executor = new OpenCliExecutor(props)) { + OpenCliExecutableFailureException failure = assertThrows( + OpenCliExecutableFailureException.class, () -> executor.invoke("list")); + StringWriter diagnostics = new StringWriter(); + failure.printStackTrace(new PrintWriter(diagnostics)); + assertFalse(diagnostics.toString().contains(canary)); + assertEquals(OpenCliExecutionDetails.TerminationReason.SPAWN_FAILED, + failure.getPartialResult().getExecutionDetails().getTerminationReason()); + assertNull(failure.getPartialResult().getExitCode()); + } + } } From 1485788e3674d6e7eb72fbd02b2aed82ef49e3d1 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 13:00:23 +0800 Subject: [PATCH 025/146] fix: correlate payload-free remote HTTP diagnostics --- .../remote/OpenCliRemoteAgentHttpClient.java | 36 ++++++++++++------- .../OpenCliRemoteAgentHttpClientTest.java | 7 ++++ 2 files changed, 30 insertions(+), 13 deletions(-) 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 fa16b15..f1b89e1 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", null); + log.warn("Agent request serialization failed correlationId={}", correlationId); + throw failure("Failed to serialize collect request", correlationId); } try { HttpResponse response = @@ -86,18 +89,19 @@ public OpenCliResult collect(OpenCliCollectRequest request) { int status = response.getStatus(); String respBody = Objects.isNull(response.getBody()) ? "" : response.getBody(); if (status < 200 || status >= 300) { - log.warn("Agent HTTP non-2xx status={} responseChars={}", status, respBody.length()); - throw new OpenCliExecutableFailureException("Agent HTTP " + status, null); + log.warn("Agent HTTP non-2xx correlationId={} status={} responseChars={}", + correlationId, status, respBody.length()); + throw failure("Agent HTTP " + status, correlationId); } - return mapResponse(respBody); + return mapResponse(respBody, correlationId); } catch (OpenCliNonZeroExitException e) { throw e; } catch (com.fasterxml.jackson.core.JsonProcessingException e) { - log.warn("Agent response parse failed"); - throw new OpenCliExecutableFailureException("Failed to parse agent response", null); + log.warn("Agent response parse failed correlationId={}", correlationId); + throw failure("Failed to parse agent response", correlationId); } catch (UnirestException e) { - log.warn("Agent HTTP I/O failed"); - throw new OpenCliExecutableFailureException("Agent HTTP I/O error", null); + log.warn("Agent HTTP I/O failed correlationId={}", correlationId); + throw failure("Agent HTTP I/O error", correlationId); } } @@ -147,15 +151,20 @@ private int resolveTimeoutMillis() { return (int) Math.min(timeoutMs, Integer.MAX_VALUE); } - private OpenCliResult mapResponse(String respBody) + 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 responseChars={}", respBody.length()); - throw new OpenCliExecutableFailureException("Failed to parse agent response envelope", null); + log.warn("Agent response envelope parse failed correlationId={} responseChars={}", + correlationId, respBody.length()); + throw failure("Failed to parse agent response envelope", correlationId); } boolean success = Objects.nonNull(env.success) && env.success; String err = Objects.isNull(env.error) ? "" : env.error; @@ -170,7 +179,8 @@ private OpenCliResult mapResponse(String respBody) OpenCliParsedFields parsed = OpenCliOutputParser.parseBestEffort(stdout, err); if (!success) { log.warn( - "Agent collect reported failure errorChars={} stdoutLength={}", + "Agent collect reported failure correlationId={} errorChars={} stdoutLength={}", + correlationId, err.length(), stdout.length()); OpenCliResult failed = @@ -182,7 +192,7 @@ private OpenCliResult mapResponse(String respBody) .parsed(parsed) .remoteRawHttpBody(rawCapture) .build(); - throw new OpenCliNonZeroExitException("OpenCLI agent reported failure", 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/remote/OpenCliRemoteAgentHttpClientTest.java b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java index 71966d5..7a0b3ba 100644 --- a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java +++ b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java @@ -16,6 +16,8 @@ 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; @@ -110,6 +112,11 @@ void nonSuccessHttpResponseDoesNotExposeBodyCanaryInException() throws IOExcepti 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()) { From 611441d32b0b211aa4e9a247ec54186089cd50d9 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 17:37:58 +0800 Subject: [PATCH 026/146] Keep caller values out of OpenCLI debug logs --- .../browser/OpenCliBrowserSession.java | 22 +------------ .../remote/OpenCliArgvToCollectParser.java | 8 +---- .../browser/OpenCliBrowserArgvTest.java | 27 ++++++++++++++++ .../OpenCliArgvToCollectParserTest.java | 32 ++++++++++++++++++- src/test/resources/simplelogger.properties | 2 ++ 5 files changed, 62 insertions(+), 29 deletions(-) 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..7341ac7 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() { + 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)) { + 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); + 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..18b3959 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() { + 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)) { + 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); + 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 index 5124b74..25abecb 100644 --- a/src/test/resources/simplelogger.properties +++ b/src/test/resources/simplelogger.properties @@ -1 +1,3 @@ org.slf4j.simpleLogger.log.io.github.easy4j.opencli.parser.OpenCliStdoutJson=debug +org.slf4j.simpleLogger.log.io.github.easy4j.opencli.browser.OpenCliBrowserSession=debug +org.slf4j.simpleLogger.log.io.github.easy4j.opencli.remote.OpenCliArgvToCollectParser=debug From 129075895167419bb163c4ca95940e1cb84fcd52 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 17:40:14 +0800 Subject: [PATCH 027/146] Keep OpenCLI HTTP and argv errors safe to print --- .../opencli/core/OpenCliArgSupport.java | 2 +- .../remote/OpenCliRemoteAgentHttpClient.java | 5 +++ .../opencli/core/OpenCliArgSupportTest.java | 8 ++++- .../OpenCliRemoteAgentHttpClientTest.java | 31 +++++++++++++++++++ 4 files changed, 44 insertions(+), 2 deletions(-) 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 f1186a8..9531dbc 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliArgSupport.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliArgSupport.java @@ -62,7 +62,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/remote/OpenCliRemoteAgentHttpClient.java b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java index f1b89e1..482c411 100644 --- a/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java +++ b/src/main/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClient.java @@ -166,6 +166,11 @@ private OpenCliResult mapResponse(String respBody, String correlationId) 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; String stdout; 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 0dc6a8b..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 { @@ -62,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 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 7a0b3ba..6e8974e 100644 --- a/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java +++ b/src/test/java/io/github/easy4j/opencli/remote/OpenCliRemoteAgentHttpClientTest.java @@ -13,6 +13,8 @@ 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; @@ -126,6 +128,35 @@ void nonSuccessHttpResponseDoesNotExposeBodyCanaryInException() throws IOExcepti } } + @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(); From 0e1557f518c4adf43a4e723bcef24f9f4c11be26 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 17:47:22 +0800 Subject: [PATCH 028/146] Verify OpenCLI process privacy across supported JDK lines --- .../core/OpenCliProcessPrivacyTest.java | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java 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; + } +} From 72abff8d0d09918922886aef364a3b85c14f4d09 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 17:52:26 +0800 Subject: [PATCH 029/146] 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 97a142dc62a0f04d1cd398c868223a6c600fd06c Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 17:53:04 +0800 Subject: [PATCH 030/146] Record three-line diagnostic export verification --- .../harden-opencli-diagnostics-privacy/tasks.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/openspec/changes/harden-opencli-diagnostics-privacy/tasks.md b/openspec/changes/harden-opencli-diagnostics-privacy/tasks.md index 2f95b95..136f7f4 100644 --- a/openspec/changes/harden-opencli-diagnostics-privacy/tasks.md +++ b/openspec/changes/harden-opencli-diagnostics-privacy/tasks.md @@ -1,6 +1,6 @@ # C09 Tasks · 默认日志与异常的隐私边界 -> 全部为待执行实现任务。文档/格式检查通过不允许提前勾选。 +> 勾选项已有实现和对应测试证据。文档和格式检查单独记录。 关联规范:[spec](specs/opencli-diagnostics-privacy/spec.md)。 @@ -13,14 +13,23 @@ - [ ] 2.1 将commandLine/args/bodyPreview/remote error输出改成允许表元数据与correlationId。 - [ ] 2.2 实现安全异常摘要和cause处理,避免logger输出provider原始对象。 -- [ ] 2.3 保留raw业务结果与默认关闭的HTTPdebugcapture,新增显式有限export策略。 +- [x] 2.3 保留raw业务结果与默认关闭的HTTPdebugcapture,新增显式有限export策略。 ## 3. 验证 - [ ] 3.1 覆盖DEBUG、timeout、malformedresponse、断线和超限路径,任何canary出现均失败。 -- [ ] 3.2 验证raw结果内容未被脱敏逻辑无声修改。 +- [x] 3.2 验证raw结果内容未被脱敏逻辑无声修改。 - [ ] 3.3 三线执行相同隐私矩阵并记录证据;文档标明SDK与应用日志责任边界。 ## 证据交付模板(实施时填写) 每项任务的完成记录包含:Requirement/Scenario、分支HEAD、测试命令、失败→通过证据、测试数/跳过数、退出码、报告位置。没有记录的任务保持未完成。 + +## 2.3 与 3.2 验证记录 + +- OC-PRIV-003 与 OC-PRIV-005。公开入口为 `OpenCliDiagnosticExport.export(result, maxBytes)`。SDK 在内存中生成允许表投影,保留原始结果的内容,SDK 自身的导出保留时间为零。 +- `OpenCliDiagnosticExportTest` 覆盖原值保留、全量与截断、恰好满足预算、预算少一个字节、非法预算和缺失字段。API 缺失时验证失败,边界回归随后复现截断标记不一致。修复后全部通过。现有 HTTP 测试也验证原报文的显式捕获和默认关闭。 +- 1.0.x 功能分支提交 `295f1d32d2b00f7f3d1ae74eb4f95d792b309d9c`,JDK 8,`mvn -B --no-transfer-progress clean verify`,2016 个测试。 +- 2.0.x 功能分支实现提交 `72abff8d0d09918922886aef364a3b85c14f4d09`,JDK 17,`mvn -B --no-transfer-progress verify`,2087 个测试。 +- 3.0.x 功能分支提交 `6fa874a3c811733126350ca75beb750f78ba8956`,JDK 21,`bash ./mvnw -B --no-transfer-progress clean verify`,2016 个测试。 +- 三线本地构建退出码均为 0,失败、错误和跳过均为 0。报告位于各构建目录的 `target/surefire-reports`。其余场景和跨平台验收仍由相应任务跟踪。 From 5e6a36c68d2bfa34fc322190ca398bda717c78f5 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 20:43:21 +0800 Subject: [PATCH 031/146] Initialize OpenCLI watchdog only for spawned processes --- .../support/SubprocessExecutionSupport.java | 17 +++++++++---- .../support/SubprocessCleanupFaultTest.java | 25 +++++++++++++++---- 2 files changed, 32 insertions(+), 10 deletions(-) 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 4cabcb8..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 @@ -95,8 +95,7 @@ public static final class Runtime { private volatile boolean quarantined; public Runtime(int maxConcurrent) { - this(maxConcurrent, ProcessBuilder::start, timeoutMillis -> ExecuteWatchdog.builder() - .setTimeout(Duration.ofMillis(timeoutMillis)).get()); + this(maxConcurrent, ProcessBuilder::start, SubprocessExecutionSupport::newWatchdog); } Runtime(int maxConcurrent, ProcessStarter processStarter, WatchdogFactory watchdogFactory) { @@ -120,7 +119,7 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup Process process = null; Reader stdoutReader = null; Reader stderrReader = null; - ExecuteWatchdog watchdog = watchdogFactory.create(request.timeoutMillis); + ExecuteWatchdog watchdog = null; TerminationReason reason = null; IOException ioFailure = null; boolean acquired = false; @@ -214,7 +213,9 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup } finally { try { try { - watchdog.stop(); + if (Objects.nonNull(watchdog)) { + watchdog.stop(); + } } catch (RuntimeException ex) { cleanupOperationFailed = true; } @@ -282,12 +283,18 @@ public RunSession execute(ExecutionRequest request) throws IOException, Interrup .stderrCapturedBytes(err.size()).stderrObservedBytes(err.observed()).stderrTruncated(err.isTruncated()) .elapsedMillis(elapsedMillis(request.submittedAtNanos)).queueWaitMillis(queueWaitMillis) .descendantsExitConfirmed(false).build(); - return new RunSession(out, err, handler, watchdog, request.timeoutMillis, + // 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 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 { 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 0940ffc..79fd220 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 @@ -59,7 +59,6 @@ void watchdogStartFailureStillCleansOwnedChildAndReleasesPermit() throws Excepti @Test void watchdogCreationFailureAfterSpawnStillCleansChildAndReleasesPermit() throws Exception { int[] starts = new int[1]; - int[] watchdogCreations = new int[1]; FakeProcess[] last = new FakeProcess[1]; SubprocessExecutionSupport.Runtime runtime = new SubprocessExecutionSupport.Runtime(1, builder -> { @@ -67,10 +66,8 @@ void watchdogCreationFailureAfterSpawnStillCleansChildAndReleasesPermit() throws last[0] = new FakeProcess(false); return last[0]; }, timeout -> { - if (++watchdogCreations[0] % 2 == 0) { - throw new IllegalStateException("injected watchdog creation failure"); - } - return new FakeWatchdog(false); + assertNotNull(last[0], "watchdog must be created after spawn"); + throw new IllegalStateException("injected watchdog creation failure"); }); for (int attempt = 0; attempt < 2; attempt++) { @@ -151,6 +148,24 @@ void unconfirmedForcedStopQuarantinesRuntimeWithoutFabricatingExit() throws Exce 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); From 4aeae17eddd0833588561500fc6bb5de4b6cdbcc Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 20:48:38 +0800 Subject: [PATCH 032/146] Record verified OpenCLI lifecycle contracts across three JDK lines --- .../harden-opencli-process-lifecycle/tasks.md | 20 +++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/openspec/changes/harden-opencli-process-lifecycle/tasks.md b/openspec/changes/harden-opencli-process-lifecycle/tasks.md index 253d98a..c86aa34 100644 --- a/openspec/changes/harden-opencli-process-lifecycle/tasks.md +++ b/openspec/changes/harden-opencli-process-lifecycle/tasks.md @@ -1,6 +1,6 @@ # C02 Tasks · 有界执行、排队超时与进程清理 -> 全部为待执行实现任务。文档/格式检查通过不允许提前勾选。 +> 已勾选任务有对应实现和测试证据。 关联规范:[spec](specs/opencli-process-lifecycle/spec.md)。 @@ -11,16 +11,28 @@ ## 2. 执行核修复 -- [ ] 2.1 引入稳定 limiter 和单调 deadline,将许可等待纳入总预算。 -- [ ] 2.2 实现有限 capture、OUTPUT_LIMIT 和安全 UTF-8 截断策略。 +- [x] 2.1 引入稳定 limiter 和单调 deadline,将许可等待纳入总预算。 +- [x] 2.2 实现有限 capture、OUTPUT_LIMIT 和安全 UTF-8 截断策略。 - [ ] 2.3 实现统一终结路径与有限 cleanup,保护共享 daemon/用户进程。 ## 3. 兼容和证据 - [ ] 3.1 明确 0/负数配置语义、总预算与 cleanup grace、同步 follow 限制。 - [ ] 3.2 在三线和声明支持的 OS 上验证真实进程资源回收;能力缺口不得标绿。 -- [ ] 3.3 回归现有超时/UTF-8/异常测试,记录 HEAD、数量、跳过项和退出码。 +- [x] 3.3 回归现有超时/UTF-8/异常测试,记录 HEAD、数量、跳过项和退出码。 ## 证据交付模板(实施时填写) 每项任务的完成记录包含:Requirement/Scenario、分支HEAD、测试命令、失败→通过证据、测试数/跳过数、退出码、报告位置。没有记录的任务保持未完成。 + +## 2026-11-18 三线验证 + +OC-PROC-001/002 使用实际子进程验证独立及共享许可、排队超时前不启动进程。总预算实现使用 `System.nanoTime()`。OC-PROC-003 验证 stdout 和 stderr 的独立字节上限、超限部分结果、UTF-8 截断及反向执行器复制配置。Watchdog 故障注入和并发终结测试补充了 OC-PROC-004/005 的证据。 + +| JDK | 功能分支代码提交 | 验证 | +| --- | --- | --- | +| 8 | `3e1bfb3531ace72a504237bfc2ec838b92f9dc75` | 旧执行器的 `OpenCliProcessContractTest` 8 项失败。回移后 `mvn -B -ntp -o clean verify` 退出 0,2,087 项通过,0 失败、错误或跳过。[CI](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44307253778) | +| 17 | `5e6a36c68d2bfa34fc322190ca398bda717c78f5` | Watchdog 定向红灯 2 项失败,修复后定向 18 项通过。`mvn -B -ntp -o clean verify` 退出 0,2,088 项通过,0 失败、错误或跳过。[CI](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44306649188) | +| 21 | `a9d690675e1e7b5febab12eea2b17cfca77de4de` | 旧执行器的 `OpenCliProcessContractTest` 8 项失败。回移后 `bash ./mvnw -B -ntp -o clean verify` 退出 0,2,087 项通过,0 失败、错误或跳过。[CI](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44307253570) | + +各线的 JaCoCo 90% 告警门槛保留。完整后代所有权与回收证明、声明支持的 OS 实机矩阵、持续输出策略和独立评审仍待完成。 From 848a7d1aafd3872e041c964d077390de84dddf0e Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 20:52:01 +0800 Subject: [PATCH 033/146] docs: clarify OpenCLI local subprocess limits --- README.md | 9 +++++++-- README.zh-CN.md | 10 ++++++++-- .../changes/harden-opencli-process-lifecycle/tasks.md | 5 ++++- 3 files changed, 19 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 08ccaff..0957514 100644 --- a/README.md +++ b/README.md @@ -176,8 +176,12 @@ 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) | -| `maxConcurrentExecutions` | `0` | Max concurrent subprocesses (0 = unlimited) | +| `commandTimeoutMillis` | `300000` | Positive timeout in milliseconds. Local queueing and execution share one monotonic deadline. Remote mode uses an HTTP timeout. | +| `maxConcurrentExecutions` | `0` | Per-client subprocess capacity, fixed at construction. Zero uses `max(2, availableProcessors)`. Negative values are invalid. | +| `maxStdoutBytes` | `8388608` | Positive local stdout capture limit in bytes. | +| `maxStderrBytes` | `2097152` | Positive local stderr capture limit in bytes. | +| `maxOutputBytes` | `10485760` | Legacy ceiling for each local stream. A positive value can reduce either limit. A nonpositive value leaves the two stream limits in effect. | +| `cleanupGraceMillis` | `5000` | Positive, separate local cleanup grace in milliseconds. Timeout values must fit the monotonic nanosecond budget. | | `startupProbeTimeoutMillis` | `30000` | Availability-probe timeout | | `environment` | `{}` | Extra environment variables (e.g. `OPENCLI_CDP_ENDPOINT`) | | `remoteAgentBaseUrl` | — | Remote agent base URL | @@ -188,6 +192,7 @@ Configuration is object-based via `OpenCliProperties`: Notes: +- Local `browser console --follow` uses synchronous capture and the same finite timeout and byte limits. It returns collected output after completion or a terminal condition. It provides no live output stream. - 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. - `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 89693d5..cd8824a 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -175,8 +175,12 @@ cli.gemini().deepResearch("topic", | `executionTarget` | `LOCAL_PROCESS` | `LOCAL_PROCESS` 或 `REMOTE_AGENT_HTTP` | | `executable` | `opencli` | 可执行文件名或绝对路径 | | `workingDirectory` | — | 子进程工作目录 | -| `commandTimeoutMillis` | `300000` | 命令超时(毫秒;远程模式复用为 HTTP 超时) | -| `maxConcurrentExecutions` | `0` | 最大并发子进程数(0 = 不限) | +| `commandTimeoutMillis` | `300000` | 正数,单位毫秒。本地排队与执行共享同一个单调时钟预算,远程模式使用 HTTP 超时。 | +| `maxConcurrentExecutions` | `0` | 每个客户端的子进程并发数,构造时固定。零使用 `max(2, availableProcessors)`,负数无效。 | +| `maxStdoutBytes` | `8388608` | 本地标准输出采集上限,单位字节,必须为正数。 | +| `maxStderrBytes` | `2097152` | 本地标准错误采集上限,单位字节,必须为正数。 | +| `maxOutputBytes` | `10485760` | 每个本地输出流的兼容上限。正数可进一步降低各流的上限,非正数沿用分别配置的上限。 | +| `cleanupGraceMillis` | `5000` | 独立的本地清理等待上限,单位毫秒,必须为正数。时间配置必须可换算成单调时钟的纳秒预算。 | | `startupProbeTimeoutMillis` | `30000` | 可用性探测超时 | | `environment` | `{}` | 额外环境变量(如 `OPENCLI_CDP_ENDPOINT`) | | `remoteAgentBaseUrl` | — | 远程 Agent 根地址 | @@ -185,6 +189,8 @@ cli.gemini().deepResearch("topic", | `remoteCdpEndpoint` | — | 可选,覆盖 Agent 默认 CDP 端点 | | `remoteCaptureRawHttpResponse` | `false` | 在 `OpenCliResult#getRemoteRawHttpBody()` 中保留原始 HTTP 报文(大响应请谨慎开启) | +本地 `browser console --follow` 使用同步采集,仍受超时和输出字节上限约束。命令完成或进入终止状态后返回已采集输出,不提供实时输出流。 + 注意事项: - 远程模式下 `stdout` 为 Agent 返回的 `items` 的 JSON(已按 `format` 解析为行列表),与本地原始子进程文本可能不同;`leadingArguments` 等仅影响本地进程拼装,**远程路径不注入**。 diff --git a/openspec/changes/harden-opencli-process-lifecycle/tasks.md b/openspec/changes/harden-opencli-process-lifecycle/tasks.md index c86aa34..b161f76 100644 --- a/openspec/changes/harden-opencli-process-lifecycle/tasks.md +++ b/openspec/changes/harden-opencli-process-lifecycle/tasks.md @@ -17,7 +17,7 @@ ## 3. 兼容和证据 -- [ ] 3.1 明确 0/负数配置语义、总预算与 cleanup grace、同步 follow 限制。 +- [x] 3.1 明确 0/负数配置语义、总预算与 cleanup grace、同步 follow 限制。 - [ ] 3.2 在三线和声明支持的 OS 上验证真实进程资源回收;能力缺口不得标绿。 - [x] 3.3 回归现有超时/UTF-8/异常测试,记录 HEAD、数量、跳过项和退出码。 @@ -36,3 +36,6 @@ OC-PROC-001/002 使用实际子进程验证独立及共享许可、排队超时 | 21 | `a9d690675e1e7b5febab12eea2b17cfca77de4de` | 旧执行器的 `OpenCliProcessContractTest` 8 项失败。回移后 `bash ./mvnw -B -ntp -o clean verify` 退出 0,2,087 项通过,0 失败、错误或跳过。[CI](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44307253570) | 各线的 JaCoCo 90% 告警门槛保留。完整后代所有权与回收证明、声明支持的 OS 实机矩阵、持续输出策略和独立评审仍待完成。 + + +中英文 README 已对齐当前本地执行器的配置默认值、非法值、排队与执行共用预算、独立清理等待,以及同步 `--follow` 的限制。配置边界由 `OpenCliProcessBoundaryTest` 和 `OpenCliProcessContractTest` 验证。连续输出策略完整验收仍跟踪 OC-PROC-006。 From ae85c19b378b54e5918907bec70b0207d475d2f5 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:11:22 +0800 Subject: [PATCH 034/146] ci: verify OpenCLI subprocess contracts on macOS and Windows --- .github/workflows/contracts.yml | 55 +++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index 4919a4f..fa61bcb 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -135,3 +135,58 @@ jobs: target/surefire-reports target/site/jacoco if-no-files-found: error + + process-platform: + name: Subprocess contracts (${{ matrix.os }}) + if: github.ref_name == 'feature/REQ-20261118-wandl-opencli-contracts-20' + strategy: + fail-fast: false + matrix: + os: [macos-latest, 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: '17' + cache: maven + - uses: actions/setup-python@v7 + with: + python-version: '3.13' + - name: Exercise real subprocess contracts + run: | + mkdir -p platform-evidence + 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 \ + 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 \ + --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 From 7edcda4030a9c006a7d8a0e32245a301af199d14 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:16:59 +0800 Subject: [PATCH 035/146] fix: preserve literal quotes for Windows native executables --- .github/workflows/contracts.yml | 8 ++++ .../support/SubprocessExecutionSupport.java | 45 ++++++++++++++++++- .../contract/OpenCliArgvContractTest.java | 23 ++++++++++ .../opencli-contracts/argv-probe.cjs | 5 +++ 4 files changed, 80 insertions(+), 1 deletion(-) create mode 100644 src/test/resources/opencli-contracts/argv-probe.cjs diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index fa61bcb..f1c0b50 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -158,9 +158,17 @@ jobs: - 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 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..36082ce 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; @@ -158,7 +159,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(); @@ -305,6 +306,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..7287669 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,17 @@ 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.setLeadingArguments(Collections.singletonList(new File(location).getAbsolutePath())); + } catch (URISyntaxException e) { + throw new AssertionError("Invalid Windows argv fixture location", e); + } + } p.setCommandTimeoutMillis(10000L); return p; } @@ -96,6 +111,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 a41f548555d02fe3e31e42dee831bc6687f40ded Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:17:21 +0800 Subject: [PATCH 036/146] Report incomplete OpenCLI stream cleanup at the deadline --- .../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 36082ce..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 @@ -127,6 +127,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()) { @@ -249,7 +251,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; } @@ -265,7 +271,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)); @@ -277,8 +282,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 6fcd9ba25287b895e818b38919e98cc546dd3826 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:18:36 +0800 Subject: [PATCH 037/146] test: preserve mutable argv fixture prefixes on Windows --- .../easy4j/opencli/contract/OpenCliArgvContractTest.java | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 7287669..1bad49f 100644 --- a/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliArgvContractTest.java @@ -45,7 +45,8 @@ private static OpenCliProperties properties() { p.setExecutable(node); try { URI location = Objects.requireNonNull(probe, "Windows argv fixture is required").toURI(); - p.setLeadingArguments(Collections.singletonList(new File(location).getAbsolutePath())); + p.getLeadingArguments().clear(); + p.getLeadingArguments().add(new File(location).getAbsolutePath()); } catch (URISyntaxException e) { throw new AssertionError("Invalid Windows argv fixture location", e); } From a05e3c01256994db4229bc76b92accb27cccb03d Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:26:40 +0800 Subject: [PATCH 038/146] test: verify the installed Windows OpenCLI launch path --- .github/workflows/contracts.yml | 17 ++++++ README.md | 10 ++++ README.zh-CN.md | 10 ++++ .../contract/OpenCliInstalledLauncherIT.java | 59 +++++++++++++++++++ 4 files changed, 96 insertions(+) create mode 100644 src/test/java/io/github/easy4j/opencli/contract/OpenCliInstalledLauncherIT.java diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index f1c0b50..7687f76 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -189,6 +189,23 @@ jobs: --suite process=io.github.easy4j.opencli.contract.OpenCliProcessBoundaryTest \ --output platform-evidence/report.json exit "$result" + - name: Verify npm-installed OpenCLI on Windows + if: runner.os == 'Windows' + run: | + install_dir="$RUNNER_TEMP/opencli-launcher-check" + npm install --prefix "$install_dir" --ignore-scripts --no-audit --no-fund @jackwener/opencli@1.8.8 + package_dir="$install_dir/node_modules/@jackwener/opencli" + cli_entry="$package_dir/dist/src/main.js" + registry="$install_dir/registry.json" + node "$cli_entry" --version | tee platform-evidence/installed-opencli-version.txt + grep -Fx '1.8.8' platform-evidence/installed-opencli-version.txt + node "$cli_entry" list -f json > "$registry" + OPENCLI_INSTALLED_NODE="$(node -p 'process.execPath')" + OPENCLI_INSTALLED_ENTRY="$(cygpath -w "$cli_entry")" + OPENCLI_INSTALLED_REGISTRY="$(cygpath -w "$registry")" + OPENCLI_INSTALLED_BATCH_SHIM="$(cygpath -w "$install_dir/node_modules/.bin/opencli.cmd")" + export OPENCLI_INSTALLED_NODE OPENCLI_INSTALLED_ENTRY OPENCLI_INSTALLED_REGISTRY OPENCLI_INSTALLED_BATCH_SHIM + mvn -B --no-transfer-progress -Dtest=OpenCliInstalledLauncherIT test - name: Upload platform subprocess evidence if: always() uses: actions/upload-artifact@v7 diff --git a/README.md b/README.md index 0957514..2d07fc6 100644 --- a/README.md +++ b/README.md @@ -196,6 +196,16 @@ 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. - `execution-target=REMOTE_AGENT_HTTP` makes the availability probe report `SKIPPED_REMOTE_MODE` (treated as startable). +### Windows npm launcher + +For an npm-installed OpenCLI, configure the full path to `node.exe` and place the package's JavaScript entry point first in `leadingArguments`. Use the entry declared in the installed package's `bin.opencli` field. The SDK rejects `.cmd` and `.bat` executables because Windows batch shims parse arguments through a shell. + +```java +OpenCliProperties props = new OpenCliProperties(); +props.setExecutable("C:/Program Files/nodejs/node.exe"); +props.getLeadingArguments().add("C:/path/to/node_modules/@jackwener/opencli/dist/src/main.js"); +``` + ## 8. Core Usage diff --git a/README.zh-CN.md b/README.zh-CN.md index cd8824a..0d3653a 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -196,6 +196,16 @@ cli.gemini().deepResearch("topic", - 远程模式下 `stdout` 为 Agent 返回的 `items` 的 JSON(已按 `format` 解析为行列表),与本地原始子进程文本可能不同;`leadingArguments` 等仅影响本地进程拼装,**远程路径不注入**。 - `execution-target=REMOTE_AGENT_HTTP` 时可用性探测报告 `SKIPPED_REMOTE_MODE`(视为可启动)。 +### Windows npm 启动入口 + +通过 npm 安装 OpenCLI 时,将 `executable` 配为 `node.exe` 的完整路径,并将包的 JavaScript 入口放在 `leadingArguments` 首位。入口以已安装包的 `bin.opencli` 字段为准。Windows 批处理通过 Shell 解析参数,SDK 会明确拒绝将 `.cmd` 或 `.bat` 用作可执行文件。 + +```java +OpenCliProperties props = new OpenCliProperties(); +props.setExecutable("C:/Program Files/nodejs/node.exe"); +props.getLeadingArguments().add("C:/path/to/node_modules/@jackwener/opencli/dist/src/main.js"); +``` + ## 8. 核心用法 diff --git a/src/test/java/io/github/easy4j/opencli/contract/OpenCliInstalledLauncherIT.java b/src/test/java/io/github/easy4j/opencli/contract/OpenCliInstalledLauncherIT.java new file mode 100644 index 0000000..182fc5b --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/contract/OpenCliInstalledLauncherIT.java @@ -0,0 +1,59 @@ +package io.github.easy4j.opencli.contract; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import io.github.easy4j.opencli.OpenCliClient; +import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.core.OpenCliResult; +import java.io.File; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.Collections; +import java.util.Objects; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.condition.EnabledOnOs; +import org.junit.jupiter.api.condition.OS; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +class OpenCliInstalledLauncherIT { + + @Test + void nativeNodeLaunchReachesInstalledOpenCli() throws Exception { + OpenCliProperties properties = new OpenCliProperties(); + properties.setExecutable(requireFixture("OPENCLI_INSTALLED_NODE").toString()); + properties.setLeadingArguments(Collections.singletonList(requireFixture("OPENCLI_INSTALLED_ENTRY").toString())); + properties.setCommandTimeoutMillis(30_000L); + + try (OpenCliClient client = new OpenCliClient(properties)) { + OpenCliResult result = client.meta().list("json"); + assertTrue(result.isSuccess()); + ObjectMapper mapper = new ObjectMapper(); + JsonNode actual = mapper.readTree(result.getStdout()); + JsonNode expected = mapper.readTree(requireFixture("OPENCLI_INSTALLED_REGISTRY").toFile()); + assertTrue(actual.isArray()); + assertTrue(actual.size() > 0); + assertEquals(expected, actual); + } + } + + @Test + @EnabledOnOs(OS.WINDOWS) + void installedNpmBatchShimIsRejectedExplicitly() { + File shim = requireFixture("OPENCLI_INSTALLED_BATCH_SHIM").toFile(); + assertTrue(shim.isFile(), "npm must provide the Windows batch shim"); + OpenCliProperties properties = new OpenCliProperties(); + properties.setExecutable(shim.getAbsolutePath()); + try (OpenCliClient client = new OpenCliClient(properties)) { + UnsupportedOperationException error = assertThrows(UnsupportedOperationException.class, + () -> client.meta().list("json")); + assertTrue(error.getMessage().contains("native node executable")); + } + } + + private static Path requireFixture(String name) { + return Paths.get(Objects.requireNonNull(System.getenv(name), name + " fixture is required")); + } +} From d40f4deb3efecd6f9ad99dfeb4d1996443a69b86 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:31:46 +0800 Subject: [PATCH 039/146] test: exercise reverse WebSocket sessions with a real child process --- .../harden-opencli-reverse-agent/tasks.md | 4 + .../ws/OpenCliWsReverseAgentSessionTest.java | 196 ++++++++++++++++++ 2 files changed, 200 insertions(+) create mode 100644 src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java diff --git a/openspec/changes/harden-opencli-reverse-agent/tasks.md b/openspec/changes/harden-opencli-reverse-agent/tasks.md index f7ff684..86dd990 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、测试命令、失败→通过证据、测试数/跳过数、退出码、报告位置。没有记录的任务保持未完成。 + +## 2.0 线的现有协议回归证据 + +`OpenCliWsReverseAgentSessionTest` 在回环接口启动独立 WebSocket 服务,验证注册默认值、心跳、异常帧后的继续处理、collect 参数到真实子进程的传递、错误结果,以及注册前和注册后断线重连。JDK 17 `mvn -B -ntp -o clean verify` 通过 2,092 项测试,零失败、零错误、零跳过。JaCoCo XML 记录 2,806 / 3,067 行覆盖(91.49%)。准入、背压、去重、完整生命周期和三线验收仍由上面的任务跟踪。 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..fd2a5b3 --- /dev/null +++ b/src/test/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentSessionTest.java @@ -0,0 +1,196 @@ +package io.github.easy4j.opencli.center.ws; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import io.github.easy4j.opencli.OpenCliProperties; +import io.github.easy4j.opencli.contract.ContractProbe; +import java.io.File; +import java.io.IOException; +import java.net.InetSocketAddress; +import java.nio.charset.StandardCharsets; +import java.util.Arrays; +import java.util.Base64; +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 org.java_websocket.WebSocket; +import org.java_websocket.handshake.ClientHandshake; +import org.java_websocket.server.WebSocketServer; +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.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNotSame; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +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 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 LocalCenter() throws Exception { + super(new InetSocketAddress("127.0.0.1", 0), 1); + 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("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); + } + } +} From 55b31d452ae1919725e987d05add4cc466793bc0 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:33:14 +0800 Subject: [PATCH 040/146] fix: gate reverse WebSocket collection on registration --- .../harden-opencli-reverse-agent/tasks.md | 2 ++ .../ws/OpenCliWsReverseAgentClient.java | 6 +++++ .../ws/OpenCliWsReverseAgentSessionTest.java | 23 +++++++++++++++++++ 3 files changed, 31 insertions(+) diff --git a/openspec/changes/harden-opencli-reverse-agent/tasks.md b/openspec/changes/harden-opencli-reverse-agent/tasks.md index 86dd990..43c6652 100644 --- a/openspec/changes/harden-opencli-reverse-agent/tasks.md +++ b/openspec/changes/harden-opencli-reverse-agent/tasks.md @@ -29,3 +29,5 @@ ## 2.0 线的现有协议回归证据 `OpenCliWsReverseAgentSessionTest` 在回环接口启动独立 WebSocket 服务,验证注册默认值、心跳、异常帧后的继续处理、collect 参数到真实子进程的传递、错误结果,以及注册前和注册后断线重连。JDK 17 `mvn -B -ntp -o clean verify` 通过 2,092 项测试,零失败、零错误、零跳过。JaCoCo XML 记录 2,806 / 3,067 行覆盖(91.49%)。准入、背压、去重、完整生命周期和三线验收仍由上面的任务跟踪。 + +OC-WS-001 的提前收单场景使用子进程启动标记验证。旧实现收到 `registered` 之前的 collect 后会创建标记,定向用例因此失败。修复后同一回环请求收到明确失败结果,临时目录里没有启动标记。已注册成功的收单行为继续通过回归。JDK 17 `clean verify` 共通过 2,093 项测试,零跳过,JaCoCo 行覆盖率为 2,810 / 3,071(91.50%)。 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..c8aca4e 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 @@ -294,6 +294,12 @@ private void handleTextMessage( return; } if ("collect".equals(type)) { + if (shutdownRequested || !ws.isOpen() || registered.getCount() > 0 + || Objects.nonNull(handshakeFailure.get())) { + sendResult(ws, root.path("request_id").asText(""), false, Collections.emptyList(), + "worker is not registered"); + return; + } final JsonNode msg = root; collectPool.submit(() -> runCollectSafe(ws, msg)); } 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 fd2a5b3..e7d964c 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 @@ -4,10 +4,13 @@ import com.fasterxml.jackson.databind.ObjectMapper; 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.net.InetSocketAddress; import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; import java.util.Arrays; import java.util.Base64; import java.util.List; @@ -22,6 +25,7 @@ import org.java_websocket.handshake.ClientHandshake; import org.java_websocket.server.WebSocketServer; import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; @@ -89,6 +93,25 @@ void exchangesRegistrationAndCollectResultsAndReconnectsAfterRemoteClose() throw } } + @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 retriesAfterHandshakeCloseAndReturnsChildFailureToCenter() throws Exception { try (LocalCenter center = new LocalCenter(); From cddc1466e66c2a32af7cd68b1c18d6233e6a6f66 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 041/146] test: verify bounded OpenCLI network follow outcomes --- README.md | 2 +- README.zh-CN.md | 2 +- .../harden-opencli-process-lifecycle/tasks.md | 6 + .../opencli/contract/LifecycleProbe.java | 32 ++++++ .../contract/OpenCliProcessContractTest.java | 108 ++++++++++++++++++ 5 files changed, 148 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2d07fc6..27188b8 100644 --- a/README.md +++ b/README.md @@ -192,7 +192,7 @@ Configuration is object-based via `OpenCliProperties`: Notes: -- Local `browser console --follow` uses synchronous capture and the same finite timeout and byte limits. It returns collected output after completion or a terminal condition. It provides no live output stream. +- Local `browser console --follow` and `browser network --follow` use synchronous capture with a finite execution timeout and stdout/stderr byte limits. A successful CLI exit returns the collected output. Timeout, cancellation, excess output, and nonzero exit expose the termination reason and available partial output through the execution exception. A disabled command timeout is rejected before launch. Live streaming is unsupported. - 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. - `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 0d3653a..fbabed2 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -189,7 +189,7 @@ cli.gemini().deepResearch("topic", | `remoteCdpEndpoint` | — | 可选,覆盖 Agent 默认 CDP 端点 | | `remoteCaptureRawHttpResponse` | `false` | 在 `OpenCliResult#getRemoteRawHttpBody()` 中保留原始 HTTP 报文(大响应请谨慎开启) | -本地 `browser console --follow` 使用同步采集,仍受超时和输出字节上限约束。命令完成或进入终止状态后返回已采集输出,不提供实时输出流。 +本地 `browser console --follow` 和 `browser network --follow` 使用同步采集,受有限执行时限以及 stdout、stderr 字节上限约束。CLI 正常退出后返回采集结果。超时、中断、输出超限和非零退出时,可从执行异常取得终止原因与已有部分输出。禁用命令时限会在启动前被拒绝。当前接口仅支持同步采集。 注意事项: diff --git a/openspec/changes/harden-opencli-process-lifecycle/tasks.md b/openspec/changes/harden-opencli-process-lifecycle/tasks.md index b161f76..d5a7f00 100644 --- a/openspec/changes/harden-opencli-process-lifecycle/tasks.md +++ b/openspec/changes/harden-opencli-process-lifecycle/tasks.md @@ -39,3 +39,9 @@ OC-PROC-001/002 使用实际子进程验证独立及共享许可、排队超时 中英文 README 已对齐当前本地执行器的配置默认值、非法值、排队与执行共用预算、独立清理等待,以及同步 `--follow` 的限制。配置边界由 `OpenCliProcessBoundaryTest` 和 `OpenCliProcessContractTest` 验证。连续输出策略完整验收仍跟踪 OC-PROC-006。 + +## OC-PROC-006 本地同步采集验证 + +`OpenCliProcessContractTest` 经 typed `browser network --follow` 入口运行真实 JVM fixture,校验 CLI argv,并覆盖正常退出、CLI 非零退出、输出超限、调用线程中断、执行超时,以及禁用时限时启动前拒绝。超时测试同时启动独立进程,确认该进程仍运行并可自行正常退出。JDK 17 执行 `mvn -B -ntp -o clean verify` 退出 0,全量 2,099 项(其中该类 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 ec49fffb39915d04fe93bd3efed134ab79eab36b Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:38:23 +0800 Subject: [PATCH 042/146] fix: bound reverse WebSocket collect execution and waiting --- README.md | 2 + README.zh-CN.md | 2 + .../harden-opencli-reverse-agent/tasks.md | 4 +- .../OpenCliWsAgentConnectionProperties.java | 6 + .../ws/OpenCliWsReverseAgentClient.java | 32 +++-- .../ws/OpenCliWsReverseAgentSessionTest.java | 114 ++++++++++++++++++ 6 files changed, 149 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 27188b8..a6d16fb 100644 --- a/README.md +++ b/README.md @@ -239,6 +239,8 @@ 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`. + ### 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 fbabed2..be90bf8 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -239,6 +239,8 @@ 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`。 + ### 诊断导出 如需导出诊断,请调用 `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 43c6652..11ada97 100644 --- a/openspec/changes/harden-opencli-reverse-agent/tasks.md +++ b/openspec/changes/harden-opencli-reverse-agent/tasks.md @@ -12,7 +12,7 @@ ## 2. 治理实现 - [ ] 2.1 建立显式状态机及 READY gate,接收线程仅做有界解析与准入。 -- [ ] 2.2 用有限执行器替换 cached pool,加入容量校验和兼容 BUSY result。 +- [x] 2.2 用有限执行器替换 cached pool,加入容量校验和兼容 BUSY result。 - [ ] 2.3 实现 payload digest、在途记录与有界完成缓存;同 ID 不同载荷拒绝。 - [ ] 2.4 实现连接代际与有界 drain/cancel,CLOSED 终态。 @@ -31,3 +31,5 @@ `OpenCliWsReverseAgentSessionTest` 在回环接口启动独立 WebSocket 服务,验证注册默认值、心跳、异常帧后的继续处理、collect 参数到真实子进程的传递、错误结果,以及注册前和注册后断线重连。JDK 17 `mvn -B -ntp -o clean verify` 通过 2,092 项测试,零失败、零错误、零跳过。JaCoCo XML 记录 2,806 / 3,067 行覆盖(91.49%)。准入、背压、去重、完整生命周期和三线验收仍由上面的任务跟踪。 OC-WS-001 的提前收单场景使用子进程启动标记验证。旧实现收到 `registered` 之前的 collect 后会创建标记,定向用例因此失败。修复后同一回环请求收到明确失败结果,临时目录里没有启动标记。已注册成功的收单行为继续通过回归。JDK 17 `clean verify` 共通过 2,093 项测试,零跳过,JaCoCo 行覆盖率为 2,810 / 3,071(91.50%)。 + +OC-WS-002 使用实际子进程启动标记验证容量。旧实现启动第五个子进程,定向用例失败。修复后默认保持四个并行任务,等待任务在释放后启动。队列容量为零和一的用例验证超额请求返回 `worker is busy`,且从未启动对应子进程。负数、零并发及溢出配置在创建客户端时拒绝。 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/OpenCliWsReverseAgentClient.java b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsReverseAgentClient.java index c8aca4e..b6566a6 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 @@ -18,9 +18,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; @@ -53,13 +57,7 @@ public final class OpenCliWsReverseAgentClient implements AutoCloseable { 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 volatile boolean shutdownRequested; @@ -76,6 +74,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()); } @@ -300,8 +309,11 @@ private void handleTextMessage( "worker is not registered"); return; } - final JsonNode msg = root; - collectPool.submit(() -> runCollectSafe(ws, msg)); + try { + collectPool.execute(() -> runCollectSafe(ws, root)); + } catch (RejectedExecutionException e) { + sendResult(ws, root.path("request_id").asText(""), false, Collections.emptyList(), "worker is busy"); + } } } 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 e7d964c..a0e7a08 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 @@ -2,6 +2,7 @@ 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; @@ -13,6 +14,8 @@ import java.nio.file.Path; import java.util.Arrays; import java.util.Base64; +import java.util.HashSet; +import java.util.Set; import java.util.List; import java.util.Objects; import java.util.concurrent.BlockingQueue; @@ -26,12 +29,16 @@ import org.java_websocket.server.WebSocketServer; 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.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; class OpenCliWsReverseAgentSessionTest { @@ -112,6 +119,113 @@ void collectBeforeRegistrationAcknowledgementDoesNotStartChild(@TempDir Path tem } } + @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)); + } + + 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(); From e9330452418cbbc47351100b249735b9c3a52bb9 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:40:40 +0800 Subject: [PATCH 043/146] fix: cancel queued collect work on reverse worker close --- .../harden-opencli-reverse-agent/tasks.md | 2 ++ .../ws/OpenCliWsReverseAgentClient.java | 28 +++++++++++++++-- .../ws/OpenCliWsReverseAgentSessionTest.java | 31 +++++++++++++++++++ 3 files changed, 59 insertions(+), 2 deletions(-) diff --git a/openspec/changes/harden-opencli-reverse-agent/tasks.md b/openspec/changes/harden-opencli-reverse-agent/tasks.md index 11ada97..e780670 100644 --- a/openspec/changes/harden-opencli-reverse-agent/tasks.md +++ b/openspec/changes/harden-opencli-reverse-agent/tasks.md @@ -33,3 +33,5 @@ OC-WS-001 的提前收单场景使用子进程启动标记验证。旧实现收到 `registered` 之前的 collect 后会创建标记,定向用例因此失败。修复后同一回环请求收到明确失败结果,临时目录里没有启动标记。已注册成功的收单行为继续通过回归。JDK 17 `clean verify` 共通过 2,093 项测试,零跳过,JaCoCo 行覆盖率为 2,810 / 3,071(91.50%)。 OC-WS-002 使用实际子进程启动标记验证容量。旧实现启动第五个子进程,定向用例失败。修复后默认保持四个并行任务,等待任务在释放后启动。队列容量为零和一的用例验证超额请求返回 `worker is busy`,且从未启动对应子进程。负数、零并发及溢出配置在创建客户端时拒绝。 + +OC-WS-006 的关闭回归先复现旧实现关闭后仍启动队列任务。关闭现在丢弃队列、请求中断在途执行,并为执行器与重连线程共用最多 5 秒等待。回归验证队列中的子进程未启动、重复关闭安全、已关闭实例拒绝重启。JDK 17 `clean verify` 通过 2,108 项测试,零跳过,行覆盖率为 2,838 / 3,095(91.70%)。完整的断线代际及三线资源回收验收仍由对应任务跟踪。 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 b6566a6..dad1446 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 @@ -52,6 +52,7 @@ 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; @@ -92,6 +93,9 @@ public OpenCliWsReverseAgentClient( * 启动后台重连线程。 */ public synchronized void start() { + if (collectPool.isShutdown()) { + throw new IllegalStateException("WebSocket worker is closed"); + } if (runnerThread != null && runnerThread.isAlive()) { return; } @@ -122,8 +126,25 @@ public synchronized void stop() { @Override public void close() { - stop(); - collectPool.shutdown(); + Thread runner; + synchronized (this) { + if (collectPool.isShutdown()) { + return; + } + stop(); + collectPool.shutdownNow(); + 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() { @@ -318,6 +339,9 @@ private void handleTextMessage( } private void runCollectSafe(WebSocketClient ws, JsonNode msg) { + if (collectPool.isShutdown() || Thread.currentThread().isInterrupted()) { + return; + } String requestId = msg.path("request_id").asText(""); try { String site = msg.path("site").asText(""); 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 a0e7a08..5ef8dd3 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 @@ -211,6 +211,37 @@ void rejectsInvalidCapacityBeforeConnection(int workers, int pending) { () -> 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); + } + } + } + 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()); From 599ce1dcb69c6910c6d4d31231b420421830e735 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:48:24 +0800 Subject: [PATCH 044/146] fix: deduplicate reverse WebSocket collect requests --- README.md | 2 + README.zh-CN.md | 2 + .../harden-opencli-reverse-agent/tasks.md | 4 +- .../center/ws/OpenCliWsCollectRequests.java | 80 ++++++++ .../ws/OpenCliWsReverseAgentClient.java | 136 +++++++++----- .../ws/OpenCliWsCollectRequestsTest.java | 45 +++++ .../ws/OpenCliWsReverseAgentSessionTest.java | 177 +++++++++++++++++- .../opencli/contract/LifecycleProbe.java | 8 +- 8 files changed, 399 insertions(+), 55 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 diff --git a/README.md b/README.md index a6d16fb..298abc9 100644 --- a/README.md +++ b/README.md @@ -241,6 +241,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`. +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 be90bf8..048005a 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -241,6 +241,8 @@ 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 重启后会清空缓存。 + ### 诊断导出 如需导出诊断,请调用 `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 e780670..f53dec0 100644 --- a/openspec/changes/harden-opencli-reverse-agent/tasks.md +++ b/openspec/changes/harden-opencli-reverse-agent/tasks.md @@ -13,7 +13,7 @@ - [ ] 2.1 建立显式状态机及 READY gate,接收线程仅做有界解析与准入。 - [x] 2.2 用有限执行器替换 cached pool,加入容量校验和兼容 BUSY result。 -- [ ] 2.3 实现 payload digest、在途记录与有界完成缓存;同 ID 不同载荷拒绝。 +- [x] 2.3 实现 payload digest、在途记录与有界完成缓存;同 ID 不同载荷拒绝。 - [ ] 2.4 实现连接代际与有界 drain/cancel,CLOSED 终态。 ## 3. 兼容与验收 @@ -35,3 +35,5 @@ OC-WS-001 的提前收单场景使用子进程启动标记验证。旧实现收 OC-WS-002 使用实际子进程启动标记验证容量。旧实现启动第五个子进程,定向用例失败。修复后默认保持四个并行任务,等待任务在释放后启动。队列容量为零和一的用例验证超额请求返回 `worker is busy`,且从未启动对应子进程。负数、零并发及溢出配置在创建客户端时拒绝。 OC-WS-006 的关闭回归先复现旧实现关闭后仍启动队列任务。关闭现在丢弃队列、请求中断在途执行,并为执行器与重连线程共用最多 5 秒等待。回归验证队列中的子进程未启动、重复关闭安全、已关闭实例拒绝重启。JDK 17 `clean verify` 通过 2,108 项测试,零跳过,行覆盖率为 2,838 / 3,095(91.70%)。完整的断线代际及三线资源回收验收仍由对应任务跟踪。 + +OC-WS-003/004/005 本地回环验证覆盖 128 字节请求 ID 边界、相同请求在途去重、同 ID 不同载荷拒绝、完成缓存淘汰与过期。断线测试保留真实子进程在途,验证旧结果未主动发送到新连接。经过 JVM 信任及主机名校验的 TLS 连接显式重发后得到缓存结果。明文连接按会话隔离。缓存默认保留最近 1,024 条已完成结果,每条最多 10 分钟,进程重启后重新建立去重状态。JDK 17 全量构建通过 2,113 项测试,零失败、零跳过,JaCoCo 行覆盖率为 2,891 / 3,149(91.81%)。 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..edcda31 --- /dev/null +++ b/src/main/java/io/github/easy4j/opencli/center/ws/OpenCliWsCollectRequests.java @@ -0,0 +1,80 @@ +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 + } + + record Key(Object center, String requestId) { } + + record Admission(Status status, ObjectNode cachedResult) { } + + private record Completed(byte[] digest, ObjectNode result, long 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 dad1446..6d1462e 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; @@ -59,6 +60,8 @@ public final class OpenCliWsReverseAgentClient implements AutoCloseable { private final OpenCliWsAgentConnectionProperties connectionProperties; private final ExecutorService collectPool; + private final OpenCliWsCollectRequests collectRequests = + new OpenCliWsCollectRequests(1024, TimeUnit.MINUTES.toNanos(10), System::nanoTime); private volatile boolean shutdownRequested; @@ -133,6 +136,7 @@ public void close() { } stop(); collectPool.shutdownNow(); + collectRequests.clear(); runner = runnerThread; } long deadline = System.nanoTime() + CLOSE_WAIT_NANOS; @@ -183,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); @@ -193,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 { @@ -208,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"); } @@ -306,6 +311,7 @@ private String buildRegisterJson() throws Exception { private void handleTextMessage( WebSocketClient ws, + Object centerIdentity, String payload, CountDownLatch registered, AtomicReference handshakeFailure) @@ -324,25 +330,61 @@ private void handleTextMessage( return; } if ("collect".equals(type)) { + JsonNode id = root.path("request_id"); + String requestId = id.isTextual() ? id.textValue() : ""; + if (OpenCliStrings.isBlank(requestId.strip()) || 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, root.path("request_id").asText(""), false, Collections.emptyList(), - "worker is not registered"); + sendResult(ws, result(requestId, false, Collections.emptyList(), "worker is not registered")); return; } - try { - collectPool.execute(() -> runCollectSafe(ws, root)); - } catch (RejectedExecutionException e) { - sendResult(ws, root.path("request_id").asText(""), false, Collections.emptyList(), "worker is busy"); - } + admitCollect(ws, centerIdentity, requestId, root); } } - private void runCollectSafe(WebSocketClient ws, JsonNode msg) { - if (collectPool.isShutdown() || Thread.currentThread().isInterrupted()) { - return; + 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); } - 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(""); @@ -355,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"); } } @@ -427,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 index 5ef8dd3..e3a0d59 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 @@ -8,10 +8,13 @@ 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.HashSet; @@ -24,11 +27,16 @@ 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; @@ -41,6 +49,7 @@ 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(); @@ -242,6 +251,162 @@ void closeDropsQueuedCollectsAndRejectsRestart(@TempDir Path temporary) throws E } } + @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("界".repeat(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 = "界".repeat(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()); @@ -303,8 +468,18 @@ private static final class LocalCenter extends WebSocketServer implements AutoCl 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); @@ -314,7 +489,7 @@ private LocalCenter() throws Exception { private OpenCliWsAgentConnectionProperties agentProperties() { OpenCliWsAgentConnectionProperties properties = new OpenCliWsAgentConnectionProperties(); - properties.setCentralApiBaseUrl("http://127.0.0.1:" + getPort()); + properties.setCentralApiBaseUrl((secure ? "https" : "http") + "://127.0.0.1:" + getPort()); properties.setAgentAdvertiseUrl(AGENT_URL); properties.setMinReconnectDelayMillis(25); properties.setMaxReconnectDelayMillis(50); 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 5ba97e5ca2e3172d7cfa41e86c238387d8d10890 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 045/146] ci: exercise reverse WebSocket contracts across platforms --- .github/workflows/contracts.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index 7687f76..b5ecc9c 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -173,7 +173,7 @@ jobs: mvn -version > platform-evidence/maven.txt 2>&1 result=0 mvn -B --no-transfer-progress \ - -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest \ + -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,OpenCliWsReverseAgentSessionTest,OpenCliWsCollectRequestsTest \ test > platform-evidence/maven.log 2>&1 || result=$? tail -100 platform-evidence/maven.log python scripts/contract_report.py \ @@ -187,6 +187,8 @@ 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 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: Verify npm-installed OpenCLI on Windows From c327bc5e97e6fa691463621cf246e0246763247f 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 046/146] test: exercise OpenCLI process privacy across platforms --- .github/workflows/contracts.yml | 3 +- .../opencli/contract/LifecycleProbe.java | 24 +++++++++ .../core/OpenCliProcessPrivacyTest.java | 53 +++++++++++++------ 3 files changed, 64 insertions(+), 16 deletions(-) diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index b5ecc9c..9d15bb3 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -173,7 +173,7 @@ jobs: mvn -version > platform-evidence/maven.txt 2>&1 result=0 mvn -B --no-transfer-progress \ - -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,OpenCliWsReverseAgentSessionTest,OpenCliWsCollectRequestsTest \ + -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,OpenCliWsReverseAgentSessionTest,OpenCliWsCollectRequestsTest,OpenCliProcessPrivacyTest \ test > platform-evidence/maven.log 2>&1 || result=$? tail -100 platform-evidence/maven.log python scripts/contract_report.py \ @@ -189,6 +189,7 @@ jobs: --suite process=io.github.easy4j.opencli.contract.OpenCliProcessBoundaryTest \ --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: Verify npm-installed OpenCLI on Windows 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 d22a1937ca43f03cb17a707710fb8899fa963b6d Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:48:06 +0800 Subject: [PATCH 047/146] test: capture OpenCLI 1.8.8 error envelope fixtures --- .../evidence/2026-11-18-upstream-stderr.md | 39 +++++++++++++++++++ .../preserve-opencli-error-envelope/tasks.md | 4 +- .../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 ++++ 6 files changed, 64 insertions(+), 2 deletions(-) create mode 100644 openspec/changes/preserve-opencli-error-envelope/evidence/2026-11-18-upstream-stderr.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/tasks.md b/openspec/changes/preserve-opencli-error-envelope/tasks.md index fee0afa..eadcc70 100644 --- a/openspec/changes/preserve-opencli-error-envelope/tasks.md +++ b/openspec/changes/preserve-opencli-error-envelope/tasks.md @@ -1,12 +1,12 @@ # 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 与结果 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 42e1597cfdfb719d8e0e29cde76f3ace3cf893fb 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 048/146] 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 d5a7f00..1b5bf00 100644 --- a/openspec/changes/harden-opencli-process-lifecycle/tasks.md +++ b/openspec/changes/harden-opencli-process-lifecycle/tasks.md @@ -44,4 +44,16 @@ OC-PROC-001/002 使用实际子进程验证独立及共享许可、排队超时 `OpenCliProcessContractTest` 经 typed `browser network --follow` 入口运行真实 JVM fixture,校验 CLI argv,并覆盖正常退出、CLI 非零退出、输出超限、调用线程中断、执行超时,以及禁用时限时启动前拒绝。超时测试同时启动独立进程,确认该进程仍运行并可自行正常退出。JDK 17 执行 `mvn -B -ntp -o clean verify` 退出 0,全量 2,099 项(其中该类 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 ea9cccf77ac5555e7c007d68837e71d989b4bfa7 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 049/146] test: record OpenCLI error parser review evidence --- .../evidence/2026-11-18-yaml-parser-review.md | 16 ++++++++++++++++ .../preserve-opencli-error-envelope/tasks.md | 2 +- 2 files changed, 17 insertions(+), 1 deletion(-) create mode 100644 openspec/changes/preserve-opencli-error-envelope/evidence/2026-11-18-yaml-parser-review.md 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 eadcc70..b8ab4f1 100644 --- a/openspec/changes/preserve-opencli-error-envelope/tasks.md +++ b/openspec/changes/preserve-opencli-error-envelope/tasks.md @@ -11,7 +11,7 @@ ## 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。 From 9d2b43bc115e89a728c53fb066fa023c99cc56a5 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 050/146] 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 1b5bf00..323ffdc 100644 --- a/openspec/changes/harden-opencli-process-lifecycle/tasks.md +++ b/openspec/changes/harden-opencli-process-lifecycle/tasks.md @@ -57,3 +57,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 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,115 项通过,0 失败、0 错误、0 跳过。真实 OpenCLI 1.8.6 两项复验通过。4,500 ms 时限返回 `EXECUTION_TIMEOUT` 并保留 33 条完整事件。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 76248eb..0a1e041 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 @@ -362,7 +362,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; @@ -378,12 +378,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..4882af5 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 @@ -49,6 +49,22 @@ void shouldCapCapturedOutputAtMaxBytes() throws Exception { assertTrue(session.isStdoutOverflowed()); } + @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 shouldNotOverflowWhenCapDisabled() throws Exception { org.apache.commons.exec.CommandLine cmd = From dd4f395296821bb036730b09c8bfbc2d380d064e 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 051/146] 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 323ffdc..4269406 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. 执行核修复 @@ -64,4 +64,12 @@ JDK 17 红灯测试以 8,193 字节作为捕获上限,分两次写满,观察 JDK 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,115 项通过,0 失败、0 错误、0 跳过。真实 OpenCLI 1.8.6 两项复验通过。4,500 ms 时限返回 `EXECUTION_TIMEOUT` 并保留 33 条完整事件。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 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,116 项通过,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 0340522d3ed3818123ba7f776e23dd309d59282b 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 052/146] 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 4269406..72b5fab 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. 执行核修复 @@ -73,3 +73,11 @@ JDK 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,115 项通过,0 释放后,两次调用均确认根进程退出,四条输出流保留 393,224 字节,恰好达到两个执行槽的合计捕获预算,零截断。这个数值由执行详情测得,对应离线 fixture 的捕获量。JVM 整体堆内存还包含其他分配,本场景不对其计量。 JDK 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,116 项通过,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 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,117 项通过,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 6e599453360b8033d9a27e25e36261615a66ab35 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 053/146] 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 72b5fab..03c8b81 100644 --- a/openspec/changes/harden-opencli-process-lifecycle/tasks.md +++ b/openspec/changes/harden-opencli-process-lifecycle/tasks.md @@ -81,3 +81,11 @@ JDK 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,116 项通过,0 新增真实继承管道回归。根进程启动继承 stdout、stderr 的独立 JVM,后者通过文件汇报心跳。观察到后代进程启动后取消调用。清理宽限配置为 250 ms,测试允许 1,500 ms 等待窗口,包含线程调度。SDK 仍返回 `CANCELLED`,流未排空时必须报告 `UNCONFIRMED`,并且不声称后代已退出。断言取消后后代心跳仍更新,最后由测试自己的释放文件终止它。 JDK 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,117 项通过,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 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,118 项通过,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 0a1e041..5f550d6 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(); @@ -369,7 +370,7 @@ static final class BoundedCapture extends ByteArrayOutputStream { private boolean frozen; BoundedCapture(int limit) { - super(Math.min(8192, limit)); + super(0); this.limit = limit; } @@ -380,8 +381,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; @@ -410,7 +411,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 4882af5..ff2f918 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 @@ -49,6 +49,19 @@ void shouldCapCapturedOutputAtMaxBytes() throws Exception { assertTrue(session.isStdoutOverflowed()); } + @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 2a5ecb798063cd3d3e980d19dae00ce3f1a64689 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 054/146] fix: bound blocking OpenCLI process termination --- .github/workflows/contracts.yml | 4 +- .../harden-opencli-process-lifecycle/tasks.md | 8 ++ .../support/SubprocessExecutionSupport.java | 118 ++++++++++++++---- .../support/SubprocessCleanupFaultTest.java | 74 ++++++++++- 4 files changed, 176 insertions(+), 28 deletions(-) diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index 9d15bb3..90472d2 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -124,6 +124,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 \ --output contract-evidence/report.json - name: Upload actual JVM evidence if: always() @@ -173,7 +174,7 @@ jobs: mvn -version > platform-evidence/maven.txt 2>&1 result=0 mvn -B --no-transfer-progress \ - -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,OpenCliWsReverseAgentSessionTest,OpenCliWsCollectRequestsTest,OpenCliProcessPrivacyTest \ + -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,SubprocessCleanupFaultTest,OpenCliWsReverseAgentSessionTest,OpenCliWsCollectRequestsTest,OpenCliProcessPrivacyTest \ test > platform-evidence/maven.log 2>&1 || result=$? tail -100 platform-evidence/maven.log python scripts/contract_report.py \ @@ -187,6 +188,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 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 \ diff --git a/openspec/changes/harden-opencli-process-lifecycle/tasks.md b/openspec/changes/harden-opencli-process-lifecycle/tasks.md index 03c8b81..34188fc 100644 --- a/openspec/changes/harden-opencli-process-lifecycle/tasks.md +++ b/openspec/changes/harden-opencli-process-lifecycle/tasks.md @@ -89,3 +89,11 @@ JDK 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,117 项通过,0 修复后,第一次非空写入才分配对应捕获数组,仍受流的配置上限约束。预取消路径的 stdout、stderr 容量均为零,读取线程的工作缓冲和 JVM 总堆内存属独立指标。红灯 2 项失败,修复后 JDK 17 定向 33 项通过。 JDK 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,118 项通过,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 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,120 项通过,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 5f550d6..98aa0ee 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 01513226e14c4e73e0ed602332285d407a1489a9 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 055/146] 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..1fe2c4a 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 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,121 项通过,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 324b9e1613cea07dadaa8e346f0203f0a5dfa217 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 056/146] 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 1fe2c4a..70c77cf 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 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,121 项通过,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 76e92d47469355effe49560e6e929ac231d9a941 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 057/146] 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 f53dec0..8c4dbda 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. 治理实现 @@ -37,3 +37,9 @@ OC-WS-002 使用实际子进程启动标记验证容量。旧实现启动第五 OC-WS-006 的关闭回归先复现旧实现关闭后仍启动队列任务。关闭现在丢弃队列、请求中断在途执行,并为执行器与重连线程共用最多 5 秒等待。回归验证队列中的子进程未启动、重复关闭安全、已关闭实例拒绝重启。JDK 17 `clean verify` 通过 2,108 项测试,零跳过,行覆盖率为 2,838 / 3,095(91.70%)。完整的断线代际及三线资源回收验收仍由对应任务跟踪。 OC-WS-003/004/005 本地回环验证覆盖 128 字节请求 ID 边界、相同请求在途去重、同 ID 不同载荷拒绝、完成缓存淘汰与过期。断线测试保留真实子进程在途,验证旧结果未主动发送到新连接。经过 JVM 信任及主机名校验的 TLS 连接显式重发后得到缓存结果。明文连接按会话隔离。缓存默认保留最近 1,024 条已完成结果,每条最多 10 分钟,进程重启后重新建立去重状态。JDK 17 全量构建通过 2,113 项测试,零失败、零跳过,JaCoCo 行覆盖率为 2,891 / 3,149(91.81%)。 + +## 2026-11-19 OC-WS-005/006 代际发布与停止竞态 + +`stopDuringConnectionSetupDoesNotPublishAnotherGeneration` 在连接线程读取端点时阻塞配置读取,随后调用 `stop()`,再解除阻塞。修复前本地中心收到已停止 worker 的注册消息,1 项失败,退出 1。修复后停止和连接发布共用同步边界,晚到连接无法发布。异常、关闭及退出均只退役对应 socket,当前代际检查用于注册、收单和异步结果投递。同一个已验证 TLS 中心显式重发仍可读取对应缓存。异常的默认日志保持固定文本。 + +`OpenCliWsReverseAgentSessionTest` 的回环服务同时覆盖提前收单、空白和超大 ID、队列溢出、重复请求、断线时在途工作、TLS 显式重发、明文会话隔离、关闭丢弃队列及关闭后拒绝重启。JDK 17 定向验证 27 项通过。JDK 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,122 项通过,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 6d1462e..e37bc8a 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 e3a0d59..f002fe4 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 @@ -55,6 +55,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 ae4d409eb29a216218c2de63eac7879caa84aa2b 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 058/146] 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 298abc9..57470a1 100644 --- a/README.md +++ b/README.md @@ -241,7 +241,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 048005a..541761f 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -241,7 +241,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 8c4dbda..eaccdf7 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,接收线程仅做有界解析与准入。 - [x] 2.2 用有限执行器替换 cached pool,加入容量校验和兼容 BUSY result。 - [x] 2.3 实现 payload digest、在途记录与有界完成缓存;同 ID 不同载荷拒绝。 -- [ ] 2.4 实现连接代际与有界 drain/cancel,CLOSED 终态。 +- [x] 2.4 实现连接代际与有界 drain/cancel,CLOSED 终态。见 OC-WS-006 验证。 ## 3. 兼容与验收 @@ -43,3 +43,11 @@ OC-WS-003/004/005 本地回环验证覆盖 128 字节请求 ID 边界、相同 `stopDuringConnectionSetupDoesNotPublishAnotherGeneration` 在连接线程读取端点时阻塞配置读取,随后调用 `stop()`,再解除阻塞。修复前本地中心收到已停止 worker 的注册消息,1 项失败,退出 1。修复后停止和连接发布共用同步边界,晚到连接无法发布。异常、关闭及退出均只退役对应 socket,当前代际检查用于注册、收单和异步结果投递。同一个已验证 TLS 中心显式重发仍可读取对应缓存。异常的默认日志保持固定文本。 `OpenCliWsReverseAgentSessionTest` 的回环服务同时覆盖提前收单、空白和超大 ID、队列溢出、重复请求、断线时在途工作、TLS 显式重发、明文会话隔离、关闭丢弃队列及关闭后拒绝重启。JDK 17 定向验证 27 项通过。JDK 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,122 项通过,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 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,123 项通过,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 e37bc8a..4fd4384 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 f002fe4..4d674c8 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 @@ -259,6 +259,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 e2b956c5dcdea91c5c7c5bb3b3afeded57c0da87 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 059/146] 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 57470a1..0352d46 100644 --- a/README.md +++ b/README.md @@ -241,6 +241,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 541761f..43fd637 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -241,6 +241,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 eaccdf7..ae7a940 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,接收线程仅做有界解析与准入。见本文入站验证。 - [x] 2.2 用有限执行器替换 cached pool,加入容量校验和兼容 BUSY result。 - [x] 2.3 实现 payload digest、在途记录与有界完成缓存;同 ID 不同载荷拒绝。 - [x] 2.4 实现连接代际与有界 drain/cancel,CLOSED 终态。见 OC-WS-006 验证。 @@ -51,3 +51,11 @@ OC-WS-003/004/005 本地回环验证覆盖 128 字节请求 ID 边界、相同 已启动任务保留去重占位到实际执行收尾。等待任务撤销时释放占位。重连使用原有固定线程池及其容量。终态 `close()` 仍立即取消在途工作,丢弃队列并在共用预算内等待资源回收,关闭后拒绝重启。 JDK 17 定向 28 项通过。JDK 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,123 项通过,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 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,129 项通过,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 4fd4384..de6109c 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,7 +1,9 @@ package io.github.easy4j.opencli.center.ws; +import com.fasterxml.jackson.databind.DeserializationFeature; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.ObjectReader; import com.fasterxml.jackson.databind.node.ArrayNode; import com.fasterxml.jackson.databind.node.ObjectNode; import io.github.easy4j.opencli.OpenCliProperties; @@ -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 4d674c8..8d78dce 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; @@ -31,6 +32,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; @@ -167,6 +169,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"); @@ -552,6 +616,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; @@ -595,7 +660,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 8c3e96c3c443e94e728f91e3df545dd146b815f3 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 060/146] 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 ae7a940..9177dd9 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,记录执行次数、线程数与终结资源结果。 ## 证据交付模板(实施时填写) @@ -59,3 +59,9 @@ JDK 17 定向 28 项通过。JDK 17 使用系统 Maven 执行 `-B -ntp -o clean JDK 17 定向红灯复现三项失败,退出 1。拼接 JSON 错误推进注册,超长单帧和分片均未关闭连接。修复后验证合法确认仍可接单,两个超限场景均关闭连接、没有 CLI 标记且重新注册。发送单个超长帧时,接收方可能在对端写完前关闭连接,对端可观察到 1006 或 1009。分片超限场景验证 1009。补充拒绝零、负数及库定义的无限哨兵设置。JDK 17 定向 34 项通过。 JDK 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,129 项通过,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 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,130 项通过,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 de6109c..1a42f68 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 0b888208173bb1d6e4f4f9729ac750d27ae81f85 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 061/146] 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 9177dd9..5e70280 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,记录执行次数、线程数与终结资源结果。 ## 证据交付模板(实施时填写) @@ -65,3 +65,11 @@ JDK 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,129 项通过,0 在 TLS 回环环境向第一次结果发送注入异常,CLI 子进程实际写入执行标记。修复前中心等待第二次注册超时,定向 2 项中 1 项失败,退出 1。修复后失败连接退役。第二条连接完成注册和心跳时,中心仍未收到自动投递。中心显式重发相同请求后,收到原成功结果和 `cached: true`,`error` 为空,实际子进程标记始终为一条。日志捕获包含固定的投递失败消息,异常内测试密钥未出现在日志中。 旧协议夹具继续核对 register 的五个字段、pong 的单字段、成功与失败 result 的五个字段,以及实际进程收到的完整 argv。三个版本的直接字段断言通过。JDK 17 定向 35 项通过。JDK 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,130 项通过,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 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,131 项通过,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 ef0319a..14aa442 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 @@ -238,6 +238,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 d0ecad713ae181fee380e45363bddb623503f5d8 Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:37:00 +0800 Subject: [PATCH 062/146] ci: add Intel macOS subprocess coverage --- .github/workflows/contracts.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index 90472d2..629e8bb 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -143,7 +143,7 @@ jobs: strategy: fail-fast: false matrix: - os: [macos-latest, windows-latest] + os: [macos-latest, macos-15-intel, windows-latest] runs-on: ${{ matrix.os }} timeout-minutes: 15 defaults: From f3022d42b8db38a9c1804cf98332a9370704c26a 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 063/146] 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 0352d46..ea8a427 100644 --- a/README.md +++ b/README.md @@ -253,6 +253,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 43fd637..3de88a0 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -253,6 +253,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 136f7f4..c2a83f8 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,9 +17,9 @@ ## 3. 验证 -- [ ] 3.1 覆盖DEBUG、timeout、malformedresponse、断线和超限路径,任何canary出现均失败。 +- [x] 3.1 覆盖DEBUG、timeout、malformedresponse、断线和超限路径,任何canary出现均失败。 - [x] 3.2 验证raw结果内容未被脱敏逻辑无声修改。 -- [ ] 3.3 三线执行相同隐私矩阵并记录证据;文档标明SDK与应用日志责任边界。 +- [x] 3.3 三线执行相同隐私矩阵并记录证据;文档标明SDK与应用日志责任边界。 ## 证据交付模板(实施时填写) @@ -33,3 +33,17 @@ - 2.0.x 功能分支实现提交 `72abff8d0d09918922886aef364a3b85c14f4d09`,JDK 17,`mvn -B --no-transfer-progress verify`,2087 个测试。 - 3.0.x 功能分支提交 `6fa874a3c811733126350ca75beb750f78ba8956`,JDK 21,`bash ./mvnw -B --no-transfer-progress clean verify`,2016 个测试。 - 三线本地构建退出码均为 0,失败、错误和跳过均为 0。报告位于各构建目录的 `target/surefire-reports`。其余场景和跨平台验收仍由相应任务跟踪。 + +## 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 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,134 项通过,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 98aa0ee..41a4e07 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) { @@ -560,6 +560,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..ac993a6 100644 --- a/src/test/java/io/github/easy4j/opencli/core/OpenCliArgSupportTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/OpenCliArgSupportTest.java @@ -1,6 +1,8 @@ package io.github.easy4j.opencli.core; import static org.junit.jupiter.api.Assertions.*; +import java.io.PrintWriter; +import java.io.StringWriter; import java.util.ArrayList; import java.util.Arrays; import java.util.List; @@ -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..5e741f4 100644 --- a/src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java +++ b/src/test/java/io/github/easy4j/opencli/core/OpenCliProcessPrivacyTest.java @@ -16,12 +16,14 @@ import org.junit.jupiter.api.Test; import org.junit.jupiter.api.function.Executable; import org.junit.jupiter.api.io.TempDir; +import org.junit.jupiter.api.parallel.Isolated; 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; +@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 ff2f918..440d82e 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,10 +1,34 @@ package io.github.easy4j.opencli.core.support; import static org.junit.jupiter.api.Assertions.*; +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 org.junit.jupiter.api.Test; class SubprocessExecutionSupportTest { + @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 25abecb..84d9f17 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.parser.OpenCliStdoutJson=debug 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.core.OpenCliAdapterChannel=debug From f2e9e037b30b1c71782e92a03f83bf3d8670188b 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 064/146] ci: require exception privacy evidence on hosted platforms --- .github/workflows/contracts.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index 629e8bb..337d929 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -174,7 +174,7 @@ jobs: mvn -version > platform-evidence/maven.txt 2>&1 result=0 mvn -B --no-transfer-progress \ - -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,SubprocessCleanupFaultTest,OpenCliWsReverseAgentSessionTest,OpenCliWsCollectRequestsTest,OpenCliProcessPrivacyTest \ + -Dtest=OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,SubprocessCleanupFaultTest,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 \ @@ -192,6 +192,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: Verify npm-installed OpenCLI on Windows From e16dd2d52b73aa87ecffbc26935b59a602814275 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 065/146] docs: align OpenCLI consumer examples with the version line --- README.md | 29 +++++++++++++++-------------- README.zh-CN.md | 29 +++++++++++++++-------------- 2 files changed, 30 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index ea8a427..96a9084 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-17-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/2.0.x` +> **Version**: `2.0.x.20260630-SNAPSHOT` +> **JDK baseline**: 17 +> **Release notes**: [2.0.x.20260630](https://github.com/easy-4-java/opencli-java-sdk/releases/tag/v2.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 | 17+ | 2.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.22.1 | 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 + 2.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:2.0.x.20260630-SNAPSHOT' ``` Snapshot builds require an enabled snapshot repository (Aliyun Maven snapshot repository per `distributionManagement` in `pom.xml`). @@ -272,9 +273,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 3de88a0..62487c7 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-17-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/2.0.x` +> **版本**:`2.0.x.20260630-SNAPSHOT` +> **JDK 基线**:17 +> **发布说明**:[2.0.x.20260630](https://github.com/easy-4-java/opencli-java-sdk/releases/tag/v2.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 | 17+ | 2.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.22.1 | JSON 解析 | | SLF4J | 2.0.18 | 日志门面 | 版本线矩阵: @@ -132,14 +133,14 @@ Maven: io.github.easy4j opencli-java-sdk - 3.0.x.20260630-SNAPSHOT + 2.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:2.0.x.20260630-SNAPSHOT' ``` 快照版本需要启用对应快照仓库(`pom.xml` 中 `distributionManagement` 指向 Aliyun Maven 仓库)。 @@ -272,9 +273,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 cf9360e99647c935d7ee10c87a391ed602647682 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 066/146] Reject malformed legacy collect response envelopes Refs #5 --- 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 96a9084..3247bea 100644 --- a/README.md +++ b/README.md @@ -195,6 +195,7 @@ Notes: - Local `browser console --follow` and `browser network --follow` use synchronous capture with a finite execution timeout and stdout/stderr byte limits. A successful CLI exit returns the collected output. Timeout, cancellation, excess output, and nonzero exit expose the termination reason and available partial output through the execution exception. A disabled command timeout is rejected before launch. Live streaming is unsupported. - 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). ### Windows npm launcher diff --git a/README.zh-CN.md b/README.zh-CN.md index 62487c7..cdb3f8f 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -195,6 +195,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`(视为可启动)。 ### Windows npm 启动入口 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 e5c745d459707477061e298d48e5f47604253f9f Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:16:34 +0800 Subject: [PATCH 067/146] docs: record verified OpenCLI branch build evidence --- .../design.md | 2 +- .../tasks.md | 20 ++++++++++++++++--- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/openspec/changes/enforce-opencli-branch-contract-parity/design.md b/openspec/changes/enforce-opencli-branch-contract-parity/design.md index 2d8d0f9..46df17e 100644 --- a/openspec/changes/enforce-opencli-branch-contract-parity/design.md +++ b/openspec/changes/enforce-opencli-branch-contract-parity/design.md @@ -50,7 +50,7 @@ C10基础(锁定/fixture runner/门禁框架)先做;C10最终关闭需选 ## Migration plan -在已补回的coverage基础上增量强化契约与适配测试,修复仍存在的README工具声明和示例。规范只有完成评审、实现和真实验收后才archive到openspec/specs;本包全部implementation tasks保持unchecked。 +在已补回的coverage基础上增量强化契约与适配测试,修复仍存在的README工具声明和示例。已验证的准备任务及其证据记录在 tasks.md;规范只有完成评审、实现和真实验收后才archive到openspec/specs。 每条版本线的迁移分开验证:Java8/17/21、Jackson2/3、各自Maven wrapper。保留现有公开门面,涉及失败行为收紧时提供调用示例与兼容边界。 diff --git a/openspec/changes/enforce-opencli-branch-contract-parity/tasks.md b/openspec/changes/enforce-opencli-branch-contract-parity/tasks.md index f3ad8ba..e503eb1 100644 --- a/openspec/changes/enforce-opencli-branch-contract-parity/tasks.md +++ b/openspec/changes/enforce-opencli-branch-contract-parity/tasks.md @@ -1,6 +1,6 @@ # C10 Tasks · 共享契约测试、分支差异与上游锁定 -> 全部为待执行实现任务。文档/格式检查通过不允许提前勾选。 +> 已验收的准备任务见下方证据。文档/格式检查通过不允许提前勾选。 关联规范:[spec](specs/opencli-branch-contract-parity/spec.md)。 @@ -13,8 +13,8 @@ ## 2. 上游与文档 - [ ] 2.1 采集锁定上游的实际help/manifest/output,保存hash与范围,移除对作者绝对路径的依赖。 -- [ ] 2.2 修正各分支README/POMdescription/Gradle示例,检查Java/Jackson/Maven实际声明。 -- [ ] 2.3 配置三线正确wrapper/JDK的独立构建与报告,不通过修改coverage阈值绕开行为问题。 +- [x] 2.2 修正各分支README/POMdescription/Gradle示例,检查Java/Jackson/Maven实际声明。 +- [x] 2.3 配置三线正确wrapper/JDK的独立构建与报告,不通过修改coverage阈值绕开行为问题。 ## 3. 最终集成门禁 @@ -26,3 +26,17 @@ ## 证据交付模板(实施时填写) 每项任务的完成记录包含:Requirement/Scenario、分支HEAD、测试命令、失败→通过证据、测试数/跳过数、退出码、报告位置。没有记录的任务保持未完成。 + +### 2.2 与 2.3 的三线验收 + +OC-PARITY-005:以表中检出的三条线为准,逐条核对中英文 README 的 Maven 和 Gradle 坐标、POM 描述与 Java/Jackson 声明,以及 Wrapper 的分发版本。三个版本的坐标均为 `io.github.easy4j:opencli-java-sdk`,分别使用 `1.0.x.20260630-SNAPSHOT`、`2.0.x.20260630-SNAPSHOT` 和 `3.0.x.20260630-SNAPSHOT`。 + +OC-PARITY-004:维护线原 CI 将 JaCoCo 参数丢在 Surefire JVM 之外,构建成功时仍缺执行数据。修复后的各线 CI 使用其 Wrapper 执行 `./mvnw -B --no-transfer-progress clean verify`。三次退出码均为 0,Surefire XML 的失败、错误、跳过数均为 0,且均上传了 `surefire-reports` 和 `jacoco-coverage`。三条线保留 90% 行覆盖率告警阈值,并要求上传 JaCoCo 报告。 + +| JDK | Wrapper Maven | Jackson | 构建提交 | 测试数 | 行覆盖率 | GitHub CI | +| --- | --- | --- | --- | ---: | ---: | --- | +| 8 | 3.9.16 | 2.18.9 | `aaa295fc6e65708554ab7bb55cf7c05fb990f6ae` | 2144 | 3043/3303(92.13%) | [44356116353](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44356116353) | +| 17 | 3.9.16 | 2.22.1 | `cf9360e99647c935d7ee10c87a391ed602647682` | 2145 | 3030/3286(92.21%) | [44355648596](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44355648596) | +| 21 | 4.0.0-rc-5 | 3.2.1 | `fa7e001da203d31fd5afb2921f90c3f428db2d5b` | 2144 | 3028/3285(92.18%) | [44356116107](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44356116107) | + +上述记录覆盖文档事实和分支构建。最终集成门禁仍按第 3 节逐项验收。 From a5448e1fdc40f26d3931e98bee7919dc7eef1c67 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 068/146] Reject lossy legacy collect argv before dispatch Refs #5 --- 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 3247bea..3b4bfc0 100644 --- a/README.md +++ b/README.md @@ -196,6 +196,7 @@ Notes: - Local `browser console --follow` and `browser network --follow` use synchronous capture with a finite execution timeout and stdout/stderr byte limits. A successful CLI exit returns the collected output. Timeout, cancellation, excess output, and nonzero exit expose the termination reason and available partial output through the execution exception. A disabled command timeout is rejected before launch. Live streaming is unsupported. - 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). ### Windows npm launcher diff --git a/README.zh-CN.md b/README.zh-CN.md index cdb3f8f..b078984 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -196,6 +196,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`(视为可启动)。 ### Windows npm 启动入口 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 624e7586da0317e4ae36fa06b1e2d4b01d91004d 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 069/146] Preserve executor overrides for local passthrough Refs #5 --- .../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 bf05ba69dbaaa27002c874ce72b4bee2707c3f64 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 070/146] Bound decoded legacy collect response bodies Refs #5 --- 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 3b4bfc0..996443b 100644 --- a/README.md +++ b/README.md @@ -190,6 +190,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 b078984..0feeb45 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -189,6 +189,7 @@ cli.gemini().deepResearch("topic", | `remoteOutputFormat` | `json` | 向 Agent 请求的输出格式 | | `remoteCdpEndpoint` | — | 可选,覆盖 Agent 默认 CDP 端点 | | `remoteCaptureRawHttpResponse` | `false` | 在 `OpenCliResult#getRemoteRawHttpBody()` 中保留原始 HTTP 报文(大响应请谨慎开启) | +| `maxRemoteResponseBytes` | `10485760` | HTTP 解压后的响应体字节上限,须为正数。超限抛出 `OpenCliRemoteResponseLimitException`,含 HTTP 状态和上限。原文捕获受同一上限约束。 | 本地 `browser console --follow` 和 `browser network --follow` 使用同步采集,受有限执行时限以及 stdout、stderr 字节上限约束。CLI 正常退出后返回采集结果。超时、中断、输出超限和非零退出时,可从执行异常取得终止原因与已有部分输出。禁用命令时限会在启动前被拒绝。当前接口仅支持同步采集。 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 9466220..ccd1e8e 100644 --- a/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java +++ b/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java @@ -24,6 +24,8 @@ public class OpenCliProperties { private String remoteCdpEndpoint = ""; /** Raw HTTP capture is explicitly opt-in and may contain sensitive business data. */ private boolean remoteCaptureRawHttpResponse = false; + /** Maximum decoded HTTP response body bytes accepted from a remote Agent. */ + private int maxRemoteResponseBytes = 10 * 1024 * 1024; private String executable = "opencli"; private String workingDirectory; /** Total local queue plus execution budget; remote mode uses an HTTP timeout. */ 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 8d826a11a5f56c926c1df4946e07390caa65dc0c 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 071/146] Apply a total budget to legacy HTTP collect Refs #5 --- 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 996443b..fd8ec00 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 | 17+ | 2.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.22.1 | 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` | Positive timeout in milliseconds. Local queueing and execution share one monotonic deadline. Remote mode uses an HTTP timeout. | +| `commandTimeoutMillis` | `300000` | Positive timeout in milliseconds. Local queueing and execution share one monotonic deadline. Remote pool acquisition, connection and response reading share the invocation budget. | | `maxConcurrentExecutions` | `0` | Per-client subprocess capacity, fixed at construction. Zero uses `max(2, availableProcessors)`. Negative values are invalid. | | `maxStdoutBytes` | `8388608` | Positive local stdout capture limit in bytes. | | `maxStderrBytes` | `2097152` | Positive local stderr capture limit in bytes. | @@ -198,6 +198,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). ### Windows npm launcher diff --git a/README.zh-CN.md b/README.zh-CN.md index 0feeb45..7cf8009 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 | 17+ | 2.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.22.1 | 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` | 每个客户端的子进程并发数,构造时固定。零使用 `max(2, availableProcessors)`,负数无效。 | | `maxStdoutBytes` | `8388608` | 本地标准输出采集上限,单位字节,必须为正数。 | | `maxStderrBytes` | `2097152` | 本地标准错误采集上限,单位字节,必须为正数。 | @@ -198,6 +198,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`(视为可启动)。 ### Windows npm 启动入口 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 ccd1e8e..97017a3 100644 --- a/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java +++ b/src/main/java/io/github/easy4j/opencli/OpenCliProperties.java @@ -9,7 +9,7 @@ /** * OpenCLI runtime configuration without Spring dependencies. * Local execution uses a monotonic submission-to-exit deadline; cleanup has a - * separate finite grace. Remote HTTP retains its own transport timeout semantics. + * separate finite grace. Remote HTTP uses one invocation budget for transport I/O. * * @author Loong Wan * @since 3.0.0 @@ -28,7 +28,7 @@ public class OpenCliProperties { private int maxRemoteResponseBytes = 10 * 1024 * 1024; private String executable = "opencli"; private String workingDirectory; - /** Total local queue plus execution budget; remote mode uses an HTTP timeout. */ + /** Total local queue and execution budget, or the remote HTTP transport budget. */ private long commandTimeoutMillis = 300_000L; /** Legacy per-stream ceiling; nonpositive values keep the finite stdout/stderr budgets. */ private long maxOutputBytes = 10L * 1024 * 1024; 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 106585e16ea67c6bfde5fc827b1913e4bc73cec9 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 072/146] Retain status and exit provenance for legacy collect Refs #5 --- 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 fd8ec00..a6258fb 100644 --- a/README.md +++ b/README.md @@ -199,6 +199,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). ### Windows npm launcher diff --git a/README.zh-CN.md b/README.zh-CN.md index 7cf8009..c4333b8 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -199,6 +199,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`(视为可启动)。 ### Windows npm 启动入口 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 b1fd2e4..6dd9af2 100644 --- a/src/main/java/io/github/easy4j/opencli/core/OpenCliResult.java +++ b/src/main/java/io/github/easy4j/opencli/core/OpenCliResult.java @@ -24,4 +24,6 @@ public class OpenCliResult { private final String remoteRawHttpBody; /** Observed local execution metadata; null for a legacy remote result. */ 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 b40ed5a91ed357478fe0f05b4936e4ac3508ec31 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 073/146] Send explicit collect credentials only over verified HTTPS Refs #5 --- README.md | 1 + README.zh-CN.md | 1 + .../harden-opencli-remote-collect/tasks.md | 9 +- .../easy4j/opencli/OpenCliProperties.java | 5 + .../opencli/OpenCliRemoteAuthentication.java | 38 +++++ .../remote/OpenCliRemoteAgentHttpClient.java | 31 +++- .../ws/OpenCliWsReverseAgentSessionTest.java | 40 +---- .../OpenCliRemoteAgentHttpClientTest.java | 152 +++++++++++++++++- .../testsupport/OpenCliTlsFixture.java | 59 +++++++ 9 files changed, 288 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 a6258fb..60a9d06 100644 --- a/README.md +++ b/README.md @@ -200,6 +200,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). ### Windows npm launcher diff --git a/README.zh-CN.md b/README.zh-CN.md index c4333b8..5883653 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -200,6 +200,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`(视为可启动)。 ### Windows npm 启动入口 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 97017a3..e8b9ede 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 without Spring dependencies. @@ -18,7 +19,11 @@ public class OpenCliProperties { private OpenCliExecutionTarget executionTarget = OpenCliExecutionTarget.LOCAL_PROCESS; /** Root URL of an opencli-admin compatible Agent. */ + @ToString.Exclude private String remoteAgentBaseUrl; + /** Explicit credential header for the configured HTTPS Agent. */ + @ToString.Exclude + private OpenCliRemoteAuthentication remoteAuthentication; private String remoteCollectMode = "cdp"; private String remoteOutputFormat = "json"; private String remoteCdpEndpoint = ""; 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 14aa442..e8fc9a0 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; @@ -9,15 +10,12 @@ import java.io.ByteArrayOutputStream; import java.io.File; import java.io.IOException; -import java.io.InputStream; import java.io.PrintStream; 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.HashSet; @@ -31,9 +29,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; @@ -559,40 +555,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 0cbb3ee750062675813f1d3389c5f7f14b50345c Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:53:35 +0800 Subject: [PATCH 074/146] Verify authenticated HTTPS collect across the three JDK lines --- README.md | 2 +- README.zh-CN.md | 2 +- .../harden-opencli-remote-collect/tasks.md | 18 ++++++++++++++++-- .../OpenCliRemoteAgentHttpClientTest.java | 12 ++++++++---- 4 files changed, 26 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 60a9d06..73aa4d9 100644 --- a/README.md +++ b/README.md @@ -185,7 +185,7 @@ Configuration is object-based via `OpenCliProperties`: | `cleanupGraceMillis` | `5000` | Positive, separate local cleanup grace in milliseconds. Timeout values must fit the monotonic nanosecond budget. | | `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 5883653..3dfd8f1 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -184,7 +184,7 @@ cli.gemini().deepResearch("topic", | `cleanupGraceMillis` | `5000` | 独立的本地清理等待上限,单位毫秒,必须为正数。时间配置必须可换算成单调时钟的纳秒预算。 | | `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/openspec/changes/harden-opencli-remote-collect/tasks.md b/openspec/changes/harden-opencli-remote-collect/tasks.md index 5f6f2b0..26b879b 100644 --- a/openspec/changes/harden-opencli-remote-collect/tasks.md +++ b/openspec/changes/harden-opencli-remote-collect/tasks.md @@ -14,12 +14,12 @@ - [ ] 2.1 引入显式 legacy capability guard 和保真转换子集,避免无条件解析任意 argv。 - [x] 2.2 区分 HTTP、协议与命令失败,保留兼容退出码及其来源。见 OC-REMOTE-003/004 验证。 -- [ ] 2.3 使 body/timeout 有界并实现可测试的显式 header 配置,保持 TLS。 +- [x] 2.3 使 body/timeout 有界并实现可测试的显式 header 配置,保持 TLS。见 OC-REMOTE-005/006 验证。 ## 3. 三线与安全 - [x] 3.1 验证凭据、URL query、正文和异常 cause 的默认诊断边界。见 OC-REMOTE-006 验证。 -- [ ] 3.2 在三分支分别跑本地 HTTP fixture;记录旧 API 的行为收紧与迁移例子。 +- [x] 3.2 在三分支分别跑本地 HTTP fixture;记录旧 API 的行为收紧与迁移例子。见三线验证。 - [ ] 3.3 未取得服务端契约的扩展仍标记 unsupported,不借此宣称远程全量兼容。 ## 证据交付模板(实施时填写) @@ -69,3 +69,17 @@ JDK 17 基线中,chunked 响应每 125 ms 持续发送数据,900 ms 的原 基线先增加配置和夹具,尚未接入传输。HTTPS 认证成功、明文认证拒绝及三类 URL 凭据输入共 5 项验收失败。接入后,回环 HTTPS 服务使用独立测试证书和显式信任。未信任的证书在请求转交应用处理器前被拒绝。信任证书后,桩仅在明确收到正确的指定请求头时返回成功。去除配置后按 401 处理,不自动生成认证数据。错误凭据的 401 回显未出现在默认日志、异常栈或原文捕获关闭时的失败快照中。 显式认证采用 SDK 已有 Apache HttpClient 的 HTTPS 校验。明文认证、URL 用户信息、查询参数和片段均在发送前拒绝。测试复用了 WebSocket 的回环证书生成方式。真实 Agent 可接受的请求头和生产认证流程仍待部署契约验证。 + +### 三线验证 + +以分别包含显式 HTTPS 认证的 `c03aac0`、`b40ed5a`、`1ee75dc` 为基线,补测带部署路径前缀的 HTTPS Agent。原基址 `https:///agent///` 在桩上实际到达 `/agent/collect`,认证值由指定请求头传递,URL 和请求体中均没有认证值。普通 HTTP 的认证请求、包含用户信息或查询或片段的基址继续在发起 HTTP 前拒绝。配置样例见中英文 README,认证值从调用方环境读取。 + +三条线分别使用其 Wrapper 执行 `./mvnw -B -ntp clean verify`,退出码均为 0。每条线的 `OpenCliRemoteAgentHttpClientTest` 均运行 54 项,零失败、错误和跳过。下表是构建实测。日志、Surefire XML 和 JaCoCo XML 由对应构建产生。 + +| JDK | 路径前缀验证提交 | 全量测试数 | 行覆盖率 | +| --- | --- | ---: | ---: | +| 8 | `f0286587c9caa98aa50fa4d4ab0045d23776b453` | 2178 | 92.44% | +| 17 | 本提交的路径前缀测试,基于 `b40ed5a91ed357478fe0f05b4936e4ac3508ec31` | 2179 | 92.53% | +| 21 | `85de78f4e847ac1c1ff73d855573954a5898e9ee` | 2178 | 92.52% | + +这组测试覆盖可控 HTTP 和 HTTPS 服务端。真实 opencli-admin 部署的认证协议及扩展契约仍待验收。 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 3406ee03b8751cebbd6c68d510c04c634cff3f69 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 075/146] Capture OpenCLI 1.8.8 structured help contracts Refs #5 --- .../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 64d0abaca8a784304ef73646b375f5fc4afc403d Mon Sep 17 00:00:00 2001 From: loong10k <20489781+loong10k@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:59:43 +0800 Subject: [PATCH 076/146] Keep raw availability details out of startup diagnostics --- README.md | 2 ++ README.zh-CN.md | 2 ++ .../harden-opencli-diagnostics-privacy/tasks.md | 7 +++++++ .../availability/OpenCliAvailabilityReport.java | 17 ++--------------- .../OpenCliAvailabilityReportTest.java | 13 ++++++++----- 5 files changed, 21 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 73aa4d9..78148bf 100644 --- a/README.md +++ b/README.md @@ -260,6 +260,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 3dfd8f1..7084a18 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -260,6 +260,8 @@ collect 请求 ID 必须为非空白字符串,长度上限 128 个 UTF-8 字 SDK 在内存中返回文本,由应用决定目的地和保留时间。SDK 诊断会排除命令参数、原始内容、URL 和文件路径。应用读取或记录原始结果时应自行保护这些数据。`remoteCaptureRawHttpResponse` 仍需显式开启。 +`OpenCliAvailabilityReport.toDiagnosticMessage()` 可用于启动日志,只输出就绪状态和状态码。需要查看可执行文件路径或原始探测消息时,调用对应的 getter。 + 低层进程接口的 `RunSession.getHandler().getException()` 返回安全的 I/O 摘要。`RunSession.getIoFailure()` 是显式读取原始诊断的入口,异常可能包含本地路径,应按敏感数据处理。 diff --git a/openspec/changes/harden-opencli-diagnostics-privacy/tasks.md b/openspec/changes/harden-opencli-diagnostics-privacy/tasks.md index c2a83f8..7825505 100644 --- a/openspec/changes/harden-opencli-diagnostics-privacy/tasks.md +++ b/openspec/changes/harden-opencli-diagnostics-privacy/tasks.md @@ -45,5 +45,12 @@ JDK 17 两项定向红灯实际退出 1。选项对象的 `toString()` 抛出带 | HTTP 503、凭据 URL、畸形 JSON、原文捕获开关 | `OpenCliRemoteAgentHttpClientTest` | | WebSocket 断线和投递异常、配置 URL、日志测试密钥 | `OpenCliWsReverseAgentSessionTest`、`OpenCliWsReverseAgentClientTest` | | JSON 解析 DEBUG、默认不写入的有界导出 | `OpenCliStdoutJsonTest`、`OpenCliDiagnosticExportTest` | +| 启动日志的可用性摘要,配置和探测原始值的显式读取 | `OpenCliAvailabilityReportTest` | JDK 17 使用系统 Maven 执行 `-B -ntp -o clean verify`,2,134 项通过,0 失败、0 错误、0 跳过。中英文 README 记录应用显式访问原始低层诊断的责任。C03 的 YAML 解码器仍待实施,对其解析日志的验证保留在后续矩阵中。 + +## 启动诊断摘要验证 + +JDK 17 基线 `0cbb3ee750062675813f1d3389c5f7f14b50345c` 的定向用例在 3 项中失败 1 项。面向日志的 `toDiagnosticMessage()` 输出了配置值、解析后的可执行文件路径和原始探测消息。修改后,该方法只输出就绪状态和状态码。用例继续断言 `getConfiguredExecutable()`、`getResolvedExecutablePath()` 和 `getMessage()` 保留原始值。 + +三条线使用其 Maven Wrapper 运行 `./mvnw -B -ntp clean verify`,报告位于各自的 `target/surefire-reports`。Java 8 提交 `49250f97cb6618502b40e5989b8521fc733d7fab`、Java 17 本提交和 Java 21 提交 `7001ed85439408f9d2724e7edee92d3cfc7853e9` 分别通过 2178、2179、2178 项,均为零失败、零错误、零跳过。 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 bf4498db1e4b3bb87a5193bed82a0737b8995727 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 077/146] Require pinned structured help evidence in OpenCLI CI --- .github/workflows/ci.yml | 4 ++++ .github/workflows/contracts.yml | 2 ++ .../changes/enforce-opencli-branch-contract-parity/tasks.md | 4 ++++ 3 files changed, 10 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c04cc83..30374ef 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -34,6 +34,10 @@ jobs: java-version: '17' 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 diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index 337d929..9656b1d 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -31,6 +31,7 @@ jobs: run: | python3 -m unittest discover -s scripts/tests -v (cd src/test/resources/opencli-contracts/v1 && sha256sum -c SHA256SUMS) + (cd src/test/resources/opencli-contracts/v1/structured-help-1.8.8 && sha256sum --strict -c SHA256SUMS) - name: Install pinned official OpenSpec run: npm install --prefix "$RUNNER_TEMP/opencli-openspec" --ignore-scripts --no-audit --no-fund @fission-ai/openspec@1.13.1 - name: Validate all proposals and each change with strict mode @@ -120,6 +121,7 @@ jobs: --java-version-file contract-evidence/java.txt \ --maven-version-file contract-evidence/maven.txt \ --exit-code "$(cat contract-evidence/maven.exit)" \ + --suite enumeration=io.github.easy4j.opencli.contract.OpenCliStructuredHelpFixtureTest \ --suite argv=io.github.easy4j.opencli.contract.OpenCliArgvContractTest \ --suite argv=io.github.easy4j.opencli.contract.OpenCliStructuredArgvContractTest \ --suite process=io.github.easy4j.opencli.contract.OpenCliProcessContractTest \ diff --git a/openspec/changes/enforce-opencli-branch-contract-parity/tasks.md b/openspec/changes/enforce-opencli-branch-contract-parity/tasks.md index e503eb1..f05488c 100644 --- a/openspec/changes/enforce-opencli-branch-contract-parity/tasks.md +++ b/openspec/changes/enforce-opencli-branch-contract-parity/tasks.md @@ -40,3 +40,7 @@ OC-PARITY-004:维护线原 CI 将 JaCoCo 参数丢在 Surefire JVM 之外, | 21 | 4.0.0-rc-5 | 3.2.1 | `fa7e001da203d31fd5afb2921f90c3f428db2d5b` | 2144 | 3028/3285(92.18%) | [44356116107](https://github.com/easy-4-java/opencli-java-sdk/actions/runs/44356116107) | 上述记录覆盖文档事实和分支构建。最终集成门禁仍按第 3 节逐项验收。 + +### 结构化帮助证据门禁 + +OC-PARITY-003/004:在 `98f28346e7bc3307608122a0086a8e1072e39536` 的 GitHub 工件中,Surefire 记录了三个通过的 `OpenCliStructuredHelpFixtureTest` 用例,契约报告的枚举层仍显示 `NOT_RUN`。从该工件重放报告命令并声明枚举套件后,枚举层显示 `PASS`、执行三项,真实 CLI 执行层仍为 `NOT_RUN`。移除套件报告时,报告命令返回非零。三条开发线使用同一份 SHA-256 清单检查九个帮助样本,在临时副本的 `root.json` 末尾追加换行会使校验失败。样本提供离线结构证据,实时能力发现和真实执行由对应任务另行验收。 From 1ff63779142004331660da11226aaa3e53b5dd44 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 078/146] Decode versioned OpenCLI structured help with explicit unknown states Refs #5 --- 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 78148bf..3f79ea1 100644 --- a/README.md +++ b/README.md @@ -201,6 +201,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). ### Windows npm launcher diff --git a/README.zh-CN.md b/README.zh-CN.md index 7084a18..85c8bee 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -201,6 +201,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`(视为可启动)。 ### Windows npm 启动入口 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 f02aa1bf69953c0a31eb4bd01a7d029b6739cc08 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 079/146] Validate complete OpenCLI structured help output --- .github/workflows/contracts.yml | 1 + .../add-opencli-capability-discovery/tasks.md | 4 ++++ .../opencli/parser/OpenCliHelpParser.java | 18 ++++++++++++++---- .../contract/OpenCliHelpParserTest.java | 10 ++++++++++ 4 files changed, 29 insertions(+), 4 deletions(-) diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index 9656b1d..08feaf2 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -122,6 +122,7 @@ jobs: --maven-version-file contract-evidence/maven.txt \ --exit-code "$(cat contract-evidence/maven.exit)" \ --suite enumeration=io.github.easy4j.opencli.contract.OpenCliStructuredHelpFixtureTest \ + --suite enumeration=io.github.easy4j.opencli.contract.OpenCliHelpParserTest \ --suite argv=io.github.easy4j.opencli.contract.OpenCliArgvContractTest \ --suite argv=io.github.easy4j.opencli.contract.OpenCliStructuredArgvContractTest \ --suite process=io.github.easy4j.opencli.contract.OpenCliProcessContractTest \ diff --git a/openspec/changes/add-opencli-capability-discovery/tasks.md b/openspec/changes/add-opencli-capability-discovery/tasks.md index 975b8fa..65a4b06 100644 --- a/openspec/changes/add-opencli-capability-discovery/tasks.md +++ b/openspec/changes/add-opencli-capability-discovery/tasks.md @@ -31,3 +31,7 @@ `OpenCliHelpParser` 在 Java 8 API 范围内提供帮助解析结果。根目录、站点、命名空间和叶子按真实 1.8.8 结构识别。Schema 保留命令显示路径、会话占位符、命令层级、位置参数、别名和分作用域选项。缺失字段、显式 false、可选取值、否定和默认值分别保留。原文和各节点的来源 JSON 可以追溯未解释字段。纯文本、JSON 后缀、重复字段或无效结构返回 `UNKNOWN` 及对应原因。 基线的 API 验收先因缺少解析入口而无法编译。加入实现后,以 1.8.8 的七个 JSON 样本、两个原始负例和合成扩展验证,详见 `OpenCliHelpParserTest`。当前验证范围为原文解码,运行时探测、快照来源与失效、类型化会话绑定仍由其余任务验收。 + +OC-CAP-005 控制字符回归:在 JDK 17 基线 `1ff6377` 上,合法 JSON 后带 NUL 的用例返回 `AVAILABLE`,定向测试失败。解析器现按 JSON 规定识别四种前导空白,并把完整原文交给严格 JSON 解析。首尾出现 NUL 或只有 NUL 均返回 `UNKNOWN/INVALID_JSON`,原文仍可由调用方显式取得。空格、制表符、回车和换行仍能包围合法文档。 + +对 `af62b29`、`1ff6377`、`6a50081` 应用同一修复后,分别用 Java 8、17、21 执行 `./mvnw -B -ntp clean verify`,退出码均为 0。每条线五项解析测试全部执行,全量测试数分别为 2186、2187、2186,均为零失败、零错误、零跳过。GitHub 契约报告将解析用例计入枚举层,与帮助样本形态测试共同验收。 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 b22796f3c4c0b7688fafb42ad26dbaa5a1078f25 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 080/146] 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 65a4b06..a5f2719 100644 --- a/openspec/changes/add-opencli-capability-discovery/tasks.md +++ b/openspec/changes/add-opencli-capability-discovery/tasks.md @@ -35,3 +35,9 @@ OC-CAP-005 控制字符回归:在 JDK 17 基线 `1ff6377` 上,合法 JSON 后带 NUL 的用例返回 `AVAILABLE`,定向测试失败。解析器现按 JSON 规定识别四种前导空白,并把完整原文交给严格 JSON 解析。首尾出现 NUL 或只有 NUL 均返回 `UNKNOWN/INVALID_JSON`,原文仍可由调用方显式取得。空格、制表符、回车和换行仍能包围合法文档。 对 `af62b29`、`1ff6377`、`6a50081` 应用同一修复后,分别用 Java 8、17、21 执行 `./mvnw -B -ntp clean verify`,退出码均为 0。每条线五项解析测试全部执行,全量测试数分别为 2186、2187、2186,均为零失败、零错误、零跳过。GitHub 契约报告将解析用例计入枚举层,与帮助样本形态测试共同验收。 + +## 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 b475035da426d5b216a11689bbe0f84e7f999509 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 081/146] Reject malformed structured help catalogs --- .../add-opencli-capability-discovery/tasks.md | 6 +++++- .../opencli/parser/OpenCliHelpParser.java | 21 ++++++++++++++++--- .../OpenCliCapabilityDiscoveryTest.java | 15 +++++++++++++ .../contract/OpenCliHelpParserTest.java | 21 +++++++++++++++++++ 4 files changed, 59 insertions(+), 4 deletions(-) diff --git a/openspec/changes/add-opencli-capability-discovery/tasks.md b/openspec/changes/add-opencli-capability-discovery/tasks.md index a5f2719..97d4d90 100644 --- a/openspec/changes/add-opencli-capability-discovery/tasks.md +++ b/openspec/changes/add-opencli-capability-discovery/tasks.md @@ -18,7 +18,7 @@ ## 3. 边界验证 - [ ] 3.1 测试本地override/插件来源未知时不伪造来源和全量覆盖率。 -- [ ] 3.2 测试原有raw入口不会因为发现故障被无声禁用,remote拒绝范围仍受C04控制。 +- [x] 3.2 验证发现失败后仍可调用本地 raw 入口,远程拒绝范围继续由 C04 测试验收。 - [ ] 3.3 三线同一schema fixture结果一致;报告未运行的真实上游采集项。 ## 证据交付模板(实施时填写) @@ -36,6 +36,10 @@ OC-CAP-005 控制字符回归:在 JDK 17 基线 `1ff6377` 上,合法 JSON 对 `af62b29`、`1ff6377`、`6a50081` 应用同一修复后,分别用 Java 8、17、21 执行 `./mvnw -B -ntp clean verify`,退出码均为 0。每条线五项解析测试全部执行,全量测试数分别为 2186、2187、2186,均为零失败、零错误、零跳过。GitHub 契约报告将解析用例计入枚举层,与帮助样本形态测试共同验收。 +OC-CAP-005 根目录形态与本地回退:JDK 17 基线 `b22796f3` 上,空注册表对象和空参数名均被错误标记为 `AVAILABLE`,两项定向测试失败。根据 1.8.8 的根帮助样本,根注册表要求 `site_adapters.sites` 为数组,成员为非空白名称。显式空数组仍是合法的空目录。参数名和别名必须包含有效字符,选项候选值保留显式空字符串。实际子进程测试返回缺少 sites 的根帮助,发现结果为 `UNKNOWN/INVALID_SCHEMA`,随后同一客户端成功执行本地 raw 调用。远程模式的发现仍返回 `LOCAL_DISCOVERY_ONLY`,C04 远程契约用例随全量构建一并执行。 + +使用各条线的 Wrapper 执行 `./mvnw -B -ntp clean verify`,Java 8、17、21 分别通过 2194、2195、2194 项。每条线均执行 7 项解析测试和 6 项发现测试,零失败、零错误、零跳过。报告位于对应构建目录的 `target/surefire-reports`。 + ## OC-CAP-004/005/006 本地根发现 `OpenCliClient.discoverCapabilities()` 接受调用者信任的绝对本地可执行文件配置,记录规范路径、观测版本、采集时刻、配置指纹及完整帮助文本的 SHA-256。探测固定为 `--version` 和 `--help -f json`,复用客户端执行器的本地并发容量、队列和进程清理。每次探测的队列与运行合计最多 10 秒,清理最多 1 秒,每路最多保留 1 MiB,调用者设置的更小预算优先。命令来源为 `UNKNOWN`,观察范围为 `ROOT_HELP`。采用按需重新观测,同版本改动可形成不同帮助摘要;缓存和 STALE 仍待实现。远端和 PATH 查找的发现请求返回 `UNSUPPORTED`,原有显式本地调用仍可使用。 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 532cf673b7ecf7b337e09c3b50c36a0b4ded9f1c 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 082/146] 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 97d4d90..4a88900 100644 --- a/openspec/changes/add-opencli-capability-discovery/tasks.md +++ b/openspec/changes/add-opencli-capability-discovery/tasks.md @@ -45,3 +45,9 @@ OC-CAP-005 根目录形态与本地回退:JDK 17 基线 `b22796f3` 上,空 `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 a6b59b54c3a099bd72d79256d307e3b409d014a7 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 083/146] 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 4a88900..f3e56ce 100644 --- a/openspec/changes/add-opencli-capability-discovery/tasks.md +++ b/openspec/changes/add-opencli-capability-discovery/tasks.md @@ -51,3 +51,9 @@ OC-CAP-005 根目录形态与本地回退:JDK 17 基线 `b22796f3` 上,空 客户端保存一个最近成功的根帮助快照,每次显式发现均重新探测。刷新失败且配置指纹一致、未观测到不同版本时,返回 `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 528fac17933e5062fb635df8d232910fa7514898 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 084/146] Reject malformed version output before capability discovery --- .../add-opencli-capability-discovery/tasks.md | 8 ++++++- .../OpenCliCapabilityDiscovery.java | 8 ++++--- .../OpenCliCapabilityDiscoveryTest.java | 23 +++++++++++++++++++ 3 files changed, 35 insertions(+), 4 deletions(-) diff --git a/openspec/changes/add-opencli-capability-discovery/tasks.md b/openspec/changes/add-opencli-capability-discovery/tasks.md index f3e56ce..0bad4c4 100644 --- a/openspec/changes/add-opencli-capability-discovery/tasks.md +++ b/openspec/changes/add-opencli-capability-discovery/tasks.md @@ -42,7 +42,7 @@ OC-CAP-005 根目录形态与本地回退:JDK 17 基线 `b22796f3` 上,空 ## OC-CAP-004/005/006 本地根发现 -`OpenCliClient.discoverCapabilities()` 接受调用者信任的绝对本地可执行文件配置,记录规范路径、观测版本、采集时刻、配置指纹及完整帮助文本的 SHA-256。探测固定为 `--version` 和 `--help -f json`,复用客户端执行器的本地并发容量、队列和进程清理。每次探测的队列与运行合计最多 10 秒,清理最多 1 秒,每路最多保留 1 MiB,调用者设置的更小预算优先。命令来源为 `UNKNOWN`,观察范围为 `ROOT_HELP`。采用按需重新观测,同版本改动可形成不同帮助摘要;缓存和 STALE 仍待实现。远端和 PATH 查找的发现请求返回 `UNSUPPORTED`,原有显式本地调用仍可使用。 +`OpenCliClient.discoverCapabilities()` 接受调用者信任的绝对本地可执行文件配置,记录规范路径、观测版本、采集时刻、配置指纹及完整帮助文本的 SHA-256。探测固定为 `--version` 和 `--help -f json`,复用客户端执行器的本地并发容量、队列和进程清理。每次探测的队列与运行合计最多 10 秒,清理最多 1 秒,每路最多保留 1 MiB,调用者设置的更小预算优先。命令来源为 `UNKNOWN`,观察范围为 `ROOT_HELP`。初始实现采用按需重新观测,同版本改动可形成不同帮助摘要。后续快照失效和 `STALE` 行为见下文。远端和 PATH 查找的发现请求返回 `UNSUPPORTED`,原有显式本地调用仍可使用。 `OpenCliCapabilityDiscoveryTest` 先因缺少公开发现 API 无法编译。真实 JVM 子进程验收固定参数、同版本变更、无来源推断、文本降级、输出超限、非零退出、超时及 local raw。Maven 定向测试同时验证原有帮助解析。范围仍为根级目录,细粒度帮助探测及类型化执行仍未验收。 @@ -57,3 +57,9 @@ OC-CAP-005 根目录形态与本地回退:JDK 17 基线 `b22796f3` 上,空 `discoverCapabilities(OpenCliHelpScope)` 提供根目录、浏览器、浏览器 tab/get/state、auth、list 及 npm 站点和 search 的九个固定查询。细粒度参数只在已验证的 OpenCLI 1.8.8 启用。浏览器查询使用固定的帮助会话占位,不接受调用者提供的命令路径,也不执行帮助描述中的内容。结构化结果需匹配请求范围;纯文本和混合输出维持原有失败原因。 每个范围只保存其最近成功的观察,且配置或已观测版本变化使其他不匹配的范围一并失效。OpenCLI 能力仍按请求观察,并保留来源未知标记。增加 `OpenCliCapabilityDiscoveryTest` 的进程验收后,缺少范围 API 时失败,加入实现后定向测试通过。类型化会话绑定及执行前参数校验仍待验收。 + +### OC-CAP-006 版本探测输出校验 + +真实 JVM 子进程在版本号后输出 NUL 和换行。JDK 17 基线 `532cf673` 的定向回归检测到后续帮助进程被启动,退出码为 1。修复后仅允许空格、制表符、回车和换行包围版本号。遇到 NUL 时返回 `UNKNOWN/INVALID_VERSION_OUTPUT`,观测版本为空,且不启动帮助进程。 + +在固定范围帮助探测基线 `8d1ccb6`、`a6b59b54`、`e83bc00` 上应用修复后,分别用 Java 8、17、21 执行 `./mvnw -B -ntp clean verify`。三个构建均退出 0,各运行 12 项发现测试。全量测试数分别为 2200、2201、2200,零失败、零错误、零跳过。报告见 `target/surefire-reports`。 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 441122f129822c70126390331853d28d64faa66c 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 085/146] 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 0bad4c4..090fec1 100644 --- a/openspec/changes/add-opencli-capability-discovery/tasks.md +++ b/openspec/changes/add-opencli-capability-discovery/tasks.md @@ -63,3 +63,9 @@ OC-CAP-005 根目录形态与本地回退:JDK 17 基线 `b22796f3` 上,空 真实 JVM 子进程在版本号后输出 NUL 和换行。JDK 17 基线 `532cf673` 的定向回归检测到后续帮助进程被启动,退出码为 1。修复后仅允许空格、制表符、回车和换行包围版本号。遇到 NUL 时返回 `UNKNOWN/INVALID_VERSION_OUTPUT`,观测版本为空,且不启动帮助进程。 在固定范围帮助探测基线 `8d1ccb6`、`a6b59b54`、`e83bc00` 上应用修复后,分别用 Java 8、17、21 执行 `./mvnw -B -ntp clean verify`。三个构建均退出 0,各运行 12 项发现测试。全量测试数分别为 2200、2201、2200,零失败、零错误、零跳过。报告见 `target/surefire-reports`。 + +## 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