arminius_lib_component/

error.rs

// SPDX-FileCopyrightText: 2025 BWI GmbH
//
// SPDX-License-Identifier: Apache-2.0

//! Easy error handling types for the Matrix API
//!
//! Contains the trait MatrixApiError, and a couple of error types that are
//! shared across a lot of endpoints. Every error that can be returned to the
//! user should implement [MatrixApiError], and
//! [`axum::response::IntoResponse`], preferably through the derive macro
//! [`MatrixApiError`](derive@MatrixApiError)
//!
//! The point of MatrixApiError, in contrast to other error types in Arminius,
//! is to handle errors from which no recovery is possible. This can happen
//! either because it's a "this should never happen bug", like an invalid
//! database state, or because the error is due to user input.
//!
//! From this it follows that the only job of a MatrixApiError is to return
//! information to the user, and not to provide diagnostics. Diagnostics should,
//! if needed, be emitted in the [`From<T>`] trait for the relevant error type,
//! because that is the point at which we give up on handling the error, and
//! begin propagating it.

mod tests;

use std::panic::Location;

/// Re-export the MatrixApiError derive macro here, so one just needs to depend
/// on arminius-lib-component when implementing MatrixApiErrors.
pub use arminius_lib_macros::__MatrixApiError as MatrixApiError;
use axum::http::StatusCode;
use ruma::api::error::{
	Error as MatrixError, ErrorBody as MatrixErrorBody, ErrorKind, StandardErrorBody,
};
use serde::{Deserialize, Serialize};
use serde_json::json;

/// Trait for errors that can be converted into matrix errors
pub trait MatrixApiError {
	/// Create a matrix error from the error
	fn create_matrix_error(&self) -> MatrixError;
}

/// Create a matrix error
#[must_use]
pub fn create_matrix_error(status_code: StatusCode, kind: &ErrorKind, error: &str) -> MatrixError {
	MatrixErrorBody::Standard(StandardErrorBody::new(kind.clone(), error.to_owned()))
		.into_error(status_code)
}

/// Create a custom matrix error
#[must_use]
pub fn create_custom_matrix_error(
	status_code: StatusCode,
	errcode: &str,
	error: &str,
) -> MatrixError {
	MatrixErrorBody::Json(json!({
		"errcode": errcode,
		"error": error,
	}))
	.into_error(status_code)
}

/// Error for when user sends us invalid JSON
#[derive(thiserror::Error, Debug, MatrixApiError, Serialize, Deserialize)]
#[matrix_api_error(status_code = StatusCode::BAD_REQUEST, error_kind = ErrorKind::NotJson, component_crate_root = crate)]
#[error("{0}")]
pub struct NotJson(pub String);

/// Error when user JSON is missing fields
#[derive(thiserror::Error, Debug, MatrixApiError, Serialize, Deserialize)]
#[matrix_api_error(status_code = StatusCode::BAD_REQUEST, error_kind = ErrorKind::BadJson, component_crate_root = crate)]
#[error("{0}")]
pub struct BadJson(pub String);

