Skip to main content

ngrok/
session.rs

1use std::{
2    collections::{
3        HashMap,
4        VecDeque,
5    },
6    env,
7    io,
8    iter,
9    num::NonZeroU32,
10    pin::pin,
11    sync::{
12        Arc,
13        atomic::{
14            AtomicBool,
15            Ordering,
16        },
17    },
18    time::Duration,
19};
20
21use arc_swap::ArcSwap;
22use async_trait::async_trait;
23use bytes::Bytes;
24use futures::{
25    FutureExt,
26    prelude::*,
27};
28use futures_rustls::rustls::{
29    self,
30    RootCertStore,
31    pki_types,
32};
33use hyper_http_proxy::{
34    Intercept,
35    Proxy,
36    ProxyConnector,
37};
38use hyper_util::client::legacy::connect::HttpConnector;
39use muxado::heartbeat::HeartbeatConfig;
40pub use muxado::heartbeat::HeartbeatHandler;
41use once_cell::sync::{
42    Lazy,
43    OnceCell,
44};
45use regex::Regex;
46use rustls_pemfile::Item;
47use thiserror::Error;
48use tokio::{
49    io::{
50        AsyncRead,
51        AsyncWrite,
52    },
53    runtime::Handle,
54    sync::{
55        Mutex,
56        Notify,
57        RwLock,
58        mpsc::{
59            Sender,
60            channel,
61        },
62    },
63};
64use tokio_retry::strategy::jitter;
65use tokio_util::compat::{
66    FuturesAsyncReadCompatExt,
67    TokioAsyncReadCompatExt,
68};
69use tower_service::Service;
70use tracing::{
71    debug,
72    warn,
73};
74use url::Url;
75
76pub use crate::internals::{
77    proto::{
78        CommandResp,
79        Restart,
80        Stop,
81        StopTunnel,
82        Update,
83    },
84    raw_session::{
85        CommandHandler,
86        RpcError,
87    },
88};
89use crate::{
90    config::{
91        HttpTunnelBuilder,
92        LabeledTunnelBuilder,
93        ProxyProto,
94        TcpTunnelBuilder,
95        TlsTunnelBuilder,
96        TunnelConfig,
97    },
98    conn::ConnInner,
99    internals::{
100        proto::{
101            AuthExtra,
102            BindExtra,
103            BindOpts,
104            Error,
105            HttpEndpoint,
106            SecretString,
107            TcpEndpoint,
108            TlsEndpoint,
109        },
110        raw_session::{
111            AcceptError as RawAcceptError,
112            CommandHandlers,
113            IncomingStreams,
114            NOT_IMPLEMENTED,
115            RawSession,
116            RpcClient,
117            StartSessionError,
118        },
119    },
120    tunnel::{
121        AcceptError,
122        TunnelInner,
123        TunnelInnerInfo,
124    },
125};
126
127pub(crate) const CERT_BYTES: &[u8] = include_bytes!("../assets/ngrok.ca.crt");
128const CLIENT_TYPE: &str = "ngrok-rust";
129const VERSION: &str = env!("CARGO_PKG_VERSION");
130
131#[derive(Clone)]
132struct BoundTunnel {
133    proto: String,
134    opts: Option<BindOpts>,
135    extra: BindExtra,
136    labels: HashMap<String, String>,
137    forwards_to: String,
138    forwards_proto: String,
139    verify_upstream_tls: bool,
140    tx: Sender<Result<ConnInner, AcceptError>>,
141}
142
143type TunnelConns = HashMap<String, BoundTunnel>;
144
145/// An ngrok session.
146///
147/// Encapsulates an established session with the ngrok service. Sessions recover
148/// from network failures by automatically reconnecting.
149#[derive(Clone)]
150pub struct Session {
151    // Note: this is implicitly used to detect when the session (and its
152    // tunnels) have been dropped in order to shut down the accept loop.
153    _dropref: awaitdrop::Ref,
154    inner: Arc<ArcSwap<SessionInner>>,
155}
156
157struct SessionInner {
158    runtime: Handle,
159    client: Mutex<RpcClient>,
160    closed: AtomicBool,
161    // Notified when `closed` is set, to end a wait between reconnect attempts.
162    closing: Notify,
163    tunnels: RwLock<TunnelConns>,
164    builder: SessionBuilder,
165}
166
167/// A trait alias for types that can provide the base ngrok transport, i.e.
168/// bidirectional byte streams.
169///
170/// It is blanket-implemented for all types that satisfy its bounds. Most
171/// commonly, it will be a tls-wrapped tcp stream.
172pub trait IoStream: AsyncRead + AsyncWrite + Unpin + Send + 'static {}
173impl<T> IoStream for T where T: AsyncRead + AsyncWrite + Unpin + Send + 'static {}
174
175/// Trait for establishing the connection to the ngrok server.
176#[async_trait]
177pub trait Connector: Sync + Send + 'static {
178    /// The function used to establish the connection to the ngrok server.
179    ///
180    /// This is effectively `async |addr, tls_config, err| -> Result<IoStream>`.
181    ///
182    /// If it is being called due to a disconnect, the [AcceptError] argument will
183    /// be populated.
184    ///
185    /// If it returns `Err(ConnectError::Canceled)`, reconnecting will be canceled
186    /// and the session will be terminated, without asking the session's
187    /// [ReconnectPolicy]. Note that this error will never be returned from the
188    /// [default_connect] function.
189    async fn connect(
190        &self,
191        host: String,
192        port: u16,
193        tls_config: Arc<rustls::ClientConfig>,
194        err: Option<AcceptError>,
195    ) -> Result<Box<dyn IoStream>, ConnectError>;
196}
197
198#[async_trait]
199impl<F, U> Connector for F
200where
201    F: Fn(String, u16, Arc<rustls::ClientConfig>, Option<AcceptError>) -> U + Send + Sync + 'static,
202    U: Future<Output = Result<Box<dyn IoStream>, ConnectError>> + Send,
203{
204    async fn connect(
205        &self,
206        host: String,
207        port: u16,
208        tls_config: Arc<rustls::ClientConfig>,
209        err: Option<AcceptError>,
210    ) -> Result<Box<dyn IoStream>, ConnectError> {
211        self(host, port, tls_config, err).await
212    }
213}
214
215/// The shortest wait between reconnect attempts. A shorter wait from a
216/// [ReconnectPolicy] is raised to this, and [SessionBuilder::reconnect_backoff]
217/// rejects one: tokio's timers fire on millisecond ticks, so a shorter wait
218/// retries about every millisecond.
219const MIN_RECONNECT_WAIT: Duration = Duration::from_millis(1);
220
221/// The longest wait between reconnect attempts. A longer wait from a
222/// [ReconnectPolicy] is reduced to this, and
223/// [SessionBuilder::reconnect_backoff] rejects one. It also keeps the doubling
224/// in [ReconnectBackoff] from overflowing.
225const MAX_RECONNECT_WAIT: Duration = Duration::from_secs(24 * 60 * 60);
226
227/// Decides how long a session waits between attempts to reconnect after it
228/// loses its connection to the ngrok service, and when it stops trying. Set
229/// it with [SessionBuilder::reconnect_policy].
230///
231/// It is implemented for closures returning a [ReconnectSchedule]. For
232/// example, to give up after five failed attempts, waiting a second longer
233/// after each:
234///
235/// ```
236/// # use std::time::Duration;
237/// # use ngrok::session::ConnectError;
238/// # let mut builder = ngrok::Session::builder();
239/// builder.reconnect_policy(|| {
240///     let mut failures = 0;
241///     move |_err: &ConnectError| {
242///         failures += 1;
243///         (failures < 5).then(|| Duration::from_secs(failures))
244///     }
245/// });
246/// ```
247///
248/// The inner closure needs its parameter's type written out, `&ConnectError`:
249/// without it, Rust infers a closure for one particular lifetime, which is not
250/// a [ReconnectSchedule].
251pub trait ReconnectPolicy: Send + Sync + 'static {
252    /// Called each time the session loses its connection, before its first
253    /// reconnect attempt, which is immediate. The schedule it returns decides
254    /// the waits of that outage only.
255    fn start(&self) -> Box<dyn ReconnectSchedule>;
256}
257
258impl<F, S> ReconnectPolicy for F
259where
260    F: Fn() -> S + Send + Sync + 'static,
261    S: ReconnectSchedule + 'static,
262{
263    fn start(&self) -> Box<dyn ReconnectSchedule> {
264        Box::new(self())
265    }
266}
267
268/// The waits of one outage, from a [ReconnectPolicy].
269///
270/// It is implemented for closures taking the `&ConnectError` and returning an
271/// `Option<Duration>`.
272pub trait ReconnectSchedule: Send {
273    /// Called after each failed reconnect attempt with its error: how long to
274    /// wait before the next attempt, or `None` to stop reconnecting, after
275    /// which every tunnel receives that error.
276    ///
277    /// A wait under 1 ms is raised to 1 ms, and one over a day is reduced to
278    /// a day. A [Connector] returning [ConnectError::Canceled] stops
279    /// reconnecting without calling this. Closing the session stops
280    /// reconnecting and cuts short a wait already started, but an attempt
281    /// already under way when the session closes can still fail and call
282    /// this.
283    fn next_wait(&mut self, err: &ConnectError) -> Option<Duration>;
284}
285
286impl<F> ReconnectSchedule for F
287where
288    F: FnMut(&ConnectError) -> Option<Duration> + Send,
289{
290    fn next_wait(&mut self, err: &ConnectError) -> Option<Duration> {
291        self(err)
292    }
293}
294
295/// The default ngrok connector.
296///
297/// Establishes a TCP connection to `addr`, and then performs a TLS handshake
298/// using the `tls_config`.
299///
300/// Never returns [ConnectError::Canceled], so it leaves when to stop
301/// reconnecting to the session's [ReconnectPolicy].
302pub async fn default_connect(
303    host: String,
304    port: u16,
305    tls_config: Arc<rustls::ClientConfig>,
306    _: Option<AcceptError>,
307) -> Result<Box<dyn IoStream>, ConnectError> {
308    let stream = tokio::net::TcpStream::connect(&(host.as_str(), port))
309        .await
310        .map_err(ConnectError::Tcp)?
311        .compat();
312
313    let domain = pki_types::ServerName::try_from(host)
314        .expect("host should have been validated by SessionBuilder::server_addr");
315
316    let tls_conn = futures_rustls::TlsConnector::from(tls_config)
317        .connect(domain, stream)
318        .await
319        .map_err(ConnectError::Tls)?;
320    Ok(Box::new(tls_conn.compat()) as Box<dyn IoStream>)
321}
322
323#[derive(Debug, Clone, Error)]
324#[error("unsupported proxy address: {0}")]
325/// An unsupported proxy address was provided.
326pub struct ProxyUnsupportedError(Url);
327
328fn connect_proxy(url: Url) -> Result<Arc<dyn Connector>, ProxyUnsupportedError> {
329    Ok(match url.scheme() {
330        "http" | "https" => Arc::new(connect_http_proxy(url)),
331        "socks5" => {
332            let host = url.host_str().unwrap_or_default();
333            let port = url.port().unwrap_or(1080);
334            Arc::new(connect_socks_proxy(format!("{host}:{port}")))
335        }
336        _ => return Err(ProxyUnsupportedError(url)),
337    })
338}
339
340fn connect_http_proxy(url: Url) -> impl Connector {
341    move |host: String, port, tls_config, _| {
342        let mut proxy = Proxy::new(
343            Intercept::All,
344            url.as_str().try_into().expect("urls should be valid uris"),
345        );
346        proxy.force_connect();
347        let mut connector = HttpConnector::new();
348        connector.enforce_http(false);
349        async move {
350            let mut connector = ProxyConnector::from_proxy(connector, proxy)
351                .map_err(|e| ConnectError::ProxyConnect(Box::new(e)))?;
352
353            let server_uri = format!("http://{host}:{port}")
354                .parse()
355                .expect("host should have been validated by SessionBuilder::server_addr");
356
357            let conn = connector
358                .call(server_uri)
359                .await
360                .map_err(|e| ConnectError::ProxyConnect(Box::new(e)))?;
361
362            let tls_conn = futures_rustls::TlsConnector::from(tls_config)
363                .connect(
364                    pki_types::ServerName::try_from(host)
365                        .expect("host should have been validated by SessionBuilder::server_addr"),
366                    hyper_util::rt::TokioIo::new(conn).compat(),
367                )
368                .await
369                .map_err(ConnectError::Tls)?;
370
371            Ok(Box::new(tls_conn.compat()) as Box<dyn IoStream>)
372        }
373    }
374}
375
376fn connect_socks_proxy(proxy_addr: String) -> impl Connector {
377    move |server_host: String, server_port, tls_config, _| {
378        let proxy_addr = proxy_addr.clone();
379        async move {
380            let conn = tokio_socks::tcp::Socks5Stream::connect(
381                proxy_addr.as_str(),
382                format!("{server_host}:{server_port}"),
383            )
384            .await
385            .map_err(|e| ConnectError::ProxyConnect(Box::new(e)))?
386            .compat();
387
388            let tls_conn = futures_rustls::TlsConnector::from(tls_config)
389                .connect(
390                    pki_types::ServerName::try_from(server_host)
391                        .expect("host should have been validated by SessionBuilder::server_addr"),
392                    conn,
393                )
394                .await
395                .map_err(ConnectError::Tls)?;
396
397            Ok(Box::new(tls_conn.compat()) as Box<dyn IoStream>)
398        }
399    }
400}
401
402/// The builder for an ngrok [Session].
403#[derive(Clone)]
404pub struct SessionBuilder {
405    // Consuming libraries and applications can add a client type and version on
406    // top of the "base" type and version declared by this library.
407    versions: VecDeque<(String, String, Option<String>)>,
408    authtoken: Option<SecretString>,
409    metadata: Option<String>,
410    heartbeat_interval: Option<i64>,
411    heartbeat_tolerance: Option<i64>,
412    heartbeat_handler: Option<Arc<dyn HeartbeatHandler>>,
413    server_host: String,
414    server_port: u16,
415    ca_cert: Option<bytes::Bytes>,
416    tls_config: Option<rustls::ClientConfig>,
417    connector: Arc<dyn Connector>,
418    reconnect: ReconnectBackoff,
419    // Takes precedence over `reconnect` when set.
420    reconnect_policy: Option<Arc<dyn ReconnectPolicy>>,
421    handlers: CommandHandlers,
422    cookie: Option<SecretString>,
423    id: Option<String>,
424}
425
426/// The built-in [ReconnectPolicy], which [SessionBuilder::reconnect_backoff],
427/// [SessionBuilder::reconnect_jitter] and
428/// [SessionBuilder::reconnect_max_attempts] configure: `initial` before the
429/// second attempt (the first is immediate), doubling each time up to `max`,
430/// each wait scaled by a random factor in [0, 1) when `jitter` is on. It stops
431/// reconnecting only once `max_attempts` attempts of one outage have failed.
432#[derive(Copy, Clone, Debug)]
433struct ReconnectBackoff {
434    initial: Duration,
435    max: Duration,
436    jitter: bool,
437    max_attempts: Option<NonZeroU32>,
438}
439
440impl Default for ReconnectBackoff {
441    fn default() -> Self {
442        ReconnectBackoff {
443            initial: Duration::from_millis(50),
444            max: Duration::from_secs(30),
445            jitter: true,
446            max_attempts: None,
447        }
448    }
449}
450
451impl ReconnectBackoff {
452    /// This backoff with its first wait and cap replaced. Rejects an
453    /// `initial` below [MIN_RECONNECT_WAIT] or above `max`, and a `max` above
454    /// [MAX_RECONNECT_WAIT].
455    fn with_waits(self, initial: Duration, max: Duration) -> Result<Self, InvalidReconnectBackoff> {
456        let rule = if initial < MIN_RECONNECT_WAIT {
457            Some("the start must be at least 1 ms")
458        } else if initial > max {
459            Some("the start must not be above the cap")
460        } else if max > MAX_RECONNECT_WAIT {
461            Some("the cap must be at most one day")
462        } else {
463            None
464        };
465        match rule {
466            Some(rule) => Err(InvalidReconnectBackoff { initial, max, rule }),
467            None => Ok(ReconnectBackoff {
468                initial,
469                max,
470                ..self
471            }),
472        }
473    }
474}
475
476impl ReconnectPolicy for ReconnectBackoff {
477    /// `with_waits` keeps `max` at most [MAX_RECONNECT_WAIT], which keeps the
478    /// doubling from overflowing.
479    fn start(&self) -> Box<dyn ReconnectSchedule> {
480        let ReconnectBackoff {
481            initial,
482            max,
483            jitter: jittered,
484            max_attempts,
485        } = *self;
486        let waits = iter::successors(Some(initial.min(max)), move |wait| {
487            Some((*wait * 2).min(max))
488        })
489        .map(move |wait| if jittered { jitter(wait) } else { wait });
490        // One wait between each two attempts, so a limit of n attempts allows
491        // n - 1 waits. Without a limit the waits never run out.
492        let mut waits: Box<dyn Iterator<Item = Duration> + Send> = match max_attempts {
493            Some(n) => Box::new(waits.take(n.get() as usize - 1)),
494            None => Box::new(waits),
495        };
496        Box::new(move |_: &ConnectError| waits.next())
497    }
498}
499
500/// Errors arising at [SessionBuilder::connect] time.
501#[derive(Error, Debug)]
502#[non_exhaustive]
503pub enum ConnectError {
504    /// An error occurred when establishing a TCP connection to the ngrok
505    /// server.
506    #[error("failed to establish tcp connection")]
507    Tcp(#[source] io::Error),
508    /// A TLS handshake error occurred.
509    ///
510    /// This is usually a certificate validation issue, or an attempt to connect
511    /// to something that doesn't actually speak TLS.
512    #[error("tls handshake error")]
513    Tls(#[source] io::Error),
514    /// An error occurred when starting the ngrok session.
515    ///
516    /// This might occur when there's a protocol mismatch interfering with the
517    /// heartbeat routine.
518    #[error("failed to start ngrok session")]
519    Start(#[source] StartSessionError),
520    /// An error occurred when attempting to authenticate.
521    #[error("authentication failure")]
522    Auth(#[source] RpcError),
523    /// An error occurred when rebinding tunnels during a reconnect
524    #[error("error rebinding tunnel after reconnect")]
525    Rebind(#[source] RpcError),
526    /// An error arising from a failure to connect through a proxy.
527    #[error("failed to connect through proxy")]
528    ProxyConnect(#[source] Box<dyn std::error::Error + Send + Sync + 'static>),
529    /// The (re)connect function gave up.
530    ///
531    /// This will never be returned by the default connect function, and is
532    /// instead used by a [Connector] to cancel the reconnect loop. A
533    /// [ReconnectPolicy] can also stop it, by answering `None`.
534    #[error("the connect function gave up")]
535    Canceled,
536}
537
538impl Error for ConnectError {
539    fn error_code(&self) -> Option<&str> {
540        match self {
541            ConnectError::Auth(resp) | ConnectError::Rebind(resp) => resp.error_code(),
542            _ => None,
543        }
544    }
545    fn msg(&self) -> String {
546        match self {
547            ConnectError::Auth(resp) | ConnectError::Rebind(resp) => resp.msg(),
548            _ => format!("{self}"),
549        }
550    }
551}
552
553/// The builder specified an invalid heartbeat interval.
554///
555/// This is most likely caused a [Duration] that's outside of the [i64::MAX]
556/// nanosecond range.
557#[derive(Copy, Clone, Debug, Error)]
558#[error("invalid heartbeat interval: {0}")]
559pub struct InvalidHeartbeatInterval(u128);
560/// The builder specified an invalid heartbeat tolerance.
561///
562/// This is most likely caused a [Duration] that's outside of the [i64::MAX]
563/// nanosecond range.
564#[derive(Copy, Clone, Debug, Error)]
565#[error("invalid heartbeat tolerance: {0}")]
566pub struct InvalidHeartbeatTolerance(u128);
567
568/// The builder specified an invalid reconnect backoff: see
569/// [SessionBuilder::reconnect_backoff] for the accepted range.
570#[derive(Copy, Clone, Debug, Error)]
571#[error("invalid reconnect backoff (start {initial:?}, cap {max:?}): {rule}")]
572pub struct InvalidReconnectBackoff {
573    initial: Duration,
574    max: Duration,
575    rule: &'static str,
576}
577
578/// The builder provided an invalid server address
579#[derive(Error, Debug, Clone)]
580#[error("invalid server address: {0}")]
581pub struct InvalidServerAddr(String);
582
583impl Default for SessionBuilder {
584    fn default() -> Self {
585        SessionBuilder {
586            versions: [(CLIENT_TYPE.to_string(), VERSION.to_string(), None)]
587                .into_iter()
588                .collect(),
589            authtoken: None,
590            metadata: None,
591            heartbeat_interval: None,
592            heartbeat_tolerance: None,
593            heartbeat_handler: None,
594            server_host: "connect.ngrok-agent.com".into(),
595            server_port: 443,
596            ca_cert: None,
597            tls_config: None,
598            connector: Arc::new(default_connect),
599            reconnect: Default::default(),
600            reconnect_policy: None,
601            handlers: Default::default(),
602            cookie: None,
603            id: None,
604        }
605    }
606}
607
608fn sanitize_ua_string(s: impl AsRef<str>) -> String {
609    static UA_BANNED: OnceCell<Regex> = OnceCell::new();
610    UA_BANNED
611        .get_or_init(|| Regex::new("[^/!#$%&'*+-.^_`|~0-9a-zA-Z]").unwrap())
612        .replace_all(s.as_ref(), "#")
613        .replace('/', "-")
614}
615
616impl SessionBuilder {
617    /// Configures the session to authenticate with the provided authtoken. You
618    /// can [find your existing authtoken] or [create a new one] in the ngrok
619    /// dashboard.
620    ///
621    /// See the [authtoken parameter in the ngrok docs] for additional details.
622    ///
623    /// [find your existing authtoken]: https://dashboard.ngrok.com/get-started/your-authtoken
624    /// [create a new one]: https://dashboard.ngrok.com/tunnels/authtokens
625    /// [authtoken parameter in the ngrok docs]: https://ngrok.com/docs/ngrok-agent/config#authtoken
626    pub fn authtoken(&mut self, authtoken: impl Into<String>) -> &mut Self {
627        self.authtoken = Some(authtoken.into().into());
628        self
629    }
630    /// Shortcut for calling [SessionBuilder::authtoken] with the value of the
631    /// NGROK_AUTHTOKEN environment variable.
632    pub fn authtoken_from_env(&mut self) -> &mut Self {
633        self.authtoken = env::var("NGROK_AUTHTOKEN").ok().map(From::from);
634        self
635    }
636
637    /// Configures how often the session will send heartbeat messages to the ngrok
638    /// service to check session liveness.
639    ///
640    /// See the [heartbeat_interval parameter in the ngrok docs] for additional
641    /// details.
642    ///
643    /// [heartbeat_interval parameter in the ngrok docs]: https://ngrok.com/docs/ngrok-agent/config#heartbeat_interval
644    pub fn heartbeat_interval(
645        &mut self,
646        heartbeat_interval: Duration,
647    ) -> Result<&mut Self, InvalidHeartbeatInterval> {
648        let nanos = heartbeat_interval.as_nanos();
649        let nanos = i64::try_from(nanos).map_err(|_| InvalidHeartbeatInterval(nanos))?;
650        self.heartbeat_interval = Some(nanos);
651        Ok(self)
652    }
653
654    /// Configures the duration to wait for a response to a heartbeat before
655    /// assuming the session connection is dead and attempting to reconnect.
656    ///
657    /// See the [heartbeat_tolerance parameter in the ngrok docs] for additional
658    /// details.
659    ///
660    /// [heartbeat_tolerance parameter in the ngrok docs]: https://ngrok.com/docs/ngrok-agent/config#heartbeat_tolerance
661    pub fn heartbeat_tolerance(
662        &mut self,
663        heartbeat_tolerance: Duration,
664    ) -> Result<&mut Self, InvalidHeartbeatTolerance> {
665        let nanos = heartbeat_tolerance.as_nanos();
666        let nanos = i64::try_from(nanos).map_err(|_| InvalidHeartbeatTolerance(nanos))?;
667        self.heartbeat_tolerance = Some(nanos);
668        Ok(self)
669    }
670
671    /// Configures how long the session waits between attempts to reconnect
672    /// after it loses its connection to the ngrok service.
673    ///
674    /// The first attempt is immediate. After it, the session waits `initial`,
675    /// then twice as long before each attempt, up to `max`: the wait after
676    /// failed attempt k (from 0) is `min(initial * 2^k, max)`. Each wait is
677    /// scaled by a random factor in [0, 1) unless
678    /// [SessionBuilder::reconnect_jitter] turns that off. The defaults are
679    /// 50 ms and 30 s. For a fixed wait between every attempt, pass the same
680    /// value for both and turn jitter off.
681    ///
682    /// These waits never stop the session from reconnecting on their own:
683    /// [SessionBuilder::reconnect_max_attempts], a [Connector] that returns
684    /// [ConnectError::Canceled], or closing the session does. A
685    /// [ReconnectPolicy] set with [SessionBuilder::reconnect_policy] takes
686    /// precedence over this.
687    ///
688    /// Rejects an `initial` below 1 ms or above `max`, and a `max` above one
689    /// day, and leaves the builder unchanged. A binding for another language
690    /// should take whole milliseconds as an unsigned integer, which always
691    /// converts to a [Duration], and pass this function's error through.
692    pub fn reconnect_backoff(
693        &mut self,
694        initial: Duration,
695        max: Duration,
696    ) -> Result<&mut Self, InvalidReconnectBackoff> {
697        self.reconnect = self.reconnect.with_waits(initial, max)?;
698        Ok(self)
699    }
700
701    /// Configures a custom [ReconnectPolicy]: how long the session waits
702    /// between attempts to reconnect after it loses its connection, given
703    /// each attempt's error, and when it stops trying.
704    ///
705    /// It takes precedence over [SessionBuilder::reconnect_backoff],
706    /// [SessionBuilder::reconnect_jitter] and
707    /// [SessionBuilder::reconnect_max_attempts], whichever order they are
708    /// called in: those still check their arguments, but no longer change the
709    /// waits or when reconnecting stops.
710    pub fn reconnect_policy(&mut self, policy: impl ReconnectPolicy) -> &mut Self {
711        self.reconnect_policy = Some(Arc::new(policy));
712        self
713    }
714
715    /// Configures whether each wait between reconnect attempts is scaled by a
716    /// random factor in [0, 1). On by default, so that sessions that lose
717    /// their connections together don't all reconnect at the same moment. A
718    /// [ReconnectPolicy] set with [SessionBuilder::reconnect_policy] takes
719    /// precedence over this.
720    pub fn reconnect_jitter(&mut self, enabled: bool) -> &mut Self {
721        self.reconnect.jitter = enabled;
722        self
723    }
724
725    /// Configures the session to stop reconnecting after `attempts` failed
726    /// attempts in one outage, counting the immediate first attempt. Every
727    /// tunnel then receives the last attempt's error. Each new outage starts
728    /// the count again. Without this, the session never stops on its own.
729    ///
730    /// A [ReconnectPolicy] set with [SessionBuilder::reconnect_policy] takes
731    /// precedence over this, and decides for itself when to stop.
732    ///
733    /// A binding for another language that takes the count as a number reports
734    /// zero itself, since [NonZeroU32] cannot hold it.
735    pub fn reconnect_max_attempts(&mut self, attempts: NonZeroU32) -> &mut Self {
736        self.reconnect.max_attempts = Some(attempts);
737        self
738    }
739
740    /// Configures the opaque, machine-readable metadata string for this session.
741    /// Metadata is made available to you in the ngrok dashboard and the Agents API
742    /// resource. It is a useful way to allow you to uniquely identify sessions. We
743    /// suggest encoding the value in a structured format like JSON.
744    ///
745    /// See the [metdata parameter in the ngrok docs] for additional details.
746    ///
747    /// [metdata parameter in the ngrok docs]: https://ngrok.com/docs/ngrok-agent/config#metadata
748    pub fn metadata(&mut self, metadata: impl Into<String>) -> &mut Self {
749        self.metadata = Some(metadata.into());
750        self
751    }
752
753    /// Configures the network address to dial to connect to the ngrok service.
754    /// Use this option only if you are connecting to a custom agent ingress.
755    ///
756    /// See the [server_addr parameter in the ngrok docs] for additional details.
757    ///
758    /// [server_addr parameter in the ngrok docs]: https://ngrok.com/docs/ngrok-agent/config#server_addr
759    pub fn server_addr(&mut self, addr: impl Into<String>) -> Result<&mut Self, InvalidServerAddr> {
760        let addr = addr.into();
761        let server_uri: Url = format!("http://{addr}")
762            .parse()
763            .map_err(|_| InvalidServerAddr(addr.clone()))?;
764
765        self.server_host = server_uri
766            .host_str()
767            .map(String::from)
768            .ok_or_else(|| InvalidServerAddr(addr.clone()))?;
769
770        pki_types::ServerName::try_from(self.server_host.as_str())
771            .map_err(|_| InvalidServerAddr(addr.clone()))?;
772
773        self.server_port = server_uri.port().unwrap_or(443);
774
775        Ok(self)
776    }
777
778    /// Sets the file path to a default certificate in PEM format to validate ngrok Session TLS connections.
779    /// Setting to "trusted" is the default, using the ngrok CA certificate.
780    /// Setting to "host" will verify using the certificates on the host operating system.
781    /// A client config set via tls_config after calling root_cas will override this value.
782    ///
783    /// Corresponds to the [root_cas parameter in the ngrok docs]
784    ///
785    /// [root_cas parameter in the ngrok docs]: https://ngrok.com/docs/ngrok-agent/config#root_cas
786    pub fn root_cas(&mut self, root_cas: impl Into<String>) -> Result<&mut Self, io::Error> {
787        match root_cas.into().clone().as_str() {
788            "trusted" => self.ca_cert = None,
789            "host" => self.tls_config = Some(host_certs_tls_config().map_err(|e| e.kind())?),
790            v => {
791                std::fs::read(v).map(|root_cas| self.ca_cert = Some(Bytes::from(root_cas)))?;
792            }
793        }
794        Ok(self)
795    }
796
797    /// Sets the default certificate in PEM format to validate ngrok Session TLS connections.
798    /// A client config set via tls_config will override this value.
799    ///
800    /// Roughly corresponds to the "path to a certificate PEM file" option in the
801    /// [root_cas parameter in the ngrok docs]
802    ///
803    /// [root_cas parameter in the ngrok docs]: https://ngrok.com/docs/ngrok-agent/config#root_cas
804    pub fn ca_cert(&mut self, ca_cert: Bytes) -> &mut Self {
805        self.ca_cert = Some(ca_cert);
806        self
807    }
808
809    /// Configures the TLS client used to connect to the ngrok service while
810    /// establishing the session. Use this option only if you are connecting through
811    /// a man-in-the-middle or deep packet inspection proxy. Passed to the
812    /// connect callback set with `SessionBuilder::connect`.
813    ///
814    /// Roughly corresponds to the [root_cas parameter in the ngrok docs], but allows
815    /// for deeper TLS configuration.
816    ///
817    /// [root_cas parameter in the ngrok docs]: https://ngrok.com/docs/ngrok-agent/config#root_cas
818    pub fn tls_config(&mut self, config: rustls::ClientConfig) -> &mut Self {
819        self.tls_config = Some(config);
820        self
821    }
822
823    /// Configures a function which is called to establish the connection to the
824    /// ngrok service. Use this option if you need to connect through an outbound
825    /// proxy. In the event of network disruptions, it will be called each time
826    /// the session reconnects.
827    pub fn connector(&mut self, connect: impl Connector) -> &mut Self {
828        self.connector = Arc::new(connect);
829        self
830    }
831
832    /// Configures the session to connect to ngrok through an outbound
833    /// HTTP or SOCKS5 proxy. This parameter is ignored if you override the connector
834    /// with [SessionBuilder::connector].
835    ///
836    /// See the [proxy url parameter in the ngrok docs] for additional details.
837    ///
838    /// [proxy url parameter in the ngrok docs]: https://ngrok.com/docs/ngrok-agent/config#proxy_url
839    pub fn proxy_url(&mut self, url: Url) -> Result<&mut Self, ProxyUnsupportedError> {
840        self.connector = connect_proxy(url)?;
841        Ok(self)
842    }
843
844    /// Configures a function which is called when the ngrok service requests that
845    /// this [Session] stops. Your application may choose to interpret this callback
846    /// as a request to terminate the [Session] or the entire process.
847    ///
848    /// Errors returned by this function will be visible to the ngrok dashboard or
849    /// API as the response to the Stop operation.
850    ///
851    /// Do not block inside this callback. It will cause the Dashboard or API
852    /// stop operation to time out. Do not call [std::process::exit] inside this
853    /// callback, it will also cause the operation to time out.
854    pub fn handle_stop_command(&mut self, handler: impl CommandHandler<Stop>) -> &mut Self {
855        self.handlers.on_stop = Some(Arc::new(handler));
856        self
857    }
858
859    /// Configures a function which is called when the ngrok service requests
860    /// that this [Session] updates. Your application may choose to interpret
861    /// this callback as a request to restart the [Session] or the entire
862    /// process.
863    ///
864    /// Errors returned by this function will be visible to the ngrok dashboard or
865    /// API as the response to the Restart operation.
866    ///
867    /// Do not block inside this callback. It will cause the Dashboard or API
868    /// stop operation to time out. Do not call [std::process::exit] inside this
869    /// callback, it will also cause the operation to time out.
870    pub fn handle_restart_command(&mut self, handler: impl CommandHandler<Restart>) -> &mut Self {
871        self.handlers.on_restart = Some(Arc::new(handler));
872        self
873    }
874
875    /// Configures a function which is called when the ngrok service requests
876    /// that this [Session] updates. Your application may choose to interpret
877    /// this callback as a request to update its configuration, itself, or to
878    /// invoke some other application-specific behavior.
879    ///
880    /// Errors returned by this function will be visible to the ngrok dashboard or
881    /// API as the response to the Restart operation.
882    ///
883    /// Do not block inside this callback. It will cause the Dashboard or API
884    /// stop operation to time out. Do not call [std::process::exit] inside this
885    /// callback, it will also cause the operation to time out.
886    pub fn handle_update_command(&mut self, handler: impl CommandHandler<Update>) -> &mut Self {
887        self.handlers.on_update = Some(Arc::new(handler));
888        self
889    }
890
891    /// Call the provided handler whenever a heartbeat response is received.
892    ///
893    /// If the handler returns an error, the heartbeat task will exit, resulting
894    /// in the session eventually dying as well.
895    pub fn handle_heartbeat(&mut self, callback: impl HeartbeatHandler) -> &mut Self {
896        self.heartbeat_handler = Some(Arc::new(callback));
897        self
898    }
899
900    /// Add client type and version information for a client application.
901    ///
902    /// This is a way for applications and library consumers of this crate
903    /// identify themselves.
904    ///
905    /// This will add a new entry to the `User-Agent` field in the "most significant"
906    /// (first) position. Comments must follow [RFC 7230] or a connection error may occur.
907    ///
908    /// [RFC 7230]: https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6
909    pub fn client_info(
910        &mut self,
911        client_type: impl Into<String>,
912        version: impl Into<String>,
913        comments: Option<impl Into<String>>,
914    ) -> &mut Self {
915        self.versions.push_front((
916            client_type.into(),
917            version.into(),
918            comments.map(|c| c.into()),
919        ));
920        self
921    }
922
923    /// Begins a new ngrok [Session] by connecting to the ngrok service.
924    /// `connect` blocks until the session is successfully established or fails with
925    /// an error.
926    pub async fn connect(&self) -> Result<Session, ConnectError> {
927        let (dropref, dropped) = awaitdrop::awaitdrop();
928        let (inner, mut incoming) = self.connect_inner(None).await?;
929
930        let rt = inner.runtime.clone();
931
932        let inner = Arc::new(ArcSwap::new(inner.into()));
933
934        let session = Session {
935            _dropref: dropref,
936            inner: inner.clone(),
937        };
938
939        // store the session for use with StopTunnel
940        incoming.session = Some(session.clone());
941
942        rt.spawn(future::select(
943            accept_incoming(incoming, inner).boxed(),
944            dropped.wait(),
945        ));
946
947        Ok(session)
948    }
949
950    pub(crate) fn get_or_create_tls_config(&self) -> rustls::ClientConfig {
951        // if the user has provided a custom TLS config, use that
952        if let Some(tls_config) = &self.tls_config {
953            return tls_config.clone();
954        }
955        // generate a default TLS config
956        let mut root_store = rustls::RootCertStore::empty();
957        let cert_pem = self.ca_cert.as_ref().map_or(CERT_BYTES, |it| it.as_ref());
958        let certs = rustls_pemfile::read_all(&mut io::Cursor::new(cert_pem))
959            .filter_map(|it| match it {
960                Ok(Item::X509Certificate(bs)) => Some(bs),
961                Err(e) => {
962                    warn!(error = ?e, "skipping certificate which failed to parse");
963                    None
964                }
965                Ok(_) => {
966                    warn!("skipping non-x509 certificate");
967                    None
968                }
969            })
970            .collect::<Vec<_>>();
971        root_store.add_parsable_certificates(certs);
972
973        rustls::ClientConfig::builder()
974            .with_root_certificates(root_store)
975            .with_no_client_auth()
976    }
977
978    async fn connect_inner(
979        &self,
980        err: impl Into<Option<AcceptError>>,
981    ) -> Result<(SessionInner, IncomingStreams), ConnectError> {
982        let conn = self
983            .connector
984            .connect(
985                self.server_host.clone(),
986                self.server_port,
987                Arc::new(self.get_or_create_tls_config()),
988                err.into(),
989            )
990            .await?;
991
992        let mut heartbeat_config = HeartbeatConfig::default();
993        if let Some(interval) = self.heartbeat_interval {
994            heartbeat_config.interval = Duration::from_nanos(interval as u64);
995        }
996        if let Some(tolerance) = self.heartbeat_tolerance {
997            heartbeat_config.tolerance = Duration::from_nanos(tolerance as u64);
998        }
999        heartbeat_config.handler = self.heartbeat_handler.clone();
1000
1001        // convert these while we have ownership
1002        let heartbeat_interval = heartbeat_config.interval.as_nanos() as i64;
1003        let heartbeat_tolerance = heartbeat_config.tolerance.as_nanos() as i64;
1004
1005        let mut raw = RawSession::start(conn, heartbeat_config, self.handlers.clone())
1006            .await
1007            .map_err(ConnectError::Start)?;
1008
1009        // list of possibilities: https://doc.rust-lang.org/std/env/consts/constant.OS.html
1010        let os = match env::consts::OS {
1011            "macos" => "darwin",
1012            _ => env::consts::OS,
1013        };
1014
1015        let user_agent = self
1016            .versions
1017            .iter()
1018            .map(|(name, version, comments)| {
1019                format!(
1020                    "{}/{}{}",
1021                    sanitize_ua_string(name),
1022                    sanitize_ua_string(version),
1023                    comments
1024                        .as_ref()
1025                        .map_or(String::new(), |f| format!(" ({f})"))
1026                )
1027            })
1028            .collect::<Vec<_>>()
1029            .join(" ");
1030
1031        let client_type = self.versions[0].0.clone();
1032        let version = self.versions[0].1.clone();
1033
1034        let resp = raw
1035            .auth(
1036                self.id.as_deref().unwrap_or_default(),
1037                AuthExtra {
1038                    version,
1039                    client_type,
1040                    user_agent,
1041                    auth_token: self.authtoken.clone().unwrap_or_default(),
1042                    metadata: self.metadata.clone().unwrap_or_default(),
1043                    os: os.into(),
1044                    arch: std::env::consts::ARCH.into(),
1045                    heartbeat_interval,
1046                    heartbeat_tolerance,
1047                    restart_unsupported_error: self
1048                        .handlers
1049                        .on_restart
1050                        .is_none()
1051                        .then_some(NOT_IMPLEMENTED.into())
1052                        .or(Some("".into())),
1053                    stop_unsupported_error: self
1054                        .handlers
1055                        .on_stop
1056                        .is_none()
1057                        .then_some(NOT_IMPLEMENTED.into())
1058                        .or(Some("".into())),
1059                    update_unsupported_error: self
1060                        .handlers
1061                        .on_update
1062                        .is_none()
1063                        .then_some(NOT_IMPLEMENTED.into())
1064                        .or(Some("".into())),
1065                    cookie: self.cookie.clone().unwrap_or_default(),
1066                    ..Default::default()
1067                },
1068            )
1069            .await
1070            .map_err(ConnectError::Auth)?;
1071
1072        let (client, incoming) = raw.split();
1073
1074        let builder = SessionBuilder {
1075            cookie: resp.extra.cookie,
1076            id: resp.client_id.into(),
1077            ..self.clone()
1078        };
1079
1080        Ok((
1081            SessionInner {
1082                runtime: Handle::current(),
1083                client: client.into(),
1084                tunnels: Default::default(),
1085                closed: Default::default(),
1086                closing: Default::default(),
1087                builder,
1088            },
1089            incoming,
1090        ))
1091    }
1092}
1093
1094impl Session {
1095    /// Create a new [SessionBuilder] to configure a new ngrok session.
1096    pub fn builder() -> SessionBuilder {
1097        SessionBuilder::default()
1098    }
1099
1100    /// Start building a tunnel for an HTTP endpoint.
1101    ///
1102    /// https://ngrok.com/docs/http/
1103    pub fn http_endpoint(&self) -> HttpTunnelBuilder {
1104        self.clone().into()
1105    }
1106
1107    /// Start building a tunnel for a TCP endpoint.
1108    ///
1109    /// https://ngrok.com/docs/tcp/
1110    pub fn tcp_endpoint(&self) -> TcpTunnelBuilder {
1111        self.clone().into()
1112    }
1113
1114    /// Start building a tunnel for a TLS endpoint.
1115    ///
1116    /// https://ngrok.com/docs/tls/
1117    pub fn tls_endpoint(&self) -> TlsTunnelBuilder {
1118        self.clone().into()
1119    }
1120
1121    /// Start building a labeled tunnel.
1122    ///
1123    /// https://ngrok.com/docs/network-edge/edges/#tunnel-group
1124    pub fn labeled_tunnel(&self) -> LabeledTunnelBuilder {
1125        self.clone().into()
1126    }
1127
1128    /// Get the unique ID of this session.
1129    pub fn id(&self) -> String {
1130        self.inner
1131            .load()
1132            .builder
1133            .id
1134            .as_ref()
1135            .expect("Session ID not set")
1136            .clone()
1137    }
1138
1139    /// Start a new tunnel in this session.
1140    pub(crate) async fn start_tunnel<C>(&self, tunnel_cfg: C) -> Result<TunnelInner, RpcError>
1141    where
1142        C: TunnelConfig,
1143    {
1144        let inner = self.inner.load();
1145        let mut client = inner.client.lock().await;
1146
1147        // let tunnelCfg: dyn TunnelConfig = TunnelConfig(opts);
1148        let (tx, rx) = channel(64);
1149
1150        let proto = tunnel_cfg.proto();
1151        let opts = tunnel_cfg.opts();
1152        let mut extra = tunnel_cfg.extra();
1153        let labels = tunnel_cfg.labels();
1154        let forwards_to = tunnel_cfg.forwards_to();
1155        let forwards_proto = tunnel_cfg.forwards_proto();
1156        let verify_upstream_tls = tunnel_cfg.verify_upstream_tls();
1157
1158        // non-labeled tunnel
1159        let (tunnel, bound) = if tunnel_cfg.proto() != "" {
1160            let resp = client
1161                .listen(
1162                    &proto,
1163                    opts.clone().unwrap(), // this is crate-defined, and must exist if proto is non-empty
1164                    extra.clone(),
1165                    "",
1166                    &forwards_to,
1167                    &forwards_proto,
1168                )
1169                .await?;
1170
1171            extra.token = resp.extra.token;
1172            let info = TunnelInnerInfo {
1173                id: resp.client_id,
1174                proto: resp.proto.clone(),
1175                url: resp.url,
1176                labels: HashMap::new(),
1177                forwards_to: tunnel_cfg.forwards_to(),
1178                metadata: extra.metadata.clone(),
1179            };
1180
1181            (
1182                TunnelInner {
1183                    info,
1184                    session: self.clone(),
1185                    incoming: rx.into(),
1186                },
1187                BoundTunnel {
1188                    proto: resp.proto,
1189                    opts: resp.bind_opts.into(),
1190                    extra,
1191                    labels,
1192                    forwards_to,
1193                    forwards_proto,
1194                    verify_upstream_tls,
1195                    tx,
1196                },
1197            )
1198        } else {
1199            // labeled tunnel
1200            let resp = client
1201                .listen_label(
1202                    labels.clone(),
1203                    &extra.metadata,
1204                    &forwards_to,
1205                    &forwards_proto,
1206                )
1207                .await?;
1208
1209            let info = TunnelInnerInfo {
1210                id: resp.id,
1211                proto: Default::default(),
1212                url: Default::default(),
1213                labels: tunnel_cfg.labels(),
1214                forwards_to: tunnel_cfg.forwards_to(),
1215                metadata: extra.metadata.clone(),
1216            };
1217
1218            (
1219                TunnelInner {
1220                    info,
1221                    session: self.clone(),
1222                    incoming: rx.into(),
1223                },
1224                BoundTunnel {
1225                    extra,
1226                    proto: Default::default(),
1227                    opts: Default::default(),
1228                    forwards_to,
1229                    forwards_proto,
1230                    verify_upstream_tls,
1231                    labels,
1232                    tx,
1233                },
1234            )
1235        };
1236
1237        let mut tunnels = inner.tunnels.write().await;
1238        tunnels.insert(tunnel.info.id.clone(), bound);
1239
1240        Ok(tunnel)
1241    }
1242
1243    /// Close a tunnel with an error from the remote.
1244    /// Skips the call to unlisten, since the remote has already rejected it.
1245    pub(crate) async fn close_tunnel_with_error(&self, id: impl AsRef<str>, err: AcceptError) {
1246        let id = id.as_ref();
1247        let inner = self.inner.load();
1248        if let Some(tun) = inner.tunnels.write().await.remove(id) {
1249            let _ = tun.tx.send(Err(err)).await;
1250        };
1251    }
1252
1253    /// Close a tunnel with the given ID.
1254    pub async fn close_tunnel(&self, id: impl AsRef<str>) -> Result<(), RpcError> {
1255        let id = id.as_ref();
1256        let inner = self.inner.load();
1257        inner.client.lock().await.unlisten(id).await?;
1258        inner.tunnels.write().await.remove(id);
1259        Ok(())
1260    }
1261
1262    pub(crate) fn runtime(&self) -> Handle {
1263        self.inner.load().runtime.clone()
1264    }
1265
1266    /// Close the ngrok session.
1267    pub async fn close(&mut self) -> Result<(), RpcError> {
1268        let inner = self.inner.load();
1269        let res = inner.client.lock().await.close().await;
1270        inner.closed.store(true, Ordering::SeqCst);
1271        inner.closing.notify_waiters();
1272        res
1273    }
1274}
1275
1276pub(crate) fn host_certs_tls_config() -> Result<rustls::ClientConfig, &'static io::Error> {
1277    // The root certificate store, lazily loaded once.
1278    static ROOT_STORE: Lazy<Result<RootCertStore, io::Error>> = Lazy::new(|| {
1279        let der_certs = rustls_native_certs::load_native_certs()?
1280            .into_iter()
1281            .collect::<Vec<_>>();
1282        let mut root_store = RootCertStore::empty();
1283        root_store.add_parsable_certificates(der_certs);
1284        Ok(root_store)
1285    });
1286
1287    let root_store = ROOT_STORE.as_ref()?;
1288    Ok(rustls::ClientConfig::builder()
1289        .with_root_certificates(root_store.clone())
1290        .with_no_client_auth())
1291}
1292
1293async fn accept_one(
1294    incoming: &mut IncomingStreams,
1295    inner: &ArcSwap<SessionInner>,
1296) -> Result<(), AcceptError> {
1297    let conn = match incoming.accept().await {
1298        Ok(conn) => conn,
1299        // Assume if we got a muxado error, the session is borked. Break and
1300        // propagate the error to all of the tunnels out in the wild.
1301        Err(RawAcceptError::Transport(error)) => return Err(error.into()),
1302        // The other errors are either a bad header or an unrecognized
1303        // stream type. They're non-fatal, but could signal a protocol
1304        // mismatch.
1305        Err(error) => {
1306            warn!(?error, "protocol error when accepting tunnel connection");
1307            return Ok(());
1308        }
1309    };
1310    let id = conn.header.id.clone();
1311    let remote_addr = conn.header.client_addr.parse().unwrap_or_else(|error| {
1312        warn!(
1313            client_addr = conn.header.client_addr,
1314            %error,
1315            "invalid remote addr for tunnel connection",
1316        );
1317        "0.0.0.0:0".parse().unwrap()
1318    });
1319    let inner = inner.load();
1320    let guard = inner.tunnels.read().await;
1321    let res = if let Some(tun) = guard.get(&id) {
1322        let mut header = conn.header;
1323        let app_protocol = Some(tun.forwards_proto.to_string()).filter(|s| !s.is_empty());
1324        let verify_upstream_tls = tun.verify_upstream_tls;
1325        // Note: this is a bit of a hack. Normally, passthrough_tls is only
1326        // a thing on edge connections, but we're making sure it's set for
1327        // endpoint connections as well. In their case, we have to look at the
1328        // options used to bind the endpoint.
1329        if let Some(BindOpts::Tls(opts)) = &tun.opts {
1330            header.passthrough_tls = opts.tls_termination.is_none();
1331        }
1332        let proxy_proto = if let Some(
1333            BindOpts::Tls(TlsEndpoint { proxy_proto, .. })
1334            | BindOpts::Http(HttpEndpoint { proxy_proto, .. })
1335            | BindOpts::Tcp(TcpEndpoint { proxy_proto, .. }),
1336        ) = tun.opts
1337        {
1338            proxy_proto
1339        } else {
1340            ProxyProto::None
1341        };
1342        tun.tx
1343            .send(Ok(ConnInner {
1344                info: crate::conn::Info {
1345                    app_protocol,
1346                    verify_upstream_tls,
1347                    remote_addr,
1348                    header,
1349                    proxy_proto,
1350                },
1351                stream: conn.stream,
1352            }))
1353            .await
1354    } else {
1355        Ok(())
1356    };
1357    drop(guard);
1358    if res.is_err() {
1359        RwLock::write(&inner.tunnels).await.remove(&id);
1360    }
1361    Ok(())
1362}
1363
1364async fn try_reconnect(
1365    inner: Arc<ArcSwap<SessionInner>>,
1366    err: impl Into<Option<AcceptError>>,
1367) -> Result<IncomingStreams, ConnectError> {
1368    let old_inner = inner.load();
1369    if old_inner.closed.load(Ordering::SeqCst) {
1370        return Err(ConnectError::Canceled);
1371    }
1372    let (new_inner, new_incoming) = old_inner.builder.connect_inner(err).await?;
1373    let mut client = new_inner.client.lock().await;
1374    let mut new_tunnels = new_inner.tunnels.write().await;
1375    let old_tunnels = old_inner.tunnels.read().await;
1376
1377    for (id, tun) in old_tunnels.iter() {
1378        if !tun.proto.is_empty() {
1379            let resp = client
1380                .listen(
1381                    &tun.proto,
1382                    tun.opts.clone().unwrap(),
1383                    tun.extra.clone(),
1384                    id,
1385                    &tun.forwards_to,
1386                    &tun.forwards_proto,
1387                )
1388                .await
1389                .map_err(ConnectError::Rebind)?;
1390            debug!(?resp, %id, %tun.proto, ?tun.opts, ?tun.extra, %tun.forwards_to, "rebound tunnel");
1391            new_tunnels.insert(id.clone(), tun.clone());
1392        } else {
1393            let resp = client
1394                .listen_label(
1395                    tun.labels.clone(),
1396                    &tun.extra.metadata,
1397                    &tun.forwards_to,
1398                    &tun.forwards_proto,
1399                )
1400                .await
1401                .map_err(ConnectError::Rebind)?;
1402
1403            if !resp.id.is_empty() {
1404                new_tunnels.insert(resp.id, tun.clone());
1405            } else {
1406                new_tunnels.insert(id.clone(), tun.clone());
1407            }
1408        }
1409    }
1410
1411    drop(old_tunnels);
1412    drop(client);
1413    drop(new_tunnels);
1414    inner.store(new_inner.into());
1415
1416    Ok(new_incoming)
1417}
1418
1419async fn accept_incoming(mut incoming: IncomingStreams, inner: Arc<ArcSwap<SessionInner>>) {
1420    let error: AcceptError = loop {
1421        if let Err(error) = accept_one(&mut incoming, &inner).await {
1422            debug!(%error, "failed to accept stream, attempting reconnect");
1423            incoming = match reconnect(&inner, error).await {
1424                Ok(incoming) => incoming,
1425                Err(error) => {
1426                    debug!(%error, "reconnect failed, giving up");
1427                    break AcceptError::Reconnect(error);
1428                }
1429            };
1430        }
1431    };
1432    for (_id, tun) in inner.load().tunnels.write().await.drain() {
1433        let _ = tun.tx.send(Err(error.clone())).await;
1434    }
1435}
1436
1437/// Reconnects a session that lost its connection with `cause`: tries at
1438/// once, then again after each wait the session's [ReconnectPolicy] gives,
1439/// until an attempt succeeds, the policy answers `None`, or an attempt fails
1440/// with [ConnectError::Canceled]. Each attempt passes the previous one's error
1441/// to the connector as its cause.
1442async fn reconnect(
1443    inner: &Arc<ArcSwap<SessionInner>>,
1444    mut cause: AcceptError,
1445) -> Result<IncomingStreams, Arc<ConnectError>> {
1446    // Each successful reconnect stores a clone of the builder, so this reads
1447    // what the caller configured.
1448    let mut schedule = {
1449        let session = inner.load();
1450        match &session.builder.reconnect_policy {
1451            Some(policy) => policy.start(),
1452            None => session.builder.reconnect.start(),
1453        }
1454    };
1455    loop {
1456        let error = match try_reconnect(inner.clone(), cause).await {
1457            Ok(incoming) => return Ok(incoming),
1458            Err(error) => Arc::new(error),
1459        };
1460        if let ConnectError::Canceled = *error {
1461            return Err(error);
1462        }
1463        let Some(wait) = schedule.next_wait(&error) else {
1464            return Err(error);
1465        };
1466        let wait = wait.clamp(MIN_RECONNECT_WAIT, MAX_RECONNECT_WAIT);
1467        // Closing the session ends the wait early; the next attempt then sees
1468        // `closed` and stops. Registering for the notification before reading
1469        // `closed` means a close between the two is not missed.
1470        let session = inner.load_full();
1471        let mut closing = pin!(session.closing.notified());
1472        closing.as_mut().enable();
1473        if !session.closed.load(Ordering::SeqCst) {
1474            let _ = tokio::time::timeout(wait, closing).await;
1475        }
1476        cause = AcceptError::Reconnect(error);
1477    }
1478}
1479
1480#[cfg(test)]
1481mod test {
1482    use std::sync::atomic::AtomicUsize;
1483
1484    use muxado::typed::{
1485        TypedAccept,
1486        TypedOpenClose,
1487    };
1488    use tokio::{
1489        io::{
1490            AsyncReadExt,
1491            AsyncWriteExt,
1492            DuplexStream,
1493        },
1494        sync::mpsc,
1495        time::Instant,
1496    };
1497
1498    use super::*;
1499    use crate::internals::proto::{
1500        AUTH_REQ,
1501        AuthResp,
1502    };
1503
1504    /// Plays the ngrok service for one connection: accepts the session's
1505    /// authentication, then closes the session, which the client sees as a
1506    /// lost connection.
1507    async fn serve_auth_then_disconnect(io: DuplexStream) {
1508        let mut sess = muxado::typed::Typed::new(muxado::SessionBuilder::new(io).server().start());
1509        // Hold the other streams the client opens, such as its heartbeat,
1510        // so that nothing but the close below ends the session.
1511        let mut held = Vec::new();
1512        let mut auth = loop {
1513            let stream = sess.accept_typed().await.expect("client opens a stream");
1514            if stream.typ() == AUTH_REQ {
1515                break stream;
1516            }
1517            held.push(stream);
1518        };
1519        let mut req = Vec::new();
1520        while serde_json::from_slice::<serde_json::Value>(&req).is_err() {
1521            let mut buf = [0u8; 1024];
1522            let n = auth.read(&mut buf).await.expect("client sends auth");
1523            assert_ne!(n, 0, "client closed the auth stream before a request");
1524            req.extend_from_slice(&buf[..n]);
1525        }
1526        let resp = AuthResp {
1527            version: "2".into(),
1528            client_id: "fake-client-id".into(),
1529            extra: Default::default(),
1530        };
1531        auth.write_all(&serde_json::to_vec(&resp).unwrap())
1532            .await
1533            .expect("write auth response");
1534        auth.shutdown().await.expect("end auth response");
1535        // Closing the session drops data still in flight, so wait for the
1536        // client to read the response and let go of the stream.
1537        let _ = auth.read_to_end(&mut Vec::new()).await;
1538        sess.close(muxado::Error::None, "".into())
1539            .await
1540            .expect("close session");
1541    }
1542
1543    /// What the fake ngrok service does with one connect.
1544    #[derive(Clone, Copy)]
1545    enum Answer {
1546        /// Accept the session's authentication, then drop the connection.
1547        Serve,
1548        /// Fail the connect as a refused TCP connection.
1549        Refuse,
1550        /// Fail the connect with ConnectError::Canceled.
1551        Cancel,
1552    }
1553
1554    /// A reconnect attempt: when it started, and the cause the session
1555    /// passed to its connector.
1556    #[derive(Debug)]
1557    struct Attempt {
1558        at: Instant,
1559        cause: Option<AcceptError>,
1560    }
1561
1562    /// Connects `builder` to a fake ngrok service that answers connect k
1563    /// (from 0, the first connect) with `script(k)`.
1564    ///
1565    /// Returns the session, which must be kept alive for it to keep
1566    /// reconnecting, and a receiver of every reconnect attempt, that is
1567    /// every connect after the first.
1568    async fn connect_scripted(
1569        builder: &mut SessionBuilder,
1570        script: impl Fn(usize) -> Answer + Send + Sync + 'static,
1571    ) -> (Session, mpsc::UnboundedReceiver<Attempt>) {
1572        let connects = Arc::new(AtomicUsize::new(0));
1573        let (attempt_tx, attempt_rx) = mpsc::unbounded_channel();
1574        let connector =
1575            move |_: String, _: u16, _: Arc<rustls::ClientConfig>, cause: Option<AcceptError>| {
1576                let k = connects.fetch_add(1, Ordering::SeqCst);
1577                if k > 0 {
1578                    let _ = attempt_tx.send(Attempt {
1579                        at: Instant::now(),
1580                        cause,
1581                    });
1582                }
1583                let answer = script(k);
1584                async move {
1585                    match answer {
1586                        Answer::Serve => {
1587                            let (client, server) = tokio::io::duplex(64 * 1024);
1588                            tokio::spawn(serve_auth_then_disconnect(server));
1589                            Ok(Box::new(client) as Box<dyn IoStream>)
1590                        }
1591                        Answer::Refuse => {
1592                            Err(ConnectError::Tcp(io::ErrorKind::ConnectionRefused.into()))
1593                        }
1594                        Answer::Cancel => Err(ConnectError::Canceled),
1595                    }
1596                }
1597            };
1598        let session = builder
1599            .connector(connector)
1600            .connect()
1601            .await
1602            .expect("connects to the fake ngrok service");
1603        (session, attempt_rx)
1604    }
1605
1606    /// Connects `builder` to a fake ngrok service that drops the session
1607    /// after it starts, and fails every reconnect attempt after that.
1608    async fn connect_then_fail_reconnects(
1609        builder: &mut SessionBuilder,
1610    ) -> (Session, mpsc::UnboundedReceiver<Attempt>) {
1611        connect_scripted(builder, |k| {
1612            if k == 0 {
1613                Answer::Serve
1614            } else {
1615                Answer::Refuse
1616            }
1617        })
1618        .await
1619    }
1620
1621    /// The waits between the next `n + 1` reconnect attempts.
1622    ///
1623    /// On tokio's paused clock these are exact when every wait is a whole
1624    /// number of milliseconds, since the clock jumps straight to each
1625    /// timer's deadline and timers fire on millisecond ticks.
1626    async fn reconnect_gaps(
1627        attempts: &mut mpsc::UnboundedReceiver<Attempt>,
1628        n: usize,
1629    ) -> Vec<Duration> {
1630        let mut last = next_attempt(attempts).await.at;
1631        let mut gaps = Vec::new();
1632        for _ in 0..n {
1633            let attempt = next_attempt(attempts).await.at;
1634            gaps.push(attempt - last);
1635            last = attempt;
1636        }
1637        gaps
1638    }
1639
1640    async fn next_attempt(attempts: &mut mpsc::UnboundedReceiver<Attempt>) -> Attempt {
1641        attempts.recv().await.expect("session keeps reconnecting")
1642    }
1643
1644    /// Asserts that the session makes no reconnect attempt for a day, which
1645    /// on tokio's paused clock takes no real time.
1646    async fn assert_no_attempt_for_a_day(attempts: &mut mpsc::UnboundedReceiver<Attempt>) {
1647        let next = tokio::time::timeout(Duration::from_secs(24 * 60 * 60), attempts.recv()).await;
1648        assert!(next.is_err(), "the session reconnected again: {next:?}");
1649    }
1650
1651    /// Adds a tunnel to `session` by hand, as a bound listener would, and
1652    /// returns the receiver its listener reads connections and errors from.
1653    async fn add_tunnel(session: &Session) -> mpsc::Receiver<Result<ConnInner, AcceptError>> {
1654        let (tx, rx) = channel(1);
1655        let tunnel = BoundTunnel {
1656            proto: "tcp".into(),
1657            opts: None,
1658            extra: Default::default(),
1659            labels: Default::default(),
1660            forwards_to: String::new(),
1661            forwards_proto: String::new(),
1662            verify_upstream_tls: false,
1663            tx,
1664        };
1665        session
1666            .inner
1667            .load()
1668            .tunnels
1669            .write()
1670            .await
1671            .insert("fake-tunnel".into(), tunnel);
1672        rx
1673    }
1674
1675    /// The reconnect error a tunnel's listener receives within a day, on
1676    /// tokio's paused clock. Waiting no longer keeps a session that never
1677    /// stops reconnecting from hanging the test.
1678    async fn tunnel_error(
1679        tunnel: &mut mpsc::Receiver<Result<ConnInner, AcceptError>>,
1680    ) -> Arc<ConnectError> {
1681        let next = tokio::time::timeout(Duration::from_secs(24 * 60 * 60), tunnel.recv())
1682            .await
1683            .expect("the tunnel should receive an error within a day");
1684        match next {
1685            Some(Err(AcceptError::Reconnect(err))) => err,
1686            Some(Err(other)) => panic!("the tunnel should receive a reconnect error: {other:?}"),
1687            Some(Ok(_)) => panic!("the tunnel should receive an error, not a connection"),
1688            None => panic!("the tunnel closed without an error"),
1689        }
1690    }
1691
1692    /// The first reconnect attempt starts the moment the connection drops,
1693    /// with the disconnect as its cause; each later attempt's cause is the
1694    /// previous attempt's error.
1695    #[tokio::test(start_paused = true)]
1696    async fn reconnect_starts_at_once_and_passes_on_each_cause() {
1697        let (_session, mut attempts) = connect_then_fail_reconnects(&mut Session::builder()).await;
1698        let dropped = Instant::now();
1699
1700        let first = next_attempt(&mut attempts).await;
1701        let second = next_attempt(&mut attempts).await;
1702
1703        assert_eq!(first.at, dropped);
1704        assert!(
1705            matches!(first.cause, Some(AcceptError::Transport(_))),
1706            "the first attempt's cause should be the dropped connection: {:?}",
1707            first.cause,
1708        );
1709        match second.cause {
1710            Some(AcceptError::Reconnect(err)) => assert!(
1711                matches!(&*err, ConnectError::Tcp(e) if e.kind() == io::ErrorKind::ConnectionRefused),
1712                "the second attempt's cause should be the first attempt's error: {err:?}",
1713            ),
1714            other => panic!("the second attempt's cause should be a reconnect error: {other:?}"),
1715        }
1716    }
1717
1718    /// A connector returning Canceled stops reconnecting, and every tunnel
1719    /// receives that error.
1720    #[tokio::test(start_paused = true)]
1721    async fn canceled_connect_stops_reconnecting_and_tells_the_tunnels() {
1722        let (session, mut attempts) = connect_scripted(&mut Session::builder(), |k| match k {
1723            0 => Answer::Serve,
1724            3 => Answer::Cancel,
1725            _ => Answer::Refuse,
1726        })
1727        .await;
1728        let mut tunnel = add_tunnel(&session).await;
1729
1730        for _ in 0..3 {
1731            next_attempt(&mut attempts).await;
1732        }
1733        assert_no_attempt_for_a_day(&mut attempts).await;
1734
1735        let err = tunnel_error(&mut tunnel).await;
1736        assert!(
1737            matches!(*err, ConnectError::Canceled),
1738            "the tunnel should receive the cancel: {err:?}",
1739        );
1740    }
1741
1742    /// Closing the session while it waits to reconnect stops reconnecting
1743    /// without another connect, and every tunnel receives Canceled.
1744    #[tokio::test(start_paused = true)]
1745    async fn closing_during_a_wait_stops_reconnecting() {
1746        let (mut session, mut attempts) =
1747            connect_then_fail_reconnects(&mut Session::builder()).await;
1748        let mut tunnel = add_tunnel(&session).await;
1749        next_attempt(&mut attempts).await;
1750
1751        let _ = session.close().await;
1752
1753        assert_no_attempt_for_a_day(&mut attempts).await;
1754        let err = tunnel_error(&mut tunnel).await;
1755        assert!(
1756            matches!(*err, ConnectError::Canceled),
1757            "the tunnel should receive Canceled: {err:?}",
1758        );
1759    }
1760
1761    /// A policy that waits 1 s, then 2 s, then 3 s, and so on, recording the
1762    /// error it is given each time.
1763    fn counting_policy(errors: Arc<std::sync::Mutex<Vec<String>>>) -> impl ReconnectPolicy {
1764        move || {
1765            let errors = errors.clone();
1766            let mut failures = 0;
1767            move |err: &ConnectError| {
1768                errors.lock().unwrap().push(format!("{err:?}"));
1769                failures += 1;
1770                Some(Duration::from_secs(failures))
1771            }
1772        }
1773    }
1774
1775    /// A custom policy is asked once per failed attempt, with that attempt's
1776    /// error, and its answers are the waits between attempts.
1777    #[tokio::test(start_paused = true)]
1778    async fn reconnect_policy_sees_each_error_and_sets_the_waits() {
1779        let errors = Arc::new(std::sync::Mutex::new(Vec::new()));
1780        let (_session, mut attempts) = connect_then_fail_reconnects(
1781            Session::builder().reconnect_policy(counting_policy(errors.clone())),
1782        )
1783        .await;
1784
1785        let gaps = reconnect_gaps(&mut attempts, 3).await;
1786
1787        assert_eq!(gaps, [1, 2, 3].map(Duration::from_secs));
1788        // Four attempts have failed, and the policy has been asked after each.
1789        let errors = errors.lock().unwrap().clone();
1790        assert_eq!(
1791            errors.len(),
1792            4,
1793            "the policy should be asked once per failure: {errors:?}"
1794        );
1795        assert!(
1796            errors.iter().all(|e| e.contains("ConnectionRefused")),
1797            "the policy should see each attempt's error: {errors:?}",
1798        );
1799    }
1800
1801    /// When a policy answers None, the session stops reconnecting and every
1802    /// tunnel receives the error of the last attempt.
1803    #[tokio::test(start_paused = true)]
1804    async fn reconnect_policy_stops_reconnecting_with_none() {
1805        let mut builder = Session::builder();
1806        builder.reconnect_policy(|| {
1807            let mut failures = 0;
1808            move |_err: &ConnectError| {
1809                failures += 1;
1810                (failures < 3).then(|| Duration::from_secs(1))
1811            }
1812        });
1813        let (session, mut attempts) = connect_then_fail_reconnects(&mut builder).await;
1814        let mut tunnel = add_tunnel(&session).await;
1815
1816        for _ in 0..3 {
1817            next_attempt(&mut attempts).await;
1818        }
1819        assert_no_attempt_for_a_day(&mut attempts).await;
1820
1821        let err = tunnel_error(&mut tunnel).await;
1822        assert!(
1823            matches!(&*err, ConnectError::Tcp(e) if e.kind() == io::ErrorKind::ConnectionRefused),
1824            "the tunnel should receive the last attempt's error: {err:?}",
1825        );
1826    }
1827
1828    /// A wait under 1 ms is raised to 1 ms, and one over a day is reduced to
1829    /// a day.
1830    #[tokio::test(start_paused = true)]
1831    async fn reconnect_policy_waits_are_kept_between_1ms_and_1_day() {
1832        let mut builder = Session::builder();
1833        builder.reconnect_policy(|| {
1834            let mut answers = [Duration::ZERO, Duration::MAX].into_iter().cycle();
1835            move |_err: &ConnectError| answers.next()
1836        });
1837        let (_session, mut attempts) = connect_then_fail_reconnects(&mut builder).await;
1838
1839        let gaps = reconnect_gaps(&mut attempts, 2).await;
1840
1841        assert_eq!(
1842            gaps,
1843            [Duration::from_millis(1), Duration::from_secs(24 * 60 * 60)]
1844        );
1845    }
1846
1847    /// reconnect_backoff and reconnect_jitter, called after a custom policy,
1848    /// do not replace it.
1849    #[tokio::test(start_paused = true)]
1850    async fn reconnect_policy_takes_precedence_over_the_backoff_setters() {
1851        let errors = Arc::new(std::sync::Mutex::new(Vec::new()));
1852        let mut builder = Session::builder();
1853        builder
1854            .reconnect_policy(counting_policy(errors))
1855            .reconnect_jitter(false)
1856            .reconnect_backoff(Duration::from_millis(100), Duration::from_millis(100))
1857            .expect("100 ms to 100 ms is accepted");
1858        let (_session, mut attempts) = connect_then_fail_reconnects(&mut builder).await;
1859
1860        let gaps = reconnect_gaps(&mut attempts, 3).await;
1861
1862        assert_eq!(gaps, [1, 2, 3].map(Duration::from_secs));
1863    }
1864
1865    /// A custom policy starts a fresh schedule on each outage, and is kept
1866    /// across a successful reconnect.
1867    #[tokio::test(start_paused = true)]
1868    async fn reconnect_policy_starts_fresh_on_each_outage() {
1869        let errors = Arc::new(std::sync::Mutex::new(Vec::new()));
1870        let (_session, mut attempts) = connect_scripted(
1871            Session::builder().reconnect_policy(counting_policy(errors)),
1872            |k| match k {
1873                0 | 4 => Answer::Serve,
1874                _ => Answer::Refuse,
1875            },
1876        )
1877        .await;
1878
1879        // Attempts 1 to 3 fail, attempt 4 reconnects and is dropped at once,
1880        // so attempt 5 follows it immediately, and 6 and 7 wait as 2 and 3
1881        // did.
1882        let gaps = reconnect_gaps(&mut attempts, 6).await;
1883
1884        assert_eq!(gaps, [1, 2, 3, 0, 1, 2].map(Duration::from_secs));
1885    }
1886
1887    /// After a reconnect succeeds, the next lost connection starts its waits
1888    /// from the first again.
1889    #[tokio::test(start_paused = true)]
1890    async fn each_outage_starts_its_waits_from_the_first() {
1891        let (_session, mut attempts) =
1892            connect_scripted(Session::builder().reconnect_jitter(false), |k| match k {
1893                0 | 4 => Answer::Serve,
1894                _ => Answer::Refuse,
1895            })
1896            .await;
1897
1898        // Attempts 1 to 3 fail, attempt 4 reconnects and is dropped at once,
1899        // so attempt 5 follows it immediately, and 6 and 7 wait as 2 and 3
1900        // did.
1901        let gaps = reconnect_gaps(&mut attempts, 6).await;
1902
1903        assert_eq!(gaps, [50, 100, 200, 0, 50, 100].map(Duration::from_millis));
1904    }
1905
1906    fn attempts(n: u32) -> NonZeroU32 {
1907        NonZeroU32::new(n).unwrap()
1908    }
1909
1910    /// With reconnect_max_attempts(3), the session makes three attempts, the
1911    /// immediate first included, then stops and tells the tunnels.
1912    #[tokio::test(start_paused = true)]
1913    async fn reconnect_max_attempts_stops_after_that_many_attempts() {
1914        let (session, mut attempt_rx) =
1915            connect_then_fail_reconnects(Session::builder().reconnect_max_attempts(attempts(3)))
1916                .await;
1917        let mut tunnel = add_tunnel(&session).await;
1918
1919        for _ in 0..3 {
1920            next_attempt(&mut attempt_rx).await;
1921        }
1922        assert_no_attempt_for_a_day(&mut attempt_rx).await;
1923
1924        let err = tunnel_error(&mut tunnel).await;
1925        assert!(
1926            matches!(&*err, ConnectError::Tcp(e) if e.kind() == io::ErrorKind::ConnectionRefused),
1927            "the tunnel should receive the last attempt's error: {err:?}",
1928        );
1929    }
1930
1931    /// The limit counts the attempts of one outage: after a reconnect
1932    /// succeeds, the next outage gets the full count again.
1933    #[tokio::test(start_paused = true)]
1934    async fn reconnect_max_attempts_counts_each_outage_on_its_own() {
1935        let (_session, mut attempt_rx) = connect_scripted(
1936            Session::builder().reconnect_max_attempts(attempts(2)),
1937            |k| match k {
1938                0 | 2 => Answer::Serve,
1939                _ => Answer::Refuse,
1940            },
1941        )
1942        .await;
1943
1944        // Attempt 1 fails and attempt 2 reconnects; the new connection drops
1945        // at once, and attempts 3 and 4 both fail before the session stops.
1946        for _ in 0..4 {
1947            next_attempt(&mut attempt_rx).await;
1948        }
1949        assert_no_attempt_for_a_day(&mut attempt_rx).await;
1950    }
1951
1952    /// A custom policy decides for itself: reconnect_max_attempts does not
1953    /// stop it.
1954    #[tokio::test(start_paused = true)]
1955    async fn reconnect_max_attempts_does_not_limit_a_custom_policy() {
1956        let errors = Arc::new(std::sync::Mutex::new(Vec::new()));
1957        let mut builder = Session::builder();
1958        builder
1959            .reconnect_policy(counting_policy(errors))
1960            .reconnect_max_attempts(attempts(1));
1961        let (_session, mut attempt_rx) = connect_then_fail_reconnects(&mut builder).await;
1962
1963        for _ in 0..3 {
1964            next_attempt(&mut attempt_rx).await;
1965        }
1966    }
1967
1968    /// reconnect_backoff, called after reconnect_max_attempts, keeps the
1969    /// limit.
1970    #[tokio::test(start_paused = true)]
1971    async fn reconnect_backoff_keeps_the_attempt_limit() {
1972        let mut builder = Session::builder();
1973        builder
1974            .reconnect_max_attempts(attempts(2))
1975            .reconnect_backoff(Duration::from_secs(1), Duration::from_secs(4))
1976            .expect("1 s to 4 s is accepted");
1977        let (_session, mut attempt_rx) = connect_then_fail_reconnects(&mut builder).await;
1978
1979        for _ in 0..2 {
1980            next_attempt(&mut attempt_rx).await;
1981        }
1982        assert_no_attempt_for_a_day(&mut attempt_rx).await;
1983    }
1984
1985    /// With jitter off, the default waits are exactly 50 ms before the
1986    /// second attempt, doubling each time up to 30 s.
1987    #[tokio::test(start_paused = true)]
1988    async fn reconnect_waits_without_jitter_double_from_50ms_to_30s() {
1989        let mut builder = Session::builder();
1990        builder.reconnect.jitter = false;
1991        let (_session, mut attempts) = connect_then_fail_reconnects(&mut builder).await;
1992
1993        let gaps = reconnect_gaps(&mut attempts, 12).await;
1994
1995        let expected = [
1996            50, 100, 200, 400, 800, 1_600, 3_200, 6_400, 12_800, 25_600, 30_000, 30_000,
1997        ]
1998        .map(Duration::from_millis);
1999        assert_eq!(gaps, expected);
2000    }
2001
2002    /// With reconnect_backoff(1 s, 4 s) and jitter off, the waits are exactly
2003    /// 1 s, then doubling to 4 s; a rejected setting afterwards changes
2004    /// nothing.
2005    #[tokio::test(start_paused = true)]
2006    async fn reconnect_backoff_sets_the_start_and_cap_of_the_waits() {
2007        let mut builder = Session::builder();
2008        builder
2009            .reconnect_jitter(false)
2010            .reconnect_backoff(Duration::from_secs(1), Duration::from_secs(4))
2011            .expect("1 s to 4 s is accepted");
2012        builder
2013            .reconnect_backoff(Duration::from_secs(2), Duration::from_secs(1))
2014            .map(|_| ())
2015            .expect_err("a start above the cap is rejected");
2016        let (_session, mut attempts) = connect_then_fail_reconnects(&mut builder).await;
2017
2018        let gaps = reconnect_gaps(&mut attempts, 5).await;
2019
2020        assert_eq!(gaps, [1, 2, 4, 4, 4].map(Duration::from_secs));
2021    }
2022
2023    #[test]
2024    fn reconnect_backoff_accepts_1ms_to_1_day_with_start_at_most_cap() {
2025        let ms = Duration::from_millis;
2026        let day = Duration::from_secs(24 * 60 * 60);
2027        for (initial, max) in [(ms(1), ms(1)), (day, day), (ms(1), day), (ms(500), ms(500))] {
2028            assert!(
2029                Session::builder().reconnect_backoff(initial, max).is_ok(),
2030                "({initial:?}, {max:?}) should be accepted",
2031            );
2032        }
2033        for (initial, max) in [
2034            (Duration::from_micros(999), ms(1)),
2035            (Duration::ZERO, ms(1)),
2036            (ms(2), ms(1)),
2037            (ms(1), day + ms(1)),
2038        ] {
2039            let err = Session::builder()
2040                .reconnect_backoff(initial, max)
2041                .map(|_| ())
2042                .expect_err(&format!("({initial:?}, {max:?}) should be rejected"));
2043            assert!(
2044                err.to_string().contains("reconnect backoff"),
2045                "error should say what it rejects: {err}",
2046            );
2047        }
2048    }
2049
2050    /// Closing the session during a long wait between reconnect attempts
2051    /// stops reconnecting at once, rather than when the wait ends: the tunnels
2052    /// receive Canceled without the clock moving.
2053    #[tokio::test(start_paused = true)]
2054    async fn closing_ends_a_long_reconnect_wait_at_once() {
2055        let day = Duration::from_secs(24 * 60 * 60);
2056        let mut builder = Session::builder();
2057        builder
2058            .reconnect_jitter(false)
2059            .reconnect_backoff(day, day)
2060            .expect("a day is accepted");
2061        let (mut session, mut attempts) = connect_then_fail_reconnects(&mut builder).await;
2062        let mut tunnel = add_tunnel(&session).await;
2063        next_attempt(&mut attempts).await;
2064        let closed_at = Instant::now();
2065
2066        let _ = session.close().await;
2067        let err = tunnel_error(&mut tunnel).await;
2068
2069        assert!(
2070            matches!(*err, ConnectError::Canceled),
2071            "the tunnel should receive Canceled: {err:?}",
2072        );
2073        assert_eq!(
2074            Instant::now() - closed_at,
2075            Duration::ZERO,
2076            "the tunnel should hear of the close without waiting out the reconnect wait",
2077        );
2078    }
2079
2080    /// A session whose connection drops after it starts, and whose every
2081    /// reconnect attempt then fails, waits at most 50 ms before its second
2082    /// attempt, at most twice as long before each one after that, and never
2083    /// more than 30 s, at jittered intervals.
2084    ///
2085    /// The clock is tokio's paused clock, which jumps to each timer, so an
2086    /// uncapped backoff's hours-long waits take no real time.
2087    #[tokio::test(start_paused = true)]
2088    async fn reconnect_attempts_double_up_to_30s_and_are_jittered() {
2089        let (_session, mut attempt_rx) =
2090            connect_then_fail_reconnects(&mut Session::builder()).await;
2091
2092        // Sixteen attempts, so fifteen gaps: ten while the delay doubles from
2093        // 50 ms to 25.6 s, then five at the cap. Each gap is checked as it
2094        // arrives, so an uncapped backoff fails before its waits grow large
2095        // enough to overflow the clock.
2096        let mut last = next_attempt(&mut attempt_rx).await.at;
2097        let mut gaps = Vec::new();
2098        for k in 0..15 {
2099            let attempt = next_attempt(&mut attempt_rx).await.at;
2100            let gap = attempt - last;
2101            last = attempt;
2102            gaps.push(gap);
2103            let bound = Duration::from_millis(50 << k).min(Duration::from_secs(30));
2104            assert!(
2105                gap <= bound,
2106                "reconnect wait {k} is longer than {bound:?}; gaps: {gaps:?}",
2107            );
2108        }
2109        let capped = &gaps[10..];
2110        assert!(
2111            capped.windows(2).any(|w| w[0] != w[1]),
2112            "reconnect delays at the cap are all equal, so they are not jittered; gaps: {gaps:?}",
2113        );
2114    }
2115
2116    #[test]
2117    fn test_sanitize_ua() {
2118        assert_eq!(
2119            sanitize_ua_string("library/official/rust"),
2120            "library-official-rust"
2121        );
2122        assert_eq!(
2123            sanitize_ua_string("something@really☺weird"),
2124            "something#really#weird"
2125        );
2126    }
2127}