ruma_events

Module message

Source
Expand description

Types for extensible text message events (MSC1767).

§Extensible events

MSC1767 defines a new structure for events that is made of two parts: a type and zero or more reusable content blocks.

This allows to construct new event types from a list of known content blocks that allows in turn clients to be able to render unknown event types by using the known content blocks as a fallback. When a new type is defined, all the content blocks it can or must contain are defined too.

There are also some content blocks called “mixins” that can apply to any event when they are defined.

§MSCs

This is a list of MSCs defining the extensible events and deprecating the corresponding legacy types. Note that “primary type” means the type field at the root of the event and “message type” means the msgtype field in the content of the m.room.message primary type.

  • MSC1767: Text messages, where the m.message primary type replaces the m.text message type.
  • MSC3954: Emotes, where the m.emote primary type replaces the m.emote message type.
  • MSC3955: Automated events, where the m.automated mixin replaces the m.notice message type.
  • MSC3956: Encrypted events, where the m.encrypted primary type replaces the m.room.encrypted primary type.
  • MSC3551: Files, where the m.file primary type replaces the m.file message type.
  • MSC3552: Images and Stickers, where the m.image primary type replaces the m.image message type and the m.sticker primary type.
  • MSC3553: Videos, where the m.video primary type replaces the m.video message type.
  • MSC3927: Audio, where the m.audio primary type replaces the m.audio message type.
  • MSC3488: Location, where the m.location primary type replaces the m.location message type.

There are also the following MSCs that introduce new features with extensible events:

§How to use them in Matrix

The extensible events types are meant to be used separately than the legacy types. As such, their use is reserved for room versions that support it.

Currently no stable room version supports extensible events so they can only be sent with unstable room versions that support them.

An exception is made for some new extensible events types that don’t have a legacy type. They can be used with stable room versions without support for extensible types, but they might be ignored by clients that have no support for extensible events. The types that support this must advertise it in their MSC.

Note that if a room version supports extensible events, it doesn’t support the legacy types anymore and those should be ignored. There is not yet a definition of the deprecated legacy types in extensible events rooms.

§How to use them in Ruma

First, you can enable the unstable-extensible-events feature from the ruma crate, that will enable all the MSCs for the extensible events that correspond to the legacy types. It is also possible to enable only the MSCs you want with the unstable-mscXXXX features (where XXXX is the number of the MSC). When enabling an MSC, all MSC dependencies are enabled at the same time to avoid issues.

Currently the extensible events use the unstable prefixes as defined in the corresponding MSCs.

Structs§

Type Aliases§