/// Error type that may occur when working with user-provided JSON.
///
/// This error type figures out on its own whether the error is due to invalid
/// JSON or JSON not matching the object we're trying to deserialize.
/// It will then use the underlying serde error to produce a nice error message,
/// which points out exactly what in the user's JSON string was invalid.
///
/// The main point of this type is that it provides [`From<serde_json::Error>`].
/// It should be used in a handler like this:
///
/// ```rust
/// # use arminius_lib_component::error::InputJsonError;
/// # use arminius_lib_component::ruma_requests::ArminiusResponse;
/// # use ruma::api::client::config::set_room_account_data;
/// # use ruma::events::AnyRoomAccountDataEventContent;
/// # use ruma::serde::Raw;
/// async fn room_account_data_set(
/// 	account_data: Raw<AnyRoomAccountDataEventContent>,
/// ) -> Result<
/// 	ArminiusResponse<set_room_account_data::v3::Response>,
/// 	InputJsonError,
/// > {
/// 	let value: serde_json::Value =
/// 		serde_json::to_value(account_data.into_json())
/// 			.map_err(InputJsonError::from)?;
///
/// 	/* Save the user data somehow */
///
/// 	Ok(set_room_account_data::v3::Response::new().into())
/// }
/// ```
///
/// <div class="example-wrap" style="display:inline-block"><pre
/// class="compile_fail" style="white-space:normal;font:inherit;">
///
/// **Warning**: This error type is meant to simplify the error handling for
/// <b>user input</b>, provided as part of the current request. If you use it
/// with data that was not provided by the user as part of this request, you
/// will risk returning "Bad Request" when the request is perfectly fine.
///
/// This means that you should not use this error type when processing
/// information that you have loaded from the database. If the database has
/// inconsistent data, that does not mean that the user has made a bad request.
///
/// You also risk creating security issues, by leaking information to the user
/// about data they would not have access to otherwise as part of the error.
///
/// </pre></div>
#[derive(thiserror::Error, Debug, MatrixApiError, Serialize, Deserialize)]
#[matrix_api_error(component_crate_root = crate)]
pub enum InputJsonError {
	/// Error in JSON parsing, due to an IO error. This is not the users fault,
	/// so they don't get to hear about it.
	#[error(transparent)]
	InternalServerError(InternalServerError),
	/// The data the user provided is not correct JSON
	#[error(transparent)]
	NotJson(NotJson),
	/// The JSON that the user provided cannot be deserialized into the
	/// requested datatype
	#[error(transparent)]
	BadJson(BadJson),
}

impl From<serde_json::Error> for InputJsonError {
	fn from(value: serde_json::Error) -> Self {
		match value.classify() {
			serde_json::error::Category::Io => {
				InputJsonError::InternalServerError(InternalServerError)
			}
			serde_json::error::Category::Data => {
				InputJsonError::BadJson(BadJson(value.to_string()))
			}
			serde_json::error::Category::Eof | serde_json::error::Category::Syntax => {
				InputJsonError::NotJson(NotJson(value.to_string()))
			}
		}
	}
}

#[expect(
	missing_docs,
	reason = "TODO(#2003): This exception predates us enabling `clippy::allow_attributes_without_reason`, so we don't know why it was enabled"
)]
#[derive(thiserror::Error, Debug, MatrixApiError, Serialize, Deserialize)]
#[matrix_api_error(status_code = StatusCode::NOT_FOUND, error_kind = ErrorKind::NotFound, component_crate_root = crate)]
#[error("Event not found")]
pub struct EventNotFound;

#[expect(
	missing_docs,
	reason = "TODO(#2003): This exception predates us enabling `clippy::allow_attributes_without_reason`, so we don't know why it was enabled"
)]
#[derive(thiserror::Error, Debug, MatrixApiError, Serialize, Deserialize)]
#[matrix_api_error(status_code = StatusCode::NOT_FOUND, error_kind = ErrorKind::NotFound, component_crate_root = crate)]
#[error("Room not found")]
pub struct RoomNotFound;

#[expect(
	missing_docs,
	reason = "TODO(#2003): This exception predates us enabling `clippy::allow_attributes_without_reason`, so we don't know why it was enabled"
)]
#[derive(thiserror::Error, Debug, MatrixApiError, Serialize, Deserialize)]
#[matrix_api_error(status_code = StatusCode::UNAUTHORIZED, error_kind = ErrorKind::Unauthorized, component_crate_root = crate)]
#[error("Unauthorized")]
pub struct Unauthorized;

#[expect(
	missing_docs,
	reason = "TODO(#2003): This exception predates us enabling `clippy::allow_attributes_without_reason`, so we don't know why it was enabled"
)]
#[derive(thiserror::Error, Debug, MatrixApiError, Serialize, Deserialize)]
#[matrix_api_error(status_code = StatusCode::FORBIDDEN, error_kind = ErrorKind::Forbidden, component_crate_root = crate)]
#[error("Forbidden")]
pub struct Forbidden;

/// A feature that has not been implemented.
///
/// While HTTP has the `501 NOT IMPLEMENTED` return code, the Matrix spec
/// specifically decided not to use it.
#[derive(thiserror::Error, Debug, MatrixApiError, Serialize, Deserialize, Eq, PartialEq)]
#[matrix_api_error(status_code = StatusCode::BAD_REQUEST, error_kind = ErrorKind::InvalidParam, component_crate_root = crate)]
#[error("Feature not implemented: {0}")]
pub struct FeatureNotImplemented(pub String);

