diff --git a/CHANGELOG.md b/CHANGELOG.md index 7a446392..ce8a339d 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.reconnect_backoff(initial_ms, max_ms)`, which sets the first wait between reconnect attempts and the cap the doubling waits stop at, and `SessionBuilder.reconnect_jitter(enabled)`, which turns off or on the random scaling of each wait. The defaults are 50 ms, 30 s and jitter on. `reconnect_backoff` refuses a start below 1 ms or above the cap, and a cap above one day, with a `ValueError`. +- Add `SessionBuilder.reconnect_max_attempts(attempts)`, which stops a session reconnecting after that many failed attempts in one outage; every listener then stops forwarding, and awaiting its `forward()` or `join()` raises the last attempt's error. The forwarding that `ngrok.forward` and `ngrok.listen(server)` start then stops without raising or logging. It refuses anything but an int 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. - Add support for service users diff --git a/Cargo.lock b/Cargo.lock index b6988c17..9998a19a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1051,9 +1051,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", @@ -1071,7 +1071,6 @@ dependencies = [ "hyper-util", "muxado", "once_cell", - "parking_lot", "pin-project", "proxy-protocol", "regex", diff --git a/Cargo.toml b/Cargo.toml index cea4cc57..69eb2ee2 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -15,7 +15,7 @@ futures = "0.3.26" lazy_static = "1.4.0" log = "0.4" mio = { version = "1.0.3" } -ngrok = { version = "0.19.0", features = ["hyper"] } +ngrok = { version = "0.19.1", features = ["hyper"] } once_cell = {version = "1.21"} pyo3 = { version = "0.22", features = ["abi3", "abi3-py310", "extension-module", "multiple-pymethods", "experimental-async", "gil-refs", "generate-import-lib"]} pyo3-async-runtimes = { version = "0.22", features = ["attributes", "tokio-runtime"] } diff --git a/python/ngrok/ngrok.pyi b/python/ngrok/ngrok.pyi index 2456cbcb..4853f291 100644 --- a/python/ngrok/ngrok.pyi +++ b/python/ngrok/ngrok.pyi @@ -64,6 +64,9 @@ class SessionBuilder: def heartbeat_interval(self, heartbeat_interval: int) -> SessionBuilder: ... def heartbeat_tolerance(self, heartbeat_tolerance: int) -> SessionBuilder: ... def metadata(self, metadata: str) -> SessionBuilder: ... + def reconnect_backoff(self, initial_ms: int, max_ms: int) -> SessionBuilder: ... + def reconnect_jitter(self, enabled: bool) -> SessionBuilder: ... + def reconnect_max_attempts(self, attempts: int) -> SessionBuilder: ... def root_cas(self, root_cas: str) -> SessionBuilder: ... def server_addr(self, server_addr: str) -> SessionBuilder: ... diff --git a/src/session.rs b/src/session.rs index 4e5ded18..4124733d 100644 --- a/src/session.rs +++ b/src/session.rs @@ -1,6 +1,8 @@ use std::{ borrow::BorrowMut, env, + fmt::Display, + num::NonZeroU32, sync::Arc, time::Duration, }; @@ -24,8 +26,13 @@ use pyo3::{ pyclass, pyfunction, pymethods, - types::PyByteArray, + types::{ + PyAnyMethods, + PyByteArray, + PyLong, + }, Bound, + FromPyObject, PyAny, PyErr, PyObject, @@ -50,6 +57,7 @@ use crate::{ TcpListenerBuilder, TlsListenerBuilder, }, + py_err, py_ngrok_err, }; @@ -252,6 +260,88 @@ impl SessionBuilder { 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 ``initial_ms``, + /// then twice as long before each attempt, up to ``max_ms``. Each wait is + /// scaled by a random factor in [0, 1) unless :meth:`reconnect_jitter` + /// 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: + /// :meth:`reconnect_max_attempts`, or closing the session, does. + /// + /// An argument that is not an int is refused with a ``TypeError``, and an + /// int below 0 or above 18446744073709551615 with a ``ValueError``, each + /// naming the argument. The ngrok Rust SDK then checks the range: it + /// rejects an ``initial_ms`` below 1 or above ``max_ms``, and a ``max_ms`` + /// above one day (86400000), with a ``ValueError`` that starts with the + /// call and its arguments, as in + /// "reconnect_backoff(initial_ms=2000, max_ms=1000): ", and names the rule + /// broken. A refused call leaves the builder unchanged. + pub fn reconnect_backoff<'a>( + self_: PyRefMut<'a, Self>, + initial_ms: &Bound<'_, PyLong>, + max_ms: &Bound<'_, PyLong>, + ) -> PyResult> { + let initial_ms: u64 = int_in_range("initial_ms", initial_ms, 0, u64::MAX)?; + let max_ms: u64 = int_in_range("max_ms", max_ms, 0, u64::MAX)?; + let mut result = Ok(()); + self_.set(|b| { + result = b + .reconnect_backoff( + Duration::from_millis(initial_ms), + Duration::from_millis(max_ms), + ) + .map(|_| ()) + .map_err(|e| { + py_err(format!( + "reconnect_backoff(initial_ms={initial_ms}, max_ms={max_ms}): {e}" + )) + }); + }); + result.map(|_| 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. + pub fn reconnect_jitter(self_: PyRefMut, enabled: bool) -> PyRefMut { + self_.set(|b| { + b.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: awaiting a listener's ``forward`` raises a ``ValueError`` + /// whose message starts "error forwarding:", and awaiting its ``join`` one + /// that starts "error on join:". Nothing raises for the forwarding that + /// ``ngrok.forward``, or ``ngrok.listen`` given a server, starts: it ends + /// without a sign. The handler given to + /// :meth:`handle_disconnection` is called before each attempt, and not + /// again once the session stops. + /// + /// ``attempts`` must be an int from 1 to 4294967295. Anything else is + /// refused, naming the argument: what is not an int with a ``TypeError``, + /// an int out of that range with a ``ValueError``. + pub fn reconnect_max_attempts<'a>( + self_: PyRefMut<'a, Self>, + attempts: &Bound<'_, PyLong>, + ) -> PyResult> { + let attempts: NonZeroU32 = int_in_range("attempts", attempts, 1, u32::MAX)?; + self_.set(|b| { + b.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 @@ -552,3 +642,16 @@ impl Drop for Session { debug!("Session drop"); } } + +/// `value` as a `T`, or a ValueError naming the argument and the range from +/// `min` to `max` that `T` holds. +fn int_in_range<'py, T: FromPyObject<'py>>( + name: &str, + value: &Bound<'py, PyLong>, + min: impl Display, + max: impl Display, +) -> PyResult { + value + .extract() + .map_err(|_| py_err(format!("{name} must be from {min} to {max}, got {value}"))) +} diff --git a/test/test.py b/test/test.py index 2fcbea40..adb2bda7 100644 --- a/test/test.py +++ b/test/test.py @@ -175,6 +175,20 @@ async def test_https_listener(self): await self.forward_validate_shutdown(http_server, listener, listener.url()) + async def test_reconnect_options_connect(self): + http_server = make_http() + session = ( + await ngrok.SessionBuilder() + .authtoken_from_env() + .reconnect_backoff(100, 5000) + .reconnect_jitter(False) + .reconnect_max_attempts(5) + .connect() + ) + listener = await session.http_endpoint().listen() + self.assertTrue(listener.url().startswith("https://")) + await self.forward_validate_shutdown(http_server, listener, listener.url()) + async def test_http_listener(self): http_server, session = await make_http_and_session() listener = await session.http_endpoint().scheme("hTtP").listen() diff --git a/test/test_reconnect.py b/test/test_reconnect.py new file mode 100644 index 00000000..97cae101 --- /dev/null +++ b/test/test_reconnect.py @@ -0,0 +1,96 @@ +"""SessionBuilder's reconnect options, checked without connecting.""" + +import re +import unittest + +import ngrok + + +class TestReconnectBackoff(unittest.TestCase): + # The range rules are ngrok-rust's; the binding passes its error through, + # after the call and its arguments. + def test_rejects_ranges_ngrok_rust_refuses(self): + cases = [ + ("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 32-bit argument would wrap it to 50 ms and + # accept it. + ("a cap of 2**32 + 50 ms", 1, 2**32 + 50, "the cap must be at most one day"), + ] + for name, initial_ms, max_ms, rule in cases: + with self.subTest(name): + with self.assertRaisesRegex( + ValueError, + rf"^reconnect_backoff\(initial_ms={initial_ms}, max_ms={max_ms}\): " + rf".*{re.escape(rule)}$", + ): + ngrok.SessionBuilder().reconnect_backoff(initial_ms, max_ms) + + # An int a u64 cannot hold is refused before ngrok-rust sees it, naming + # the argument. + def test_rejects_ints_out_of_u64_range(self): + cases = [ + ("a negative start", -1, 1000, "initial_ms", "-1"), + ("a negative cap", 1, -1, "max_ms", "-1"), + ("a start of 2**64", 2**64, 1000, "initial_ms", "18446744073709551616"), + ] + for name, initial_ms, max_ms, argument, shown in cases: + with self.subTest(name): + with self.assertRaisesRegex( + ValueError, + rf"^{argument} must be from 0 to 18446744073709551615, got {shown}$", + ): + ngrok.SessionBuilder().reconnect_backoff(initial_ms, max_ms) + + def test_rejects_what_is_not_an_int(self): + cases = [ + ("a fractional start", 0.5, 1000, "initial_ms"), + ("a fractional cap", 1, 1000.5, "max_ms"), + ("a string cap", 1, "1000", "max_ms"), + ] + for name, initial_ms, max_ms, argument in cases: + with self.subTest(name): + with self.assertRaisesRegex(TypeError, rf"^argument '{argument}': "): + ngrok.SessionBuilder().reconnect_backoff(initial_ms, max_ms) + + def test_accepts_1_ms_to_one_day(self): + builder = ngrok.SessionBuilder() + self.assertIs(builder.reconnect_backoff(1, 86_400_000), builder) + + def test_a_refused_call_leaves_the_builder_usable(self): + builder = ngrok.SessionBuilder() + with self.assertRaises(ValueError): + builder.reconnect_backoff(2000, 1000) + self.assertIs(builder.reconnect_backoff(100, 5000), builder) + + +class TestReconnectJitter(unittest.TestCase): + def test_returns_the_builder(self): + builder = ngrok.SessionBuilder() + self.assertIs(builder.reconnect_jitter(False), builder) + self.assertIs(builder.reconnect_jitter(True), builder) + + +class TestReconnectMaxAttempts(unittest.TestCase): + def test_rejects_ints_out_of_range(self): + for attempts in [0, -1, 2**32]: + with self.subTest(attempts): + with self.assertRaisesRegex( + ValueError, + rf"^attempts must be from 1 to 4294967295, got {attempts}$", + ): + ngrok.SessionBuilder().reconnect_max_attempts(attempts) + + def test_rejects_what_is_not_an_int(self): + with self.assertRaisesRegex(TypeError, r"^argument 'attempts': "): + ngrok.SessionBuilder().reconnect_max_attempts(2.5) + + def test_accepts_1_to_4294967295(self): + builder = ngrok.SessionBuilder() + self.assertIs(builder.reconnect_max_attempts(1), builder) + self.assertIs(builder.reconnect_max_attempts(2**32 - 1), builder) + + +if __name__ == "__main__": + unittest.main()