Adding Blurhashing

Cargo.toml

@@ -179,7 +179,7 @@ version = "0.5.3"
 features = ["alloc", "rand"]
 default-features = false
 
-# Used to generate thumbnails for images
+# Used to generate thumbnails for images & blurhashes
 [workspace.dependencies.image]
 version = "0.25.5"
 default-features = false
@@ -190,6 +190,14 @@ features = [
 	"webp",
 ]
 
+[workspace.dependencies.blurhash]
+version = "0.2.3"
+default-features = false
+features = [
+	"fast-linear-to-srgb",
+	"image",
+]
+
 # logging
 [workspace.dependencies.log]
 version = "0.4.22"

conduwuit-example.toml

@@ -1607,3 +1607,21 @@
 # This item is undocumented. Please contribute documentation for it.
 #
 #support_mxid =
+
+[global.blurhashing]
+
+# blurhashing x component, 4 is recommended by https://blurha.sh/
+#
+#components_x = 4
+
+# blurhashing y component, 3 is recommended by https://blurha.sh/
+#
+#components_y = 3
+
+# Max raw size that the server will blurhash, this is the size of the
+# image after converting it to raw data, it should be higher than the
+# upload limit but not too high. The higher it is the higher the
+# potential load will be for clients requesting blurhashes. The default
+# is 33.55MB. Setting it to 0 disables blurhashing.
+#
+#blurhash_max_raw_size = 33554432

src/api/client/media.rs

