diff --git a/CHANGELOG.md b/CHANGELOG.md index c6ea750..b67e441 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +## Unreleased + +- Change how a session waits between reconnect attempts after it loses its connection, for every session: the wait starts at 50 ms and doubles up to 30 s, each wait scaled by a random factor in [0, 1). Before, the wait grew 50-fold per attempt with no cap and no random factor: about 2 minutes before the fourth attempt and 1 h 44 min before the fifth. +- Add `SessionBuilder.reconnectBackoff(initialMs, maxMs)`, which sets the first wait between reconnect attempts and the cap the doubling waits stop at, and `SessionBuilder.reconnectJitter(enabled)`, which turns off or on the random scaling of each wait. The defaults are 50 ms, 30 s and jitter on. `reconnectBackoff` refuses a value that is not a whole number of milliseconds, such as a fraction, NaN or Infinity, with an error naming the argument. +- Add `SessionBuilder.reconnectMaxAttempts(attempts)`, which stops a session reconnecting after that many failed attempts in one outage; every listener then stops forwarding, and its `forward()` and `join()` reject with the last attempt's error. `listenAndServe`, `ngrok.listen` and `net.Server.listen(listener)` log that error with `console.error` and leave the process running. It refuses anything but a whole number from 1 to 4294967295. By default a session never stops reconnecting on its own. + ## 1.7.0 - Add support for CEL filtering when listing resources. diff --git a/Cargo.lock b/Cargo.lock index 2ab349b..cfa7d8a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1122,9 +1122,9 @@ dependencies = [ [[package]] name = "ngrok" -version = "0.19.0" +version = "0.19.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "10f6c455d972d973dded17538cb01426ca79eccb9774ae8ab8f1af637f469f3f" +checksum = "cc448f204f9e168e07f71ee16b8462591408315dc0d3dc3b6977bdb4a0d12f68" dependencies = [ "arc-swap", "async-trait", @@ -1143,7 +1143,6 @@ dependencies = [ "hyper-util", "muxado", "once_cell", - "parking_lot", "pin-project", "proxy-protocol", "regex", diff --git a/Cargo.toml b/Cargo.toml index cc83efd..e9f0169 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -17,7 +17,7 @@ mio = { version = "=0.8.6" } # Default enable napi4 feature, see https://nodejs.org/api/n-api.html#node-api-version-matrix napi = { version = "2.12.1", default-features = false, features = ["napi4", "tokio_rt"] } napi-derive = "2.12.1" -ngrok = {version = "0.19.0", features = ["hyper", "axum"]} +ngrok = {version = "0.19.1", features = ["hyper", "axum"]} parking_lot = "0.12.1" regex = "1.9.5" rustls = "0.23.25" diff --git a/__test__/online.spec.mjs b/__test__/online.spec.mjs index cbe9635..d751ccd 100644 --- a/__test__/online.spec.mjs +++ b/__test__/online.spec.mjs @@ -506,6 +506,130 @@ test("connect heartbeat callbacks", async () => { expect(undefined).toBe(disconn_addr); }); +// The limits are ngrok-rust's; the binding passes its error through, after +// the call and its arguments. +test.each([ + ["a start of 0 ms", 0, 1000, "the start must be at least 1 ms"], + ["a start above the cap", 2000, 1000, "the start must not be above the cap"], + ["a cap above one day", 1, 86_400_001, "the cap must be at most one day"], + // Above 2**32, so a u32 argument would wrap these to 50 ms and accept them. + ["a start of 2**32 + 50 ms", 2 ** 32 + 50, 1000, "the start must not be above the cap"], + ["a cap of 2**32 + 50 ms", 1, 2 ** 32 + 50, "the cap must be at most one day"], +])("session reconnect backoff rejects %s", (_, initialMs, maxMs, rule) => { + const builder = new ngrok.SessionBuilder(); + expect(() => builder.reconnectBackoff(initialMs, maxMs)).toThrow( + new RegExp(`^reconnectBackoff\\(initialMs: ${initialMs}, maxMs: ${maxMs}\\): .*${rule}$`), + ); +}); + +// The binding refuses what is not a whole number of milliseconds, naming the +// argument, before ngrok-rust sees it. +test.each([ + ["a negative start", -1, 1000, "initialMs", "-1"], + ["a negative cap", 1, -1, "maxMs", "-1"], + ["a fractional start", 0.5, 1000, "initialMs", "0.5"], + ["a fractional cap", 1, 1000.5, "maxMs", "1000.5"], + ["a NaN start", NaN, 1000, "initialMs", "NaN"], + ["an infinite cap", 1, Infinity, "maxMs", "Infinity"], +])("session reconnect backoff rejects %s", (_, initialMs, maxMs, name, shown) => { + const builder = new ngrok.SessionBuilder(); + expect(() => builder.reconnectBackoff(initialMs, maxMs)).toThrow( + `${name} must be a whole number of milliseconds, at least 0, got ${shown}`, + ); +}); + +test("session reconnect backoff accepts 1 ms to one day", () => { + const builder = new ngrok.SessionBuilder(); + expect(builder.reconnectBackoff(1, 86_400_000)).toBe(builder); +}); + +test.each([ + ["0", 0, "0"], + ["-1", -1, "-1"], + ["2**32 + 1", 2 ** 32 + 1, "4294967297"], + ["2.5", 2.5, "2.5"], + ["NaN", NaN, "NaN"], + ["Infinity", Infinity, "Infinity"], +])("session reconnect max attempts rejects %s", (_, attempts, shown) => { + const builder = new ngrok.SessionBuilder(); + expect(() => builder.reconnectMaxAttempts(attempts)).toThrow( + `attempts must be a whole number from 1 to 4294967295, got ${shown}`, + ); +}); + +test("session reconnect max attempts accepts 3", () => { + const builder = new ngrok.SessionBuilder(); + expect(builder.reconnectMaxAttempts(3)).toBe(builder); +}); + +test("session reconnect options connect", async () => { + const session = await new ngrok.SessionBuilder() + .authtoken(process.env["NGROK_AUTHTOKEN"]) + .reconnectBackoff(100, 5000) + .reconnectJitter(false) + .reconnectMaxAttempts(5) + .connect(); + const httpServer = await makeHttp(); + const listener = await session.httpEndpoint().listen(); + expect(listener.url().startsWith("https://")).toBeTruthy(); + await forwardValidateShutdown(httpServer, listener, listener.url()); + await session.close(); +}); + +// A listener's forward() rejects once its session stops reconnecting, which no +// test here can bring about, so a fake builder and listener stand in for the +// native ones. +function givenUpBuilder() { + const listener = { + id: () => "given-up-" + Math.floor(Math.random() * 1000000), + forward: () => Promise.reject(new Error("error forwarding: session gave up")), + }; + return { _listen: async () => listener }; +} + +async function errorsLoggedDuring(run) { + const logged = []; + const consoleError = console.error; + console.error = (message) => logged.push(String(message)); + try { + await run(); + // let the rejection's handler run + await new Promise((resolve) => setImmediate(resolve)); + } finally { + console.error = consoleError; + } + return logged; +} + +test("listenAndServe logs forwarding that ends with an error", async () => { + const server = createHttpServer(); + const logged = await errorsLoggedDuring(() => + ngrok.HttpListenerBuilder.prototype.listenAndServe.call(givenUpBuilder(), server), + ); + server.close(); + expect(logged).toEqual([ + expect.stringMatching( + /^ngrok listener stopped forwarding to \S+: Error: error forwarding: session gave up$/, + ), + ]); +}); + +test("net.Server.listen(listener) logs forwarding that ends with an error", async () => { + const server = createHttpServer(); + let listener; + const logged = await errorsLoggedDuring(async () => { + listener = await ngrok.HttpListenerBuilder.prototype.listen.call(givenUpBuilder()); + server.listen(listener); + }); + server.close(); + listener.socket.close(); + expect(logged).toEqual([ + expect.stringMatching( + /^ngrok listener stopped forwarding to localhost:\d+: Error: error forwarding: session gave up$/, + ), + ]); +}); + test("session ca_cert", async () => { const builder = new ngrok.SessionBuilder(); try { diff --git a/index.d.ts b/index.d.ts index e8836dc..163ac35 100644 --- a/index.d.ts +++ b/index.d.ts @@ -843,6 +843,56 @@ export declare class SessionBuilder { * [heartbeat_tolerance parameter in the ngrok docs]: https://ngrok.com/docs/ngrok-agent/config#heartbeat_tolerance */ heartbeatTolerance(heartbeatTolerance: number): this + /** + * Configures how long the session waits between attempts to reconnect + * after it loses its connection to the ngrok service, in milliseconds. + * + * The first attempt is immediate. After it, the session waits `initialMs`, + * then twice as long before each attempt, up to `maxMs`. Each wait is + * scaled by a random factor in [0, 1) unless + * [SessionBuilder::reconnectJitter] turns that off. The defaults are + * 50 ms and 30 s. For a fixed wait between every attempt, pass the same + * value for both and turn jitter off. + * + * These waits never stop the session from reconnecting on their own: + * [SessionBuilder::reconnectMaxAttempts], or closing the session, does. + * + * A value that is not a whole number of milliseconds of at least 0 (a + * fraction, a negative number, NaN or Infinity) is refused with an error + * naming the argument. The ngrok Rust SDK then checks the range: it + * rejects an `initialMs` below 1 or above `maxMs`, and a `maxMs` above one + * day (86400000), with an error that starts with the call and its + * arguments, as in "reconnectBackoff(initialMs: 2000, maxMs: 1000): ", + * and names the rule broken. A refused call leaves the builder unchanged. + */ + reconnectBackoff(initialMs: number, maxMs: number): this + /** + * Configures whether each wait between reconnect attempts is scaled by a + * random factor in [0, 1). On by default, so that sessions that lose + * their connections together don't all reconnect at the same moment. + */ + reconnectJitter(enabled: boolean): this + /** + * Configures the session to stop reconnecting after `attempts` failed + * attempts in one outage, counting the immediate first attempt. Each new + * outage starts the count again. By default the session never stops on + * its own. + * + * When the session stops, every listener stops forwarding with the last + * attempt's error: [Listener::forward] rejects with an error whose message + * starts "error forwarding:", and [Listener::join] with one that starts + * "error on join:". Nothing rejects for the forwarding that `ngrok.forward` + * starts. The forwarding that `listenAndServe`, `ngrok.listen` and + * `net.Server.listen(listener)` start logs the error with `console.error` + * and leaves the process running. The + * [SessionBuilder::handleDisconnection] handler is called before each + * attempt, and not again once the session stops. + * + * `attempts` must be a whole number from 1 to 4294967295; anything else, + * a fraction, NaN or Infinity included, is refused with an error naming + * the argument. + */ + reconnectMaxAttempts(attempts: number): this /** * Configures the opaque, machine-readable metadata string for this session. * Metadata is made available to you in the ngrok dashboard and the Agents API diff --git a/index.js b/index.js index 5af1b25..85bab05 100644 --- a/index.js +++ b/index.js @@ -411,7 +411,7 @@ function defineListenerHandle(listener, socket) { Object.defineProperty(listener, "handle", { get: function () { // turn on forwarding now that it has been requested - listener.forward("localhost:" + socket.address().port); + forwardInBackground(listener, "localhost:" + socket.address().port); return socket._handle; }, }); @@ -486,10 +486,19 @@ async function ngrokLinkTcp(listener, server) { // random local port const socket = await asyncListen(server, { host: "localhost", port: 0 }); // forward to socket - listener.forward("localhost:" + socket.address().port); + forwardInBackground(listener, "localhost:" + socket.address().port); return socket; } +// Start forwarding without waiting for it to end. Forwarding ends with an error +// when the session stops reconnecting (SessionBuilder.reconnectMaxAttempts); +// that error is logged, since a rejection left unhandled ends the process. +function forwardInBackground(listener, addr) { + listener.forward(addr).catch((err) => { + console.error(`ngrok listener stopped forwarding to ${addr}: ${err}`); + }); +} + function generatePipeFilename(listener, server) { var proposed = "tun-" + listener.id() + ".sock"; @@ -552,7 +561,7 @@ async function ngrokLinkPipe(listener, server) { // convert pipe path to url addr = "pipe:" + filename.replace("\\\\.\\pipe\\", "//./"); } - listener.forward(addr); + forwardInBackground(listener, addr); socket.path = filename; // surface to caller return socket; diff --git a/src/session.rs b/src/session.rs index cf3ea32..ad6afc3 100644 --- a/src/session.rs +++ b/src/session.rs @@ -1,5 +1,6 @@ use std::{ env, + num::NonZeroU32, sync::Arc, time::Duration, }; @@ -182,6 +183,94 @@ impl SessionBuilder { Ok(self) } + /// Configures how long the session waits between attempts to reconnect + /// after it loses its connection to the ngrok service, in milliseconds. + /// + /// The first attempt is immediate. After it, the session waits `initialMs`, + /// then twice as long before each attempt, up to `maxMs`. Each wait is + /// scaled by a random factor in [0, 1) unless + /// [SessionBuilder::reconnectJitter] turns that off. The defaults are + /// 50 ms and 30 s. For a fixed wait between every attempt, pass the same + /// value for both and turn jitter off. + /// + /// These waits never stop the session from reconnecting on their own: + /// [SessionBuilder::reconnectMaxAttempts], or closing the session, does. + /// + /// A value that is not a whole number of milliseconds of at least 0 (a + /// fraction, a negative number, NaN or Infinity) is refused with an error + /// naming the argument. The ngrok Rust SDK then checks the range: it + /// rejects an `initialMs` below 1 or above `maxMs`, and a `maxMs` above one + /// day (86400000), with an error that starts with the call and its + /// arguments, as in "reconnectBackoff(initialMs: 2000, maxMs: 1000): ", + /// and names the rule broken. A refused call leaves the builder unchanged. + #[napi] + pub fn reconnect_backoff(&mut self, initial_ms: f64, max_ms: f64) -> Result<&Self> { + let millis = |name: &str, ms: f64| { + whole_number(ms).map(Duration::from_millis).ok_or_else(|| { + napi_err(format!( + "{name} must be a whole number of milliseconds, at least 0, got {}", + js_number(ms) + )) + }) + }; + let initial = millis("initialMs", initial_ms)?; + let max = millis("maxMs", max_ms)?; + let mut builder = self.raw_builder.lock(); + builder.reconnect_backoff(initial, max).map_err(|e| { + napi_err(format!( + "reconnectBackoff(initialMs: {}, maxMs: {}): {e}", + js_number(initial_ms), + js_number(max_ms) + )) + })?; + Ok(self) + } + + /// Configures whether each wait between reconnect attempts is scaled by a + /// random factor in [0, 1). On by default, so that sessions that lose + /// their connections together don't all reconnect at the same moment. + #[napi] + pub fn reconnect_jitter(&mut self, enabled: bool) -> &Self { + let mut builder = self.raw_builder.lock(); + builder.reconnect_jitter(enabled); + self + } + + /// Configures the session to stop reconnecting after `attempts` failed + /// attempts in one outage, counting the immediate first attempt. Each new + /// outage starts the count again. By default the session never stops on + /// its own. + /// + /// When the session stops, every listener stops forwarding with the last + /// attempt's error: [Listener::forward] rejects with an error whose message + /// starts "error forwarding:", and [Listener::join] with one that starts + /// "error on join:". Nothing rejects for the forwarding that `ngrok.forward` + /// starts. The forwarding that `listenAndServe`, `ngrok.listen` and + /// `net.Server.listen(listener)` start logs the error with `console.error` + /// and leaves the process running. The + /// [SessionBuilder::handleDisconnection] handler is called before each + /// attempt, and not again once the session stops. + /// + /// `attempts` must be a whole number from 1 to 4294967295; anything else, + /// a fraction, NaN or Infinity included, is refused with an error naming + /// the argument. + #[napi] + pub fn reconnect_max_attempts(&mut self, attempts: f64) -> Result<&Self> { + let attempts = whole_number(attempts) + .and_then(|n| u32::try_from(n).ok()) + .and_then(NonZeroU32::new) + .ok_or_else(|| { + napi_err(format!( + "attempts must be a whole number from 1 to {}, got {}", + u32::MAX, + js_number(attempts) + )) + })?; + let mut builder = self.raw_builder.lock(); + builder.reconnect_max_attempts(attempts); + Ok(self) + } + /// Configures the opaque, machine-readable metadata string for this session. /// Metadata is made available to you in the ngrok dashboard and the Agents API /// resource. It is a useful way to allow you to uniquely identify sessions. We @@ -527,6 +616,25 @@ impl ObjectFinalize for Session { } } +/// `n` as a u64 if it is a whole number from 0 to u64::MAX, else None. +fn whole_number(n: f64) -> Option { + // 2^64 itself is exactly representable, and the first value out of range. + (n.fract() == 0.0 && (0.0..18_446_744_073_709_551_616.0).contains(&n)).then_some(n as u64) +} + +/// `n` for error messages: NaN and Infinity spelled as JavaScript spells them, +/// other values as Rust prints them, which differs from JavaScript for -0 and +/// for values JavaScript writes with an exponent. +fn js_number(n: f64) -> String { + if n.is_nan() { + "NaN".to_string() + } else if n.is_infinite() { + if n > 0.0 { "Infinity" } else { "-Infinity" }.to_string() + } else { + n.to_string() + } +} + /// Container for UpdateRequest information. #[derive(Clone)] #[napi] diff --git a/trailer.js b/trailer.js index 9a0c87c..5cc44fd 100644 --- a/trailer.js +++ b/trailer.js @@ -80,7 +80,7 @@ function defineListenerHandle(listener, socket) { Object.defineProperty(listener, "handle", { get: function () { // turn on forwarding now that it has been requested - listener.forward("localhost:" + socket.address().port); + forwardInBackground(listener, "localhost:" + socket.address().port); return socket._handle; }, }); @@ -155,10 +155,19 @@ async function ngrokLinkTcp(listener, server) { // random local port const socket = await asyncListen(server, { host: "localhost", port: 0 }); // forward to socket - listener.forward("localhost:" + socket.address().port); + forwardInBackground(listener, "localhost:" + socket.address().port); return socket; } +// Start forwarding without waiting for it to end. Forwarding ends with an error +// when the session stops reconnecting (SessionBuilder.reconnectMaxAttempts); +// that error is logged, since a rejection left unhandled ends the process. +function forwardInBackground(listener, addr) { + listener.forward(addr).catch((err) => { + console.error(`ngrok listener stopped forwarding to ${addr}: ${err}`); + }); +} + function generatePipeFilename(listener, server) { var proposed = "tun-" + listener.id() + ".sock"; @@ -221,7 +230,7 @@ async function ngrokLinkPipe(listener, server) { // convert pipe path to url addr = "pipe:" + filename.replace("\\\\.\\pipe\\", "//./"); } - listener.forward(addr); + forwardInBackground(listener, addr); socket.path = filename; // surface to caller return socket;