//! Types for extensible text message events ([MSC1767]). //! //! # Extensible events //! //! MSCs [1767] (Text, Emote and Notice), [3551] (Files), [3552] (Images and Stickers), [3553] //! (Videos), [3246] (Audio), and [3488] (Location) introduce new primary types called extensible //! events. These types are meant to replace the `m.room.message` primary type and its `msgtype`s. //! Other MSCs introduce new types with an `m.room.message` fallback, like [MSC3245] (Voice //! Messages), and types that only have an extensible events format, like [MSC3381] (Polls). //! //! # Transition Period //! //! MSC1767 defines a transition period that will start after the extensible events are released in //! a Matrix version. It should last approximately one year, but the end of that period will be //! formalized in a new Matrix version. //! //! The new primary types should not be sent over the Matrix network before the end of the //! transition period. Instead, transitional `m.room.message` events should be sent. These //! transitional events include the content of the now legacy `m.room.message` event and the content //! of the new extensible event types in a single event. //! //! # How to use them //! //! First, enable the `unstable-mscXXXX` features (where `XXXX` is the number of the MSC) for the //! needed extensible types. //! //! The recommended way to send transitional extensible events while they are unstable and during //! the transition period is to build one of the new primary types and then to convert it to a //! [`RoomMessageEventContent`] by using `.into()` or `RoomMessageEventContent::from()`. The //! provided constructors will copy the relevant data in the legacy fields. //! //! For incoming events, a `RoomMessageEventContent` can be converted to an extensible event with //! the relevant `from_*_room_message` method on the primary type. This conversion will work even //! with legacy `m.room.message` events that don't have extensible events content. //! //! It is also possible to enable extensible events support and continue using //! `RoomMessageEventContent`'s constructors. The data will be duplicated in both the legacy and //! extensible events fields. //! //! [MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 //! [1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 //! [3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551 //! [3552]: https://github.com/matrix-org/matrix-spec-proposals/pull/3552 //! [3553]: https://github.com/matrix-org/matrix-spec-proposals/pull/3553 //! [3246]: https://github.com/matrix-org/matrix-spec-proposals/pull/3246 //! [3488]: https://github.com/matrix-org/matrix-spec-proposals/pull/3488 //! [MSC3245]: https://github.com/matrix-org/matrix-spec-proposals/pull/3245 //! [MSC3381]: https://github.com/matrix-org/matrix-spec-proposals/pull/3381 //! [`RoomMessageEventContent`]: super::room::message::RoomMessageEventContent use ruma_macros::EventContent; use serde::{Deserialize, Serialize}; mod content_serde; use content_serde::MessageContentSerDeHelper; use super::room::message::{FormattedBody, MessageFormat, Relation, TextMessageEventContent}; /// The payload for an extensible text message. /// /// This is the new primary type introduced in [MSC1767] and should not be sent before the end of /// the transition period. See the documentation of the [`message`] module for more information. /// /// `MessageEventContent` can be converted to a [`RoomMessageEventContent`] with a /// [`MessageType::Text`]. You can convert it back with /// [`MessageEventContent::from_text_room_message()`]. /// /// [MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 /// [`message`]: super::message /// [`RoomMessageEventContent`]: super::room::message::RoomMessageEventContent /// [`MessageType::Text`]: super::room::message::MessageType::Text #[derive(Clone, Debug, Serialize, Deserialize, EventContent)] #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)] #[ruma_event(type = "m.message", kind = MessageLike)] pub struct MessageEventContent { /// The message's text content. #[serde(flatten)] pub message: MessageContent, /// Information about related messages for [rich replies]. /// /// [rich replies]: https://spec.matrix.org/v1.2/client-server-api/#rich-replies #[serde(flatten, skip_serializing_if = "Option::is_none")] pub relates_to: Option, } impl MessageEventContent { /// A convenience constructor to create a plain text message. pub fn plain(body: impl Into) -> Self { Self { message: MessageContent::plain(body), relates_to: None } } /// A convenience constructor to create an HTML message. pub fn html(body: impl Into, html_body: impl Into) -> Self { Self { message: MessageContent::html(body, html_body), relates_to: None } } /// A convenience constructor to create a Markdown message. /// /// Returns an HTML message if some Markdown formatting was detected, otherwise returns a plain /// text message. #[cfg(feature = "markdown")] pub fn markdown(body: impl AsRef + Into) -> Self { Self { message: MessageContent::markdown(body), relates_to: None } } /// Create a new `MessageEventContent` from the given `TextMessageEventContent` and optional /// relation. pub fn from_text_room_message( content: TextMessageEventContent, relates_to: Option, ) -> Self { let TextMessageEventContent { body, formatted, message, .. } = content; if let Some(message) = message { Self { message, relates_to } } else { Self { message: MessageContent::from_room_message_content(body, formatted), relates_to } } } } /// Text message content. #[derive(Clone, Debug, Deserialize)] #[serde(try_from = "MessageContentSerDeHelper")] pub struct MessageContent(pub(crate) Vec); impl MessageContent { /// A convenience constructor to create a plain text message. pub fn plain(body: impl Into) -> Self { Self(vec![Text::plain(body)]) } /// A convenience constructor to create an HTML message. pub fn html(body: impl Into, html_body: impl Into) -> Self { Self(vec![Text::html(html_body), Text::plain(body)]) } /// A convenience constructor to create a Markdown message. /// /// Returns an HTML message if some Markdown formatting was detected, otherwise returns a plain /// text message. #[cfg(feature = "markdown")] pub fn markdown(body: impl AsRef + Into) -> Self { let mut message = Vec::with_capacity(2); if let Some(html_body) = Text::markdown(&body) { message.push(html_body); } message.push(Text::plain(body)); Self(message) } /// Create a new `MessageContent` from the given body and optional formatted body. pub fn from_room_message_content(body: String, formatted: Option) -> Self { if let Some(FormattedBody { body: html_body, .. }) = formatted.filter(|formatted| formatted.format == MessageFormat::Html) { Self::html(body, html_body) } else { Self::plain(body) } } /// Get the plain text representation of this message. pub fn find_plain(&self) -> Option<&str> { self.variants() .iter() .find(|content| content.mimetype == "text/plain") .map(|content| content.body.as_ref()) } /// Get the HTML representation of this message. pub fn find_html(&self) -> Option<&str> { self.variants() .iter() .find(|content| content.mimetype == "text/html") .map(|content| content.body.as_ref()) } /// Get all the text representations of this message. pub fn variants(&self) -> &[Text] { &self.0 } } impl From> for MessageContent { fn from(variants: Vec) -> Self { Self(variants) } } /// Text message content. #[derive(Clone, Debug, Serialize, Deserialize)] #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)] pub struct Text { /// The mime type of the `body`. #[serde(default = "Text::default_mimetype")] pub mimetype: String, /// The text content. pub body: String, /// The language of the text. /// /// This must be a valid language code according to [BCP 47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt). #[cfg(feature = "unstable-msc3554")] #[serde(skip_serializing_if = "Option::is_none")] pub lang: Option, } impl Text { /// Creates a new plain text message body. pub fn plain(body: impl Into) -> Self { Self { mimetype: "text/plain".to_owned(), body: body.into(), #[cfg(feature = "unstable-msc3554")] lang: None, } } /// Creates a new HTML-formatted message body. pub fn html(body: impl Into) -> Self { Self { mimetype: "text/html".to_owned(), body: body.into(), #[cfg(feature = "unstable-msc3554")] lang: None, } } /// Creates a new HTML-formatted message body by parsing the Markdown in `body`. /// /// Returns `None` if no Markdown formatting was found. #[cfg(feature = "markdown")] pub fn markdown(body: impl AsRef) -> Option { let body = body.as_ref(); let mut html_body = String::new(); pulldown_cmark::html::push_html(&mut html_body, pulldown_cmark::Parser::new(body)); (html_body != format!("

{}

\n", body)).then(|| Self::html(html_body)) } fn default_mimetype() -> String { "text/plain".to_owned() } }