Crate ruma_events

(De)serializable types for the events in the Matrix specification. These types are used by other ruma crates.

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, although the core event types all use the special “m” TLD, e.g. m.room.message.

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.

Extending Ruma with custom events

For our example we will create a reaction message event. This can be used with ruma-events structs, for this event we will use a SyncMessageEvent struct but any MessageEvent struct would work.

use ruma_events::{macros::EventContent, SyncMessageEvent};
use ruma_identifiers::EventId;
use serde::{Deserialize, Serialize};

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(tag = "rel_type")]
pub enum RelatesTo {
    #[serde(rename = "m.annotation")]
    Annotation {
        /// The event this reaction relates to.
        event_id: EventId,
        /// The displayable content of the reaction.
        key: String,
    },

    /// Since this event is not fully specified in the Matrix spec
    /// it may change or types may be added, we are ready!
    #[serde(rename = "m.whatever")]
    Whatever,
}

/// The payload for our reaction event.
#[derive(Clone, Debug, Deserialize, Serialize, EventContent)]
#[ruma_event(type = "m.reaction", kind = Message)]
pub struct ReactionEventContent {
    #[serde(rename = "m.relates_to")]
    pub relates_to: RelatesTo,
}

let json = serde_json::json!({
    "content": {
        "m.relates_to": {
            "event_id": "$xxxx-xxxx",
            "key": "👍",
            "rel_type": "m.annotation"
        }
    },
    "event_id": "$xxxx-xxxx",
    "origin_server_ts": 1,
    "sender": "@someone:example.org",
    "type": "m.reaction",
    "unsigned": {
        "age": 85
    }
});

// The downside of this event is we cannot use it with event enums,
// but could be deserialized from a `Raw<_>` that has failed to deserialize.
matches::assert_matches!(
    serde_json::from_value::<SyncMessageEvent<ReactionEventContent>>(json),
    Ok(SyncMessageEvent {
        content: ReactionEventContent {
            relates_to: RelatesTo::Annotation { key, .. },
        },
        ..
    }) if key == "👍"
);

Serialization and deserialization

All concrete event types in ruma-events can be serialized via the Serialize trait from serde and can be deserialized from as Raw<EventType>. In order to handle incoming data that may not conform to ruma-events’ strict definitions of event structures, deserialization will return Raw::Err on error. This error covers both structurally invalid JSON data as well as structurally valid JSON that doesn’t fulfill additional constraints the matrix specification defines for some event types. The error exposes the deserialized serde_json::Value so that developers can still work with the received event data. This makes it possible to deserialize a collection of events without the entire collection failing to deserialize due to a single invalid event. The “content” type for each event also implements Serialize and either TryFromRaw (enabling usage as Raw<ContentType> for dedicated content types) or Deserialize (when the content is a type alias), allowing content to be converted to and from JSON independently of the surrounding event structure, if needed.

Modules

call	Modules for events in the m.call namespace.
custom	Types for custom events outside of the Matrix specification.
direct	Types for the m.direct event.
dummy	Types for the m.dummy event.
forwarded_room_key	Types for the m.forwarded_room_key event.
fully_read	Types for the m.fully_read event.
ignored_user_list	Types for the m.ignored_user_list event.
key	Modules for events in the m.key namespace.
macros	Re-export of all the derives needed to create your own event types.
pdu	Types for persistent data unit schemas
policy	Modules for events in the m.policy namespace.
presence	A presence event is represented by a struct with a set content field.
push_rules	Types for the m.push_rules event.
receipt	Types for the m.receipt event.
room	Modules for events in the m.room namespace.
room_key	Types for the m.room_key event.
room_key_request	Types for the m.room_key_request event.
sticker	Types for the m.sticker event.
tag	Types for the m.tag event.
typing	Types for the m.typing event.

Structs

