matrix_sdk/
media.rs

1// Copyright 2021 Kévin Commaille
2// Copyright 2022 The Matrix.org Foundation C.I.C.
3//
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at
7//
8//     http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15
16//! High-level media API.
17
18#[cfg(feature = "e2e-encryption")]
19use std::io::Read;
20use std::time::Duration;
21#[cfg(not(target_family = "wasm"))]
22use std::{fmt, fs::File, path::Path};
23
24use eyeball::SharedObservable;
25use futures_util::future::try_join;
26use matrix_sdk_base::media::store::IgnoreMediaRetentionPolicy;
27pub use matrix_sdk_base::media::{store::MediaRetentionPolicy, *};
28use mime::Mime;
29use ruma::{
30    MilliSecondsSinceUnixEpoch, MxcUri, OwnedMxcUri, TransactionId, UInt,
31    api::{
32        OutgoingRequest,
33        client::{authenticated_media, error::ErrorKind, media},
34    },
35    assign,
36    events::room::{MediaSource, ThumbnailInfo},
37};
38#[cfg(not(target_family = "wasm"))]
39use tempfile::{Builder as TempFileBuilder, NamedTempFile, TempDir};
40#[cfg(not(target_family = "wasm"))]
41use tokio::{fs::File as TokioFile, io::AsyncWriteExt};
42
43use crate::{
44    Client, Error, Result, TransmissionProgress, attachment::Thumbnail,
45    client::futures::SendMediaUploadRequest, config::RequestConfig,
46};
47
48/// A conservative upload speed of 1Mbps
49const DEFAULT_UPLOAD_SPEED: u64 = 125_000;
50/// 5 min minimal upload request timeout, used to clamp the request timeout.
51const MIN_UPLOAD_REQUEST_TIMEOUT: Duration = Duration::from_secs(60 * 5);
52/// The server name used to generate local MXC URIs.
53// This mustn't represent a potentially valid media server, otherwise it'd be
54// possible for an attacker to return malicious content under some
55// preconditions (e.g. the cache store has been cleared before the upload
56// took place). To mitigate against this, we use the .localhost TLD,
57// which is guaranteed to be on the local machine. As a result, the only attack
58// possible would be coming from the user themselves, which we consider a
59// non-threat.
60const LOCAL_MXC_SERVER_NAME: &str = "send-queue.localhost";
61
62/// A high-level API to interact with the media API.
63#[derive(Debug, Clone)]
64pub struct Media {
65    /// The underlying HTTP client.
66    client: Client,
67}
68
69/// A file handle that takes ownership of a media file on disk. When the handle
70/// is dropped, the file will be removed from the disk.
71#[derive(Debug)]
72#[cfg(not(target_family = "wasm"))]
73pub struct MediaFileHandle {
74    /// The temporary file that contains the media.
75    file: NamedTempFile,
76    /// An intermediary temporary directory used in certain cases.
77    ///
78    /// Only stored for its `Drop` semantics.
79    _directory: Option<TempDir>,
80}
81
82#[cfg(not(target_family = "wasm"))]
83impl MediaFileHandle {
84    /// Get the media file's path.
85    pub fn path(&self) -> &Path {
86        self.file.path()
87    }
88
89    /// Persist the media file to the given path.
90    pub fn persist(self, path: &Path) -> Result<File, PersistError> {
91        self.file.persist(path).map_err(|e| PersistError {
92            error: e.error,
93            file: Self { file: e.file, _directory: self._directory },
94        })
95    }
96}
97
98/// Error returned when [`MediaFileHandle::persist`] fails.
99#[cfg(not(target_family = "wasm"))]
100pub struct PersistError {
101    /// The underlying IO error.
102    pub error: std::io::Error,
103    /// The temporary file that couldn't be persisted.
104    pub file: MediaFileHandle,
105}
106
107#[cfg(not(any(target_family = "wasm", tarpaulin_include)))]
108impl fmt::Debug for PersistError {
109    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
110        write!(f, "PersistError({:?})", self.error)
111    }
112}
113
114#[cfg(not(any(target_family = "wasm", tarpaulin_include)))]
115impl fmt::Display for PersistError {
116    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
117        write!(f, "failed to persist temporary file: {}", self.error)
118    }
119}
120
121/// A preallocated MXC URI created by [`Media::create_content_uri()`], and
122/// to be used with [`Media::upload_preallocated()`].
123#[derive(Debug)]
124pub struct PreallocatedMxcUri {
125    /// The URI for the media URI.
126    pub uri: OwnedMxcUri,
127    /// The expiration date for the media URI.
128    expire_date: Option<MilliSecondsSinceUnixEpoch>,
129}
130
131/// An error that happened in the realm of media.
132#[derive(Debug, thiserror::Error)]
133pub enum MediaError {
134    /// A preallocated MXC URI has expired.
135    #[error("a preallocated MXC URI has expired")]
136    ExpiredPreallocatedMxcUri,
137
138    /// Preallocated media already had content, cannot overwrite.
139    #[error("preallocated media already had content, cannot overwrite")]
140    CannotOverwriteMedia,
141
142    /// Local-only media content was not found.
143    #[error("local-only media content was not found")]
144    LocalMediaNotFound,
145
146    /// The provided media is too large to upload.
147    #[error(
148        "The provided media is too large to upload. \
149         Maximum upload length is {max} bytes, tried to upload {current} bytes"
150    )]
151    MediaTooLargeToUpload {
152        /// The `max_upload_size` value for this homeserver.
153        max: UInt,
154        /// The size of the current media to upload.
155        current: UInt,
156    },
157
158    /// Fetching the `max_upload_size` value from the homeserver failed.
159    #[error("Fetching the `max_upload_size` value from the homeserver failed: {0}")]
160    FetchMaxUploadSizeFailed(String),
161}
162
163impl Media {
164    pub(crate) fn new(client: Client) -> Self {
165        Self { client }
166    }
167
168    /// Upload some media to the server.
169    ///
170    /// # Arguments
171    ///
172    /// * `content_type` - The type of the media, this will be used as the
173    ///   content-type header.
174    ///
175    /// * `data` - Vector of bytes to be uploaded to the server.
176    ///
177    /// * `request_config` - Optional request configuration for the HTTP client,
178    ///   overriding the default. If not provided, a reasonable timeout value is
179    ///   inferred.
180    ///
181    /// # Examples
182    ///
183    /// ```no_run
184    /// # use std::fs;
185    /// # use matrix_sdk::{Client, ruma::room_id};
186    /// # use url::Url;
187    /// # use mime;
188    /// # async {
189    /// # let homeserver = Url::parse("http://localhost:8080")?;
190    /// # let mut client = Client::new(homeserver).await?;
191    /// let image = fs::read("/home/example/my-cat.jpg")?;
192    ///
193    /// let response =
194    ///     client.media().upload(&mime::IMAGE_JPEG, image, None).await?;
195    ///
196    /// println!("Cat URI: {}", response.content_uri);
197    /// # anyhow::Ok(()) };
198    /// ```
199    pub fn upload(
200        &self,
201        content_type: &Mime,
202        data: Vec<u8>,
203        request_config: Option<RequestConfig>,
204    ) -> SendMediaUploadRequest {
205        let request_config = request_config.unwrap_or_else(|| {
206            self.client.request_config().timeout(Self::reasonable_upload_timeout(&data))
207        });
208
209        let request = assign!(media::create_content::v3::Request::new(data), {
210            content_type: Some(content_type.essence_str().to_owned()),
211        });
212
213        let request = self.client.send(request).with_request_config(request_config);
214        SendMediaUploadRequest::new(request)
215    }
216
217    /// Returns a reasonable upload timeout for an upload, based on the size of
218    /// the data to be uploaded.
219    pub(crate) fn reasonable_upload_timeout(data: &[u8]) -> Duration {
220        std::cmp::max(
221            Duration::from_secs(data.len() as u64 / DEFAULT_UPLOAD_SPEED),
222            MIN_UPLOAD_REQUEST_TIMEOUT,
223        )
224    }
225
226    /// Preallocates an MXC URI for a media that will be uploaded soon.
227    ///
228    /// This preallocates an URI *before* any content is uploaded to the server.
229    /// The resulting preallocated MXC URI can then be consumed with
230    /// [`Media::upload_preallocated`].
231    ///
232    /// # Examples
233    ///
234    /// ```no_run
235    /// # use std::fs;
236    /// # use matrix_sdk::{Client, ruma::room_id};
237    /// # use url::Url;
238    /// # use mime;
239    /// # async {
240    /// # let homeserver = Url::parse("http://localhost:8080")?;
241    /// # let mut client = Client::new(homeserver).await?;
242    ///
243    /// let preallocated = client.media().create_content_uri().await?;
244    /// println!("Cat URI: {}", preallocated.uri);
245    ///
246    /// let image = fs::read("/home/example/my-cat.jpg")?;
247    /// client
248    ///     .media()
249    ///     .upload_preallocated(preallocated, &mime::IMAGE_JPEG, image)
250    ///     .await?;
251    ///
252    /// # anyhow::Ok(()) };
253    /// ```
254    pub async fn create_content_uri(&self) -> Result<PreallocatedMxcUri> {
255        // Note: this request doesn't have any parameters.
256        let request = media::create_mxc_uri::v1::Request::default();
257
258        let response = self.client.send(request).await?;
259
260        Ok(PreallocatedMxcUri {
261            uri: response.content_uri,
262            expire_date: response.unused_expires_at,
263        })
264    }
265
266    /// Fills the content of a preallocated MXC URI with the given content type
267    /// and data.
268    ///
269    /// The URI must have been preallocated with [`Self::create_content_uri`].
270    /// See this method's documentation for a full example.
271    pub async fn upload_preallocated(
272        &self,
273        uri: PreallocatedMxcUri,
274        content_type: &Mime,
275        data: Vec<u8>,
276    ) -> Result<()> {
277        // Do a best-effort at reporting an expired MXC URI here; otherwise the server
278        // may complain about it later.
279        if let Some(expire_date) = uri.expire_date
280            && MilliSecondsSinceUnixEpoch::now() >= expire_date
281        {
282            return Err(Error::Media(MediaError::ExpiredPreallocatedMxcUri));
283        }
284
285        let timeout = std::cmp::max(
286            Duration::from_secs(data.len() as u64 / DEFAULT_UPLOAD_SPEED),
287            MIN_UPLOAD_REQUEST_TIMEOUT,
288        );
289
290        let request = assign!(media::create_content_async::v3::Request::from_url(&uri.uri, data)?, {
291            content_type: Some(content_type.as_ref().to_owned()),
292        });
293
294        let request_config = self.client.request_config().timeout(timeout);
295
296        if let Err(err) = self.client.send(request).with_request_config(request_config).await {
297            match err.client_api_error_kind() {
298                Some(ErrorKind::CannotOverwriteMedia) => {
299                    Err(Error::Media(MediaError::CannotOverwriteMedia))
300                }
301
302                // Unfortunately, the spec says a server will return 404 for either an expired MXC
303                // ID or a non-existing MXC ID. Do a best-effort guess to recognize an expired MXC
304                // ID based on the error string, which will work with Synapse (as of 2024-10-23).
305                Some(ErrorKind::Unknown) if err.to_string().contains("expired") => {
306                    Err(Error::Media(MediaError::ExpiredPreallocatedMxcUri))
307                }
308
309                _ => Err(err.into()),
310            }
311        } else {
312            Ok(())
313        }
314    }
315
316    /// Gets a media file by copying it to a temporary location on disk.
317    ///
318    /// The file won't be encrypted even if it is encrypted on the server.
319    ///
320    /// Returns a `MediaFileHandle` which takes ownership of the file. When the
321    /// handle is dropped, the file will be deleted from the temporary location.
322    ///
323    /// # Arguments
324    ///
325    /// * `request` - The `MediaRequest` of the content.
326    ///
327    /// * `filename` - The filename specified in the event. It is suggested to
328    ///   use the `filename()` method on the event's content instead of using
329    ///   the `filename` field directly. If not provided, a random name will be
330    ///   generated.
331    ///
332    /// * `content_type` - The type of the media, this will be used to set the
333    ///   temporary file's extension when one isn't included in the filename.
334    ///
335    /// * `use_cache` - If we should use the media cache for this request.
336    ///
337    /// * `temp_dir` - Path to a directory where temporary directories can be
338    ///   created. If not provided, a default, global temporary directory will
339    ///   be used; this may not work properly on Android, where the default
340    ///   location may require root access on some older Android versions.
341    #[cfg(not(target_family = "wasm"))]
342    pub async fn get_media_file(
343        &self,
344        request: &MediaRequestParameters,
345        filename: Option<String>,
346        content_type: &Mime,
347        use_cache: bool,
348        temp_dir: Option<String>,
349    ) -> Result<MediaFileHandle> {
350        let data = self.get_media_content(request, use_cache).await?;
351
352        let inferred_extension = mime2ext::mime2ext(content_type);
353
354        let filename_as_path = filename.as_ref().map(Path::new);
355
356        let (sanitized_filename, filename_has_extension) = if let Some(path) = filename_as_path {
357            let sanitized_filename = path.file_name().and_then(|f| f.to_str());
358            let filename_has_extension = path.extension().is_some();
359            (sanitized_filename, filename_has_extension)
360        } else {
361            (None, false)
362        };
363
364        let (temp_file, temp_dir) =
365            match (sanitized_filename, filename_has_extension, inferred_extension) {
366                // If the file name has an extension use that
367                (Some(filename_with_extension), true, _) => {
368                    // Use an intermediary directory to avoid conflicts
369                    let temp_dir = temp_dir.map(TempDir::new_in).unwrap_or_else(TempDir::new)?;
370                    let temp_file = TempFileBuilder::new()
371                        .prefix(filename_with_extension)
372                        .rand_bytes(0)
373                        .tempfile_in(&temp_dir)?;
374                    (temp_file, Some(temp_dir))
375                }
376                // If the file name doesn't have an extension try inferring one for it
377                (Some(filename), false, Some(inferred_extension)) => {
378                    // Use an intermediary directory to avoid conflicts
379                    let temp_dir = temp_dir.map(TempDir::new_in).unwrap_or_else(TempDir::new)?;
380                    let temp_file = TempFileBuilder::new()
381                        .prefix(filename)
382                        .suffix(&(".".to_owned() + inferred_extension))
383                        .rand_bytes(0)
384                        .tempfile_in(&temp_dir)?;
385                    (temp_file, Some(temp_dir))
386                }
387                // If the only thing we have is an inferred extension then use that together with a
388                // randomly generated file name
389                (None, _, Some(inferred_extension)) => (
390                    TempFileBuilder::new()
391                        .suffix(&&(".".to_owned() + inferred_extension))
392                        .tempfile()?,
393                    None,
394                ),
395                // Otherwise just use a completely random file name
396                _ => (TempFileBuilder::new().tempfile()?, None),
397            };
398
399        let mut file = TokioFile::from_std(temp_file.reopen()?);
400        file.write_all(&data).await?;
401        // Make sure the file metadata is flushed to disk.
402        file.sync_all().await?;
403
404        Ok(MediaFileHandle { file: temp_file, _directory: temp_dir })
405    }
406
407    /// Get a media file's content.
408    ///
409    /// If the content is encrypted and encryption is enabled, the content will
410    /// be decrypted.
411    ///
412    /// # Arguments
413    ///
414    /// * `request` - The `MediaRequest` of the content.
415    ///
416    /// * `use_cache` - If we should use the media cache for this request.
417    pub async fn get_media_content(
418        &self,
419        request: &MediaRequestParameters,
420        use_cache: bool,
421    ) -> Result<Vec<u8>> {
422        // Ignore request parameters for local medias, notably those pending in the send
423        // queue.
424        if let Some(uri) = Self::as_local_uri(&request.source) {
425            return self.get_local_media_content(uri).await;
426        }
427
428        // Read from the cache.
429        if use_cache
430            && let Some(content) =
431                self.client.media_store().lock().await?.get_media_content(request).await?
432        {
433            return Ok(content);
434        }
435
436        let request_config = self
437            .client
438            .request_config()
439            // Downloading a file should have no timeout as we don't know the network connectivity
440            // available for the user or the file size
441            .timeout(Some(Duration::MAX));
442
443        // Use the authenticated endpoints when the server supports it.
444        let supported_versions = self.client.supported_versions().await?;
445        let use_auth =
446            authenticated_media::get_content::v1::Request::is_supported(&supported_versions);
447
448        let content: Vec<u8> = match &request.source {
449            MediaSource::Encrypted(file) => {
450                let content = if use_auth {
451                    let request =
452                        authenticated_media::get_content::v1::Request::from_uri(&file.url)?;
453                    self.client.send(request).with_request_config(request_config).await?.file
454                } else {
455                    #[allow(deprecated)]
456                    let request = media::get_content::v3::Request::from_url(&file.url)?;
457                    self.client.send(request).with_request_config(request_config).await?.file
458                };
459
460                #[cfg(feature = "e2e-encryption")]
461                let content = {
462                    let content_len = content.len();
463                    let mut cursor = std::io::Cursor::new(content);
464                    let mut reader = matrix_sdk_base::crypto::AttachmentDecryptor::new(
465                        &mut cursor,
466                        file.as_ref().clone().into(),
467                    )?;
468
469                    // Encrypted size should be the same as the decrypted size,
470                    // rounded up to a cipher block.
471                    let mut decrypted = Vec::with_capacity(content_len);
472
473                    reader.read_to_end(&mut decrypted)?;
474
475                    decrypted
476                };
477
478                content
479            }
480
481            MediaSource::Plain(uri) => {
482                if let MediaFormat::Thumbnail(settings) = &request.format {
483                    if use_auth {
484                        let mut request =
485                            authenticated_media::get_content_thumbnail::v1::Request::from_uri(
486                                uri,
487                                settings.width,
488                                settings.height,
489                            )?;
490                        request.method = Some(settings.method.clone());
491                        request.animated = Some(settings.animated);
492
493                        self.client.send(request).with_request_config(request_config).await?.file
494                    } else {
495                        #[allow(deprecated)]
496                        let request = {
497                            let mut request = media::get_content_thumbnail::v3::Request::from_url(
498                                uri,
499                                settings.width,
500                                settings.height,
501                            )?;
502                            request.method = Some(settings.method.clone());
503                            request.animated = Some(settings.animated);
504                            request
505                        };
506
507                        self.client.send(request).with_request_config(request_config).await?.file
508                    }
509                } else if use_auth {
510                    let request = authenticated_media::get_content::v1::Request::from_uri(uri)?;
511                    self.client.send(request).with_request_config(request_config).await?.file
512                } else {
513                    #[allow(deprecated)]
514                    let request = media::get_content::v3::Request::from_url(uri)?;
515                    self.client.send(request).with_request_config(request_config).await?.file
516                }
517            }
518        };
519
520        if use_cache {
521            self.client
522                .media_store()
523                .lock()
524                .await?
525                .add_media_content(request, content.clone(), IgnoreMediaRetentionPolicy::No)
526                .await?;
527        }
528
529        Ok(content)
530    }
531
532    /// Get a media file's content that is only available in the media cache.
533    ///
534    /// # Arguments
535    ///
536    /// * `uri` - The local MXC URI of the media content.
537    async fn get_local_media_content(&self, uri: &MxcUri) -> Result<Vec<u8>> {
538        // Read from the cache.
539        self.client
540            .media_store()
541            .lock()
542            .await?
543            .get_media_content_for_uri(uri)
544            .await?
545            .ok_or_else(|| MediaError::LocalMediaNotFound.into())
546    }
547
548    /// Remove a media file's content from the store.
549    ///
550    /// # Arguments
551    ///
552    /// * `request` - The `MediaRequest` of the content.
553    pub async fn remove_media_content(&self, request: &MediaRequestParameters) -> Result<()> {
554        Ok(self.client.media_store().lock().await?.remove_media_content(request).await?)
555    }
556
557    /// Delete all the media content corresponding to the given
558    /// uri from the store.
559    ///
560    /// # Arguments
561    ///
562    /// * `uri` - The `MxcUri` of the files.
563    pub async fn remove_media_content_for_uri(&self, uri: &MxcUri) -> Result<()> {
564        Ok(self.client.media_store().lock().await?.remove_media_content_for_uri(uri).await?)
565    }
566
567    /// Get the file of the given media event content.
568    ///
569    /// If the content is encrypted and encryption is enabled, the content will
570    /// be decrypted.
571    ///
572    /// Returns `Ok(None)` if the event content has no file.
573    ///
574    /// This is a convenience method that calls the
575    /// [`get_media_content`](#method.get_media_content) method.
576    ///
577    /// # Arguments
578    ///
579    /// * `event_content` - The media event content.
580    ///
581    /// * `use_cache` - If we should use the media cache for this file.
582    pub async fn get_file(
583        &self,
584        event_content: &impl MediaEventContent,
585        use_cache: bool,
586    ) -> Result<Option<Vec<u8>>> {
587        let Some(source) = event_content.source() else { return Ok(None) };
588        let file = self
589            .get_media_content(
590                &MediaRequestParameters { source, format: MediaFormat::File },
591                use_cache,
592            )
593            .await?;
594        Ok(Some(file))
595    }
596
597    /// Remove the file of the given media event content from the cache.
598    ///
599    /// This is a convenience method that calls the
600    /// [`remove_media_content`](#method.remove_media_content) method.
601    ///
602    /// # Arguments
603    ///
604    /// * `event_content` - The media event content.
605    pub async fn remove_file(&self, event_content: &impl MediaEventContent) -> Result<()> {
606        if let Some(source) = event_content.source() {
607            self.remove_media_content(&MediaRequestParameters {
608                source,
609                format: MediaFormat::File,
610            })
611            .await?;
612        }
613
614        Ok(())
615    }
616
617    /// Get a thumbnail of the given media event content.
618    ///
619    /// If the content is encrypted and encryption is enabled, the content will
620    /// be decrypted.
621    ///
622    /// Returns `Ok(None)` if the event content has no thumbnail.
623    ///
624    /// This is a convenience method that calls the
625    /// [`get_media_content`](#method.get_media_content) method.
626    ///
627    /// # Arguments
628    ///
629    /// * `event_content` - The media event content.
630    ///
631    /// * `settings` - The _desired_ settings of the thumbnail. The actual
632    ///   thumbnail may not match the settings specified.
633    ///
634    /// * `use_cache` - If we should use the media cache for this thumbnail.
635    pub async fn get_thumbnail(
636        &self,
637        event_content: &impl MediaEventContent,
638        settings: MediaThumbnailSettings,
639        use_cache: bool,
640    ) -> Result<Option<Vec<u8>>> {
641        let Some(source) = event_content.thumbnail_source() else { return Ok(None) };
642        let thumbnail = self
643            .get_media_content(
644                &MediaRequestParameters { source, format: MediaFormat::Thumbnail(settings) },
645                use_cache,
646            )
647            .await?;
648        Ok(Some(thumbnail))
649    }
650
651    /// Remove the thumbnail of the given media event content from the cache.
652    ///
653    /// This is a convenience method that calls the
654    /// [`remove_media_content`](#method.remove_media_content) method.
655    ///
656    /// # Arguments
657    ///
658    /// * `event_content` - The media event content.
659    ///
660    /// * `size` - The _desired_ settings of the thumbnail. Must match the
661    ///   settings requested with [`get_thumbnail`](#method.get_thumbnail).
662    pub async fn remove_thumbnail(
663        &self,
664        event_content: &impl MediaEventContent,
665        settings: MediaThumbnailSettings,
666    ) -> Result<()> {
667        if let Some(source) = event_content.source() {
668            self.remove_media_content(&MediaRequestParameters {
669                source,
670                format: MediaFormat::Thumbnail(settings),
671            })
672            .await?
673        }
674
675        Ok(())
676    }
677
678    /// Set the [`MediaRetentionPolicy`] to use for deciding whether to store or
679    /// keep media content.
680    ///
681    /// It is used:
682    ///
683    /// * When a media needs to be cached, to check that it does not exceed the
684    ///   max file size.
685    ///
686    /// * When [`Media::clean()`], to check that all media content in the store
687    ///   fits those criteria.
688    ///
689    /// To apply the new policy to the media cache right away,
690    /// [`Media::clean()`] should be called after this.
691    ///
692    /// By default, an empty `MediaRetentionPolicy` is used, which means that no
693    /// criteria are applied.
694    ///
695    /// # Arguments
696    ///
697    /// * `policy` - The `MediaRetentionPolicy` to use.
698    pub async fn set_media_retention_policy(&self, policy: MediaRetentionPolicy) -> Result<()> {
699        self.client.media_store().lock().await?.set_media_retention_policy(policy).await?;
700        Ok(())
701    }
702
703    /// Get the current `MediaRetentionPolicy`.
704    pub async fn media_retention_policy(&self) -> Result<MediaRetentionPolicy> {
705        Ok(self.client.media_store().lock().await?.media_retention_policy())
706    }
707
708    /// Clean up the media cache with the current [`MediaRetentionPolicy`].
709    ///
710    /// If there is already an ongoing cleanup, this is a noop.
711    pub async fn clean(&self) -> Result<()> {
712        self.client.media_store().lock().await?.clean().await?;
713        Ok(())
714    }
715
716    /// Upload the file bytes in `data` and return the source information.
717    pub(crate) async fn upload_plain_media_and_thumbnail(
718        &self,
719        content_type: &Mime,
720        data: Vec<u8>,
721        thumbnail: Option<Thumbnail>,
722        send_progress: SharedObservable<TransmissionProgress>,
723    ) -> Result<(MediaSource, Option<(MediaSource, Box<ThumbnailInfo>)>)> {
724        let upload_thumbnail = self.upload_thumbnail(thumbnail, send_progress.clone());
725
726        let upload_attachment = async move {
727            self.upload(content_type, data, None).with_send_progress_observable(send_progress).await
728        };
729
730        let (thumbnail, response) = try_join(upload_thumbnail, upload_attachment).await?;
731
732        Ok((MediaSource::Plain(response.content_uri), thumbnail))
733    }
734
735    /// Uploads an unencrypted thumbnail to the media repository, and returns
736    /// its source and extra information.
737    async fn upload_thumbnail(
738        &self,
739        thumbnail: Option<Thumbnail>,
740        send_progress: SharedObservable<TransmissionProgress>,
741    ) -> Result<Option<(MediaSource, Box<ThumbnailInfo>)>> {
742        let Some(thumbnail) = thumbnail else {
743            return Ok(None);
744        };
745
746        let (data, content_type, thumbnail_info) = thumbnail.into_parts();
747
748        let response = self
749            .upload(&content_type, data, None)
750            .with_send_progress_observable(send_progress)
751            .await?;
752        let url = response.content_uri;
753
754        Ok(Some((MediaSource::Plain(url), thumbnail_info)))
755    }
756
757    /// Create an [`OwnedMxcUri`] for a file or thumbnail we want to store
758    /// locally before sending it.
759    ///
760    /// This uses a MXC ID that is only locally valid.
761    pub(crate) fn make_local_uri(txn_id: &TransactionId) -> OwnedMxcUri {
762        OwnedMxcUri::from(format!("mxc://{LOCAL_MXC_SERVER_NAME}/{txn_id}"))
763    }
764
765    /// Create a [`MediaRequest`] for a file we want to store locally before
766    /// sending it.
767    ///
768    /// This uses a MXC ID that is only locally valid.
769    pub(crate) fn make_local_file_media_request(txn_id: &TransactionId) -> MediaRequestParameters {
770        MediaRequestParameters {
771            source: MediaSource::Plain(Self::make_local_uri(txn_id)),
772            format: MediaFormat::File,
773        }
774    }
775
776    /// Create a [`MediaRequest`] for a file we want to store locally before
777    /// sending it.
778    ///
779    /// This uses a MXC ID that is only locally valid.
780    pub(crate) fn make_local_thumbnail_media_request(
781        txn_id: &TransactionId,
782        height: UInt,
783        width: UInt,
784    ) -> MediaRequestParameters {
785        MediaRequestParameters {
786            source: MediaSource::Plain(Self::make_local_uri(txn_id)),
787            format: MediaFormat::Thumbnail(MediaThumbnailSettings::new(width, height)),
788        }
789    }
790
791    /// Returns the local MXC URI contained by the given source, if any.
792    ///
793    /// A local MXC URI is a URI that was generated with `make_local_uri`.
794    fn as_local_uri(source: &MediaSource) -> Option<&MxcUri> {
795        let uri = match source {
796            MediaSource::Plain(uri) => uri,
797            MediaSource::Encrypted(file) => &file.url,
798        };
799
800        uri.server_name()
801            .is_ok_and(|server_name| server_name == LOCAL_MXC_SERVER_NAME)
802            .then_some(uri)
803    }
804}
805
806#[cfg(test)]
807mod tests {
808    use assert_matches2::assert_matches;
809    use ruma::{
810        MxcUri,
811        events::room::{EncryptedFile, MediaSource},
812        mxc_uri, owned_mxc_uri, uint,
813    };
814    use serde_json::json;
815
816    use super::Media;
817
818    /// Create an `EncryptedFile` with the given MXC URI.
819    fn encrypted_file(mxc_uri: &MxcUri) -> Box<EncryptedFile> {
820        Box::new(
821            serde_json::from_value(json!({
822                "url": mxc_uri,
823                "key": {
824                    "kty": "oct",
825                    "key_ops": ["encrypt", "decrypt"],
826                    "alg": "A256CTR",
827                    "k": "b50ACIv6LMn9AfMCFD1POJI_UAFWIclxAN1kWrEO2X8",
828                    "ext": true,
829                },
830                "iv": "AK1wyzigZtQAAAABAAAAKK",
831                "hashes": {
832                    "sha256": "foobar",
833                },
834                "v": "v2",
835            }))
836            .unwrap(),
837        )
838    }
839
840    #[test]
841    fn test_as_local_uri() {
842        let txn_id = "abcdef";
843
844        // Request generated with `make_local_file_media_request`.
845        let request = Media::make_local_file_media_request(txn_id.into());
846        assert_matches!(Media::as_local_uri(&request.source), Some(uri));
847        assert_eq!(uri.media_id(), Ok(txn_id));
848
849        // Request generated with `make_local_thumbnail_media_request`.
850        let request =
851            Media::make_local_thumbnail_media_request(txn_id.into(), uint!(100), uint!(100));
852        assert_matches!(Media::as_local_uri(&request.source), Some(uri));
853        assert_eq!(uri.media_id(), Ok(txn_id));
854
855        // Local plain source.
856        let source = MediaSource::Plain(Media::make_local_uri(txn_id.into()));
857        assert_matches!(Media::as_local_uri(&source), Some(uri));
858        assert_eq!(uri.media_id(), Ok(txn_id));
859
860        // Local encrypted source.
861        let source = MediaSource::Encrypted(encrypted_file(&Media::make_local_uri(txn_id.into())));
862        assert_matches!(Media::as_local_uri(&source), Some(uri));
863        assert_eq!(uri.media_id(), Ok(txn_id));
864
865        // Test non-local plain source.
866        let source = MediaSource::Plain(owned_mxc_uri!("mxc://server.local/poiuyt"));
867        assert_matches!(Media::as_local_uri(&source), None);
868
869        // Test non-local encrypted source.
870        let source = MediaSource::Encrypted(encrypted_file(mxc_uri!("mxc://server.local/mlkjhg")));
871        assert_matches!(Media::as_local_uri(&source), None);
872
873        // Test invalid MXC URI.
874        let source = MediaSource::Plain("https://server.local/nbvcxw".into());
875        assert_matches!(Media::as_local_uri(&source), None);
876    }
877}