Skip to content

session: cap reconnect waits and add reconnect backoff options - #80

Open
wesnel wants to merge 2 commits into
mainfrom
wgn/agent-1371-reconnect-options
Open

wesnel wants to merge 2 commits into
mainfrom
wgn/agent-1371-reconnect-options

Conversation

@wesnel

@wesnel wesnel commented Nov 16, 2026

Copy link
Copy Markdown
Member

Part of AGENT-1371. Brings the session reconnect fix to ngrok-java, as ngrok/ngrok-javascript#215 and ngrok/ngrok-javascript#216 did for @ngrok/ngrok 1.8.0.

A session that loses its connection now retries at most every 30 s, jittered, instead of waiting hours. The native crate moves from ngrok 0.14.0-pre.14 to 0.19.1, the first release with the fix. The wait between reconnect attempts starts at 50 ms and doubles up to a 30 s cap, each wait scaled by a random factor in [0, 1). Before, it grew 50-fold per attempt with no cap: about 2 minutes before the fourth attempt and 1 h 44 min before the fifth, while the process looked healthy. This applies to every session, options set or not.

Session.Builder also gets three options that pass straight through to ngrok-rust's setters of the same names:

  • reconnectBackoff(Duration initial, Duration max): the first wait between reconnect attempts and the cap. The defaults are 50 ms and 30 s.
  • reconnectJitter(boolean enabled): whether each wait is scaled by a random factor, so that sessions that drop together don't all reconnect at once. On by default.
  • reconnectMaxAttempts(int attempts): the session stops after this many failed attempts in one outage, counting the immediate first one. The count starts again with each outage. By default the session never stops trying. When it stops, Listener.accept() and Forwarder.join() throw an IOException with the last attempt's error.

ngrok-rust checks the ranges: a start of at least 1 ms and at most the cap, and a cap of at most one day. The builder only stores values, and the native builder is made in connect(), so a value out of range makes connect() throw an IOException such as reconnectBackoff: invalid reconnect backoff (start 2s, cap 1s): the start must not be above the cap. That is where heartbeatInterval's errors already surface. The setters themselves throw at once for what ngrok-rust's types cannot hold: NullPointerException for a null Duration, IllegalArgumentException for a negative one or for fewer than 1 attempt.

Validation

  • Before the code existed, the new tests failed for the expected reasons: against setters that stored nothing, the builder tests failed on their assertions, and connect() went on to open a connection instead of refusing an out-of-range backoff.
  • With the code, the builder tests and the offline ReconnectTest cases pass against the real native library and ngrok 0.19.1's checks.
  • Routing the backoff through the existing millisecond conversion makes the two sub-millisecond range tests fail, so they would catch a truncating conversion.
  • The test that connects with all three options set needs NGROK_AUTHTOKEN and runs in CI, as DataTest does.
  • The new javadoc passes javadoc -Xdoclint:all.

Weak spots, assumptions and decisions

  • The release builds for i686 Linux, Android, 32- and 64-bit Windows and macOS run only at release; this pull request's CI builds x86_64 Linux alone. ngrok 0.19.1 brings in rustls 0.23 with aws-lc-rs as its crypto provider, whose aws-lc-sys is C code that must build on each of those targets. @ngrok/ngrok ships the same provider on the same kinds of targets, but nothing here has built them.
  • The jump from 0.14.0-pre.14 to 0.19.1 spans five minor releases, and Cargo.lock moves many dependencies (tokio, hyper, rustls, muxado) through cargo update -p ngrok. src/lib.rs compiled unchanged, with no deprecation warnings, so this assumes no behaviour the binding relies on changed silently in between.
  • No test sees reconnectJitter or reconnectMaxAttempts take effect: that needs a session that loses its connection, which ngrok-rust tests against a fake service and this repository has no harness for. Dropping either pass-through line in connect_native would leave the tests green.
  • What callers see when the session stops reconnecting (accept() and join() throwing) is read from the code of ngrok 0.19.1 and this binding, not seen in a run. ngrok-jetty's NgrokConnector calls accept() in Jetty's acceptor loop, which may log and retry in a tight loop rather than stop once that happens; this pull request leaves it as it is.
  • The native code reads the four new Session.Builder getters on every connect(), so a native jar from this change beside an older ngrok-java jar fails at connect(), and the reverse pairing silently ignores the options. This assumes the two artifacts stay at one version, as the native pom's dependency and the README's single ${ngrok.version} already require, and as getTrafficPolicy already needed in 1.1.0.
  • Decision: range errors come from connect(), not the setter. The alternative was an eager check, which would copy ngrok-rust's range rules into Java or add a native call per setter.
  • Decision: the backoff is two java.time.Duration values, passed to Rust to the nanosecond from getSeconds and getNano. The alternative was whole milliseconds through the toMillis conversion heartbeatInterval uses, which truncates, so a value a fraction of a millisecond out of range would be accepted.
  • Decision: reconnectMaxAttempts takes an int, so the largest limit is 2147483647 rather than ngrok-rust's 4294967295. The alternative was a long checked against the u32 range.
  • Decision: the error prefix is the method name alone, since ngrok-rust's message already shows both durations. The alternative was the call with its arguments, as @ngrok/ngrok does.
  • reconnect_policy from ngrok-rust is not exposed: it is a Rust callback consulted on every reconnect.

