ruma_events/
file.rs

Help
1//! Types for extensible file message events ([MSC3551]).
2//!
3//! [MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551
4
5use std::collections::BTreeMap;
6
7use js_int::UInt;
8use ruma_common::{serde::Base64, OwnedMxcUri};
9use ruma_macros::EventContent;
10use serde::{Deserialize, Serialize};
11
12use super::{
13    message::TextContentBlock,
14    room::{message::Relation, EncryptedFile, JsonWebKey},
15};
16
17/// The payload for an extensible file message.
18///
19/// This is the new primary type introduced in [MSC3551] and should only be sent in rooms with a
20/// version that supports it. See the documentation of the [`message`] module for more information.
21///
22/// [MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551
23/// [`message`]: super::message
24#[derive(Clone, Debug, Serialize, Deserialize, EventContent)]
25#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
26#[ruma_event(type = "org.matrix.msc1767.file", kind = MessageLike, without_relation)]
27pub struct FileEventContent {
28    /// The text representation of the message.
29    #[serde(rename = "org.matrix.msc1767.text")]
30    pub text: TextContentBlock,
31
32    /// The file content of the message.
33    #[serde(rename = "org.matrix.msc1767.file")]
34    pub file: FileContentBlock,
35
36    /// The caption of the message, if any.
37    #[serde(rename = "org.matrix.msc1767.caption", skip_serializing_if = "Option::is_none")]
38    pub caption: Option<CaptionContentBlock>,
39
40    /// Whether this message is automated.
41    #[cfg(feature = "unstable-msc3955")]
42    #[serde(
43        default,
44        skip_serializing_if = "ruma_common::serde::is_default",
45        rename = "org.matrix.msc1767.automated"
46    )]
47    pub automated: bool,
48
49    /// Information about related messages.
50    #[serde(
51        flatten,
52        skip_serializing_if = "Option::is_none",
53        deserialize_with = "crate::room::message::relation_serde::deserialize_relation"
54    )]
55    pub relates_to: Option<Relation<FileEventContentWithoutRelation>>,
56}
57
58impl FileEventContent {
59    /// Creates a new non-encrypted `FileEventContent` with the given fallback representation, url
60    /// and file info.
61    pub fn plain(text: TextContentBlock, url: OwnedMxcUri, name: String) -> Self {
62        Self {
63            text,
64            file: FileContentBlock::plain(url, name),
65            caption: None,
66            #[cfg(feature = "unstable-msc3955")]
67            automated: false,
68            relates_to: None,
69        }
70    }
71
72    /// Creates a new non-encrypted `FileEventContent` with the given plain text fallback
73    /// representation, url and name.
74    pub fn plain_with_plain_text(
75        plain_text: impl Into<String>,
76        url: OwnedMxcUri,
77        name: String,
78    ) -> Self {
79        Self {
80            text: TextContentBlock::plain(plain_text),
81            file: FileContentBlock::plain(url, name),
82            caption: None,
83            #[cfg(feature = "unstable-msc3955")]
84            automated: false,
85            relates_to: None,
86        }
87    }
88
89    /// Creates a new encrypted `FileEventContent` with the given fallback representation, url,
90    /// name and encryption info.
91    pub fn encrypted(
92        text: TextContentBlock,
93        url: OwnedMxcUri,
94        name: String,
95        encryption_info: EncryptedContent,
96    ) -> Self {
97        Self {
98            text,
99            file: FileContentBlock::encrypted(url, name, encryption_info),
100            caption: None,
101            #[cfg(feature = "unstable-msc3955")]
102            automated: false,
103            relates_to: None,
104        }
105    }
106
107    /// Creates a new encrypted `FileEventContent` with the given plain text fallback
108    /// representation, url, name and encryption info.
109    pub fn encrypted_with_plain_text(
110        plain_text: impl Into<String>,
111        url: OwnedMxcUri,
112        name: String,
113        encryption_info: EncryptedContent,
114    ) -> Self {
115        Self {
116            text: TextContentBlock::plain(plain_text),
117            file: FileContentBlock::encrypted(url, name, encryption_info),
118            caption: None,
119            #[cfg(feature = "unstable-msc3955")]
120            automated: false,
121            relates_to: None,
122        }
123    }
124}
125
126/// A block for file content.
127#[derive(Clone, Debug, Serialize, Deserialize)]
128#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
129pub struct FileContentBlock {
130    /// The URL to the file.
131    pub url: OwnedMxcUri,
132
133    /// The original filename of the uploaded file.
134    pub name: String,
135
136    /// The mimetype of the file, e.g. "application/msword".
137    #[serde(skip_serializing_if = "Option::is_none")]
138    pub mimetype: Option<String>,
139
140    /// The size of the file in bytes.
141    #[serde(skip_serializing_if = "Option::is_none")]
142    pub size: Option<UInt>,
143
144    /// Information on the encrypted file.
145    ///
146    /// Required if the file is encrypted.
147    #[serde(flatten, skip_serializing_if = "Option::is_none")]
148    pub encryption_info: Option<Box<EncryptedContent>>,
149}
150
151impl FileContentBlock {
152    /// Creates a new non-encrypted `FileContentBlock` with the given url and name.
153    pub fn plain(url: OwnedMxcUri, name: String) -> Self {
154        Self { url, name, mimetype: None, size: None, encryption_info: None }
155    }
156
157    /// Creates a new encrypted `FileContentBlock` with the given url, name and encryption info.
158    pub fn encrypted(url: OwnedMxcUri, name: String, encryption_info: EncryptedContent) -> Self {
159        Self {
160            url,
161            name,
162            mimetype: None,
163            size: None,
164            encryption_info: Some(Box::new(encryption_info)),
165        }
166    }
167
168    /// Whether the file is encrypted.
169    pub fn is_encrypted(&self) -> bool {
170        self.encryption_info.is_some()
171    }
172}
173
174/// The encryption info of a file sent to a room with end-to-end encryption enabled.
175///
176/// To create an instance of this type, first create a `EncryptedContentInit` and convert it via
177/// `EncryptedContent::from` / `.into()`.
178#[derive(Clone, Debug, Deserialize, Serialize)]
179#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
180pub struct EncryptedContent {
181    /// A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object.
182    pub key: JsonWebKey,
183
184    /// The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64.
185    pub iv: Base64,
186
187    /// A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64.
188    ///
189    /// Clients should support the SHA-256 hash, which uses the key sha256.
190    pub hashes: BTreeMap<String, Base64>,
191
192    /// Version of the encrypted attachments protocol.
193    ///
194    /// Must be `v2`.
195    pub v: String,
196}
197
198/// Initial set of fields of `EncryptedContent`.
199///
200/// This struct will not be updated even if additional fields are added to `EncryptedContent` in a
201/// new (non-breaking) release of the Matrix specification.
202#[derive(Debug)]
203#[allow(clippy::exhaustive_structs)]
204pub struct EncryptedContentInit {
205    /// A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object.
206    pub key: JsonWebKey,
207
208    /// The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64.
209    pub iv: Base64,
210
211    /// A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64.
212    ///
213    /// Clients should support the SHA-256 hash, which uses the key sha256.
214    pub hashes: BTreeMap<String, Base64>,
215
216    /// Version of the encrypted attachments protocol.
217    ///
218    /// Must be `v2`.
219    pub v: String,
220}
221
222impl From<EncryptedContentInit> for EncryptedContent {
223    fn from(init: EncryptedContentInit) -> Self {
224        let EncryptedContentInit { key, iv, hashes, v } = init;
225        Self { key, iv, hashes, v }
226    }
227}
228
229impl From<&EncryptedFile> for EncryptedContent {
230    fn from(encrypted: &EncryptedFile) -> Self {
231        let EncryptedFile { key, iv, hashes, v, .. } = encrypted;
232        Self { key: key.to_owned(), iv: iv.to_owned(), hashes: hashes.to_owned(), v: v.to_owned() }
233    }
234}
235
236/// A block for caption content.
237///
238/// A caption is usually a text message that should be displayed next to some media content.
239///
240/// To construct a `CaptionContentBlock` with a custom [`TextContentBlock`], convert it with
241/// `CaptionContentBlock::from()` / `.into()`.
242#[derive(Clone, Debug, Serialize, Deserialize)]
243#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
244pub struct CaptionContentBlock {
245    /// The text message of the caption.
246    #[serde(rename = "org.matrix.msc1767.text")]
247    pub text: TextContentBlock,
248}
249
250impl CaptionContentBlock {
251    /// A convenience constructor to create a plain text caption content block.
252    pub fn plain(body: impl Into<String>) -> Self {
253        Self { text: TextContentBlock::plain(body) }
254    }
255
256    /// A convenience constructor to create an HTML caption content block.
257    pub fn html(body: impl Into<String>, html_body: impl Into<String>) -> Self {
258        Self { text: TextContentBlock::html(body, html_body) }
259    }
260
261    /// A convenience constructor to create a caption content block from Markdown.
262    ///
263    /// The content includes an HTML message if some Markdown formatting was detected, otherwise
264    /// only a plain text message is included.
265    #[cfg(feature = "markdown")]
266    pub fn markdown(body: impl AsRef<str> + Into<String>) -> Self {
267        Self { text: TextContentBlock::markdown(body) }
268    }
269}
270
271impl From<TextContentBlock> for CaptionContentBlock {
272    fn from(text: TextContentBlock) -> Self {
273        Self { text }
274    }
275}
ruma_events/file.rs

ruma_events/
file.rs