impl FeatureNotImplemented {
	/// Throws `FeatureNotImplemented` if the `is_used` boolean is true
	/// saying that `feature` is not implemented yet.
	///
	/// # Examples
	/// This will throw an error if the `ruma_request.event_type` is **not**
	/// `MessageLikeEventType::RoomMessage`:
	/// ```ignore
	/// FeatureNotImplemented::feature_is_used(
	/// 	ruma_request.event_type != MessageLikeEventType::RoomMessage,
	/// 	"Non-message room events".to_owned(),
	/// )?
	/// ```
	pub fn feature_is_used(is_used: bool, feature: String) -> Result<(), Self> {
		if is_used { Err(Self(feature)) } else { Ok(()) }
	}
}

/// Represents an unrecoverable error
///
/// When an error is encountered in the program, that we are unable to handle,
/// use `unrecoverable_error` to convert it into an [`InternalServerError`].
/// This way the error message gets logged, and the correct API response gets
/// returned to the user.
#[derive(thiserror::Error, Debug, MatrixApiError, Serialize, Deserialize, PartialEq, Eq)]
#[matrix_api_error(status_code = StatusCode::INTERNAL_SERVER_ERROR, error_kind = ErrorKind::Unknown, component_crate_root = crate)]
#[error("Internal server error")]
#[non_exhaustive]
pub struct InternalServerError;

impl InternalServerError {
	/// Allows creating an internal server error, which does not get logged
	///
	/// Useful if implementing a traced From handler, which uses
	/// InternalServerError as an in-between step.
	#[must_use]
	pub fn untraced_internal_server_error() -> Self {
		InternalServerError
	}
}

impl From<arminius_lib_db::DatabaseError> for InternalServerError {
	#[track_caller]
	fn from(err: arminius_lib_db::DatabaseError) -> Self {
		let location = Location::caller();
		tracing::error!(?err, ?location, "Error communicating with database");
		InternalServerError
	}
}

impl From<arminius_lib_nats::NatsError> for InternalServerError {
	#[track_caller]
	fn from(err: arminius_lib_nats::NatsError) -> Self {
		let location = Location::caller();
		tracing::error!(?err, ?location, "Error performing NATS call");
		InternalServerError
	}
}

/// Extension trait for [`Result`] that allows us to handle unrecoverable errors
pub trait ResultExt<T> {
	/// Equivalent to `map_err`, but always maps to [`InternalServerError`],
	/// logging the error and context
	fn unrecoverable_error(self, context: &str) -> Result<T, InternalServerError>;
}

// The E bound may look weird, and needs a potentially unnecessary allocation,
// but it accepts `thiserror` and `color_eyre` Errors.
impl<'a, T, E: Into<Box<dyn std::error::Error + 'a>>> ResultExt<T> for Result<T, E> {
	#[track_caller]
	fn unrecoverable_error(self, context: &str) -> Result<T, InternalServerError> {
		match self {
			Ok(value) => Ok(value),
			Err(err) => {
				let location = Location::caller();
				let err = err.into();
				tracing::error!(?err, context, ?location, "Encountered unrecoverable error");
				Err(InternalServerError)
			}
		}
	}
}

impl<T> ResultExt<T> for Option<T> {
	#[track_caller]
	fn unrecoverable_error(self, context: &str) -> Result<T, InternalServerError> {
		match self {
			Some(value) => Ok(value),
			None => {
				let location = Location::caller();
				tracing::error!(context, ?location, "Expected some");
				Err(InternalServerError)
			}
		}
	}
}

impl InternalServerError {
	/// Check that the condition `cond` is true, and if not, return an internal
	/// server error, and log the context string and line where the issue arose
	#[track_caller]
	pub fn assert(cond: bool, context: &str) -> Result<(), InternalServerError> {
		if cond {
			Ok(())
		} else {
			let location = Location::caller();
			tracing::error!(context, ?location, "Assertion failed");
			Err(InternalServerError)
		}
	}
}