Repository navigation
session: add reconnect backoff, jitter and attempt limit options - #216
Conversation
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.
7547d8d to
1927a99
Compare
1927a99 to
faafa6e
Compare
There was a problem hiding this comment.
🔵 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
7642238 to
5493182
Compare
5493182 to
243c4e4
Compare
84d3acd to
88d7915
Compare
There was a problem hiding this comment.
🔵 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
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.
88d7915 to
7ef1761
Compare
joshbottelberghe
left a comment
There was a problem hiding this comment.
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.
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.
7ef1761 to
c0ed532
Compare
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
SessionBuilderoptions 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:", andjoin()with one starting "error on join:". Nothing rejects forngrok.forward.listenAndServe,ngrok.listenandnet.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 withconsole.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
ngrokfrom 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
u32version,2**32 + 50ms 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;listenAndServeandnet.Server.listen(listener)logged nothing when forwarding rejected, and the rejection went unhandled.Weak spots, assumptions and decisions
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'si64conversion does, keeping ngrok-rust's error unprefixed, oru32, whose ToUint32 conversion wraps2**32 + 50to 50 without an error.heartbeatIntervaland the other existing numeric setters still takeu32and truncate.whole_numberandjs_numberinsrc/session.rsare the conversion and the error text. A value above 2**53 is accepted as the whole number the double holds.listener.join(), which rejects with the same error.forward()rejects, throughlistenAndServeandnet.Server.listen(listener).ngrokLinkTcp, whichngrok.listenfalls back to when it cannot listen on a pipe, goes through the sameforwardInBackgroundbut no test reaches it.reconnectJitterorreconnectMaxAttemptstake 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.reconnectJitterreturns the builder without an error, because ngrok-rust's setter cannot fail.reconnect_policyfrom ngrok-rust#213 is not exposed: it is a Rust callback consulted on every reconnect, which a JavaScript callback cannot serve.Cargo.locktakesngrok0.19.1 andmuxado0.5.4 from crates.io and changes nothing else from 0.19.0, except thatngrokno longer depends onparking_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
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 an@ngrok/ngrokrelease ships it, it is a one-way door: the three methods are public API, and removing them breaks callers.