feat: negotiate NETCONF capabilities and type rpc-errors

Teach sessions to negotiate the shared NETCONF base capability and gate operations against what the server actually advertises.

Add structured RpcErrorException and ValidateException flows, harden rpc-error parsing for namespaced replies, and update commit/load/validate behavior to preserve server detail.

Back the change with unit and integration coverage, Javadocs for the new public API, and a sanitized integration runner/docs path story.

Author: Peter Hill

.gitignore

@@ -14,6 +14,7 @@ target
 *.iml
 .idea/
 .gradle
+.gradle-user-home/
 gradle/*
 !gradle/wrapper/
 !gradle/wrapper/gradle-wrapper.jar
@@ -27,4 +28,12 @@ log-test/
 
 .DS_Store
 .factorypath
-settings.json
+settings.json
+
+# Generated integration-test container image artifacts
+/src/test/resources/*-docker-*.tgz
+/src/test/resources/manifest.json
+/src/test/resources/repositories
+/src/test/resources/[0-9a-f]*.json
+/src/test/resources/[0-9a-f]*.tar
+/src/test/resources/[0-9a-f]*/

README.md

@@ -34,6 +34,16 @@ mvn clean package
 ```
 (The wrapper script downloads the correct Gradle version automatically.)
 
+To run the live NETCONF integration suite with Gradle:
+
+```bash
+NETCONF_HOST=192.168.1.1 \
+NETCONF_USERNAME=admin \
+NETCONF_PASSWORD=secret \
+NETCONF_PORT=830 \
+./gradlew integrationTest
+```
+
 Releases
 ========
 Releases contain source code only. Due to changing JDK licensing, jar files are not released.
@@ -47,7 +57,7 @@ User may download the source code and compile it with desired JDK version.
 * Instructions to build using `mvn`
   * Download Source Code for the required release
   * Compile the code and build the jar using `mvn package`
-  * Use the jar file from (source to netconf-java)/netconf-java/target
+  * Use the jar file from `./target/`
   * Use `mvn versions:display-dependency-updates` to identify possible target versions for dependencies
 
 =======
@@ -56,11 +66,17 @@ v2.2.1
 ------
 * Hardened NETCONF XML parsing against XXE and DTD-based attacks
 * Fixed NETCONF RPC framing and `message-id` reply correlation for sequential session reuse
+* Enforced shared NETCONF base capability negotiation and derive session framing from the negotiated base version
+* Capability-gated candidate, validate, and confirmed-commit operations before sending RPCs
+* Added negotiated capability inspection via `Device.getNegotiatedCapabilities()` and `NetconfSession.getNegotiatedCapabilities()`
+* Typed NETCONF `<rpc-error>` replies as structured exceptions so callers can inspect server-reported error details
+* Added `ValidateException` and clarified `validate()` semantics: server `rpc-error` replies throw, while warning-only or other non-`<ok/>` non-error replies still return `false`
 * Improved SSH/NETCONF session cleanup on failed connection or session initialization
 * Fixed shell exec helpers so commands are set, channels are connected, and timeout/cleanup behavior is more predictable
 * Fixed nested XML path construction in the XML helper
 * Documented `NetconfSession` as a sequential request/response channel rather than a concurrent in-flight RPC transport
 * Added [`docs/compatibility.md`](docs/compatibility.md) with current RFC, capability, NMDA, and extension support details
+* Added a dedicated Gradle `integrationTest` task that forwards NETCONF connection settings for live-server testing
 * Upgraded `assertj-core` to `3.27.7` to address `CVE-2026-24400`
 
 v2.2.0
@@ -107,6 +123,7 @@ SYNOPSIS
 import java.io.IOException;
 import javax.xml.parsers.ParserConfigurationException;
 import net.juniper.netconf.NetconfException;
+import net.juniper.netconf.ValidateException;
 import org.xml.sax.SAXException;
 
 import net.juniper.netconf.XML;
@@ -142,12 +159,30 @@ public class ShowInterfaces {
 }
 ```
 
