[][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:

  1. 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
  2. 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
    • Optionally, unsigned, which is a JSON object containing arbitrary additional metadata that is not digitally signed by Matrix homeservers.
  3. 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 HashMap where the keys are the tuple (event_type, state_key).
    • Optionally, prev_content, a JSON object containing the content 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 EventResult<EventType>. In order to handle incoming data that may not conform to ruma-events' strict definitions of event structures, deserialization will return EventResult::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 EventResult<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.

collections

Enums for heterogeneous collections of events.

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.

presence

Types for the m.presence event.

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.

stripped

"Stripped-down" versions of the core state events.

tag

Types for the m.tag event.

typing

Types for the m.typing event.

Structs

CustomEvent

A custom basic event not covered by the Matrix specification.

CustomRoomEvent

A custom room event not covered by the Matrix specification.

CustomStateEvent

A custom state event not covered by the Matrix specification.

Empty

A meaningless value that serializes to an empty JSON object.

FromStrError

An error when attempting to create a value from a string via the FromStr trait.

InvalidEvent

An event that is malformed or otherwise invalid.

InvalidInput

An error returned when attempting to create an event with data that would make it invalid.

Enums

Algorithm

An encryption algorithm to be used to encrypt messages sent to a room.

EventResult

The result of deserializing an event, which may or may not be valid.

EventType

The type of an event.

Traits

Event

A basic event.

FromRaw

See TryFromRaw. This trait is merely a convenience that is be implemented instead of TryFromRaw to get a TryFromRaw implementation with slightly less code if the conversion can't fail, that is, the raw type and Self are identical in definition.

RoomEvent

An event within the context of a room.

StateEvent

An event that describes persistent state about a room.

TryFromRaw

Types corresponding to some item in the matrix spec. Types that implement this trait have a corresponding 'raw' type, a potentially invalid representation that can be converted to Self.