Skip to content

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

Merged
wesnel merged 3 commits into
wgn/agent-1371-ngrok-0.19.0from
wgn/agent-1371-reconnect-options
Nov 13, 2026
Merged

wesnel merged 3 commits into
wgn/agent-1371-ngrok-0.19.0from
wgn/agent-1371-reconnect-options

Conversation

@wesnel

@wesnel wesnel commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

Part of AGENT-1371. Stacked on #215. The 1.8.0 release that ships this is its own pull request, stacked on this one.

Adds three SessionBuilder options for how a session reconnects after it loses its connection to ngrok. They pass straight through to ngrok-rust:

  • reconnectBackoff(initialMs, maxMs): 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.
  • reconnectJitter(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.
  • reconnectMaxAttempts(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: forward() rejects with an error starting "error forwarding:", and join() with one starting "error on join:". Nothing rejects for ngrok.forward.

listenAndServe, ngrok.listen and net.Server.listen(listener) start forwarding without awaiting it. When that forwarding ends with an error, as it does once the session stops reconnecting, they log it with console.error (ngrok listener stopped forwarding to <address>: <error>) and leave the process running, where the rejection used to go unhandled and end the process.

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 error names the rule that was broken. The binding puts the call and its arguments in front of it, as in reconnectBackoff(initialMs: 2000, maxMs: 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. Each argument arrives as a JavaScript number (f64), and the binding refuses anything that is not a whole number the Rust type can hold, with an error naming the argument and the value: a fraction, NaN, ±Infinity, a negative wait, or attempts outside 1 to 4294967295.

The options need ngrok 0.19.1, the first crates.io release that has them, so this bumps ngrok from 0.19.0. That release also 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. The wait starts at 50 ms and doubles up to the 30 s cap. 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. The changelog says so.

Validation

  • Before the code existed, the new tests failed for the expected reasons:
    • the methods were missing;
    • with an earlier u32 version, 2**32 + 50 ms wrapped to 50 ms and was accepted;
    • -1, 0.5, NaN and Infinity produced ngrok-rust's error, or were accepted, instead of an error naming the argument;
    • ngrok-rust's range errors lacked the call and its arguments;
    • listenAndServe and net.Server.listen(listener) logged nothing when forwarding rejected, and the rejection went unhandled.
  • With the code, all 21 tests that need no connection pass.
  • What a caller sees when the session stops reconnecting is read from the code of ngrok 0.19.1 and of this binding, not seen in a run (see below).
  • The test that connects with all three options set runs in CI's full online suite, on the Linux x64 job.

Weak spots, assumptions and decisions

  • Decision: arguments are f64, checked to be whole numbers, and errors name the argument and, for ngrok-rust's, the call. The alternatives were truncating fractions as napi's i64 conversion does, keeping ngrok-rust's error unprefixed, or u32, whose ToUint32 conversion wraps 2**32 + 50 to 50 without an error. heartbeatInterval and the other existing numeric setters still take u32 and truncate.
  • whole_number and js_number in src/session.rs are the conversion and the error text. A value above 2**53 is accepted as the whole number the double holds.
  • Decision: a listener whose forwarding ends with an error is logged and the process keeps running, with no tunnel for that listener. The alternative was leaving the rejection unhandled, which ends the process; an app that would rather exit has listener.join(), which rejects with the same error.
  • The tests of that logging use a fake builder and listener whose forward() rejects, through listenAndServe and net.Server.listen(listener). ngrokLinkTcp, which ngrok.listen falls back to when it cannot listen on a pipe, goes through the same forwardInBackground but no test reaches it.
  • No test sees reconnectJitter or reconnectMaxAttempts 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.
  • reconnectJitter returns the builder without an error, because ngrok-rust's setter cannot fail.
  • reconnect_policy from ngrok-rust#213 is not exposed: it is a Rust callback consulted on every reconnect, which a JavaScript callback cannot serve.
  • Cargo.lock takes ngrok 0.19.1 and muxado 0.5.4 from crates.io and changes nothing else from 0.19.0, except that ngrok no longer depends on parking_lot, which this crate still uses directly.

Reverting

Before a release, this is a two-way door. Reverting removes the three methods and the logging, 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 an @ngrok/ngrok release ships it, it is a one-way door: the three methods are public API, and removing them breaks callers.

wesnel added a commit that referenced this pull request Nov 11, 2026
The reconnect options of AGENT-1371 need SessionBuilder::reconnect_backoff,
reconnect_jitter and reconnect_max_attempts, which no ngrok release has
yet. ngrok/ngrok-rust#214 holds them with the stack below it: #216 (the
reconnect loop), #209 (the capped, jittered backoff), #210 (the backoff
and jitter setters), #213 (custom reconnect policies, not exposed here)
and #214 (the attempt limit). Patch the ngrok crate to #214's head so the
binding can be built and tested now; the crate there is still 0.19.0.
The patch goes before this merges, replaced by the crates.io release that
holds that stack.

Cargo also takes muxado from the same git revision, since ngrok depends
on it by path inside that repository. It is the same version, 0.5.4,
with no change to its source since the 0.19.0 release. ngrok at that
revision no longer depends on parking_lot, which this crate still uses
directly.
@wesnel
wesnel force-pushed the wgn/agent-1371-reconnect-options branch from 7547d8d to 1927a99 Compare November 11, 2026 23:19
@wesnel
wesnel added this pull request to stack #217 November 11, 2026 23:21
@wesnel
wesnel force-pushed the wgn/agent-1371-reconnect-options branch from 1927a99 to faafa6e Compare November 11, 2026 23:35
@wesnel
wesnel requested a balanced review from Copilot November 11, 2026 23:37

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 public reconnect API and changed session defaults depend on an unreleased ngrok-rust revision, requiring release-contract verification, replacement of the temporary Cargo patch, and online CI confirmation before merge.

No open issues 🎉

What changed in this PR

Adds reconnect controls to the Node.js SessionBuilder, passing configuration and validation through to ngrok-rust.

Changes:

  • Exposes reconnect backoff, jitter, and maximum-attempt options with TypeScript declarations.
  • Documents the new default behavior: exponential waits from 50 ms, capped at 30 seconds, with jitter enabled.
  • Adds argument-validation and connection tests, using a temporary ngrok-rust Git pin pending an upstream release.
File Description
src/​session.rs Implements the three builder methods and checked numeric conversions.
index.d.ts Declares and documents the new JavaScript API.
CHANGELOG.md Records the new options and changed reconnect defaults.
Cargo.toml Temporarily pins ngrok-rust to the unreleased implementation.
Cargo.lock Locks ngrok and muxado to the pinned Git revision.
__test__/​online.spec.mjs Adds validation, boundary, chaining, and connection tests.

Review effort: Balanced

@wesnel
wesnel force-pushed the wgn/agent-1371-reconnect-options branch 2 times, most recently from 7642238 to 5493182 Compare November 11, 2026 23:50
@wesnel
wesnel removed this pull request from stack #217 November 11, 2026 23:51
@wesnel
wesnel force-pushed the wgn/agent-1371-reconnect-options branch from 5493182 to 243c4e4 Compare November 11, 2026 23:57
@wesnel
wesnel added this pull request to stack #219 November 11, 2026 23:58
@wesnel
wesnel force-pushed the wgn/agent-1371-reconnect-options branch 3 times, most recently from 84d3acd to 88d7915 Compare November 13, 2026 00:35
@wesnel
wesnel requested a balanced review from Copilot November 13, 2026 00:36
@wesnel
wesnel marked this pull request as ready for review November 13, 2026 00:36

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 dependency bump changes reconnect timing across sessions and can terminate listenAndServe on attempt exhaustion, but outage behavior lacks runtime validation and upstream source was unavailable, requiring human review.

No open issues 🎉

Review effort: Balanced

@joshbottelberghe joshbottelberghe self-assigned this Nov 13, 2026
The reconnect options of AGENT-1371 need SessionBuilder::reconnect_backoff,
reconnect_jitter (ngrok/ngrok-rust#210) and reconnect_max_attempts
(ngrok/ngrok-rust#214), which ngrok 0.19.1 is the first release to hold.

The release also changes how every session waits between reconnect
attempts: the wait now starts at 50 ms and doubles
up to 30 s, each wait scaled by a random factor, where before it grew
50-fold per attempt with no cap, about 1 h 44 min before the fifth
attempt.

ngrok 0.19.1 no longer depends on parking_lot, which this crate still
uses directly. muxado stays at 0.5.4.
AGENT-1371: a session that loses its connection should come back within
bounds the caller can choose. ngrok-rust now caps the wait between
reconnect attempts, lets the caller set its start and cap, turn the
random scaling of each wait off, and stop after a number of failed
attempts. Expose the three setters on SessionBuilder:
reconnectBackoff(initialMs, maxMs), reconnectJitter(enabled) and
reconnectMaxAttempts(attempts). reconnect_policy is not exposed.

Each number arrives as a JavaScript number (f64), and the binding
refuses anything that is not a whole number the Rust type can hold,
naming the argument and the value: a fraction, NaN, Infinity, a negative
backoff, or attempts outside 1 to 4294967295. Through i64 a fraction
would be truncated silently, and through u32 2**32 + 50 would become 50.
Every other range is checked in ngrok-rust alone; its error, which names
the rule broken, reaches JavaScript after the call and its arguments, so
a caller can tell which of initialMs and maxMs "the start" and "the cap"
mean.

The doc comment of reconnectMaxAttempts says what each way of forwarding
does with the last attempt's error once the session stops.
@wesnel
wesnel force-pushed the wgn/agent-1371-reconnect-options branch from 88d7915 to 7ef1761 Compare November 13, 2026 00:47

@joshbottelberghe joshbottelberghe 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.

Approved. Read it against 88d7915 and the 0.19.1 crate: the whole-number checks and the pass-through match Rust's rules, and the docs match the crate's. One question inline on listenAndServe.

Comment thread src/session.rs Resolved
Comment thread Cargo.toml Resolved
With reconnectMaxAttempts set, a session that gives up makes every
listener's forward() reject. listenAndServe, ngrok.listen and
net.Server.listen(listener) start forwarding without awaiting it, so the
rejection was unhandled and ended the process. Log it with console.error
instead, naming the address forwarded to, and leave the process running.
@wesnel
wesnel force-pushed the wgn/agent-1371-reconnect-options branch from 7ef1761 to c0ed532 Compare November 13, 2026 01:01
@wesnel wesnel mentioned this pull request Nov 13, 2026
@wesnel
wesnel merged commit ee42133 into main Nov 13, 2026
23 checks passed
@wesnel
wesnel deleted the wgn/agent-1371-reconnect-options branch November 13, 2026 01:22
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.

5 participants