Skip to content

session: add reconnect backoff, jitter and attempt limit options - #169

Merged
wesnel merged 2 commits into
wgn/test-fresh-endpoint-flakefrom
wgn/agent-1371-reconnect-options
Nov 17, 2026
Merged

wesnel merged 2 commits into
wgn/test-fresh-endpoint-flakefrom
wgn/agent-1371-reconnect-options

Conversation

@wesnel

@wesnel wesnel commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

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 ngrok to 0.19.1 and adds three SessionBuilder methods 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's forward() raises a ValueError starting "error forwarding:", and awaiting join() one starting "error on join:". The forwarding that ngrok.forward and ngrok.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 ValueError names the rule broken, and the binding puts the call and its arguments in front of it, as in reconnect_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's TypeError naming 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 a ValueError such as initial_ms must be from 0 to 18446744073709551615, got -1.

Validation

  • Before the methods existed, test/test_reconnect.py failed with AttributeError. With them, its 9 tests pass; they need no connection.
  • With pyo3's own u64/u32 conversion, a negative or too-large int raised OverflowError without naming the argument; that is why the binding takes ints and converts them itself.
  • Removing the call prefix from ngrok-rust's error fails the three range cases.
  • A scratch script showed that a failing pyo3 future that is never awaited, as ngrok.listen(server) starts forward, neither ends the process nor logs anything.
  • test_reconnect_options_connect in test/test.py, which connects with all three options set, needs an authtoken and runs in CI only.

Weak spots, assumptions and decisions

  • No test sees reconnect_jitter or reconnect_max_attempts take 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.
  • What a caller sees once the session stops reconnecting (forward() and join() raising, ngrok.forward going quiet) is read from the code of ngrok 0.19.1 and of this binding, not seen in a run.
  • Decision: milliseconds as ints, named as in ngrok-javascript, although heartbeat_interval and heartbeat_tolerance here take whole seconds. The alternative was float seconds, as time.sleep takes.
  • Decision: int_in_range in src/session.rs raises a ValueError naming the argument for an out-of-range int. The alternative was pyo3's OverflowError, which does not name it.
  • Decision: no logging for forwarding that ends with an error, unlike ngrok-javascript#216, which added it because an unhandled rejection ends a Node process. Here it ends nothing, but it is silent.
  • Decision: no ngrok.forward keyword arguments for these options; ngrok-javascript did not add them to its config either.
  • Decision: reconnect_policy from 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.lock changes only ngrok, which no longer depends on parking_lot; this crate still uses it directly.

Reverting

Before a release, this is a two-way door. Reverting removes the three methods, returns ngrok to 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.

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
wesnel force-pushed the wgn/agent-1371-reconnect-options branch from fe80c89 to 79619f1 Compare November 16, 2026 19:45
@wesnel
wesnel changed the base branch from main to wgn/test-fresh-endpoint-flake November 16, 2026 19:45
@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.

🟢 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 SessionBuilder methods 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
wesnel added this pull request to stack #172 November 16, 2026 22:51
@wesnel
wesnel marked this pull request as ready for review November 16, 2026 22:52
@wesnel
wesnel merged commit 4777e21 into main Nov 17, 2026
17 checks passed
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.

3 participants