1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367
//! Crate ruma_events contains serializable types for the events in the [Matrix](https://matrix.org) //! specification that can be shared by client and server code. //! //! All data exchanged over Matrix is expressed as an event. //! Different event types represent different actions, such as joining a room or sending a message. //! Events are stored and transmitted as simple JSON structures. //! While anyone can create a new event type for their own purposes, the Matrix specification //! defines a number of event types which are considered core to the protocol, and Matrix clients //! and servers must understand their semantics. //! ruma_events contains Rust types for each of the event types defined by the specification and //! facilities for extending the event system for custom event types. //! //! # Event types //! //! ruma_events includes a Rust enum called `EventType`, which provides a simple enumeration of //! all the event types defined by the Matrix specification. Matrix event types are serialized to //! JSON strings in [reverse domain name //! notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation), although the core event //! types all use the special "m" TLD, e.g. *m.room.message*. //! `EventType` also includes a variant called `Custom`, which is a catch-all that stores a string //! containing the name of any event type that isn't part of the specification. //! `EventType` is used throughout ruma_events to identify and differentiate between events of //! different types. //! //! # Event traits //! //! Matrix defines three "kinds" of events: //! //! 1. **Events**, which are arbitrary JSON structures that have two required keys: //! * `type`, which specifies the event's type //! * `content`, which is a JSON object containing the "payload" of the event //! 2. **Room events**, which are a superset of events and represent actions that occurred within //! the context of a Matrix room. //! They have at least the following additional keys: //! * `event_id`, which is a unique identifier for the event //! * `room_id`, which is a unique identifier for the room in which the event occurred //! * `sender`, which is the unique identifier of the Matrix user who created the event //! * Optionally, `unsigned`, which is a JSON object containing arbitrary additional metadata //! that is not digitally signed by Matrix homeservers. //! 3. **State events**, which are a superset of room events and represent persistent state //! specific to a room, such as the room's member list or topic. //! Within a single room, state events of the same type and with the same "state key" will //! effectively "replace" the previous one, updating the room's state. //! They have at least the following additional keys: //! * `state_key`, a string which serves as a sort of "sub-type." //! The state key allows a room to persist multiple state events of the same type. //! You can think of a room's state events as being a `HashMap` where the keys are the tuple //! `(event_type, state_key)`. //! * Optionally, `prev_content`, a JSON object containing the `content` object from the //! previous event of the given `(event_type, state_key)` tuple in the given room. //! //! ruma_events represents these three event kinds as traits, allowing any Rust type to serve as a //! Matrix event so long as it upholds the contract expected of its kind. //! //! # Core event types //! //! ruma_events includes Rust types for every one of the event types in the Matrix specification. //! To better organize the crate, these types live in separate modules with a hierarchy that //! matches the reverse domain name notation of the event type. //! For example, the *m.room.message* event lives at `ruma_events::room::message::MessageEvent`. //! Each type's module also contains a Rust type for that event type's `content` field, and any //! other supporting types required by the event's other fields. //! All concrete event types in ruma_events are serializable and deserializable using the //! [Serde](https://serde.rs/) serialization library. //! //! # Custom events //! //! Although any Rust type that implements `Event`, `RoomEvent`, or `StateEvent` can serve as a //! Matrix event type, ruma_events also includes a few convenience types for representing events //! that are not convered by the spec and not otherwise known by the application. //! `CustomEvent`, `CustomRoomEvent`, and `CustomStateEvent` are simple implementations of their //! respective event traits whose `content` field is simply a `serde_json::Value` value, which //! represents arbitrary JSON. //! //! # Collections //! //! With the trait-based approach to events, it's easy to write generic collection types like //! `Vec<Box<R: RoomEvent>>`. //! However, there are APIs in the Matrix specification that involve heterogeneous collections of //! events, i.e. a list of events of different event types. //! Because Rust does not have a facility for arrays, vectors, or slices containing multiple //! concrete types, ruma_events provides special collection types for this purpose. //! The collection types are enums which effectively "wrap" each possible event type of a //! particular event "kind." //! //! Because of the hierarchical nature of event kinds in Matrix, these collection types are divied //! into two modules, `ruma_events::collections::all` and `ruma_events::collections::only`. //! The "all" versions include every event type that implements the relevant event trait as well as //! more specific event traits. //! The "only" versions include only the event types that implement "at most" the relevant event //! trait. //! //! For example, the `ruma_events::collections::all::Event` enum includes *m.room.message*, because //! that event type is both an event and a room event. //! However, the `ruma_events::collections::only::Event` enum does *not* include *m.room.message*, //! because *m.room.message* implements a *more specific* event trait than `Event`. #![deny(missing_debug_implementations)] #![deny(missing_docs)] #![deny(warnings)] extern crate ruma_identifiers; extern crate ruma_signatures; extern crate serde; #[macro_use] extern crate serde_derive; extern crate serde_json; use std::fmt::{Debug, Display, Formatter, Error as FmtError, Result as FmtResult}; use ruma_identifiers::{EventId, RoomId, UserId}; use serde::{Deserialize, Deserializer, Serialize, Serializer}; use serde::de::{Error as SerdeError, Visitor}; use serde_json::Value; #[macro_use] mod macros; pub mod call; /// Enums for heterogeneous collections of events. pub mod collections { pub mod all; pub mod only; } pub mod presence; pub mod receipt; pub mod room; pub mod stripped; pub mod tag; pub mod typing; /// An error when attempting to convert a string to an enum that only accepts certain values. #[derive(Clone, Copy, Debug)] pub struct ParseError; /// The type of an event. #[derive(Clone, Debug, Eq, Hash, PartialEq)] pub enum EventType { /// m.call.answer CallAnswer, /// m.call.candidates CallCandidates, /// m.call.hangup CallHangup, /// m.call.invite CallInvite, /// m.presence Presence, /// m.receipt Receipt, /// m.room.aliases RoomAliases, /// m.room.avatar RoomAvatar, /// m.room.canonical_alias RoomCanonicalAlias, /// m.room.create RoomCreate, /// m.room.guest_access RoomGuestAccess, /// m.room.history_visibility RoomHistoryVisibility, /// m.room.join_rules RoomJoinRules, /// m.room.member RoomMember, /// m.room.message RoomMessage, /// m.room.name RoomName, /// m.room.power_levels RoomPowerLevels, /// m.room.redaction RoomRedaction, /// m.room.third_party_invite RoomThirdPartyInvite, /// m.room.topic RoomTopic, /// m.tag Tag, /// m.typing Typing, /// Any event that is not part of the specification. Custom(String), } /// A basic event. pub trait Event where Self: Debug + for<'a> Deserialize<'a> + Serialize { /// The event-type-specific payload this event carries. type Content: Debug + for<'a> Deserialize<'a> + Serialize; /// The event's content. fn content(&self) -> &Self::Content; /// The type of the event. fn event_type(&self) -> &EventType; /// Extra top-level key-value pairs specific to this event type, but that are not under the /// `content` field. fn extra_content(&self) -> Option<Value> { None } } /// An event within the context of a room. pub trait RoomEvent: Event { /// The unique identifier for the event. fn event_id(&self) -> &EventId; /// The unique identifier for the room associated with this event. fn room_id(&self) -> &RoomId; /// Additional key-value pairs not signed by the homeserver. fn unsigned(&self) -> Option<&Value>; /// The unique identifier for the user associated with this event. fn user_id(&self) -> &UserId; } /// An event that describes persistent state about a room. pub trait StateEvent: RoomEvent { /// The previous content for this state key, if any. fn prev_content(&self) -> Option<&Self::Content>; /// A key that determines which piece of room state the event represents. fn state_key(&self) -> &str; } event! { /// A custom basic event not covered by the Matrix specification. pub struct CustomEvent(Value) {} } room_event! { /// A custom room event not covered by the Matrix specification. pub struct CustomRoomEvent(Value) {} } state_event! { /// A custom state event not covered by the Matrix specification. pub struct CustomStateEvent(Value) {} } impl Display for EventType { fn fmt(&self, f: &mut Formatter) -> Result<(), FmtError> { let event_type_str = match *self { EventType::CallAnswer => "m.call.answer", EventType::CallCandidates => "m.call.candidates", EventType::CallHangup => "m.call.hangup", EventType::CallInvite => "m.call.invite", EventType::Presence => "m.presence", EventType::Receipt => "m.receipt", EventType::RoomAliases => "m.room.aliases", EventType::RoomAvatar => "m.room.avatar", EventType::RoomCanonicalAlias => "m.room.canonical_alias", EventType::RoomCreate => "m.room.create", EventType::RoomGuestAccess => "m.room.guest_access", EventType::RoomHistoryVisibility => "m.room.history_visibility", EventType::RoomJoinRules => "m.room.join_rules", EventType::RoomMember => "m.room.member", EventType::RoomMessage => "m.room.message", EventType::RoomName => "m.room.name", EventType::RoomPowerLevels => "m.room.power_levels", EventType::RoomRedaction => "m.room.redaction", EventType::RoomThirdPartyInvite => "m.room.third_party_invite", EventType::RoomTopic => "m.room.topic", EventType::Tag => "m.tag", EventType::Typing => "m.typing", EventType::Custom(ref event_type) => event_type, }; write!(f, "{}", event_type_str) } } impl<'a> From<&'a str> for EventType { fn from(s: &'a str) -> EventType { match s { "m.call.answer" => EventType::CallAnswer, "m.call.candidates" => EventType::CallCandidates, "m.call.hangup" => EventType::CallHangup, "m.call.invite" => EventType::CallInvite, "m.presence" => EventType::Presence, "m.receipt" => EventType::Receipt, "m.room.aliases" => EventType::RoomAliases, "m.room.avatar" => EventType::RoomAvatar, "m.room.canonical_alias" => EventType::RoomCanonicalAlias, "m.room.create" => EventType::RoomCreate, "m.room.guest_access" => EventType::RoomGuestAccess, "m.room.history_visibility" => EventType::RoomHistoryVisibility, "m.room.join_rules" => EventType::RoomJoinRules, "m.room.member" => EventType::RoomMember, "m.room.message" => EventType::RoomMessage, "m.room.name" => EventType::RoomName, "m.room.power_levels" => EventType::RoomPowerLevels, "m.room.redaction" => EventType::RoomRedaction, "m.room.third_party_invite" => EventType::RoomThirdPartyInvite, "m.room.topic" => EventType::RoomTopic, "m.tag" => EventType::Tag, "m.typing" => EventType::Typing, event_type => EventType::Custom(event_type.to_string()), } } } impl Serialize for EventType { fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where S: Serializer { serializer.serialize_str(&self.to_string()) } } impl<'de> Deserialize<'de> for EventType { fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where D: Deserializer<'de> { struct EventTypeVisitor; impl<'de> Visitor<'de> for EventTypeVisitor { type Value = EventType; fn expecting(&self, formatter: &mut Formatter) -> FmtResult { write!(formatter, "a Matrix event type as a string") } fn visit_str<E>(self, v: &str) -> Result<Self::Value, E> where E: SerdeError { Ok(EventType::from(v)) } } deserializer.deserialize_str(EventTypeVisitor) } } #[cfg(test)] mod tests { use serde_json::{from_str, to_string}; use super::EventType; #[test] fn event_types_serialize_to_display_form() { assert_eq!( to_string(&EventType::RoomCreate).unwrap(), r#""m.room.create""# ); } #[test] fn custom_event_types_serialize_to_display_form() { assert_eq!( to_string(&EventType::Custom("io.ruma.test".to_string())).unwrap(), r#""io.ruma.test""# ); } #[test] fn event_types_deserialize_from_display_form() { assert_eq!( from_str::<EventType>(r#""m.room.create""#).unwrap(), EventType::RoomCreate ); } #[test] fn custom_event_types_deserialize_from_display_form() { assert_eq!( from_str::<EventType>(r#""io.ruma.test""#).unwrap(), EventType::Custom("io.ruma.test".to_string()) ) } }