@@ -57,19 +57,28 @@ pub(crate) async fn create_content_route(
 	let filename = body.filename.as_deref();
 	let content_type = body.content_type.as_deref();
 	let content_disposition = make_content_disposition(None, content_type, filename);
-	let mxc = Mxc {
+	let ref mxc = Mxc {
 		server_name: services.globals.server_name(),
 		media_id: &utils::random_string(MXC_LENGTH),
 	};
 
 	services
 		.media
-		.create(&mxc, Some(user), Some(&content_disposition), content_type, &body.file)
-		.await
-		.map(|()| create_content::v3::Response {
-			content_uri: mxc.to_string().into(),
-			blurhash: None,
-		})
+		.create(mxc, Some(user), Some(&content_disposition), content_type, &body.file)
+		.await?;
+
+	let blurhash = body.generate_blurhash.then(|| {
+		services
+			.media
+			.create_blurhash(&body.file, content_type, filename)
+			.ok()
+			.flatten()
+	});
+
+	Ok(create_content::v3::Response {
+		content_uri: mxc.to_string().into(),
+		blurhash: blurhash.flatten(),
+	})
 }
 
 /// # `GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`

src/core/config/mod.rs

@@ -52,7 +52,7 @@ use crate::{err, error::Error, utils::sys, Result};
 ### For more information, see:
 ### https://conduwuit.puppyirl.gay/configuration.html
 "#,
-	ignore = "catchall well_known tls"
+	ignore = "catchall well_known tls blurhashing"
 )]
 pub struct Config {
 	/// The server_name is the pretty name of this server. It is used as a
@@ -1789,6 +1789,9 @@ pub struct Config {
 	#[serde(default = "true_fn")]
 	pub config_reload_signal: bool,
 
+	// external structure; separate section
+	#[serde(default)]
+	pub blurhashing: BlurhashConfig,
 	#[serde(flatten)]
 	#[allow(clippy::zero_sized_map_values)]
 	// this is a catchall, the map shouldn't be zero at runtime
@@ -1839,6 +1842,31 @@ pub struct WellKnownConfig {
 	pub support_mxid: Option<OwnedUserId>,
 }
 
+#[derive(Clone, Copy, Debug, Deserialize, Default)]
+#[allow(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
+#[config_example_generator(filename = "conduwuit-example.toml", section = "global.blurhashing")]
+pub struct BlurhashConfig {
+	/// blurhashing x component, 4 is recommended by https://blurha.sh/
+	///
+	/// default: 4
+	#[serde(default = "default_blurhash_x_component")]
+	pub components_x: u32,
+	/// blurhashing y component, 3 is recommended by https://blurha.sh/
+	///
+	/// default: 3
+	#[serde(default = "default_blurhash_y_component")]
+	pub components_y: u32,
+	/// Max raw size that the server will blurhash, this is the size of the
+	/// image after converting it to raw data, it should be higher than the
+	/// upload limit but not too high. The higher it is the higher the
+	/// potential load will be for clients requesting blurhashes. The default
+	/// is 33.55MB. Setting it to 0 disables blurhashing.
+	///
+	/// default: 33554432
+	#[serde(default = "default_blurhash_max_raw_size")]
+	pub blurhash_max_raw_size: u64,
+}
+
 #[derive(Deserialize, Clone, Debug)]
 #[serde(transparent)]
 struct ListeningPort {
@@ -2210,3 +2238,13 @@ fn default_client_response_timeout() -> u64 { 120 }
 fn default_client_shutdown_timeout() -> u64 { 15 }
 
 fn default_sender_shutdown_timeout() -> u64 { 5 }
+
+// blurhashing defaults recommended by https://blurha.sh/
+// 2^25
+pub(super) fn default_blurhash_max_raw_size() -> u64 { 33_554_432 }
+
+pub(super) fn default_blurhash_x_component() -> u32 { 4 }
+
+pub(super) fn default_blurhash_y_component() -> u32 { 3 }
+
+// end recommended & blurhashing defaults

src/main/Cargo.toml

@@ -49,6 +49,9 @@ default = [
 	"zstd_compression",
 ]
 
+blurhashing = [
+	"conduwuit-service/blurhashing",
+]
 brotli_compression = [
 	"conduwuit-api/brotli_compression",
 	"conduwuit-core/brotli_compression",

src/service/Cargo.toml

@@ -44,6 +44,7 @@ url_preview = [
 zstd_compression = [
     "reqwest/zstd",
 ]
+blurhashing = ["dep:image","dep:blurhash"]
 
 [dependencies]
 arrayvec.workspace = true
@@ -82,6 +83,8 @@ tracing.workspace = true
 url.workspace = true
 webpage.workspace = true
 webpage.optional = true
+blurhash.workspace = true
+blurhash.optional = true
 
 [lints]
 workspace = true

src/service/media/blurhash.rs

@@ -0,0 +1,176 @@
+use std::{error::Error, ffi::OsStr, fmt::Display, io::Cursor, path::Path};
+
+use conduwuit::{config::BlurhashConfig as CoreBlurhashConfig, err, implement, Result};
+use image::{DynamicImage, ImageDecoder, ImageError, ImageFormat, ImageReader};
+
+use super::Service;
+#[implement(Service)]
+pub fn create_blurhash(
+	&self,
+	file: &[u8],
+	content_type: Option<&str>,
+	file_name: Option<&str>,
+) -> Result<Option<String>> {
+	if !cfg!(feature = "blurhashing") {
+		return Ok(None);
+	}
+
+	let config = BlurhashConfig::from(self.services.server.config.blurhashing);
+
+	// since 0 means disabled blurhashing, skipped blurhashing
+	if config.size_limit == 0 {
+		return Ok(None);
+	}
+
+	get_blurhash_from_request(file, content_type, file_name, config)
+		.map_err(|e| err!(debug_error!("blurhashing error: {e}")))
+		.map(Some)
+}
+
+/// Returns the blurhash or a blurhash error which implements Display.
+#[tracing::instrument(
+	name = "blurhash",
+	level = "debug",
+	skip(data),
+	fields(
+		bytes = data.len(),
+	),
+)]
+fn get_blurhash_from_request(
+	data: &[u8],
+	mime: Option<&str>,
+	filename: Option<&str>,
+	config: BlurhashConfig,
+) -> Result<String, BlurhashingError> {
+	// Get format image is supposed to be in
+	let format = get_format_from_data_mime_and_filename(data, mime, filename)?;
+
+	// Get the image reader for said image format
+	let decoder = get_image_decoder_with_format_and_data(format, data)?;
+
+	// Check image size makes sense before unpacking whole image
+	if is_image_above_size_limit(&decoder, config) {
+		return Err(BlurhashingError::ImageTooLarge);
+	}
+
+	// decode the image finally
+	let image = DynamicImage::from_decoder(decoder)?;
+
+	blurhash_an_image(&image, config)
+}
+
+/// Gets the Image Format value from the data,mime, and filename
+/// It first checks if the mime is a valid image format
+/// Then it checks if the filename has a format, otherwise just guess based on
+/// the binary data Assumes that mime and filename extension won't be for a
+/// different file format than file.
+fn get_format_from_data_mime_and_filename(
+	data: &[u8],
+	mime: Option<&str>,
+	filename: Option<&str>,
+) -> Result<ImageFormat, BlurhashingError> {
+	let extension = filename
+		.map(Path::new)
+		.and_then(Path::extension)
+		.map(OsStr::to_string_lossy);
+
+	mime.or(extension.as_deref())
+		.and_then(ImageFormat::from_mime_type)
+		.map_or_else(|| image::guess_format(data).map_err(Into::into), Ok)
+}
+
+fn get_image_decoder_with_format_and_data(
+	image_format: ImageFormat,
+	data: &[u8],
+) -> Result<Box<dyn ImageDecoder + '_>, BlurhashingError> {
+	let mut image_reader = ImageReader::new(Cursor::new(data));
+	image_reader.set_format(image_format);
+	Ok(Box::new(image_reader.into_decoder()?))
+}
+
+fn is_image_above_size_limit<T: ImageDecoder>(
+	decoder: &T,
+	blurhash_config: BlurhashConfig,
+) -> bool {
+	decoder.total_bytes() >= blurhash_config.size_limit
+}
+
+#[cfg(feature = "blurhashing")]
+#[tracing::instrument(name = "encode", level = "debug", skip_all)]
+#[inline]
+fn blurhash_an_image(
+	image: &DynamicImage,
+	blurhash_config: BlurhashConfig,
+) -> Result<String, BlurhashingError> {
+	Ok(blurhash::encode_image(
+		blurhash_config.components_x,
+		blurhash_config.components_y,
+		&image.to_rgba8(),
+	)?)
+}
+
+#[cfg(not(feature = "blurhashing"))]
+#[inline]
+fn blurhash_an_image(
+	_image: &DynamicImage,
+	_blurhash_config: BlurhashConfig,
+) -> Result<String, BlurhashingError> {
+	Err(BlurhashingError::Unavailable)
+}
+
+#[derive(Clone, Copy, Debug)]
+pub struct BlurhashConfig {
+	pub components_x: u32,
+	pub components_y: u32,
+
+	/// size limit in bytes
+	pub size_limit: u64,
+}
+
+impl From<CoreBlurhashConfig> for BlurhashConfig {
+	fn from(value: CoreBlurhashConfig) -> Self {
+		Self {
+			components_x: value.components_x,
+			components_y: value.components_y,
+			size_limit: value.blurhash_max_raw_size,
+		}
+	}
+}
+
+#[derive(Debug)]
+pub enum BlurhashingError {
+	HashingLibError(Box<dyn Error + Send>),
+	ImageError(Box<ImageError>),
+	ImageTooLarge,
+
+	#[cfg(not(feature = "blurhashing"))]
+	Unavailable,
+}
+
+impl From<ImageError> for BlurhashingError {
+	fn from(value: ImageError) -> Self { Self::ImageError(Box::new(value)) }
+}
+
+#[cfg(feature = "blurhashing")]
+impl From<blurhash::Error> for BlurhashingError {
+	fn from(value: blurhash::Error) -> Self { Self::HashingLibError(Box::new(value)) }
+}
+
+impl Display for BlurhashingError {
+	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+		write!(f, "Blurhash Error:")?;
+		match &self {
+			| Self::ImageTooLarge => write!(f, "Image was too large to blurhash")?,
+			| Self::HashingLibError(e) =>
+				write!(f, "There was an error with the blurhashing library => {e}")?,
+
+			| Self::ImageError(e) =>
+				write!(f, "There was an error with the image loading library => {e}")?,
+
+			#[cfg(not(feature = "blurhashing"))]
+			| Self::Unavailable => write!(f, "Blurhashing is not supported")?,
+		};
+
+		Ok(())
+	}
+}

src/service/media/mod.rs

@@ -1,10 +1,10 @@
+pub mod blurhash;
 mod data;
 pub(super) mod migrations;
 mod preview;
 mod remote;
 mod tests;
 mod thumbnail;
-
 use std::{path::PathBuf, sync::Arc, time::SystemTime};
 
 use async_trait::async_trait;