Reverting

Before a release, this is a two-way door: reverting removes the three methods, returns ngrok to 0.14.0-pre.14, and nothing is stored. It also brings back the old default for every session, with waits that grow 50-fold and no cap. Once an ngrok-java release ships it, the three methods are public API, and removing them breaks callers that use them.

ngrok 0.19.1 caps the wait between session reconnect attempts at 30 s
and scales each wait by a random factor. With 0.14.0-pre.14 the wait
grew 50-fold per attempt with no cap: about 2 minutes before the fourth
attempt and 1 h 44 min before the fifth, so a session could stay offline
for hours after a short outage while the process looked healthy.

The binding builds against 0.19.1 unchanged. Cargo.lock moves only
through `cargo update -p ngrok`. rustls 0.23 now comes in with aws-lc-rs
as its only crypto provider, which ngrok's default feature selects.
Session.Builder gains reconnectBackoff(initial, max),
reconnectJitter(enabled) and reconnectMaxAttempts(attempts), which pass
straight through to ngrok-rust 0.19.1's setters of the same names, as
@ngrok/ngrok 1.8.0 does for JavaScript.

ngrok-rust owns the range rules (a start of at least 1 ms and at most
the cap, a cap of at most one day). The setters refuse only what its
types cannot hold: null, a negative Duration, or fewer than 1 attempt.
Since the native builder is made in connect(), a range error is thrown
from connect() as an IOException starting "reconnectBackoff: ", where
heartbeatInterval's errors already surface.

Durations reach Rust to the nanosecond, from getSeconds and getNano,
rather than through the toMillis path heartbeatInterval uses, so a value
a fraction of a millisecond out of range is refused rather than
truncated into range.
@wesnel
wesnel force-pushed the wgn/agent-1371-reconnect-options branch from 94d901d to 21c83b9 Compare November 16, 2026 19:13
@wesnel
wesnel requested a balanced review from Copilot November 16, 2026 21:14

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The native SDK upgrade introduces TLS/runtime changes and aws-lc-sys C builds on targets not exercised by PR CI, requiring human validation of cross-platform compatibility and JNI disconnect and terminal-error behavior.

No open issues 🎉

What changed in this PR

This PR brings capped, jittered session reconnection to ngrok-java through an ngrok Rust SDK upgrade and exposes reconnect controls in Session.Builder.

Changes:

  • Upgrades ngrok to 0.19.1, providing exponential reconnect waits capped at 30 seconds by default.
  • Adds backoff, jitter, and maximum-attempt options, preserving nanosecond duration precision across the native bridge.
  • Adds tests for builder validation, native range checks, and connecting with all reconnect options set.
File Description
ngrok-java/​src/​test/​java/​com/​ngrok/​SessionBuilderTest.java Tests option storage, defaults, and setter validation.
ngrok-java/​src/​main/​java/​com/​ngrok/​Session.java Adds and documents reconnect settings and getters.
ngrok-java-native/​src/​test/​java/​com/​ngrok/​ReconnectTest.java Tests native range validation and configured connection setup.
ngrok-java-native/​src/​lib.rs Converts Java option values and applies them to the Rust session builder.
ngrok-java-native/​Cargo.toml Upgrades the ngrok dependency to 0.19.1.
ngrok-java-native/​Cargo.lock Locks the updated SDK and transitive dependencies.

Review effort: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants