Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
5 changes: 2 additions & 3 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"] }
Expand Down
3 changes: 3 additions & 0 deletions python/ngrok/ngrok.pyi
Original file line number Diff line number Diff line change
Expand Up @@ -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: ...

Expand Down
105 changes: 104 additions & 1 deletion src/session.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
use std::{
borrow::BorrowMut,
env,
fmt::Display,
num::NonZeroU32,
sync::Arc,
time::Duration,
};
Expand All @@ -24,8 +26,13 @@ use pyo3::{
pyclass,
pyfunction,
pymethods,
types::PyByteArray,
types::{
PyAnyMethods,
PyByteArray,
PyLong,
},
Bound,
FromPyObject,
PyAny,
PyErr,
PyObject,
Expand All @@ -50,6 +57,7 @@ use crate::{
TcpListenerBuilder,
TlsListenerBuilder,
},
py_err,
py_ngrok_err,
};

Expand Down Expand Up @@ -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<PyRefMut<'a, Self>> {
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<Self>, enabled: bool) -> PyRefMut<Self> {
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<PyRefMut<'a, Self>> {
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
Expand Down Expand Up @@ -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<T> {
value
.extract()
.map_err(|_| py_err(format!("{name} must be from {min} to {max}, got {value}")))
}
14 changes: 14 additions & 0 deletions test/test.py
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
96 changes: 96 additions & 0 deletions test/test_reconnect.py
Original file line number Diff line number Diff line change
@@ -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()
Loading