Crate ruma_events

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. This module contains Rust types for all of the event types defined by the specification and facilities for extending the event system for custom event types.

§Core event types

This module includes Rust types for all 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::RoomMessageEvent. 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 examples we will start with a simple custom state event. ruma_event specifies the state event’s type and its kind.

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

#[derive(Clone, Debug, Deserialize, Serialize, EventContent)]
#[ruma_event(type = "org.example.event", kind = State, state_key_type = String)]
pub struct ExampleContent {
    field: String,
}

This can be used with events structs, such as passing it into ruma::api::client::state::send_state_event’s Request.

As a more advanced example we create a reaction message event. For this event we will use a OriginalSyncMessageLikeEvent struct but any OriginalMessageLikeEvent struct would work.

use ruma_common::OwnedEventId;
use ruma_events::{macros::EventContent, OriginalSyncMessageLikeEvent};
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: OwnedEventId,
        /// 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 = MessageLike)]
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.
assert!(matches!(
    serde_json::from_value::<OriginalSyncMessageLikeEvent<ReactionEventContent>>(json),
    Ok(OriginalSyncMessageLikeEvent {
        content: ReactionEventContent {
            relates_to: RelatesTo::Annotation { key, .. },
        },
        ..
    }) if key == "👍"
));

Re-exports§

pub use self::relation::BundledMessageLikeRelations;
pub use self::relation::BundledStateRelations;

Modules§

audio: Types for extensible audio message events (MSC3927).
beacon: Types for the org.matrix.msc3489.beacon event, the unstable version of m.beacon (MSC3489).
beacon_info: Types for the org.matrix.msc3489.beacon_info state event, the unstable version of m.beacon_info (MSC3489).
call: Modules for events in the m.call namespace.
direct: Types for the m.direct event.
do_not_disturb: Types for the dm.filament.do_not_disturb event.
dummy: Types for the m.dummy event.
emote: Types for extensible emote message events (MSC3954).
encrypted: Types for extensible encrypted events (MSC3956).
file: Types for extensible file message events (MSC3551).
forwarded_room_key: Types for the m.forwarded_room_key event.
fully_read: Types for the m.fully_read event.
identity_server: Types for the m.identity_server event.
ignored_user_list: Types for the m.ignored_user_list event.
image: Types for extensible image message events (MSC3552).
image_pack: Types for image packs in Matrix (MSC2545).
key: Modules for events in the m.key namespace.
location: Types for extensible location message events (MSC3488).
macros: Re-export of all the derives needed to create your own event types.
marked_unread: Types for the m.marked_unread event.
media_preview_config: Types for the m.media_preview_config event.
member_hints: Types for Matrix member hint state events (MSC4171).
message: Types for extensible text message events (MSC1767).
policy: Modules for events in the m.policy namespace.
poll: Modules for events in the m.poll namespace (MSC3381).
presence: A presence event is represented by a struct with a set content field.
push_rules: Types for the m.push_rules event.
reaction: Types for the m.reaction event.
receipt: Types for the m.receipt event.
relation: Types describing relationships between events.
room: Modules for events in the m.room namespace.
room_key: Types for the m.room_key event.
room_key_bundle: Types for the m.room_key_bundle event defined in MSC4268.
room_key_request: Types for the m.room_key_request event.
rtc: Modules for events in the m.rtc namespace.
secret: Module for events in the m.secret namespace.
secret_storage: Module for events in the m.secret_storage namespace.
space: Types for the m.space events.
space_order: Types for the m.space_order event.
sticker: Types for the m.sticker event.
tag: Types for the m.tag event.
typing: Types for the m.typing event.
video: Types for extensible video message events (MSC3553).
voice: Types for voice message events (MSC3245).

Structs§

