ruma_common/room_version_rules.rs
1//! Types for the rules applied to the different [room versions].
2//!
3//! [room versions]: https://spec.matrix.org/latest/rooms/
4
5/// The rules applied to a [room version].
6///
7/// This type can be constructed from one of its constants (like [`RoomVersionRules::V1`]), or from
8/// [`RoomVersionId::rules()`].
9///
10/// [room version]: https://spec.matrix.org/latest/rooms/
11/// [`RoomVersionId::rules()`]: crate::RoomVersionId::rules
12#[derive(Debug, Clone)]
13#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
14pub struct RoomVersionRules {
15 /// The stability of the room version.
16 pub disposition: RoomVersionDisposition,
17
18 /// The format of event IDs.
19 pub event_id_format: EventIdFormatVersion,
20
21 /// The state resolution algorithm used.
22 pub state_res: StateResolutionVersion,
23
24 /// Whether to enforce the key validity period when verifying signatures ([spec]), introduced
25 /// in room version 5.
26 ///
27 /// [spec]: https://spec.matrix.org/latest/rooms/v5/#signing-key-validity-period
28 pub enforce_key_validity: bool,
29
30 /// The tweaks in the authorization rules.
31 pub authorization: AuthorizationRules,
32
33 /// The tweaks in the redaction algorithm.
34 pub redaction: RedactionRules,
35
36 /// The tweaks for verifying signatures.
37 pub signatures: SignaturesRules,
38}
39
40impl RoomVersionRules {
41 /// Rules for [room version 1].
42 ///
43 /// [room version 1]: https://spec.matrix.org/latest/rooms/v1/
44 pub const V1: Self = Self {
45 disposition: RoomVersionDisposition::Stable,
46 event_id_format: EventIdFormatVersion::V1,
47 state_res: StateResolutionVersion::V1,
48 enforce_key_validity: false,
49 authorization: AuthorizationRules::V1,
50 redaction: RedactionRules::V1,
51 signatures: SignaturesRules::V1,
52 };
53
54 /// Rules for [room version 2].
55 ///
56 /// [room version 2]: https://spec.matrix.org/latest/rooms/v2/
57 pub const V2: Self = Self { state_res: StateResolutionVersion::V2, ..Self::V1 };
58
59 /// Rules for [room version 3].
60 ///
61 /// [room version 3]: https://spec.matrix.org/latest/rooms/v3/
62 pub const V3: Self = Self {
63 event_id_format: EventIdFormatVersion::V2,
64 authorization: AuthorizationRules::V3,
65 signatures: SignaturesRules::V3,
66 ..Self::V2
67 };
68
69 /// Rules for [room version 4].
70 ///
71 /// [room version 4]: https://spec.matrix.org/latest/rooms/v4/
72 pub const V4: Self = Self { event_id_format: EventIdFormatVersion::V3, ..Self::V3 };
73
74 /// Rules for [room version 5].
75 ///
76 /// [room version 5]: https://spec.matrix.org/latest/rooms/v5/
77 pub const V5: Self = Self { enforce_key_validity: true, ..Self::V4 };
78
79 /// Rules for [room version 6].
80 ///
81 /// [room version 6]: https://spec.matrix.org/latest/rooms/v6/
82 pub const V6: Self =
83 Self { authorization: AuthorizationRules::V6, redaction: RedactionRules::V6, ..Self::V5 };
84
85 /// Rules for [room version 7].
86 ///
87 /// [room version 7]: https://spec.matrix.org/latest/rooms/v7/
88 pub const V7: Self = Self { authorization: AuthorizationRules::V7, ..Self::V6 };
89
90 /// Rules for [room version 8].
91 ///
92 /// [room version 8]: https://spec.matrix.org/latest/rooms/v8/
93 pub const V8: Self = Self {
94 authorization: AuthorizationRules::V8,
95 redaction: RedactionRules::V8,
96 signatures: SignaturesRules::V8,
97 ..Self::V7
98 };
99
100 /// Rules for [room version 9].
101 ///
102 /// [room version 9]: https://spec.matrix.org/latest/rooms/v9/
103 pub const V9: Self = Self { redaction: RedactionRules::V9, ..Self::V8 };
104
105 /// Rules for [room version 10].
106 ///
107 /// [room version 10]: https://spec.matrix.org/latest/rooms/v10/
108 pub const V10: Self = Self { authorization: AuthorizationRules::V10, ..Self::V9 };
109
110 /// Rules for [room version 11].
111 ///
112 /// [room version 11]: https://spec.matrix.org/latest/rooms/v11/
113 pub const V11: Self = Self { authorization: AuthorizationRules::V11, ..Self::V10 };
114
115 /// Rules for room version `org.matrix.msc2870` ([MSC2870]).
116 ///
117 /// [MSC2870]: https://github.com/matrix-org/matrix-spec-proposals/pull/2870
118 #[cfg(feature = "unstable-msc2870")]
119 pub const MSC2870: Self = Self { redaction: RedactionRules::MSC2870, ..Self::V11 };
120}
121
122/// The stability of a room version.
123#[derive(Debug, Clone, Copy, PartialEq, Eq)]
124#[allow(clippy::exhaustive_enums)]
125pub enum RoomVersionDisposition {
126 /// A room version that has a stable specification.
127 Stable,
128
129 /// A room version that is not yet fully specified.
130 Unstable,
131}
132
133/// The format of [event IDs] for a room version.
134///
135/// [event IDs]: https://spec.matrix.org/latest/appendices/#event-ids
136#[derive(Debug, Clone, Copy, PartialEq, Eq)]
137#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
138pub enum EventIdFormatVersion {
139 /// `$id:server` format ([spec]), introduced in room version 1.
140 ///
141 /// [spec]: https://spec.matrix.org/latest/rooms/v1/#event-ids
142 V1,
143
144 /// `$hash` format using standard unpadded base64 ([spec]), introduced in room version 3.
145 ///
146 /// [spec]: https://spec.matrix.org/latest/rooms/v3/#event-ids
147 V2,
148
149 /// `$hash` format using URL-safe unpadded base64 ([spec]), introduced in room version 4.
150 ///
151 /// [spec]: https://spec.matrix.org/latest/rooms/v4/#event-ids
152 V3,
153}
154
155/// The version of [state resolution] for a room version.
156///
157/// [state resolution]: https://spec.matrix.org/latest/server-server-api/#room-state-resolution
158#[derive(Debug, Clone, Copy, PartialEq, Eq)]
159#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
160pub enum StateResolutionVersion {
161 /// First version of the state resolution algorithm ([spec]), introduced in room version 1.
162 ///
163 /// [spec]: https://spec.matrix.org/latest/rooms/v1/#state-resolution
164 V1,
165
166 /// Second version of the state resolution algorithm ([spec]), introduced in room version 2.
167 ///
168 /// [spec]: https://spec.matrix.org/latest/rooms/v2/#state-resolution
169 V2,
170}
171
172/// The tweaks in the [authorization rules] for a room version.
173///
174/// This type can be constructed from one of its constants (like [`AuthorizationRules::V1`]), or by
175/// constructing a [`RoomVersionRules`] first and using the `authorization` field.
176///
177/// [authorization rules]: https://spec.matrix.org/latest/server-server-api/#authorization-rules
178#[derive(Debug, Clone)]
179#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
180pub struct AuthorizationRules {
181 /// Whether to apply special authorization rules for `m.room.redaction` events ([spec]),
182 /// disabled since room version 3.
183 ///
184 /// [spec]: https://spec.matrix.org/latest/rooms/v3/#handling-redactions
185 pub special_case_room_redaction: bool,
186
187 /// Whether to apply special authorization rules for `m.room.aliases` events ([spec]), disabled
188 /// since room version 6.
189 ///
190 /// [spec]: https://spec.matrix.org/latest/rooms/v6/#authorization-rules
191 pub special_case_room_aliases: bool,
192
193 /// Whether to strictly enforce [canonical JSON] ([spec]), introduced in room version 6.
194 ///
195 /// Numbers in Canonical JSON must be integers in the range [-2<sup>53</sup> + 1,
196 /// 2<sup>53</sup> - 1], represented without exponents or decimal places, and negative zero
197 /// (`-0`) MUST NOT appear.
198 ///
199 /// [canonical JSON]: https://spec.matrix.org/latest/appendices/#canonical-json
200 /// [spec]: https://spec.matrix.org/latest/rooms/v6/#canonical-json
201 pub strict_canonical_json: bool,
202
203 /// Whether to check the `notifications` field when checking `m.room.power_levels` events
204 /// ([spec]), introduced in room version 6.
205 ///
206 /// [spec]: https://spec.matrix.org/latest/rooms/v6/#authorization-rules
207 pub limit_notifications_power_levels: bool,
208
209 /// Whether to allow the `knock` membership for `m.room.member` events and the `knock` join
210 /// rule for `m.room.join_rules` events ([spec]), introduced in room version 7.
211 ///
212 /// [spec]: https://spec.matrix.org/latest/rooms/v7/#authorization-rules
213 pub knocking: bool,
214
215 /// Whether to allow the `restricted` join rule for `m.room.join_rules` events ([spec]),
216 /// introduced in room version 8.
217 ///
218 /// [spec]: https://spec.matrix.org/latest/rooms/v8/#authorization-rules
219 pub restricted_join_rule: bool,
220
221 /// Whether to allow the `knock_restricted` join rule for `m.room.join_rules` events ([spec]),
222 /// introduced in room version 10.
223 ///
224 /// [spec]: https://spec.matrix.org/latest/rooms/v10/#authorization-rules
225 pub knock_restricted_join_rule: bool,
226
227 /// Whether to enforce that power levels values in `m.room.power_levels` events be integers
228 /// ([spec]), introduced in room version 10.
229 ///
230 /// [spec]: https://spec.matrix.org/latest/rooms/v10/#values-in-mroompower_levels-events-must-be-integers
231 pub integer_power_levels: bool,
232
233 /// Whether the room creator should be determined using the `m.room.create` event's `sender`,
234 /// instead of the event content's `creator` field ([spec]), introduced in room version 11.
235 ///
236 /// [spec]: https://spec.matrix.org/v1.14/rooms/v11/#event-format
237 pub use_room_create_sender: bool,
238}
239
240impl AuthorizationRules {
241 /// Authorization rules as introduced in room version 1 ([spec]).
242 ///
243 /// [spec]: https://spec.matrix.org/latest/rooms/v1/#authorization-rules
244 pub const V1: Self = Self {
245 special_case_room_redaction: true,
246 special_case_room_aliases: true,
247 strict_canonical_json: false,
248 limit_notifications_power_levels: false,
249 knocking: false,
250 restricted_join_rule: false,
251 knock_restricted_join_rule: false,
252 integer_power_levels: false,
253 use_room_create_sender: false,
254 };
255
256 /// Authorization rules with tweaks introduced in room version 3 ([spec]).
257 ///
258 /// [spec]: https://spec.matrix.org/latest/rooms/v3/#authorization-rules
259 pub const V3: Self = Self { special_case_room_redaction: false, ..Self::V1 };
260
261 /// Authorization rules with tweaks introduced in room version 6 ([spec]).
262 ///
263 /// [spec]: https://spec.matrix.org/latest/rooms/v6/#authorization-rules
264 pub const V6: Self = Self {
265 special_case_room_aliases: false,
266 strict_canonical_json: true,
267 limit_notifications_power_levels: true,
268 ..Self::V3
269 };
270
271 /// Authorization rules with tweaks introduced in room version 7 ([spec]).
272 ///
273 /// [spec]: https://spec.matrix.org/latest/rooms/v7/#authorization-rules
274 pub const V7: Self = Self { knocking: true, ..Self::V6 };
275
276 /// Authorization rules with tweaks introduced in room version 8 ([spec]).
277 ///
278 /// [spec]: https://spec.matrix.org/latest/rooms/v8/#authorization-rules
279 pub const V8: Self = Self { restricted_join_rule: true, ..Self::V7 };
280
281 /// Authorization rules with tweaks introduced in room version 10 ([spec]).
282 ///
283 /// [spec]: https://spec.matrix.org/latest/rooms/v10/#authorization-rules
284 pub const V10: Self =
285 Self { knock_restricted_join_rule: true, integer_power_levels: true, ..Self::V8 };
286
287 /// Authorization rules with tweaks introduced in room version 11 ([spec]).
288 ///
289 /// [spec]: https://spec.matrix.org/latest/rooms/v11/#authorization-rules
290 pub const V11: Self = Self { use_room_create_sender: true, ..Self::V10 };
291}
292
293/// The tweaks in the [redaction] algorithm for a room version.
294///
295/// This type can be constructed from one of its constants (like [`RedactionRules::V1`]), or by
296/// constructing a [`RoomVersionRules`] first and using the `redaction` field.
297///
298/// [redaction]: https://spec.matrix.org/latest/client-server-api/#redactions
299#[derive(Debug, Clone)]
300#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
301pub struct RedactionRules {
302 /// Whether to keep the `aliases` field in the `content` of `m.room.aliases` events ([spec]),
303 /// disabled since room version 6.
304 ///
305 /// [spec]: https://spec.matrix.org/v1.14/rooms/v6/#redactions
306 pub keep_room_aliases_aliases: bool,
307
308 /// Whether to keep the `allow` field in the `content` of `m.room.join_rules` events ([spec]),
309 /// introduced in room version 8.
310 ///
311 /// [spec]: https://spec.matrix.org/v1.14/rooms/v8/#redactions
312 pub keep_room_join_rules_allow: bool,
313
314 /// Whether to keep the `join_authorised_via_users_server` field in the `content` of
315 /// `m.room.member` events ([spec]), introduced in room version 9.
316 ///
317 /// [spec]: https://spec.matrix.org/v1.14/rooms/v9/#redactions
318 pub keep_room_member_join_authorised_via_users_server: bool,
319
320 /// Whether to keep the `origin`, `membership` and `prev_state` fields a the top-level of all
321 /// events ([spec]), disabled since room version 11.
322 ///
323 /// [spec]: https://spec.matrix.org/v1.14/rooms/v11/#redactions
324 pub keep_origin_membership_prev_state: bool,
325
326 /// Whether to keep the entire `content` of `m.room.create` events ([spec]), introduced in room
327 /// version 11.
328 ///
329 /// [spec]: https://spec.matrix.org/v1.14/rooms/v11/#redactions
330 pub keep_room_create_content: bool,
331
332 /// Whether to keep the `redacts` field in the `content` of `m.room.redaction` events ([spec]),
333 /// introduced in room version 11.
334 ///
335 /// [spec]: https://spec.matrix.org/v1.14/rooms/v11/#redactions
336 pub keep_room_redaction_redacts: bool,
337
338 /// Whether to keep the `invite` field in the `content` of `m.room.power_levels` events
339 /// ([spec]), introduced in room version 11.
340 ///
341 /// [spec]: https://spec.matrix.org/v1.14/rooms/v11/#redactions
342 pub keep_room_power_levels_invite: bool,
343
344 /// Whether to keep the `signed` field in `third_party_invite` of the `content` of
345 /// `m.room.member` events ([spec]), introduced in room version 11.
346 ///
347 /// [spec]: https://spec.matrix.org/v1.14/rooms/v11/#redactions
348 pub keep_room_member_third_party_invite_signed: bool,
349
350 /// Whether to keep the `allow`, `deny` and `allow_ip_literals` in the `content` of
351 /// `m.room.server_acl` events ([MSC2870]).
352 ///
353 /// [MSC2870]: https://github.com/matrix-org/matrix-spec-proposals/pull/2870
354 #[cfg(feature = "unstable-msc2870")]
355 pub keep_room_server_acl_allow_deny_allow_ip_literals: bool,
356}
357
358impl RedactionRules {
359 /// Redaction rules as introduced in room version 1 ([spec]).
360 ///
361 /// [spec]: https://spec.matrix.org/v1.14/rooms/v1/#redactions
362 pub const V1: Self = Self {
363 keep_room_aliases_aliases: true,
364 keep_room_join_rules_allow: false,
365 keep_room_member_join_authorised_via_users_server: false,
366 keep_origin_membership_prev_state: true,
367 keep_room_create_content: false,
368 keep_room_redaction_redacts: false,
369 keep_room_power_levels_invite: false,
370 keep_room_member_third_party_invite_signed: false,
371 #[cfg(feature = "unstable-msc2870")]
372 keep_room_server_acl_allow_deny_allow_ip_literals: false,
373 };
374
375 /// Redaction rules with tweaks introduced in room version 6 ([spec]).
376 ///
377 /// [spec]: https://spec.matrix.org/v1.14/rooms/v6/#redactions
378 pub const V6: Self = Self { keep_room_aliases_aliases: false, ..Self::V1 };
379
380 /// Redaction rules with tweaks introduced in room version 8 ([spec]).
381 ///
382 /// [spec]: https://spec.matrix.org/v1.14/rooms/v8/#redactions
383 pub const V8: Self = Self { keep_room_join_rules_allow: true, ..Self::V6 };
384
385 /// Redaction rules with tweaks introduced in room version 9 ([spec]).
386 ///
387 /// [spec]: https://spec.matrix.org/v1.14/rooms/v9/#redactions
388 pub const V9: Self =
389 Self { keep_room_member_join_authorised_via_users_server: true, ..Self::V8 };
390
391 /// Redaction rules with tweaks introduced in room version 11 ([spec]).
392 ///
393 /// [spec]: https://spec.matrix.org/v1.14/rooms/v11/#redactions
394 pub const V11: Self = Self {
395 keep_origin_membership_prev_state: false,
396 keep_room_create_content: true,
397 keep_room_redaction_redacts: true,
398 keep_room_power_levels_invite: true,
399 keep_room_member_third_party_invite_signed: true,
400 ..Self::V9
401 };
402
403 /// Redaction rules with tweaks introduced in [MSC2870].
404 ///
405 /// [MSC2870]: https://github.com/matrix-org/matrix-spec-proposals/pull/2870
406 #[cfg(feature = "unstable-msc2870")]
407 pub const MSC2870: Self =
408 Self { keep_room_server_acl_allow_deny_allow_ip_literals: true, ..Self::V11 };
409}
410
411/// The tweaks for [verifying the signatures] for a room version.
412///
413/// This type can be constructed from one of its constants (like [`SignaturesRules::V1`]), or by
414/// constructing a [`RoomVersionRules`] first and using the `signatures` field.
415///
416/// [verifying the signatures]: https://spec.matrix.org/latest/server-server-api/#validating-hashes-and-signatures-on-received-events
417#[derive(Debug, Clone)]
418#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
419pub struct SignaturesRules {
420 /// Whether to check the server of the event ID, disabled since room version 3.
421 pub check_event_id_server: bool,
422
423 /// Whether to check the server of the `join_authorised_via_users_server` field in the
424 /// `content` of `m.room.member` events ([spec]), introduced in room version 8.
425 ///
426 /// [spec]: https://spec.matrix.org/latest/rooms/v8/#authorization-rules
427 pub check_join_authorised_via_users_server: bool,
428}
429
430impl SignaturesRules {
431 /// Signatures verification rules as introduced in room version 1.
432 pub const V1: Self =
433 Self { check_event_id_server: true, check_join_authorised_via_users_server: false };
434
435 /// Signatures verification rules with tweaks introduced in room version 3.
436 pub const V3: Self = Self { check_event_id_server: false, ..Self::V1 };
437
438 /// Signatures verification rules with tweaks introduced in room version 8.
439 pub const V8: Self = Self { check_join_authorised_via_users_server: true, ..Self::V3 };
440}