[−][src]Crate ruma_events
Crate ruma_events
contains serializable types for the events in the Matrix
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, 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 kinds
Matrix defines three "kinds" of events:
- Events, which are arbitrary JSON structures that have two required keys:
type
, which specifies the event's typecontent
, which is a JSON object containing the "payload" of the event
- 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 eventroom_id
, which is a unique identifier for the room in which the event occurredsender
, 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.
- 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 aBTreeMap
where the keys are the tuple(event_type, state_key)
.- Optionally,
prev_content
, a JSON object containing thecontent
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.
Custom event types
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 covered 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.
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 indepedently of the surrounding
event structure, if needed.
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
.
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. |
pdu | Types for persistent data unit schemas |
presence | A presence event is represented by a struct with a set content field. |
push_rules | Types for the 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
BasicEvent | A basic event – one that consists only of it's type and the |
EphemeralRoomEvent | Ephemeral room event. |
FromStrError | An error when attempting to create a value from a string via the |
InvalidInput | An error returned when attempting to create an event with data that would make it invalid. |
MessageEvent | 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 |
RedactedSyncStateEvent | A redacted state event without a |
RedactedSyncUnsigned | Extra information about a redacted sync event that is not incorporated into the sync event's hash. |
RedactedUnsigned | Extra information about a redacted event that is not incorporated into the event's hash. |
StateEvent | 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 |
SyncMessageEvent | A message event without a |
SyncStateEvent | A state event without a |
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
Algorithm | An encryption algorithm to be used to encrypt messages sent to a room. |
AnyBasicEvent | Any basic event. |
AnyBasicEventContent | Any basic event. |
AnyEphemeralRoomEvent | Any ephemeral room event. |
AnyEphemeralRoomEventContent | Any ephemeral room event. |
AnyEvent | Any 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. |
AnyRedactedStateEvent | Any state event. |
AnyRedactedStrippedStateEvent | Any state event. |
AnyRedactedSyncMessageEvent | Any message event. |
AnyRedactedSyncStateEvent | Any state 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 |
AnySyncStateEvent | Any state event. |
AnyToDeviceEvent | Any to-device event. |
AnyToDeviceEventContent | Any to-device event. |
EventType | The type of an event. |
Traits
BasicEventContent | Marker trait for the content of a basic event. |
EphemeralRoomEventContent | Marker trait for the content of an ephemeral room event. |
EventContent | The base trait that all event content types implement. |
MessageEventContent | Marker trait for the content of a message event. |
RawExt | Extension trait for Raw |
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. |
RoomEventContent | Marker trait for the content of a room event. |
StateEventContent | Marker trait for the content of a state event. |