eventsource_client/
config.rs

Help
1use std::time::Duration;
2
3/// Configuration for a [`Client`]'s reconnect behaviour.
4///
5/// ```
6/// # use std::time::Duration;
7/// # use eventsource_client::ReconnectOptions;
8/// #
9/// let reconnect_options = ReconnectOptions::reconnect(true)
10///                             .retry_initial(false)
11///                             .delay(Duration::from_secs(1))
12///                             .backoff_factor(2)
13///                             .delay_max(Duration::from_secs(60))
14///                             .build();
15/// ```
16///
17/// See [`default()`] for a description of the default behaviour. See
18/// [`ReconnectOptionsBuilder`] for descriptions of each configurable parameter.
19///
20/// [`Client`]: struct.Client.html
21/// [`default()`]: #method.default
22/// [`ReconnectOptionsBuilder`]: struct.ReconnectOptionsBuilder.html
23#[derive(Clone, Debug)]
24pub struct ReconnectOptions {
25    pub(crate) retry_initial: bool,
26    pub(crate) reconnect: bool,
27    pub(crate) delay: Duration,
28    pub(crate) backoff_factor: u32,
29    pub(crate) delay_max: Duration,
30}
31
32impl ReconnectOptions {
33    /// Start building a `ReconnectOptions`, by enabling or disabling
34    /// reconnection on stream error.
35    ///
36    /// If `reconnect` is `true` (the [default]), the client will automatically
37    /// try to reconnect if the stream ends due to an error. If it is `false`,
38    /// the client will stop receiving events after an error.
39    ///
40    /// [default]: #method.default
41    pub fn reconnect(reconnect: bool) -> ReconnectOptionsBuilder {
42        ReconnectOptionsBuilder::new(reconnect)
43    }
44}
45
46impl Default for ReconnectOptions {
47    /// The default reconnect behaviour is to automatically try to reconnect if
48    /// the stream ends due to an error, but not to retry if the initial
49    /// connection fails.
50    ///
51    /// The client will wait before each reconnect attempt, to allow time for
52    /// the error condition to be resolved (e.g. for the SSE server to restart
53    /// if it went down). It will wait 1 second before the first attempt, and
54    /// then back off exponentially, up to a maximum wait of 1 minute.
55    fn default() -> ReconnectOptions {
56        ReconnectOptions {
57            retry_initial: false,
58            reconnect: true,
59            delay: Duration::from_secs(1),
60            backoff_factor: 2,
61            delay_max: Duration::from_secs(60),
62        }
63    }
64}
65
66/// Builder for [`ReconnectOptions`].
67///
68/// [`ReconnectOptions`]: struct.ReconnectOptions.html
69pub struct ReconnectOptionsBuilder {
70    opts: ReconnectOptions,
71}
72
73impl ReconnectOptionsBuilder {
74    pub fn new(reconnect: bool) -> Self {
75        let opts = ReconnectOptions {
76            reconnect,
77            ..Default::default()
78        };
79        Self { opts }
80    }
81
82    /// Configure whether to retry if the initial connection to the server
83    /// fails.
84    ///
85    /// If `true`, the client will automatically retry the connection, with the
86    /// same delay and backoff behaviour as for reconnects due to stream error.
87    /// If `false` (the [default]), the client will not retry the initial
88    /// connection.
89    ///
90    /// [default]: struct.ReconnectOptions.html#method.default
91    pub fn retry_initial(mut self, retry: bool) -> Self {
92        self.opts.retry_initial = retry;
93        self
94    }
95
96    /// Configure the initial delay before trying to reconnect (the [default] is
97    /// 1 second).
98    ///
99    /// After an error, the client will wait this long before the first attempt
100    /// to reconnect.  Subsequent reconnect attempts may wait longer, depending
101    /// on the [`backoff_factor`].
102    ///
103    /// [default]: struct.ReconnectOptions.html#method.default
104    /// [`backoff_factor`]: #method.backoff_factor
105    pub fn delay(mut self, delay: Duration) -> Self {
106        self.opts.delay = delay;
107        self
108    }
109
110    /// Configure the factor by which delays between reconnect attempts will
111    /// exponentially increase, up to [`delay_max`]. The [default] factor is 2,
112    /// so each reconnect attempt will wait twice as long as the previous one.
113    ///
114    /// Set this to 1 to disable exponential backoff (i.e. to make reconnect
115    /// attempts at regular intervals equal to the configured [`delay`]).
116    ///
117    /// [`delay_max`]: #method.delay_max
118    /// [default]: struct.ReconnectOptions.html#method.default
119    /// [`delay`]: #method.delay
120    pub fn backoff_factor(mut self, factor: u32) -> Self {
121        self.opts.backoff_factor = factor;
122        self
123    }
124
125    /// Configure the maximum delay between reconnects (the [default] is 1
126    /// minute). The exponential backoff configured by [`backoff_factor`] will
127    /// not cause a delay greater than this value.
128    ///
129    /// [default]: struct.ReconnectOptions.html#method.default
130    /// [`backoff_factor`]: #method.backoff_factor
131    pub fn delay_max(mut self, max: Duration) -> Self {
132        self.opts.delay_max = max;
133        self
134    }
135
136    /// Finish building the `ReconnectOptions`.
137    pub fn build(self) -> ReconnectOptions {
138        self.opts
139    }
140}
eventsource_client/config.rs

eventsource_client/
config.rs
