Skip to main content

tuwunel_core/config/
push.rs

1//! Configures push-gateway delivery and notification policy.
2//!
3//! Gateway transport settings control requests. Rule evaluation and
4//! active-user suppression control notification selection, and the email
5//! delay decides when notification emails go out.
6
7use serde::Deserialize;
8use tuwunel_macros::config_example_generator;
9
10/// Push notifications
11///
12/// Controls delivery to the push gateways that clients register for their
13/// users, and which events reach them. Push works with nothing set here: by
14/// default the server evaluates each user's push rules and forwards only
15/// events the rules mark as notifying. `email_delay` decides when notification
16/// emails go out to users who turn them on.
17///
18/// Tips:
19/// - Gateway requests obey `network.http.ip_range_denylist`, so with its
20///   default a gateway on a loopback or private address is refused.
21/// - `suppress_when_active` is experimental and logs a warning at startup.
22///   It judges activity from presence, so it needs `presence.allow_local`.
23#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
24#[derive(Clone, Debug, Deserialize)]
25#[config_example_generator(
26	filename = "tuwunel-example.toml",
27	section = "global.push",
28	group = "true"
29)]
30pub struct Push {
31	/// Sets the notification-gateway pusher idle connection-pool timeout.
32	///
33	/// default: 15
34	/// legacy: pusher_idle_timeout
35	#[serde(default = "default_idle_timeout")]
36	pub idle_timeout: u64,
37
38	/// Selects the suffix stripped from a gateway URL before constructing a
39	/// push request.
40	///
41	/// reloadable: yes
42	/// default: "/_matrix/push/v1/notify"
43	/// legacy: notification_push_path
44	#[serde(default = "default_notification_path")]
45	pub notification_path: String,
46
47	/// Sends every message to HTTP pushers without filtering by push rules or
48	/// actions.
49	///
50	/// This compatibility and special-purpose setting should not normally be
51	/// needed, but can bypass bugs or outdated server-side rule support, let
52	/// clients evaluate rules themselves, or support hosting and custom-pusher
53	/// requirements. It does not alter the notification records shown in the
54	/// notifications pane. Email pushers still mail only what the push rules
55	/// notify for.
56	///
57	/// reloadable: yes
58	/// legacy: push_everything
59	#[serde(default)]
60	pub everything: bool,
61
62	/// Evaluates the `im.nheko.msc3664.related_event_match` push-rule
63	/// condition.
64	///
65	/// The condition matches properties of the event an incoming event relates
66	/// to, enabling reply or reaction notifications for a user's own messages
67	/// that no other condition can express. Enabling it costs one extra event
68	/// lookup for each event carrying a relation. The default
69	/// `.im.nheko.msc3664.reply` rule uses it; disabling evaluation leaves
70	/// that rule present but unable to match replies, although clients
71	/// implementing
72	/// [MSC3664](https://github.com/matrix-org/matrix-spec-proposals/pull/3664)
73	/// may still evaluate it locally.
74	///
75	/// reloadable: yes
76	/// legacy: msc3664_related_event_match
77	#[serde(default)]
78	pub msc3664_related_event_match: bool,
79
80	/// Experimentally suppresses HTTP push notifications for active users.
81	///
82	/// When enabled, users with Online presence and recent activity,
83	/// determined from presence and sync activity, receive no HTTP push
84	/// notifications, reducing duplicate alerts while active on another
85	/// client. The default is disabled to preserve legacy behavior. Email
86	/// pushers ignore this setting; they do not mail messages the user reads
87	/// before `email_delay` ends.
88	///
89	/// reloadable: yes
90	/// legacy: suppress_push_when_active
91	#[serde(default)]
92	pub suppress_when_active: bool,
93
94	/// Seconds an unread notification waits before an email pusher mails it.
95	///
96	/// Email notifications need `[global.smtp]`; a user receives them when
97	/// their client registers an email pusher for an address verified on their
98	/// account. A notification still unread after this delay is mailed
99	/// together with any others waiting. A room in that mail is then held back
100	/// longer before it can prompt each further mail, up to a day, until the
101	/// user reads it. With a delay of 0, each notification is mailed as it
102	/// arrives and no room is held back.
103	///
104	/// reloadable: yes
105	/// default: 600
106	#[serde(default = "default_email_delay")]
107	pub email_delay: u64,
108}
109
110impl Default for Push {
111	fn default() -> Self {
112		Self {
113			idle_timeout: default_idle_timeout(),
114			notification_path: default_notification_path(),
115			everything: Default::default(),
116			msc3664_related_event_match: Default::default(),
117			suppress_when_active: Default::default(),
118			email_delay: default_email_delay(),
119		}
120	}
121}
122
123fn default_idle_timeout() -> u64 { 15 }
124
125fn default_notification_path() -> String { "/_matrix/push/v1/notify".to_owned() }
126
127fn default_email_delay() -> u64 { 600 }