Rename ImageData to DataUri and allow setting its mimetype (#3412)

Back in September 2024, Discord added [Soundboard][soundboard] APIs that allow
a bot to create a new sound by uploading raw mp3 or ogg data.

This data is specified as part of the JSON rather than a multipart upload (an
odd decision IMO); however, that means that the semantics of `ImageData` are
wrong as it makes too many assumptions about its contents. In particular, we
assume that the base64 data will always be an image, and the
`CreateAttachment::encode` method always assigns the `image/png` mimetype.

This commit removes these assumptions by renaming the struct to simply
`DataUri`, and now requiring the user to specify the mimetype when calling
`CreateAttachment::encode`.

[soundboard]: https://discord.com/developers/docs/resources/soundboard#soundboard-resource

Author: mkrasnitski

src/builder/create_attachment.rs

@@ -115,21 +115,21 @@ impl<'a> CreateAttachment<'a> {
     /// # Errors
     ///
     /// See [`CreateAttachment::get_data`] for details.
-    pub async fn encode(&self) -> Result<ImageData<'_>> {
+    pub async fn encode(&self, mimetype: &str) -> Result<DataUri<'_>> {
         use base64::engine::{Config, Engine};
 
-        const PREFIX: &str = "data:image/png;base64,";
+        let prefix = format!("data:{mimetype};base64,");
         let data = self.get_data().await?;
 
         let engine = base64::prelude::BASE64_STANDARD;
         let encoded_size = base64::encoded_len(data.len(), engine.config().encode_padding())
-            .and_then(|len| len.checked_add(PREFIX.len()))
+            .and_then(|len| len.checked_add(prefix.len()))
             .expect("buffer capacity overflow");
 
         let mut encoded = String::with_capacity(encoded_size);
-        encoded.push_str(PREFIX);
+        encoded.push_str(&prefix);
         engine.encode_string(&data, &mut encoded);
-        Ok(ImageData(encoded.into()))
+        Ok(DataUri(encoded.into()))
     }
 
     /// Sets a description for the file (max 1024 characters).
@@ -139,27 +139,27 @@ impl<'a> CreateAttachment<'a> {
     }
 }
 
-/// A wrapper around some base64-encoded image data. Used when an endpoint expects the image
-/// payload directly as part of the JSON body, instead of as a multipart upload.
+/// A wrapper around some base64-encoded data. Used when an endpoint expects a base64 payload
+/// directly as part of the JSON body, instead of as a multipart upload.
 #[derive(Clone, Debug, Serialize)]
 #[serde(transparent)]
-pub struct ImageData<'a>(Cow<'a, str>);
+pub struct DataUri<'a>(Cow<'a, str>);
 
