tuwunel_core/config/sending.rs
1//! Configures outbound delivery workers and retries.
2//!
3//! The queue serves federation, appservice, and push destinations.
4//! Timeouts, retry pacing, and startup bursting control delivery work.
5
6use serde::Deserialize;
7use tuwunel_macros::config_example_generator;
8
9use super::true_fn;
10
11/// Outbound delivery queue
12///
13/// Timeouts, retry pacing, worker count and startup behavior for the
14/// outbound queue that delivers federation transactions, appservice
15/// transactions and push notifications.
16///
17/// Tips:
18/// - Every startup trims each destination's failed or unfinished
19/// deliveries to the first `startup_netburst_keep` and deletes the rest
20/// without retrying, whether or not `startup_netburst` is enabled; `-1`
21/// keeps them all.
22#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
23#[derive(Clone, Copy, Debug, Deserialize)]
24#[config_example_generator(
25 filename = "tuwunel-example.toml",
26 section = "global.sending",
27 group = "true"
28)]
29pub struct Sending {
30 /// Sets the federation sender request timeout in seconds.
31 ///
32 /// default: 180
33 /// legacy: sender_timeout
34 #[serde(default = "default_timeout")]
35 pub timeout: u64,
36
37 /// Sets the federation sender idle connection pool timeout (seconds).
38 ///
39 /// default: 180
40 /// legacy: sender_idle_timeout
41 #[serde(default = "default_idle_timeout")]
42 pub idle_timeout: u64,
43
44 /// Sets the federation sender transaction retry backoff limit (seconds).
45 ///
46 /// reloadable: yes
47 /// default: 86400
48 /// legacy: sender_retry_backoff_limit
49 #[serde(default = "default_retry_backoff_limit")]
50 pub retry_backoff_limit: u64,
51
52 /// Sets the grace period in seconds before retrying a federation
53 /// destination that has failed exactly once.
54 ///
55 /// This replaces the quadratic backoff curve for the first retry, so a
56 /// single transient failure does not hold delivery until the next backoff
57 /// window. A second consecutive failure returns to the backoff curve. Set
58 /// to 0 to disable the grace and back off from the first failure.
59 ///
60 /// default: 15
61 /// legacy: sender_retry_grace
62 #[serde(default = "default_retry_grace")]
63 pub retry_grace: u64,
64
65 /// Sets the grace period for clean shutdown of federation requests
66 /// (seconds).
67 ///
68 /// reloadable: yes
69 /// default: 5
70 /// legacy: sender_shutdown_timeout
71 #[serde(default = "default_shutdown_timeout")]
72 pub shutdown_timeout: u64,
73
74 /// Retries failed and incomplete messages to remote servers immediately at
75 /// startup.
76 ///
77 /// This is called bursting; disabling it retries queued messages on a
78 /// paced timer after startup instead of all at once, reducing startup load
79 /// when resources are extremely limited or deployment scale is huge.
80 ///
81 /// legacy: startup_netburst
82 #[serde(default = "true_fn")]
83 pub startup_netburst: bool,
84
85 /// Caps the unsent messages kept per destination at startup.
86 ///
87 /// The cap applies whether or not `sending.startup_netburst` is enabled,
88 /// and messages past it are dropped and never reattempted. -1 keeps every
89 /// message and can consume significant disk, while 0 drops all messages
90 /// without any redelivery attempt.
91 ///
92 /// default: 50
93 /// legacy: startup_netburst_keep
94 #[serde(default = "default_startup_netburst_keep")]
95 pub startup_netburst_keep: i64,
96
97 /// Sets the number of sender task workers and their parallelism.
98 ///
99 /// The default 0 selects the count internally, likely matching Tokio
100 /// worker threads or CPU cores. Set a nonzero value to override that
101 /// count.
102 ///
103 /// default: 0
104 /// legacy: sender_workers
105 #[serde(default)]
106 pub workers: usize,
107}
108
109impl Default for Sending {
110 fn default() -> Self {
111 Self {
112 timeout: default_timeout(),
113 idle_timeout: default_idle_timeout(),
114 retry_backoff_limit: default_retry_backoff_limit(),
115 retry_grace: default_retry_grace(),
116 shutdown_timeout: default_shutdown_timeout(),
117 startup_netburst: true_fn(),
118 startup_netburst_keep: default_startup_netburst_keep(),
119 workers: Default::default(),
120 }
121 }
122}
123
124fn default_timeout() -> u64 { 180 }
125
126fn default_idle_timeout() -> u64 { 180 }
127
128fn default_retry_backoff_limit() -> u64 { 86400 }
129
130fn default_retry_grace() -> u64 { 15 }
131
132fn default_shutdown_timeout() -> u64 { 5 }
133
134fn default_startup_netburst_keep() -> i64 { 50 }