Repository navigation
Conversation
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
force-pushed
the
wgn/agent-1371-reconnect-options
branch
from
November 16, 2026 19:13
94d901d to
21c83b9
Compare
There was a problem hiding this comment.
🔵 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
ngrokto 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
wesnel
marked this pull request as ready for review
November 16, 2026 22:55
wesnel
requested review from
andrew-harris-at-ngrok,
grant-higgins-0,
joshbottelberghe,
kevin-ngrok and
sajethm
November 16, 2026 22:55
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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/ngrok1.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
ngrok0.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.Builderalso 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()andForwarder.join()throw anIOExceptionwith 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 makesconnect()throw anIOExceptionsuch asreconnectBackoff: invalid reconnect backoff (start 2s, cap 1s): the start must not be above the cap. That is whereheartbeatInterval's errors already surface. The setters themselves throw at once for what ngrok-rust's types cannot hold:NullPointerExceptionfor a nullDuration,IllegalArgumentExceptionfor a negative one or for fewer than 1 attempt.Validation
connect()went on to open a connection instead of refusing an out-of-range backoff.ReconnectTestcases pass against the real native library and ngrok 0.19.1's checks.NGROK_AUTHTOKENand runs in CI, asDataTestdoes.javadoc -Xdoclint:all.Weak spots, assumptions and decisions
aws-lc-sysis C code that must build on each of those targets.@ngrok/ngrokships the same provider on the same kinds of targets, but nothing here has built them.Cargo.lockmoves many dependencies (tokio, hyper, rustls, muxado) throughcargo update -p ngrok.src/lib.rscompiled unchanged, with no deprecation warnings, so this assumes no behaviour the binding relies on changed silently in between.reconnectJitterorreconnectMaxAttemptstake 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 inconnect_nativewould leave the tests green.accept()andjoin()throwing) is read from the code of ngrok 0.19.1 and this binding, not seen in a run. ngrok-jetty'sNgrokConnectorcallsaccept()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.Session.Buildergetters on everyconnect(), so a native jar from this change beside an olderngrok-javajar fails atconnect(), 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 asgetTrafficPolicyalready needed in 1.1.0.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.java.time.Durationvalues, passed to Rust to the nanosecond fromgetSecondsandgetNano. The alternative was whole milliseconds through thetoMillisconversionheartbeatIntervaluses, which truncates, so a value a fraction of a millisecond out of range would be accepted.reconnectMaxAttemptstakes anint, so the largest limit is 2147483647 rather than ngrok-rust's 4294967295. The alternative was alongchecked against theu32range.@ngrok/ngrokdoes.reconnect_policyfrom 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
ngrokto 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.