-impl<'a> ImageData<'a> {
-    /// Accesses the stored base64-encoded image data.
+impl<'a> DataUri<'a> {
+    /// Accesses the stored base64-encoded data.
     #[must_use]
     pub fn as_base64(&self) -> &str {
         &self.0
     }
 
-    /// Constructs image data from a base64-encoded blob of data. The string must be a valid data
+    /// Constructs a [`DataUri`] from a base64-encoded blob of data. The string must be a valid data
     /// URI, for example:
     ///
     /// ```
-    /// use serenity::builder::ImageData;
+    /// use serenity::builder::DataUri;
     ///
     /// let s = "data:image/png;base64,R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=";
-    /// assert!(ImageData::from_base64(s).is_ok());
+    /// assert!(DataUri::from_base64(s).is_ok());
     /// ```
     ///
     /// # Errors

src/builder/create_scheduled_event.rs

@@ -1,6 +1,6 @@
 use std::borrow::Cow;
 
-use super::ImageData;
+use super::DataUri;
 #[cfg(feature = "http")]
 use crate::http::Http;
 #[cfg(feature = "http")]
@@ -24,7 +24,7 @@ pub struct CreateScheduledEvent<'a> {
     description: Option<Cow<'a, str>>,
     entity_type: ScheduledEventType,
     #[serde(skip_serializing_if = "Option::is_none")]
-    image: Option<ImageData<'a>>,
+    image: Option<DataUri<'a>>,
 
     #[serde(skip)]
     audit_log_reason: Option<&'a str>,
@@ -110,7 +110,7 @@ impl<'a> CreateScheduledEvent<'a> {
     }
 
     /// Sets the cover image for the scheduled event.
-    pub fn image(mut self, image: ImageData<'a>) -> Self {
+    pub fn image(mut self, image: DataUri<'a>) -> Self {
         self.image = Some(image);
         self
     }

src/builder/create_soundboard.rs

@@ -1,4 +1,4 @@
-use super::ImageData;
+use super::DataUri;
 #[cfg(feature = "http")]
 use crate::http::CacheHttp;
 #[cfg(feature = "http")]
@@ -12,7 +12,7 @@ use crate::model::prelude::*;
 #[must_use]
 pub struct CreateSoundboard<'a> {
     name: String,
-    sound: ImageData<'a>,
+    sound: DataUri<'a>,
     volume: f64,
     #[serde(skip_serializing_if = "Option::is_none")]
     emoji_id: Option<EmojiId>,
@@ -25,7 +25,7 @@ pub struct CreateSoundboard<'a> {
 
 impl<'a> CreateSoundboard<'a> {
     /// Creates a new builder with the given data.
-    pub fn new(name: impl Into<String>, sound: ImageData<'a>) -> Self {
+    pub fn new(name: impl Into<String>, sound: DataUri<'a>) -> Self {
         Self {
             name: name.into(),
             sound,
@@ -48,7 +48,7 @@ impl<'a> CreateSoundboard<'a> {
     ///
     /// **Note**: Must be audio that is encoded in MP3 or OGG, max 512 KB, max
     /// duration 5.2 seconds.
-    pub fn sound(mut self, sound: ImageData<'a>) -> Self {
+    pub fn sound(mut self, sound: DataUri<'a>) -> Self {
         self.sound = sound;
         self
     }

src/builder/create_webhook.rs

@@ -1,6 +1,6 @@
 use std::borrow::Cow;
 
-use super::ImageData;
+use super::DataUri;
 #[cfg(feature = "http")]
 use crate::http::Http;
 #[cfg(feature = "http")]
@@ -14,7 +14,7 @@ use crate::model::prelude::*;
 pub struct CreateWebhook<'a> {
     name: Cow<'a, str>,
     #[serde(skip_serializing_if = "Option::is_none")]
-    avatar: Option<ImageData<'a>>,
+    avatar: Option<DataUri<'a>>,
 
     #[serde(skip)]
     audit_log_reason: Option<&'a str>,
@@ -39,7 +39,7 @@ impl<'a> CreateWebhook<'a> {
     }
 
     /// Set the webhook's default avatar.
-    pub fn avatar(mut self, avatar: ImageData<'a>) -> Self {
+    pub fn avatar(mut self, avatar: DataUri<'a>) -> Self {
         self.avatar = Some(avatar);
         self
     }

src/builder/edit_guild.rs

@@ -1,6 +1,6 @@
 use std::borrow::Cow;
 
-use super::ImageData;
+use super::DataUri;
 #[cfg(feature = "http")]
 use crate::http::Http;
 #[cfg(feature = "http")]
@@ -27,15 +27,15 @@ pub struct EditGuild<'a> {
     #[serde(skip_serializing_if = "Option::is_none")]
     afk_timeout: Option<AfkTimeout>,
     #[serde(skip_serializing_if = "Option::is_none")]
-    icon: Option<Option<ImageData<'a>>>,
+    icon: Option<Option<DataUri<'a>>>,
     #[serde(skip_serializing_if = "Option::is_none")]
     owner_id: Option<UserId>,
     #[serde(skip_serializing_if = "Option::is_none")]
     splash: Option<Option<Cow<'a, str>>>,
     #[serde(skip_serializing_if = "Option::is_none")]
     discovery_splash: Option<Option<Cow<'a, str>>>,
     #[serde(skip_serializing_if = "Option::is_none")]
-    banner: Option<Option<ImageData<'a>>>,
+    banner: Option<Option<DataUri<'a>>>,
     #[serde(skip_serializing_if = "Option::is_none")]
     system_channel_id: Option<Option<ChannelId>>,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -91,7 +91,7 @@ impl<'a> EditGuild<'a> {
     /// # async fn run() -> Result<(), Box<dyn std::error::Error>> {
     /// # let http: Http = unimplemented!();
     /// # let mut guild = GuildId::new(1).to_partial_guild(&http).await?;
-    /// let icon = CreateAttachment::path("./guild_icon.png".as_ref())?.encode().await?;
+    /// let icon = CreateAttachment::path("./guild_icon.png".as_ref())?.encode("image/png").await?;
     ///
     /// // assuming a `guild` has already been bound
     /// let builder = EditGuild::new().icon(Some(icon));
@@ -101,7 +101,7 @@ impl<'a> EditGuild<'a> {
     /// ```
     ///
     /// [`CreateAttachment`]: super::CreateAttachment
-    pub fn icon(mut self, icon: Option<ImageData<'a>>) -> Self {
+    pub fn icon(mut self, icon: Option<DataUri<'a>>) -> Self {
         self.icon = Some(icon);
         self
     }
@@ -184,7 +184,7 @@ impl<'a> EditGuild<'a> {
     /// guild's [`features`] list.
     ///
     /// [`features`]: Guild::features
-    pub fn banner(mut self, banner: Option<ImageData<'a>>) -> Self {
+    pub fn banner(mut self, banner: Option<DataUri<'a>>) -> Self {
         self.banner = Some(banner);
         self
     }

src/builder/edit_profile.rs

@@ -1,6 +1,6 @@
 use std::borrow::Cow;
 
-use super::ImageData;
+use super::DataUri;
 #[cfg(feature = "http")]
 use crate::http::Http;
 #[cfg(feature = "http")]
@@ -18,9 +18,9 @@ pub struct EditProfile<'a> {
     #[serde(skip_serializing_if = "Option::is_none")]
     username: Option<Cow<'a, str>>,
     #[serde(skip_serializing_if = "Option::is_none")]
-    avatar: Option<Option<ImageData<'a>>>,
+    avatar: Option<Option<DataUri<'a>>>,
     #[serde(skip_serializing_if = "Option::is_none")]
-    banner: Option<Option<ImageData<'a>>>,
+    banner: Option<Option<DataUri<'a>>>,
 }
 
 impl<'a> EditProfile<'a> {
@@ -43,13 +43,13 @@ impl<'a> EditProfile<'a> {
     /// # async fn run() -> Result<(), SerenityError> {
     /// # let http: Http = unimplemented!();
     /// # let mut user = CurrentUser::default();
-    /// let avatar = CreateAttachment::path("./my_image.jpg".as_ref())?.encode().await?;
+    /// let avatar = CreateAttachment::path("./my_image.jpg".as_ref())?.encode("image/jpeg").await?;
     /// let builder = EditProfile::new().avatar(avatar);
     /// user.edit(&http, builder).await?;
     /// # Ok(())
     /// # }
     /// ```
-    pub fn avatar(mut self, avatar: ImageData<'a>) -> Self {
+    pub fn avatar(mut self, avatar: DataUri<'a>) -> Self {
         self.avatar = Some(Some(avatar));
         self
     }
@@ -71,7 +71,7 @@ impl<'a> EditProfile<'a> {
     }
 
     /// Sets the banner of the current user.
-    pub fn banner(mut self, banner: ImageData<'a>) -> Self {
+    pub fn banner(mut self, banner: DataUri<'a>) -> Self {
         self.banner = Some(Some(banner));
         self
     }

src/builder/edit_role.rs

@@ -1,6 +1,6 @@
 use std::borrow::Cow;
 
-use super::ImageData;
+use super::DataUri;
 #[cfg(feature = "http")]
 use crate::http::Http;
 use crate::model::prelude::*;
@@ -50,7 +50,7 @@ pub struct EditRole<'a> {
     #[serde(skip_serializing_if = "Option::is_none")]
     hoist: Option<bool>,
     #[serde(skip_serializing_if = "Option::is_none")]
-    icon: Option<Option<ImageData<'a>>>,
+    icon: Option<Option<DataUri<'a>>>,
     #[serde(skip_serializing_if = "Option::is_none")]
     unicode_emoji: Option<Option<Cow<'a, str>>>,
 
@@ -131,7 +131,7 @@ impl<'a> EditRole<'a> {
     }
 
     /// Set the role icon to a custom image.
-    pub fn icon(mut self, icon: Option<ImageData<'a>>) -> Self {
+    pub fn icon(mut self, icon: Option<DataUri<'a>>) -> Self {
         self.icon = Some(icon);
         self.unicode_emoji = Some(None);
         self

src/builder/edit_scheduled_event.rs

@@ -1,6 +1,6 @@
 use std::borrow::Cow;
 
-use super::{CreateScheduledEventMetadata, ImageData};
+use super::{CreateScheduledEventMetadata, DataUri};
 #[cfg(feature = "http")]
 use crate::http::Http;
 #[cfg(feature = "http")]
@@ -30,7 +30,7 @@ pub struct EditScheduledEvent<'a> {
     #[serde(skip_serializing_if = "Option::is_none")]
     status: Option<ScheduledEventStatus>,
     #[serde(skip_serializing_if = "Option::is_none")]
-    image: Option<ImageData<'a>>,
+    image: Option<DataUri<'a>>,
 
     #[serde(skip)]
     audit_log_reason: Option<&'a str>,
@@ -152,7 +152,7 @@ impl<'a> EditScheduledEvent<'a> {
     }
 
     /// Sets the cover image for the scheduled event.
-    pub fn image(mut self, image: ImageData<'a>) -> Self {
+    pub fn image(mut self, image: DataUri<'a>) -> Self {
         self.image = Some(image);
         self
     }

src/builder/edit_webhook.rs

@@ -1,6 +1,6 @@
 use std::borrow::Cow;
 
-use super::ImageData;
+use super::DataUri;
 #[cfg(feature = "http")]
 use crate::http::Http;
 #[cfg(feature = "http")]
@@ -14,7 +14,7 @@ pub struct EditWebhook<'a> {
     #[serde(skip_serializing_if = "Option::is_none")]
     name: Option<Cow<'a, str>>,
     #[serde(skip_serializing_if = "Option::is_none")]
-    avatar: Option<Option<ImageData<'a>>>,
+    avatar: Option<Option<DataUri<'a>>>,
     #[serde(skip_serializing_if = "Option::is_none")]
     channel_id: Option<ChannelId>,
 
@@ -43,7 +43,7 @@ impl<'a> EditWebhook<'a> {
     }
 
     /// Set the webhook's default avatar.
-    pub fn avatar(mut self, avatar: ImageData<'a>) -> Self {
+    pub fn avatar(mut self, avatar: DataUri<'a>) -> Self {
         self.avatar = Some(Some(avatar));
         self
     }

src/model/guild/guild_id.rs

@@ -13,6 +13,7 @@ use crate::builder::{
     CreateScheduledEvent,
     CreateSoundboard,
     CreateSticker,
+    DataUri,
     EditAutoModRule,
     EditCommand,
     EditCommandPermissions,
@@ -24,7 +25,6 @@ use crate::builder::{
     EditScheduledEvent,
     EditSoundboard,
     EditSticker,
-    ImageData,
 };
 #[cfg(all(feature = "cache", feature = "model"))]
 use crate::cache::{Cache, GuildRef};
@@ -363,14 +363,14 @@ impl GuildId {
         self,
         http: &Http,
         name: &str,
-        image: ImageData<'_>,
+        image: DataUri<'_>,
         roles: Option<Vec<RoleId>>,
         reason: Option<&str>,
     ) -> Result<Emoji> {
         #[derive(serde::Serialize)]
         struct CreateEmoji<'a> {
             name: &'a str,
-            image: ImageData<'a>,
+            image: DataUri<'a>,
             #[serde(skip_serializing_if = "Option::is_none")]
             roles: Option<Vec<RoleId>>,
         }