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.
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
Matrix defines three "kinds" of events:
- Events, which are arbitrary JSON structures that have two required keys:
type, which specifies the event's type
content, 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 event
room_id, which is a unique identifier for the room in which the event occurred
sender, which is the unique identifier of the Matrix user who created the event
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 a
HashMapwhere the keys are the tuple
prev_content, a JSON object containing the
contentobject 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.
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
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.
All concrete event types in ruma_events are serializable and deserializable using the
Serde serialization library.
Although any Rust type that implements
StateEvent can serve as a
Matrix event type, ruma_events also includes a few convenience types for representing events
that are not convered by the spec and not otherwise known by the application.
CustomStateEvent are simple implementations of their
respective event traits whose
content field is simply a
serde_json::Value value, which
represents arbitrary JSON.
With the trait-based approach to events, it's easy to write generic collection types like
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,
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
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.
ruma_events::collections::only::Event enum does not include m.room.message,
because m.room.message implements a more specific event trait than
Modules for events in the m.call namespace.
Enums for heterogeneous collections of events.
Types for the m.direct event.
Types for the m.presence event.
Types for the m.receipt event.
Modules for events in the m.room namespace.
"Stripped-down" versions of the core state events.
Types for the m.tag event.
Types for the m.typing event.
A custom basic event not covered by the Matrix specification.
A custom room event not covered by the Matrix specification.
A custom state event not covered by the Matrix specification.
An error when attempting to convert a string to an enum that only accepts certain values.
The type of an event.
A basic event.
An event within the context of a room.
An event that describes persistent state about a room.