Crate ruma_events[][src]

Expand description

(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.

Re-exports

pub use self::relation::Relations;

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.

reactionunstable-pre-spec

Types for the m.reaction event.

receipt

Types for the m.receipt event.

relationunstable-pre-spec

Types describing event relations after MSC 2674, 2675, 2676, 2677.

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.

spaceunstable-pre-spec

Types for the m.space events.

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.