+Candidate validate example:
+
+```Java
+try {
+    boolean clean = device.validate();
+    if (!clean) {
+        // Warning-only or other non-error, non-<ok/> reply.
+        System.out.println("Validate completed without rpc-error, but did not return <ok/>");
+    }
+} catch (ValidateException e) {
+    // Server returned one or more <rpc-error> elements.
+    System.err.println("Validate failed: " + e.getMessage());
+    e.getRpcErrors().forEach(System.err::println);
+}
+```
+
 Recommended usage:
 
 * Build one `Device` per target connection and use `try-with-resources` so SSH resources are released predictably.
 * Call `connect()` before issuing RPCs. If `connect()` throws, no usable NETCONF session was established.
+* Inspect `getNegotiatedCapabilities()` after `connect()` if your application needs to branch on server support for candidate, validate, or confirmed-commit behavior.
 * Set `connectionTimeout` and `commandTimeout` explicitly for production use rather than relying on defaults.
 * Prefer NETCONF RPC helpers (`executeRPC`, `getConfig`, `loadXMLConfiguration`, `commit`, and friends) for device operations; use shell helpers only for device-specific workflows that are not available over NETCONF.
+* Treat `ValidateException` as the server-side `rpc-error` path for `validate()`. A `false` return now means the reply was non-error but not a clean `<ok/>`, typically warnings.
 * Shell helper reads are bounded by `commandTimeout`. If you use `runShellCommandRunning(...)`, always close the returned reader so the underlying exec channel is released.
 
 LICENSE

build.gradle

@@ -50,6 +50,73 @@ test {
     }
 }
 
