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 }