diff --git a/crates/matrix-sdk-contentscanner/src/api/mod.rs b/crates/matrix-sdk-contentscanner/src/api/mod.rs index d5d11da1e..a6cca0c93 100644 --- a/crates/matrix-sdk-contentscanner/src/api/mod.rs +++ b/crates/matrix-sdk-contentscanner/src/api/mod.rs @@ -38,6 +38,8 @@ impl IncomingResponse for DownloadAndScanMediaResponse { } } +/// Creates an [`EncryptedFileRequest`] from [`EncryptedFile`], using the +/// optionally provided public key if present. pub(crate) fn encrypted_file_request_from( public_key: &Option, encrypted_file: &EncryptedFile, diff --git a/crates/matrix-sdk-contentscanner/src/api/scan/encrypted.rs b/crates/matrix-sdk-contentscanner/src/api/scan/encrypted.rs index 8654fb471..281e6ae64 100644 --- a/crates/matrix-sdk-contentscanner/src/api/scan/encrypted.rs +++ b/crates/matrix-sdk-contentscanner/src/api/scan/encrypted.rs @@ -23,6 +23,7 @@ metadata! { }, } +/// A request to scan an encrypted media file using the content scanner. #[derive(Debug, Clone)] pub struct EncryptedMediaScanRequest { scanner_url: String, diff --git a/crates/matrix-sdk-contentscanner/src/api/scan/mod.rs b/crates/matrix-sdk-contentscanner/src/api/scan/mod.rs index 963209fb6..e9de72ea9 100644 --- a/crates/matrix-sdk-contentscanner/src/api/scan/mod.rs +++ b/crates/matrix-sdk-contentscanner/src/api/scan/mod.rs @@ -8,9 +8,12 @@ use serde::Deserialize; pub mod encrypted; pub mod unencrypted; +/// A media scan response containing the result of the scan. #[derive(Debug, Deserialize)] pub struct MediaScanResponse { + /// Whether the media is clean or contained something dangerous. pub clean: bool, + /// Extra information about the scan. pub info: String, } diff --git a/crates/matrix-sdk-contentscanner/src/api/scan/unencrypted.rs b/crates/matrix-sdk-contentscanner/src/api/scan/unencrypted.rs index 71787e94d..d37d51540 100644 --- a/crates/matrix-sdk-contentscanner/src/api/scan/unencrypted.rs +++ b/crates/matrix-sdk-contentscanner/src/api/scan/unencrypted.rs @@ -10,7 +10,7 @@ use ruma::{ metadata, }; -pub(crate) use crate::api::scan::MediaScanResponse; +use crate::api::scan::MediaScanResponse; metadata! { @for MediaScanRequest, @@ -22,6 +22,7 @@ metadata! { }, } +/// A request to scan an unencrypted media file using the content scanner. #[derive(Debug, Clone)] pub struct MediaScanRequest { scanner_url: String, diff --git a/crates/matrix-sdk-contentscanner/src/lib.rs b/crates/matrix-sdk-contentscanner/src/lib.rs index 60a2fda68..1432d6fc5 100644 --- a/crates/matrix-sdk-contentscanner/src/lib.rs +++ b/crates/matrix-sdk-contentscanner/src/lib.rs @@ -24,12 +24,15 @@ use tracing::trace; #[cfg(feature = "uniffi")] uniffi::setup_scaffolding!(); -use api::scan::unencrypted::{MediaScanRequest, MediaScanResponse}; - -use crate::api::{DownloadAndScanMediaResponse, scan::encrypted::EncryptedMediaScanRequest}; +pub use crate::api::scan::MediaScanResponse; +use crate::api::{ + DownloadAndScanMediaResponse, + scan::{encrypted::EncryptedMediaScanRequest, unencrypted::MediaScanRequest}, +}; mod api; +/// A helper component to download and scan media from a content scanner server. #[derive(Debug)] pub struct ContentScanner { scanner_url: String, @@ -38,6 +41,8 @@ pub struct ContentScanner { } impl ContentScanner { + /// Instantiate a new [`ContentScanner`] using the `scanner_url` and a lazy + /// [`WeakClient`]. pub fn new(scanner_url: impl Into, weak_client: WeakClient) -> Self { Self { scanner_url: scanner_url.into(), @@ -110,6 +115,8 @@ impl ContentScanner { } } + /// Scan a media source, returning a [`MediaScanResponse`] with the scan + /// result, or an error if something failed when trying to scan the media. pub async fn scan(&self, media_source: &MediaSource) -> Result { let Some(client) = self.weak_client.get() else { return Err(Error::MediaFetcher(MediaFetcherError::MissingClient)); @@ -178,6 +185,7 @@ impl EncryptedFileRequest { } } +/// A media fetcher that uses the content scanner to download and scan media. pub struct ContentScannerMediaFetcher { pub content_scanner: ContentScanner, } @@ -192,11 +200,14 @@ impl MediaFetcher for ContentScannerMediaFetcher { } } +/// A builder for the [`ContentScannerMediaFetcher`]. pub struct ContentScannerMediaFetcherBuilder { scanner_url: String, } impl ContentScannerMediaFetcherBuilder { + /// Create a new instance of [`ContentScannerMediaFetcherBuilder`] pointing + /// to the provided `scanner_url`. pub fn new(scanner_url: impl Into) -> Self { Self { scanner_url: scanner_url.into() } } @@ -209,25 +220,37 @@ impl MediaFetcherBuilder for ContentScannerMediaFetcherBuilder { } } +/// A content scanner error. #[derive(Debug, Deserialize)] pub struct ContentScannerError { pub info: String, pub reason: ErrorReason, } +/// The reason for the content scanner error. #[allow(non_camel_case_types)] #[cfg_attr(feature = "uniffi", derive(uniffi::Enum))] #[derive(Clone, Debug, Deserialize)] pub enum ErrorReason { + /// The JSON file is malformed. MCS_MALFORMED_JSON, + /// The media could not be decrypted. MCS_MEDIA_FAILED_TO_DECRYPT, + /// No access token was provided. M_MISSING_TOKEN, + /// The access token provided is invalid. M_UNKNOWN_TOKEN, + /// The media was not found. M_NOT_FOUND, + /// The media has some potentially dangerous content. MCS_MEDIA_NOT_CLEAN, + /// The media has been blocked by the server because of its mime type. MCS_MIME_TYPE_FORBIDDEN, + /// The used public key is wrong. MCS_BAD_DECRYPTION, + /// An unknown error occurred. M_UNKNOWN, + /// The server failed to request media from the media repo. MCS_MEDIA_REQUEST_FAILED, }