Crate ruma::events[][src]

This is supported on crate feature events only.
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.

Modules

Modules for events in the m.call namespace.

Types for custom events outside of the Matrix specification.

Types for the m.direct event.

Types for the m.dummy event.

Types for the m.forwarded_room_key event.

Types for the m.fully_read event.

Types for the m.ignored_user_list event.

Modules for events in the m.key namespace.

Re-export of all the derives needed to create your own event types.

Types for persistent data unit schemas

Modules for events in the m.policy namespace.

A presence event is represented by a struct with a set content field.

Types for the m.push_rules event.

Types for the m.reaction event.

Types for the m.receipt event.

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

Modules for events in the m.room namespace.

Types for the m.room_key event.

Types for the m.room_key_request event.

Module for events in the m.secret namespace.

Types for the m.space events.

Types for the m.sticker event.

Types for the m.tag event.

Types for the m.typing event.

Structs

The decrypted payload of an m.megolm.v1.aes-sha2 event.

The decrypted payload of an m.olm.v1.curve25519-aes-sha2 event.

An ephemeral room event.

A global account data event.

A minimal state event, used for creating a new room.

A message event.

Public keys used for an m.olm.v1.curve25519-aes-sha2 event.

A redacted message event.

A redacted state event.

A redacted message event without a room_id.

A redacted state event without a room_id.

Extra information about a redacted event that is not incorporated into the event’s hash.

Precompiled list of relations to this event grouped by relation type.

A room account data event.

A state event.

A stripped-down state event, used for previews of rooms the user has been invited to.

An ephemeral room event without a room_id.

A message event without a room_id.

A state event without a room_id.

An event sent using send-to-device messaging.

Extra information about an event that is not incorporated into the event’s hash.

Enums

Any ephemeral room event.

Any ephemeral room event.

Any global account data event.

Any global account data event.

Any state event.

Any message event.

Any message event.

An enum that holds either regular un-redacted events or redacted events.

An enum that holds either regular un-redacted events or redacted events.

An enum that holds either regular un-redacted events or redacted events.

An enum that holds either regular un-redacted events or redacted events.

Any message event.

Any message event.

Any redacted room event.

Any state event.

Any state event.

Any message event.

Any redacted sync room event (room event without a room_id, as returned in /sync responses)

Any state event.

Any room account data event.

Any room account data event.

Any room event.

Any state event.

Any state event.

Any state event.

Any ephemeral room event.

Any message event.

Any sync room event (room event without a room_id, as returned in /sync responses)

Any state event.

Any to-device event.

Any to-device event.

The type of EphemeralRoomEventType this is.

The “kind” of an event.

The type of EventType this is.

The type of GlobalAccountDataEventType this is.

The type of MessageEventType this is.

The type of RoomAccountDataEventType this is.

The type of RoomEventType this is.

The type of StateEventType this is.

The type of ToDeviceEventType this is.

Traits

Marker trait for the content of an ephemeral room event.

The base trait that all event content types implement.

Marker trait for the content of a global account data event.

Marker trait for the content of a message event.

Extension trait for Raw<_>.

Trait to define the behavior of redacting an event.

Trait to define the behavior of redact an event’s content object.

The base trait that all redacted event content types implement.

Marker trait for the content of a redacted message event.

Marker trait for the content of a redacted state event.

Marker trait for the content of a room account data event.

Marker trait for the content of a state event.

Trait for abstracting over event content structs.

Marker trait for the content of a to device event.