ruma_events/lib.rs
1#![doc(html_favicon_url = "https://ruma.dev/favicon.ico")]
2#![doc(html_logo_url = "https://ruma.dev/images/logo.png")]
3//! (De)serializable types for the events in the [Matrix](https://matrix.org) specification.
4//! These types are used by other Ruma crates.
5//!
6//! All data exchanged over Matrix is expressed as an event.
7//! Different event types represent different actions, such as joining a room or sending a message.
8//! Events are stored and transmitted as simple JSON structures.
9//! While anyone can create a new event type for their own purposes, the Matrix specification
10//! defines a number of event types which are considered core to the protocol.
11//! This module contains Rust types for all of the event types defined by the specification and
12//! facilities for extending the event system for custom event types.
13//!
14//! # Core event types
15//!
16//! This module includes Rust types for all event types in the Matrix specification.
17//! To better organize the crate, these types live in separate modules with a hierarchy that matches
18//! the reverse domain name notation of the event type. For example, the `m.room.message` event
19//! lives at `ruma::events::room::message::RoomMessageEvent`. Each type's module also contains a
20//! Rust type for that event type's `content` field, and any other supporting types required by the
21//! event's other fields.
22//!
23//! # Extending Ruma with custom events
24//!
25//! For our examples we will start with a simple custom state event. `ruma_event`
26//! specifies the state event's `type` and its `kind`.
27//!
28//! ```rust
29//! use ruma_events::macros::EventContent;
30//! use serde::{Deserialize, Serialize};
31//!
32//! #[derive(Clone, Debug, Deserialize, Serialize, EventContent)]
33//! #[ruma_event(type = "org.example.event", kind = State, state_key_type = String)]
34//! pub struct ExampleContent {
35//! field: String,
36//! }
37//! ```
38//!
39//! This can be used with events structs, such as passing it into
40//! `ruma::api::client::state::send_state_event`'s `Request`.
41//!
42//! As a more advanced example we create a reaction message event. For this event we will use a
43//! [`OriginalSyncMessageLikeEvent`] struct but any [`OriginalMessageLikeEvent`] struct would work.
44//!
45//! ```rust
46//! use ruma_common::OwnedEventId;
47//! use ruma_events::{macros::EventContent, OriginalSyncMessageLikeEvent};
48//! use serde::{Deserialize, Serialize};
49//!
50//! #[derive(Clone, Debug, Deserialize, Serialize)]
51//! #[serde(tag = "rel_type")]
52//! pub enum RelatesTo {
53//! #[serde(rename = "m.annotation")]
54//! Annotation {
55//! /// The event this reaction relates to.
56//! event_id: OwnedEventId,
57//! /// The displayable content of the reaction.
58//! key: String,
59//! },
60//!
61//! /// Since this event is not fully specified in the Matrix spec
62//! /// it may change or types may be added, we are ready!
63//! #[serde(rename = "m.whatever")]
64//! Whatever,
65//! }
66//!
67//! /// The payload for our reaction event.
68//! #[derive(Clone, Debug, Deserialize, Serialize, EventContent)]
69//! #[ruma_event(type = "m.reaction", kind = MessageLike)]
70//! pub struct ReactionEventContent {
71//! #[serde(rename = "m.relates_to")]
72//! pub relates_to: RelatesTo,
73//! }
74//!
75//! let json = serde_json::json!({
76//! "content": {
77//! "m.relates_to": {
78//! "event_id": "$xxxx-xxxx",
79//! "key": "👍",
80//! "rel_type": "m.annotation"
81//! }
82//! },
83//! "event_id": "$xxxx-xxxx",
84//! "origin_server_ts": 1,
85//! "sender": "@someone:example.org",
86//! "type": "m.reaction",
87//! "unsigned": {
88//! "age": 85
89//! }
90//! });
91//!
92//! // The downside of this event is we cannot use it with event enums,
93//! // but could be deserialized from a `Raw<_>` that has failed to deserialize.
94//! assert!(matches!(
95//! serde_json::from_value::<OriginalSyncMessageLikeEvent<ReactionEventContent>>(json),
96//! Ok(OriginalSyncMessageLikeEvent {
97//! content: ReactionEventContent {
98//! relates_to: RelatesTo::Annotation { key, .. },
99//! },
100//! ..
101//! }) if key == "👍"
102//! ));
103//! ```
104
105#![warn(missing_docs)]
106
107use std::{collections::BTreeSet, fmt};
108
109use ruma_common::{room_version_rules::RedactionRules, EventEncryptionAlgorithm, OwnedUserId};
110use serde::{de::IgnoredAny, Deserialize, Serialize, Serializer};
111
112// Needs to be public for trybuild tests
113#[doc(hidden)]
114pub mod _custom;
115mod content;
116mod enums;
117mod kinds;
118mod state_key;
119mod unsigned;
120
121// So event macros work inside this crate.
122extern crate self as ruma_events;
123
124/// Re-exports used by macro-generated code.
125///
126/// It is not considered part of this module's public API.
127#[doc(hidden)]
128pub mod exports {
129 pub use ruma_common;
130 pub use ruma_macros;
131 pub use serde;
132 pub use serde_json;
133}
134
135/// Re-export of all the derives needed to create your own event types.
136pub mod macros {
137 pub use ruma_macros::{Event, EventContent};
138}
139
140#[cfg(feature = "unstable-msc3927")]
141pub mod audio;
142#[cfg(feature = "unstable-msc3489")]
143pub mod beacon;
144#[cfg(feature = "unstable-msc3489")]
145pub mod beacon_info;
146pub mod call;
147pub mod direct;
148#[cfg(feature = "unstable-msc4359")]
149pub mod do_not_disturb;
150pub mod dummy;
151#[cfg(feature = "unstable-msc3954")]
152pub mod emote;
153#[cfg(feature = "unstable-msc3956")]
154pub mod encrypted;
155#[cfg(feature = "unstable-msc3551")]
156pub mod file;
157pub mod forwarded_room_key;
158pub mod fully_read;
159pub mod identity_server;
160pub mod ignored_user_list;
161#[cfg(feature = "unstable-msc3552")]
162pub mod image;
163#[cfg(feature = "unstable-msc2545")]
164pub mod image_pack;
165pub mod key;
166#[cfg(feature = "unstable-msc3488")]
167pub mod location;
168pub mod marked_unread;
169#[cfg(feature = "unstable-msc4278")]
170pub mod media_preview_config;
171#[cfg(feature = "unstable-msc4171")]
172pub mod member_hints;
173pub mod message;
174pub mod policy;
175#[cfg(feature = "unstable-msc3381")]
176pub mod poll;
177pub mod presence;
178pub mod push_rules;
179pub mod reaction;
180pub mod receipt;
181pub mod relation;
182pub mod room;
183pub mod room_key;
184#[cfg(feature = "unstable-msc4268")]
185pub mod room_key_bundle;
186pub mod room_key_request;
187#[cfg(feature = "unstable-msc4310")]
188pub mod rtc;
189pub mod secret;
190pub mod secret_storage;
191pub mod space;
192pub mod sticker;
193pub mod tag;
194pub mod typing;
195#[cfg(feature = "unstable-msc3553")]
196pub mod video;
197#[cfg(feature = "unstable-msc3245")]
198pub mod voice;
199
200pub use self::{
201 content::*,
202 enums::*,
203 kinds::*,
204 relation::{BundledMessageLikeRelations, BundledStateRelations},
205 state_key::EmptyStateKey,
206 unsigned::{MessageLikeUnsigned, RedactedUnsigned, StateUnsigned, UnsignedRoomRedactionEvent},
207};
208
209/// Trait to define the behavior of redact an event's content object.
210pub trait RedactContent {
211 /// The redacted form of the event's content.
212 type Redacted;
213
214 /// Transform `self` into a redacted form (removing most or all fields) according to the spec.
215 ///
216 /// A small number of events have room-version specific redaction behavior, so a
217 /// [`RedactionRules`] has to be specified.
218 fn redact(self, rules: &RedactionRules) -> Self::Redacted;
219}
220
221/// Helper struct to determine the event kind from a `serde_json::value::RawValue`.
222#[doc(hidden)]
223#[derive(Deserialize)]
224#[allow(clippy::exhaustive_structs)]
225pub struct EventTypeDeHelper<'a> {
226 #[serde(borrow, rename = "type")]
227 pub ev_type: std::borrow::Cow<'a, str>,
228}
229
230/// Helper struct to determine if an event has been redacted.
231#[doc(hidden)]
232#[derive(Deserialize)]
233#[allow(clippy::exhaustive_structs)]
234pub struct RedactionDeHelper {
235 /// Used to check whether redacted_because exists.
236 pub unsigned: Option<UnsignedDeHelper>,
237}
238
239#[doc(hidden)]
240#[derive(Deserialize)]
241#[allow(clippy::exhaustive_structs)]
242pub struct UnsignedDeHelper {
243 /// This is the field that signals an event has been redacted.
244 pub redacted_because: Option<IgnoredAny>,
245}
246
247/// Helper function for erroring when trying to serialize an event enum _Custom variant that can
248/// only be created by deserializing from an unknown event type.
249#[doc(hidden)]
250#[allow(clippy::ptr_arg)]
251pub fn serialize_custom_event_error<T, S: Serializer>(_: &T, _: S) -> Result<S::Ok, S::Error> {
252 Err(serde::ser::Error::custom(
253 "Failed to serialize event [content] enum: Unknown event type.\n\
254 To send custom events, turn them into `Raw<EnumType>` by going through
255 `serde_json::value::to_raw_value` and `Raw::from_json`.",
256 ))
257}
258
259/// Describes whether the event mentions other users or the room.
260#[derive(Clone, Debug, Default, Serialize, Deserialize)]
261#[non_exhaustive]
262pub struct Mentions {
263 /// The list of mentioned users.
264 ///
265 /// Defaults to an empty `BTreeSet`.
266 #[serde(default, skip_serializing_if = "BTreeSet::is_empty")]
267 pub user_ids: BTreeSet<OwnedUserId>,
268
269 /// Whether the whole room is mentioned.
270 ///
271 /// Defaults to `false`.
272 #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
273 pub room: bool,
274}
275
276impl Mentions {
277 /// Create a `Mentions` with the default values.
278 pub fn new() -> Self {
279 Self::default()
280 }
281
282 /// Create a `Mentions` for the given user IDs.
283 pub fn with_user_ids(user_ids: impl IntoIterator<Item = OwnedUserId>) -> Self {
284 Self { user_ids: BTreeSet::from_iter(user_ids), ..Default::default() }
285 }
286
287 /// Create a `Mentions` for a room mention.
288 pub fn with_room_mention() -> Self {
289 Self { room: true, ..Default::default() }
290 }
291
292 fn add(&mut self, mentions: Self) {
293 self.user_ids.extend(mentions.user_ids);
294 self.room |= mentions.room;
295 }
296}
297
298// Wrapper around `Box<str>` that cannot be used in a meaningful way outside of
299// this crate. Used for string enums because their `_Custom` variant can't be
300// truly private (only `#[doc(hidden)]`).
301#[doc(hidden)]
302#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
303pub struct PrivOwnedStr(Box<str>);
304
305impl fmt::Debug for PrivOwnedStr {
306 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
307 self.0.fmt(f)
308 }
309}