Proposal 2 — ApConnection: Provide Public Access to Active Force-Reconnect

[scottf]

Problem

The AP fast-path for active LDM calls forceReconnect() on an ApConnection instance. forceReconnect() is a public method — it is declared on the Connection interface in jnats and is fully public. The problem is not the method visibility.

The actual problem is that ApConnection lives in io.nats.client.impl, a package with no public export. It cannot be imported or referenced as a named type from outside that package. Because of this, calling any method on an ApConnection — including the already-public forceReconnect() — from external code is not possible without resorting to split-package access, which works on the classic classpath but is incompatible with the Java Module System (JPMS).

Proposed resolution

Either:

Option A — Expose ApConnection via a narrow public interface in io.nats.client:

// New public interface in io.nats.client
public interface ApConnectionSupport {
    /**
     * Forces the active connection to immediately reconnect using the pre-warmed passive socket.
     * Triggers the fast-path socket-steal failover (client-side thread swap only —
     * no network call, expected low single-digit to ~20ms).
     * Intended to be called from the active connection's LDM listener.
     */
    void activeForceReconnect() throws IOException, InterruptedException;
}
// ApConnection implements ApConnectionSupport

Option B — Move ApConnection to io.nats.client (or add a public marker) so it is importable as a named type.

Option A is preferred — it provides a narrow, stable, JPMS-compatible public contract.

Current workaround

We use the split-package pattern — placing a helper class in the same io.nats.client.impl package as ApConnection across JAR boundaries. This lets us hold a typed reference to ApConnection and call its methods. It works today on the classic classpath but is fragile: any addition of a module-info.java to either library would immediately break it without any warning at compile time.

[scottf]

Here is a full class that demonstrates it works fine.

package com.mc;

import io.nats.client.Options;
import io.nats.client.impl.ApConnection;
import io.nats.client.impl.ApOptions;
import io.nats.client.impl.ErrorListenerConsoleImpl;

public class Issue4 {
    public static void main(String[] args) {
        Options options = Options.builder()
            .connectionListener((conn, type) -> { System.out.println("ACTIVE: " + type); })
            .errorListener(new ErrorListenerConsoleImpl())
            .build();

        ApOptions apOptions = ApOptions.builder()
            .options(options)
            .passiveConnectionListener((conn, type) -> { System.out.println("PASSIVE: " + type); })
            .passiveErrorListener(new ErrorListenerConsoleImpl())
            .build();

        try (ApConnection apc = ApConnection.connect(apOptions)) {
            System.out.println("Before forceReconnect");
            apc.forceReconnect();
            System.out.println("After forceReconnect");
            Thread.sleep(1000);
        }
        catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}