Repository navigation
session: add reconnect backoff, jitter and attempt limit options - #169
Merged
wesnel merged 2 commits intoNov 17, 2026
Merged
Conversation
wesnel
force-pushed
the
wgn/agent-1371-reconnect-options
branch
from
November 16, 2026 18:59
7723ec8 to
fe80c89
Compare
ngrok 0.19.0 waited 50^n ms between reconnect attempts, with no cap and no jitter: about 2 minutes before the fourth attempt and 1 h 44 min before the fifth, so a short outage could leave a session offline for hours. 0.19.1 starts at 50 ms, doubles up to 30 s and scales each wait by a random factor, for every session.
ngrok 0.19.1 lets a session's reconnect waits and attempt limit be set; these pass its three SessionBuilder setters through to Python, as ngrok-javascript 1.8.0 does. ngrok-rust keeps the range rules, and its error is prefixed with the call and its arguments. The binding takes Python ints and refuses one its Rust type cannot hold with a ValueError naming the argument, since pyo3's own OverflowError does not name it.
wesnel
force-pushed
the
wgn/agent-1371-reconnect-options
branch
from
November 16, 2026 19:45
fe80c89 to
79619f1
Compare
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues are recorded for the session reconnection configuration changes.
No open issues 🎉
What changed in this PR
Adds configurable session reconnection behavior to the Python SDK through ngrok-rust 0.19.1. The dependency update also changes default retries to capped exponential backoff with jitter for all sessions.
Changes:
- Expose fluent
SessionBuildermethods for reconnect backoff, jitter, and attempt limits, with Python type hints. - Validate integer arguments and document defaults, range errors, and forwarding behavior when retries stop.
- Add offline validation tests and an online connection test using all three options.
| File | Description |
|---|---|
test/test.py |
Adds a connection test with all reconnect options configured. |
test/test_reconnect.py |
Tests argument validation, boundaries, and fluent builder returns without connecting. |
src/session.rs |
Implements and documents reconnect setters and integer conversion errors. |
python/ngrok/ngrok.pyi |
Adds type signatures for the three new methods. |
CHANGELOG.md |
Documents new options and the changed default retry behavior. |
Cargo.toml |
Updates the ngrok dependency to 0.19.1. |
Cargo.lock |
Locks ngrok 0.19.1 and updates its dependency list. |
Review effort: Balanced
wesnel
marked this pull request as ready for review
November 16, 2026 22:52
wesnel
requested review from
andrew-harris-at-ngrok,
grant-higgins-0,
joshbottelberghe,
kevin-ngrok and
sajethm
November 16, 2026 22:53
joshbottelberghe
approved these changes
Nov 16, 2026
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. Stacked on #171, which fixes two flaky online tests. The 1.8.0 release that ships this is its own pull request, #170, stacked on this one. ngrok-javascript made the same change in ngrok/ngrok-javascript#216.
Bumps
ngrokto 0.19.1 and adds threeSessionBuildermethods for how a session reconnects after it loses its connection to ngrok. They pass straight through to ngrok-rust:reconnect_backoff(initial_ms, max_ms): the first wait between reconnect attempts and the cap. The wait doubles after each failed attempt until it reaches the cap. The defaults are 50 ms and 30 s.reconnect_jitter(enabled): whether each wait is scaled by a random factor in [0, 1), so that sessions that drop together don't all reconnect at once. On by default.reconnect_max_attempts(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, every listener stops forwarding: awaiting a listener'sforward()raises aValueErrorstarting "error forwarding:", and awaitingjoin()one starting "error on join:". The forwarding thatngrok.forwardandngrok.listen(server)start stops without raising or logging anything.The bump changes the default for every session, options set or not: a session that loses its connection now retries at most every 30 s, jittered, instead of waiting hours. With ngrok 0.19.0 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. The changelog says so.
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. Its
ValueErrornames the rule broken, and the binding puts the call and its arguments in front of it, as inreconnect_backoff(initial_ms=2000, max_ms=1000): invalid reconnect backoff (start 2s, cap 1s): the start must not be above the cap. The binding has no range rules of its own: it takes Python ints, refuses anything else with pyo3'sTypeErrornaming the argument, and refuses an int its Rust type cannot hold (below 0 or above 2**64 - 1 for the waits, outside 1 to 4294967295 for attempts) with aValueErrorsuch asinitial_ms must be from 0 to 18446744073709551615, got -1.Validation
test/test_reconnect.pyfailed withAttributeError. With them, its 9 tests pass; they need no connection.u64/u32conversion, a negative or too-large int raisedOverflowErrorwithout naming the argument; that is why the binding takes ints and converts them itself.ngrok.listen(server)startsforward, neither ends the process nor logs anything.test_reconnect_options_connectintest/test.py, which connects with all three options set, needs an authtoken and runs in CI only.Weak spots, assumptions and decisions
reconnect_jitterorreconnect_max_attemptstake effect against the real service: 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 would leave the tests green.forward()andjoin()raising,ngrok.forwardgoing quiet) is read from the code of ngrok 0.19.1 and of this binding, not seen in a run.heartbeat_intervalandheartbeat_tolerancehere take whole seconds. The alternative was float seconds, astime.sleeptakes.int_in_rangeinsrc/session.rsraises aValueErrornaming the argument for an out-of-range int. The alternative was pyo3'sOverflowError, which does not name it.ngrok.forwardkeyword arguments for these options; ngrok-javascript did not add them to its config either.reconnect_policyfrom ngrok-rust is not exposed. Another wait shape, if a caller needs one, goes into ngrok-rust as a built-in setter every SDK passes through, so the shapes and their checks don't drift between SDKs. The alternative was a Python callable consulted on every reconnect.Cargo.lockchanges onlyngrok, which no longer depends onparking_lot; this crate still uses it directly.Reverting
Before a release, this is a two-way door. Reverting removes the three methods, returns
ngrokto 0.19.0, and nothing is stored. It also brings back the old default for every session: waits that grow 50-fold with no cap and no jitter. Once a release on PyPI ships it, it is a one-way door: the three methods are public API, and removing them breaks callers.