DecryptedMegolmV1Event: The decrypted payload of an m.megolm.v1.aes-sha2 event.
DecryptedOlmV1Event: The decrypted payload of an m.olm.v1.curve25519-aes-sha2 event.
EmptyStateKey: A type that can be used as the state_key for event types where that field is always empty.
EphemeralRoomEvent: An ephemeral room event.
False: The equivalent of the false boolean.
GlobalAccountDataEvent: A global account data event.
InitialStateEvent: A minimal state event, used for creating a new room.
Mentions: Describes whether the event mentions other users or the room.
MessageLikeUnsigned: Extra information about a message event that is not incorporated into the event’s hash.
OlmV1Keys: Public keys used for an m.olm.v1.curve25519-aes-sha2 event.
OriginalMessageLikeEvent: An unredacted message-like event.
OriginalStateEvent: An unredacted state event.
OriginalSyncMessageLikeEvent: An unredacted message-like event without a room_id.
OriginalSyncStateEvent: An unredacted state event without a room_id.
RedactedMessageLikeEvent: A redacted message-like event.
RedactedStateEvent: A redacted state event.
RedactedSyncMessageLikeEvent: A redacted message-like 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.
StateUnsigned: Extra information about a state event that is not incorporated into the event’s hash.
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.
ToDeviceEvent: An event sent using send-to-device messaging.
True: The equivalent of the true boolean.
UnsignedRoomRedactionEvent: A redaction event as found in unsigned.redacted_because.

Enums§

AnyEphemeralRoomEventContent: Any ephemeral room event.
AnyFullStateEventContent: Any state event.
AnyGlobalAccountDataEvent: Any global account data event.
AnyGlobalAccountDataEventContent: Any global account data event.
AnyInitialStateEvent: Any state event.
AnyMessageLikeEvent: Any message-like event.
AnyMessageLikeEventContent: Any message-like event.
AnyRoomAccountDataEvent: Any room account data event.
AnyRoomAccountDataEventContent: Any room account data event.
AnyStateEvent: Any state event.
AnyStateEventContent: Any state event.
AnyStrippedStateEvent: Any state event.
AnySyncEphemeralRoomEvent: Any ephemeral room event.
AnySyncMessageLikeEvent: Any message-like event.
AnySyncStateEvent: Any state event.
AnySyncTimelineEvent: Any sync room event.
AnyTimelineEvent: Any room event.
AnyToDeviceEvent: Any to-device event.
AnyToDeviceEventContent: Any to-device event.
EphemeralRoomEventType: The type of EphemeralRoomEvent this is.
FullStateEventContent: A possibly-redacted state event content.
GlobalAccountDataEventType: The type of GlobalAccountDataEvent this is.
MessageLikeEvent: A possibly-redacted message-like event.
MessageLikeEventType: The type of MessageLikeEvent this is.
RoomAccountDataEventType: The type of RoomAccountDataEvent this is.
StateEvent: A possibly-redacted state event.
StateEventType: The type of StateEvent this is.
SyncMessageLikeEvent: A possibly-redacted message-like event without a room_id.
SyncStateEvent: A possibly-redacted state event without a room_id.
TimelineEventType: The type of TimelineEvent this is.
ToDeviceEventType: The type of ToDeviceEvent this is.

Constants§

RECOMMENDED_STRIPPED_STATE_EVENT_TYPES: Event types that servers should send as stripped state to help clients identify a room when they can’t access the full room state.

Traits§

BooleanType: A trait for types representing a boolean value.
EphemeralRoomEventContent: Content of an ephemeral room event.
EventContentFromType: Event content that can be deserialized with its event type.
GlobalAccountDataEventContent: Content of a global account-data event.
MessageLikeEventContent: Content of a non-redacted message-like event.
PossiblyRedactedStateEventContent: Content of a state event.
RawExt: Extension trait for Raw<T>.
RedactContent: Trait to define the behavior of redact an event’s content object.
RedactedMessageLikeEventContent: Content of a redacted message-like event.
RedactedStateEventContent: Content of a redacted state event.
RoomAccountDataEventContent: Content of a room-specific account-data event.
StateEventContent: Content of a non-redacted state event.
StaticEventContent: An event content type with a statically-known event type value.
StaticStateEventContent: Content of a non-redacted state event with a corresponding possibly-redacted type.
ToDeviceEventContent: Content of a to-device event.