EphemeralRoomEvent	An ephemeral room event.
FromStrError	An error when attempting to create a value from a string via the FromStr trait.
GlobalAccountDataEvent	A global account data event.
InitialStateEvent	A minimal state event, used for creating a new room.
InvalidInput	An error returned when attempting to create an event with data that would make it invalid.
MessageEvent	A message event.
RedactedMessageEvent	A redacted message event.
RedactedStateEvent	A redacted state event.
RedactedStrippedStateEvent	A stripped-down redacted state event.
RedactedSyncMessageEvent	A redacted message event without a room_id.
RedactedSyncStateEvent	A redacted state event without a room_id.
RedactedUnsigned	Extra information about a redacted event that is not incorporated into the event’s hash.
RoomAccountDataEvent	A room account data event.
StateEvent	A state event.
StrippedStateEvent	A stripped-down state event, used for previews of rooms the user has been invited to.
SyncEphemeralRoomEvent	An ephemeral room event without a room_id.
SyncMessageEvent	A message event without a room_id.
SyncStateEvent	A state event without a room_id.
ToDeviceEvent	An event sent using send-to-device messaging.
Unsigned	Extra information about an event that is not incorporated into the event’s hash.

Enums

AnyEphemeralRoomEvent	Any ephemeral room event.
AnyEphemeralRoomEventContent	Any ephemeral room event.
AnyGlobalAccountDataEvent	Any global account data event.
AnyGlobalAccountDataEventContent	Any global account data event.
AnyInitialStateEvent	Any state event.
AnyMessageEvent	Any message event.
AnyMessageEventContent	Any message event.
AnyPossiblyRedactedMessageEvent	An enum that holds either regular un-redacted events or redacted events.
AnyPossiblyRedactedStateEvent	An enum that holds either regular un-redacted events or redacted events.
AnyPossiblyRedactedStrippedStateEvent	An enum that holds either regular un-redacted events or redacted events.
AnyPossiblyRedactedSyncMessageEvent	An enum that holds either regular un-redacted events or redacted events.
AnyPossiblyRedactedSyncStateEvent	An enum that holds either regular un-redacted events or redacted events.
AnyRedactedMessageEvent	Any message event.
AnyRedactedMessageEventContent	Any message event.
AnyRedactedRoomEvent	Any redacted room event.
AnyRedactedStateEvent	Any state event.
AnyRedactedStateEventContent	Any state event.
AnyRedactedStrippedStateEvent	Any state event.
AnyRedactedSyncMessageEvent	Any message event.
AnyRedactedSyncRoomEvent	Any redacted sync room event (room event without a room_id, as returned in /sync responses)
AnyRedactedSyncStateEvent	Any state event.
AnyRoomAccountDataEvent	Any room account data event.
AnyRoomAccountDataEventContent	Any room account data event.
AnyRoomEvent	Any room event.
AnyStateEvent	Any state event.
AnyStateEventContent	Any state event.
AnyStrippedStateEvent	Any state event.
AnySyncEphemeralRoomEvent	Any ephemeral room event.
AnySyncMessageEvent	Any message event.
AnySyncRoomEvent	Any sync room event (room event without a room_id, as returned in /sync responses)
AnySyncStateEvent	Any state event.
AnyToDeviceEvent	Any to-device event.
AnyToDeviceEventContent	Any to-device event.
EphemeralRoomEventType	The type of EphemeralRoomEventType this is.
EventType	The type of EventType this is.
GlobalAccountDataEventType	The type of GlobalAccountDataEventType this is.
MessageEventType	The type of MessageEventType this is.
RoomAccountDataEventType	The type of RoomAccountDataEventType this is.
RoomEventType	The type of RoomEventType this is.
StateEventType	The type of StateEventType this is.
ToDeviceEventType	The type of ToDeviceEventType this is.

Traits

EphemeralRoomEventContent	Marker trait for the content of an ephemeral room event.
EventContent	The base trait that all event content types implement.
GlobalAccountDataEventContent	Marker trait for the content of a global account data event.
MessageEventContent	Marker trait for the content of a message event.
RawExt	Extension trait for Raw<_>.
Redact	Trait to define the behavior of redacting an event.
RedactContent	Trait to define the behavior of redact an event’s content object.
RedactedEventContent	The base trait that all redacted event content types implement.
RedactedMessageEventContent	Marker trait for the content of a redacted message event.
RedactedStateEventContent	Marker trait for the content of a redacted state event.
RoomAccountDataEventContent	Marker trait for the content of a room account data event.
StateEventContent	Marker trait for the content of a state event.
ToDeviceEventContent	Marker trait for the content of a to device event.