+def netconfPropertySpecs = [
+    [name: 'netconf.host', env: 'NETCONF_HOST', required: true],
+    [name: 'netconf.username', env: 'NETCONF_USERNAME', required: true],
+    [name: 'netconf.password', env: 'NETCONF_PASSWORD', required: true],
+    [name: 'netconf.port', env: 'NETCONF_PORT', required: false, defaultValue: '830'],
+    [name: 'netconf.timeout', env: 'NETCONF_TIMEOUT', required: false, defaultValue: '30000']
+]
+
+def resolveNetconfProperty = { Map spec ->
+    if (project.hasProperty(spec.name)) {
+        return project.property(spec.name).toString()
+    }
+    if (System.getProperty(spec.name) != null) {
+        return System.getProperty(spec.name)
+    }
+    if (System.getenv(spec.env) != null) {
+        return System.getenv(spec.env)
+    }
+    return spec.defaultValue
+}
+
+tasks.register('integrationTest', org.gradle.api.tasks.testing.Test) {
+    description = 'Runs live NETCONF integration tests against a configured endpoint.'
+    group = 'verification'
+    useJUnitPlatform()
+    shouldRunAfter test
+    testClassesDirs = sourceSets.test.output.classesDirs
+    classpath = sourceSets.test.runtimeClasspath
+
+    filter {
+        includeTestsMatching 'net.juniper.netconf.integration.NetconfIntegrationTest'
+    }
+
+    testLogging {
+        events "passed", "skipped", "failed"
+    }
+
+    doFirst {
+        def resolvedProperties = [:]
+        def missingRequiredProperties = []
+
+        netconfPropertySpecs.each { spec ->
+            def value = resolveNetconfProperty(spec)
+            if (value == null || value.toString().trim().isEmpty()) {
+                if (spec.required) {
+                    missingRequiredProperties << "${spec.name} (${spec.env})"
+                }
+                return
+            }
+            resolvedProperties[spec.name] = value.toString()
+        }
+
+        if (!missingRequiredProperties.isEmpty()) {
+            throw new org.gradle.api.GradleException(
+                "integrationTest requires live NETCONF connection details. " +
+                "Provide ${missingRequiredProperties.join(', ')} via -Dnetconf.* " +
+                "or NETCONF_* environment variables."
+            )
+        }
+
+        systemProperty 'netconf.integration.enabled', 'true'
+        resolvedProperties.each { propertyName, propertyValue ->
+            systemProperty propertyName, propertyValue
+        }
+    }
+}
+
 tasks.withType(JavaCompile).configureEach {
     options.fork = true
     options.forkOptions.jvmArgs += [

docs/compatibility.md

@@ -2,7 +2,7 @@
 
 This document describes what `netconf-java` currently implements. It is an implementation matrix, not a blanket compliance claim. Interoperability still depends on the server's advertised capabilities and on whether the application stays within the library's supported session model.
 
-Mental model: today the library is a synchronous, JSch-backed NETCONF-over-SSH client. Its strongest path is one sequential RPC conversation per `NetconfSession`, with explicit timeouts and explicit cleanup. Core NETCONF 1.0 and 1.1 framing is supported, several Junos workflows are wrapped ergonomically, and the main standards gap is that optional features are not yet enforced uniformly through capability negotiation.
+Mental model: today the library is a synchronous, JSch-backed NETCONF-over-SSH client. Its strongest path is one sequential RPC conversation per `NetconfSession`, with explicit timeouts and explicit cleanup. Core NETCONF 1.0 and 1.1 framing is supported, several Junos workflows are wrapped ergonomically, and optional features are beginning to be enforced through capability negotiation, though coverage is not yet uniform across all extensions.
 
 ## Status legend
 
@@ -18,9 +18,9 @@ Mental model: today the library is a synchronous, JSch-backed NETCONF-over-SSH c
 | Standard / feature | Status | Notes |
 | --- | --- | --- |
 | RFC 6242 SSH subsystem transport | `Supported` | `Device` opens an SSH subsystem channel with `subsystem=netconf` over JSch. |
-| RFC 6241 `<hello>` parsing and generation | `Supported with caveats` | `Hello` parsing/building works, and `Hello.builder()` auto-adds `urn:ietf:params:netconf:base:1.1`. The library does not currently fail the session if the peers do not share a common base capability. |
+| RFC 6241 `<hello>` parsing and generation | `Supported with caveats` | `Hello` parsing/building works, `Hello.builder()` auto-adds `urn:ietf:params:netconf:base:1.1`, and session establishment now fails if the peers do not share a common NETCONF base capability. The remaining caveat is that the client still cannot intentionally advertise only `base:1.0`. |
 | NETCONF 1.0 end-of-message framing (`]]>]]>`) | `Supported` | Legacy framing is still supported for both outbound and inbound messages. |
-| NETCONF 1.1 chunked framing | `Supported` | Chunked framing is enabled when the server `<hello>` advertises `urn:ietf:params:netconf:base:1.1`. |
+| NETCONF 1.1 chunked framing | `Supported` | Chunked framing is selected when both peers share `urn:ietf:params:netconf:base:1.1`. |
 | NETCONF 1.0 server interoperability | `Supported with caveats` | A 1.0-only server can interoperate because the client still advertises `base:1.0` and can read/write legacy framing. |
 | NETCONF 1.0-only client advertisement | `Not implemented` | The client cannot intentionally advertise only `base:1.0`; `Hello.builder()` always injects `base:1.1`. |
 | RPC `message-id` generation and reply correlation | `Supported with caveats` | Missing `message-id` attributes are injected, replies are validated, and sequential same-session alignment is covered by tests. One `NetconfSession` is still a sequential conversation, not a safe multiplexed channel for concurrent in-flight RPCs. |
@@ -35,11 +35,11 @@ Mental model: today the library is a synchronous, JSch-backed NETCONF-over-SSH c
 | --- | --- | --- |
 | `<get>` | `Supported` | `getRunningConfigAndState(...)` issues `<get>`. |
 | `<get-config>` | `Supported` | Candidate and running helpers exist. |
-| `<edit-config>` to candidate | `Supported with caveats` | `loadXMLConfiguration(...)` and `loadTextConfiguration(...)` target `candidate`. The API does not expose `test-option`, `error-option`, or capability-gated behavior checks before use. |
-| `:candidate:1.0` | `Supported with caveats` | Candidate-oriented helpers are a primary workflow, but the default client capability still uses the legacy `urn:ietf:params:netconf:base:1.0#candidate` form rather than the RFC 6241 `urn:ietf:params:netconf:capability:candidate:1.0` URN. |
+| `<edit-config>` to candidate | `Supported with caveats` | `loadXMLConfiguration(...)` and `loadTextConfiguration(...)` target `candidate`, and candidate-dependent operations now fail locally when the server did not advertise candidate support. The API still does not expose `test-option` or `error-option`. |
+| `:candidate:1.0` | `Supported with caveats` | Candidate-oriented helpers are a primary workflow and are now runtime-gated against the server `<hello>`, but the default client capability still uses the legacy `urn:ietf:params:netconf:base:1.0#candidate` form rather than the RFC 6241 `urn:ietf:params:netconf:capability:candidate:1.0` URN. |
 | `<commit>` | `Supported` | Standard commit is implemented. |
-| `:confirmed-commit:1.1` | `Supported with caveats` | `commitConfirm(seconds, persistToken)` and `cancelCommit(persistId)` exist, but the default client capability still uses the legacy `base:1.0#confirmed-commit` form instead of the RFC 6241 capability URN. |
-| `:validate:1.0` | `Supported with caveats` | `validate()` is implemented against candidate, but default advertisement still uses the legacy `base:1.0#validate` URI and the call is not capability-gated at runtime. |
+| `:confirmed-commit:1.1` | `Supported with caveats` | `commitConfirm(seconds, persistToken)` and `cancelCommit(persistId)` are runtime-gated. Persist-based flows require modern `confirmed-commit:1.1`, while legacy confirmed-commit remains usable for same-session confirmation flows without `persist`. The default client capability advertisement still uses the legacy `base:1.0#confirmed-commit` form. |
+| `:validate:1.0` | `Supported with caveats` | `validate()` is implemented against candidate and now fails locally when validate support is absent, but default advertisement still uses the legacy `base:1.0#validate` URI. |
 | `<lock>` / `<unlock>` | `Partial` | Candidate lock/unlock helpers exist. There is no first-class running datastore lock helper. |
 | `:writable-running:1.0` | `Partial` | Running config retrieval exists, but there is no `edit-config` helper that targets `running` and the capability is not advertised by default. |
 | `:startup:1.0` | `Not implemented` | No first-class startup datastore copy/delete flows are present. |
@@ -79,7 +79,7 @@ Mental model: today the library is a synchronous, JSch-backed NETCONF-over-SSH c
 ## Interoperability caveats worth knowing
 
 - Default optional capability advertisement still uses legacy `urn:ietf:params:netconf:base:1.0#...` forms in `Device.DEFAULT_CLIENT_CAPABILITIES`. Many servers accept these, but strict RFC 6241 capability matching may not.
-- Capability negotiation is parsed but not enforced consistently before invoking optional operations. The caller can request candidate, validate, confirmed-commit, or NMDA operations even if the server never advertised them.
+- Candidate, validate, and confirmed-commit flows are now capability-gated before the RPC is sent. Other optional operations are still not enforced uniformly, especially outside the classic RFC 6241 capability set.
 - `NetconfSession` should be treated as a single sequential request/response channel. Use separate sessions for concurrent workflows.
 - The SSH transport is still tightly coupled to JSch. That preserves the current JSch-based deployment model, including existing FIPS-oriented environments, but transport abstraction is future work rather than current behavior.
 

src/main/java/net/juniper/netconf/CommitException.java

@@ -8,13 +8,17 @@
 
 package net.juniper.netconf;
 
-import java.io.IOException;
+import net.juniper.netconf.element.RpcReply;
 
 /**
  * Describes exceptions related to commit operation
  */
-public class CommitException extends IOException {
+public class CommitException extends RpcErrorException {
     CommitException(String msg) {
         super(msg);
     }
+
+    CommitException(String msg, RpcReply rpcReply) {
+        super(msg, rpcReply);
+    }
 }

src/main/java/net/juniper/netconf/Device.java

@@ -90,6 +90,7 @@ public class Device implements AutoCloseable {
 
     private final DocumentBuilder xmlBuilder;
     private final List<String> netconfCapabilities;
+    private final List<String> advertisedNetconfCapabilities;
     private final String helloRpc;
 
     private ChannelSubsystem sshChannel;
@@ -373,7 +374,9 @@ private Device(Builder b) throws NetconfException {
             throw new NetconfException("Cannot create XML Parser", e);
         }
 
-        this.helloRpc = createHelloRPC(this.netconfCapabilities);
+        Hello hello = createHello(this.netconfCapabilities);
+        this.advertisedNetconfCapabilities = hello.getCapabilities();
+        this.helloRpc = createHelloRPC(hello);
     }
 
 
@@ -385,7 +388,7 @@ private Device(Builder b) throws NetconfException {
      * @return List of default client capabilities.
      */
     protected List<String> getDefaultClientCapabilities() {
-        return DEFAULT_CLIENT_CAPABILITIES;
+        return createHello(DEFAULT_CLIENT_CAPABILITIES).getCapabilities();
     }
 
     /**
@@ -395,12 +398,14 @@ protected List<String> getDefaultClientCapabilities() {
      * @param capabilities A list of netconf capabilities
      * @return the hello RPC that represents those capabilities.
      */
-    private String createHelloRPC(List<String> capabilities) {
+    private Hello createHello(List<String> capabilities) {
         return Hello.builder()
             .capabilities(capabilities)
-            .build()
-            .getXml()
-            + NetconfConstants.DEVICE_PROMPT;
+            .build();
+    }
+
+    private String createHelloRPC(Hello hello) {
+        return hello.getXml() + NetconfConstants.DEVICE_PROMPT;
     }
 
     /**
@@ -450,7 +455,8 @@ private NetconfSession createNetconfSession() throws NetconfException {
             channel = (ChannelSubsystem) session.openChannel("subsystem");
             channel.setSubsystem("netconf");
             NetconfSession establishedSession =
-                new NetconfSession(channel, connectionTimeout, commandTimeout, helloRpc, xmlBuilder);
+                new NetconfSession(channel, connectionTimeout, commandTimeout,
+                    advertisedNetconfCapabilities, helloRpc, xmlBuilder);
             sshSession = session;
             sshChannel = channel;
             return establishedSession;
@@ -880,6 +886,20 @@ public String getSessionId() {
         return this.netconfSession.getSessionId();
     }
 
+    /**
+     * Returns the negotiated capability view for the active NETCONF session.
+     *
+     * @return immutable capability snapshot
+     * @throws IllegalStateException if the connection is not established
+     */
+    public NegotiatedCapabilities getNegotiatedCapabilities() {
+        if (netconfSession == null) {
+            throw new IllegalStateException("Cannot get negotiated capabilities, you need "
+                + "to establish a connection first.");
+        }
+        return this.netconfSession.getNegotiatedCapabilities();
+    }
+
     /**
      * Check if the last RPC reply returned from Netconf server has any error.
      *
@@ -1267,8 +1287,13 @@ public XML getRunningConfig() throws SAXException, IOException {
     /**
      * Validate the candidate configuration.
      *
-     * @return true if validation successful.
+     * @return {@code true} if validation completed with a clean {@code <ok/>}
+     *         reply; {@code false} for warning-only or other non-error
+     *         non-{@code <ok/>} replies
      * @throws java.io.IOException      If there are errors communicating with the netconf server.
+     * @throws net.juniper.netconf.ValidateException if the server returns one
+     *                                               or more {@code <rpc-error>}
+     *                                               elements
      * @throws org.xml.sax.SAXException If there are errors parsing the XML reply.
      */
     public boolean validate() throws IOException, SAXException {

src/main/java/net/juniper/netconf/LoadException.java

@@ -7,7 +7,7 @@
 
 package net.juniper.netconf;
 
-import java.io.IOException;
+import net.juniper.netconf.element.RpcReply;
 
 /**
  * Exception thrown when a <em>load</em> RPC returns &lt;rpc-error&gt; or otherwise
@@ -20,7 +20,7 @@
  *   <li>just the root cause.</li>
  * </ol>
  */
-public class LoadException extends IOException {
+public class LoadException extends RpcErrorException {
 
     /**
      * Creates a {@code LoadException} with the supplied message.
@@ -41,6 +41,16 @@ public LoadException(String message, Throwable cause) {
         super(message, cause);
     }
 
+    /**
+     * Creates a {@code LoadException} with a message and parsed reply.
+     *
+     * @param message description of the load failure
+     * @param rpcReply parsed NETCONF reply that triggered the failure
+     */
+    public LoadException(String message, RpcReply rpcReply) {
+        super(message, rpcReply);
+    }
+
     /**
      * Creates a {@code LoadException} that wraps an underlying cause.
      *