Skip to main content

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 }