use crate::{
global_context::current_scope_id, innerlude::provide_context, use_hook, Element, IntoDynNode,
Properties, ScopeId, Template, TemplateAttribute, TemplateNode, VNode,
};
use std::{
any::Any,
backtrace::Backtrace,
cell::{Ref, RefCell},
error::Error,
fmt::{Debug, Display},
rc::Rc,
str::FromStr,
};
/// A panic in a component that was caught by an error boundary.
///
///
///
/// WASM currently does not support caching unwinds, so this struct will not be created in WASM.
///
///
pub struct CapturedPanic {
#[allow(dead_code)]
/// The error that was caught
pub error: Box,
}
impl Debug for CapturedPanic {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("CapturedPanic").finish()
}
}
impl Display for CapturedPanic {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_fmt(format_args!("Encountered panic: {:?}", self.error))
}
}
impl Error for CapturedPanic {}
/// Provide an error boundary to catch errors from child components
pub fn provide_error_boundary() -> ErrorContext {
provide_context(ErrorContext::new(
Vec::new(),
current_scope_id().unwrap_or_else(|e| panic!("{}", e)),
))
}
/// A trait for any type that can be downcast to a concrete type and implements Debug. This is automatically implemented for all types that implement Any + Debug.
pub trait AnyError {
fn as_any(&self) -> &dyn Any;
fn as_error(&self) -> &dyn Error;
}
/// An wrapper error type for types that only implement Display. We use a inner type here to avoid overlapping implementations for DisplayError and impl Error
struct DisplayError(DisplayErrorInner);
impl From for DisplayError {
fn from(e: E) -> Self {
Self(DisplayErrorInner(Box::new(e)))
}
}
struct DisplayErrorInner(Box);
impl Display for DisplayErrorInner {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
self.0.fmt(f)
}
}
impl Debug for DisplayErrorInner {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
self.0.fmt(f)
}
}
impl Error for DisplayErrorInner {}
impl AnyError for DisplayError {
fn as_any(&self) -> &dyn Any {
&self.0 .0
}
fn as_error(&self) -> &dyn Error {
&self.0
}
}
/// Provides context methods to [`Result`] and [`Option`] types that are compatible with [`CapturedError`]
///
/// This trait is sealed and cannot be implemented outside of dioxus-core
pub trait Context: private::Sealed {
/// Add a visual representation of the error that the [`ErrorBoundary`] may render
///
/// # Example
/// ```rust
/// # use dioxus::prelude::*;
/// fn Component() -> Element {
/// // You can bubble up errors with `?` inside components, and event handlers
/// // Along with the error itself, you can provide a way to display the error by calling `show`
/// let number = "1234".parse::().show(|error| rsx! {
/// div {
/// background_color: "red",
/// color: "white",
/// "Error parsing number: {error}"
/// }
/// })?;
/// unimplemented!()
/// }
/// ```
fn show(self, display_error: impl FnOnce(&E) -> Element) -> Result;
/// Wrap the result additional context about the error that occurred.
///
/// # Example
/// ```rust
/// # use dioxus::prelude::*;
/// fn NumberParser() -> Element {
/// // You can bubble up errors with `?` inside components, and event handlers
/// // Along with the error itself, you can provide a way to display the error by calling `context`
/// let number = "-1234".parse::().context("Parsing number inside of the NumberParser")?;
/// unimplemented!()
/// }
/// ```
fn context(self, context: C) -> Result;
/// Wrap the result with additional context about the error that occurred. The closure will only be run if the Result is an error.
///
/// # Example
/// ```rust
/// # use dioxus::prelude::*;
/// fn NumberParser() -> Element {
/// // You can bubble up errors with `?` inside components, and event handlers
/// // Along with the error itself, you can provide a way to display the error by calling `context`
/// let number = "-1234".parse::().with_context(|| format!("Timestamp: {:?}", std::time::Instant::now()))?;
/// unimplemented!()
/// }
/// ```
fn with_context(self, context: impl FnOnce() -> C) -> Result;
}
impl Context for std::result::Result
where
E: Error + 'static,
{
fn show(self, display_error: impl FnOnce(&E) -> Element) -> Result {
// We don't use result mapping to avoid extra frames
match self {
std::result::Result::Ok(value) => Ok(value),
Err(error) => {
let render = display_error(&error).unwrap_or_default();
let mut error: CapturedError = error.into();
error.render = render;
Err(error)
}
}
}
fn context(self, context: C) -> Result {
self.with_context(|| context)
}
fn with_context(self, context: impl FnOnce() -> C) -> Result {
// We don't use result mapping to avoid extra frames
match self {
std::result::Result::Ok(value) => Ok(value),
Err(error) => {
let mut error: CapturedError = error.into();
error.context.push(Rc::new(AdditionalErrorContext {
backtrace: Backtrace::capture(),
context: Box::new(context()),
scope: current_scope_id().ok(),
}));
Err(error)
}
}
}
}
impl Context for Option {
fn show(self, display_error: impl FnOnce(&CapturedError) -> Element) -> Result {
// We don't use result mapping to avoid extra frames
match self {
Some(value) => Ok(value),
None => {
let mut error = CapturedError::from_display("Value was none");
let render = display_error(&error).unwrap_or_default();
error.render = render;
Err(error)
}
}
}
fn context(self, context: C) -> Result {
self.with_context(|| context)
}
fn with_context(self, context: impl FnOnce() -> C) -> Result {
// We don't use result mapping to avoid extra frames
match self {
Some(value) => Ok(value),
None => {
let error = CapturedError::from_display(context());
Err(error)
}
}
}
}
pub(crate) mod private {
use super::*;
pub trait Sealed {}
impl Sealed for std::result::Result where E: Error {}
impl Sealed for Option {}
}
impl AnyError for T {
fn as_any(&self) -> &dyn Any {
self
}
fn as_error(&self) -> &dyn Error {
self
}
}
/// A context with information about suspended components
#[derive(Debug, Clone)]
pub struct ErrorContext {
errors: Rc>>,
id: ScopeId,
}
impl PartialEq for ErrorContext {
fn eq(&self, other: &Self) -> bool {
Rc::ptr_eq(&self.errors, &other.errors)
}
}
impl ErrorContext {
/// Create a new suspense boundary in a specific scope
pub(crate) fn new(errors: Vec, id: ScopeId) -> Self {
Self {
errors: Rc::new(RefCell::new(errors)),
id,
}
}
/// Get all errors thrown from child components
pub fn errors(&self) -> Ref<[CapturedError]> {
Ref::map(self.errors.borrow(), |errors| errors.as_slice())
}
/// Get the Element from the first error that can be shown
pub fn show(&self) -> Option {
self.errors.borrow().iter().find_map(|task| task.show())
}
/// Push an error into this Error Boundary
pub fn insert_error(&self, error: CapturedError) {
self.errors.borrow_mut().push(error);
self.id.needs_update();
}
/// Clear all errors from this Error Boundary
pub fn clear_errors(&self) {
self.errors.borrow_mut().clear();
self.id.needs_update();
}
}
/// Errors can have additional context added as they bubble up the render tree
/// This context can be used to provide additional information to the user
struct AdditionalErrorContext {
backtrace: Backtrace,
context: Box,
scope: Option,
}
impl Debug for AdditionalErrorContext {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("ErrorContext")
.field("backtrace", &self.backtrace)
.field("context", &self.context.to_string())
.finish()
}
}
impl Display for AdditionalErrorContext {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let AdditionalErrorContext {
backtrace,
context,
scope,
} = self;
write!(f, "{context} (from ")?;
if let Some(scope) = scope {
write!(f, "scope {scope:?} ")?;
}
write!(f, "at {backtrace:?})")
}
}
/// A type alias for a result that can be either a boxed error or a value
/// This is useful to avoid having to use `Result` everywhere
pub type Result = std::result::Result;
/// A helper function for an Ok result that can be either a boxed error or a value
/// This is useful to avoid having to use `Ok` everywhere
#[allow(non_snake_case)]
pub fn Ok(value: T) -> Result {
Result::Ok(value)
}
#[derive(Clone)]
/// An instance of an error captured by a descendant component.
pub struct CapturedError {
/// The error captured by the error boundary
error: Rc,
/// The backtrace of the error
backtrace: Rc,
/// The scope that threw the error
scope: ScopeId,
/// An error message that can be displayed to the user
pub(crate) render: VNode,
/// Additional context that was added to the error
context: Vec>,
}
impl FromStr for CapturedError {
type Err = std::convert::Infallible;
fn from_str(s: &str) -> std::result::Result {
std::result::Result::Ok(Self::from_display(s.to_string()))
}
}
#[cfg(feature = "serialize")]
#[derive(serde::Serialize, serde::Deserialize)]
struct SerializedCapturedError {
error: String,
context: Vec,
}
#[cfg(feature = "serialize")]
impl serde::Serialize for CapturedError {
fn serialize(
&self,
serializer: S,
) -> std::result::Result {
let serialized = SerializedCapturedError {
error: self.error.as_error().to_string(),
context: self
.context
.iter()
.map(|context| context.to_string())
.collect(),
};
serialized.serialize(serializer)
}
}
#[cfg(feature = "serialize")]
impl<'de> serde::Deserialize<'de> for CapturedError {
fn deserialize>(
deserializer: D,
) -> std::result::Result {
let serialized = SerializedCapturedError::deserialize(deserializer)?;
let error = DisplayError::from(serialized.error);
let context = serialized
.context
.into_iter()
.map(|context| {
Rc::new(AdditionalErrorContext {
scope: None,
backtrace: Backtrace::disabled(),
context: Box::new(context),
})
})
.collect();
std::result::Result::Ok(Self {
error: Rc::new(error),
context,
backtrace: Rc::new(Backtrace::disabled()),
scope: ScopeId::ROOT,
render: VNode::placeholder(),
})
}
}
impl Debug for CapturedError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("CapturedError")
.field("error", &self.error.as_error())
.field("backtrace", &self.backtrace)
.field("scope", &self.scope)
.finish()
}
}
impl From for CapturedError {
fn from(error: E) -> Self {
Self {
error: Rc::new(error),
backtrace: Rc::new(Backtrace::capture()),
scope: current_scope_id()
.expect("Cannot create an error boundary outside of a component's scope."),
render: Default::default(),
context: Default::default(),
}
}
}
impl CapturedError {
/// Create a new captured error
pub fn new(error: impl AnyError + 'static) -> Self {
Self {
error: Rc::new(error),
backtrace: Rc::new(Backtrace::capture()),
scope: current_scope_id().unwrap_or(ScopeId::ROOT),
render: Default::default(),
context: Default::default(),
}
}
/// Create a new error from a type that only implements [`Display`]. If your type implements [`Error`], you can use [`CapturedError::from`] instead.
pub fn from_display(error: impl Display + 'static) -> Self {
Self {
error: Rc::new(DisplayError::from(error)),
backtrace: Rc::new(Backtrace::capture()),
scope: current_scope_id().unwrap_or(ScopeId::ROOT),
render: Default::default(),
context: Default::default(),
}
}
/// Mark the error as being thrown from a specific scope
pub fn with_origin(mut self, scope: ScopeId) -> Self {
self.scope = scope;
self
}
/// Get a VNode representation of the error if the error provides one
pub fn show(&self) -> Option {
if self.render == VNode::placeholder() {
None
} else {
Some(std::result::Result::Ok(self.render.clone()))
}
}
/// Create a deep clone of this error
pub(crate) fn deep_clone(&self) -> Self {
Self {
render: self.render.deep_clone(),
..self.clone()
}
}
}
impl PartialEq for CapturedError {
fn eq(&self, other: &Self) -> bool {
format!("{:?}", self) == format!("{:?}", other)
}
}
impl Display for CapturedError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_fmt(format_args!(
"Encountered error: {:?}\nIn scope: {:?}\nBacktrace: {}\nContext: ",
self.error.as_error(),
self.scope,
self.backtrace
))?;
for context in &*self.context {
f.write_fmt(format_args!("{}\n", context))?;
}
std::result::Result::Ok(())
}
}
impl CapturedError {
/// Downcast the error type into a concrete error type
pub fn downcast(&self) -> Option<&T> {
self.error.as_any().downcast_ref::()
}
}
pub(crate) fn throw_into(error: impl Into, scope: ScopeId) {
let error = error.into();
if let Some(cx) = scope.consume_context::() {
cx.insert_error(error)
} else {
tracing::error!(
"Tried to throw an error into an error boundary, but failed to locate a boundary: {:?}",
error
)
}
}
#[allow(clippy::type_complexity)]
#[derive(Clone)]
pub struct ErrorHandler(Rc Element>);
impl Element + 'static> From for ErrorHandler {
fn from(value: F) -> Self {
Self(Rc::new(value))
}
}
fn default_handler(errors: ErrorContext) -> Element {
static TEMPLATE: Template = Template {
roots: &[TemplateNode::Element {
tag: "div",
namespace: None,
attrs: &[TemplateAttribute::Static {
name: "color",
namespace: Some("style"),
value: "red",
}],
children: &[TemplateNode::Dynamic { id: 0usize }],
}],
node_paths: &[&[0u8, 0u8]],
attr_paths: &[],
};
std::result::Result::Ok(VNode::new(
None,
TEMPLATE,
Box::new([errors
.errors()
.iter()
.map(|e| {
static TEMPLATE: Template = Template {
roots: &[TemplateNode::Element {
tag: "pre",
namespace: None,
attrs: &[],
children: &[TemplateNode::Dynamic { id: 0usize }],
}],
node_paths: &[&[0u8, 0u8]],
attr_paths: &[],
};
VNode::new(
None,
TEMPLATE,
Box::new([e.to_string().into_dyn_node()]),
Default::default(),
)
})
.into_dyn_node()]),
Default::default(),
))
}
#[derive(Clone)]
pub struct ErrorBoundaryProps {
children: Element,
handle_error: ErrorHandler,
}
impl ErrorBoundaryProps {
/**
Create a builder for building `ErrorBoundaryProps`.
On the builder, call `.children(...)`(optional), `.handle_error(...)`(optional) to set the values of the fields.
Finally, call `.build()` to create the instance of `ErrorBoundaryProps`.
*/
#[allow(dead_code)]
pub fn builder() -> ErrorBoundaryPropsBuilder<((), ())> {
ErrorBoundaryPropsBuilder { fields: ((), ()) }
}
}
#[must_use]
#[doc(hidden)]
#[allow(dead_code, non_camel_case_types, non_snake_case)]
pub struct ErrorBoundaryPropsBuilder {
fields: TypedBuilderFields,
}
impl Clone for ErrorBoundaryPropsBuilder
where
TypedBuilderFields: Clone,
{
fn clone(&self) -> Self {
Self {
fields: self.fields.clone(),
}
}
}
impl Properties for ErrorBoundaryProps {
type Builder = ErrorBoundaryPropsBuilder<((), ())>;
fn builder() -> Self::Builder {
ErrorBoundaryProps::builder()
}
fn memoize(&mut self, other: &Self) -> bool {
*self = other.clone();
false
}
}
#[doc(hidden)]
#[allow(dead_code, non_camel_case_types, non_snake_case)]
pub trait ErrorBoundaryPropsBuilder_Optional {
fn into_value T>(self, default: F) -> T;
}
impl ErrorBoundaryPropsBuilder_Optional for () {
fn into_value T>(self, default: F) -> T {
default()
}
}
impl ErrorBoundaryPropsBuilder_Optional for (T,) {
fn into_value T>(self, _: F) -> T {
self.0
}
}
#[allow(dead_code, non_camel_case_types, missing_docs)]
impl<__handle_error> ErrorBoundaryPropsBuilder<((), __handle_error)> {
pub fn children(
self,
children: Element,
) -> ErrorBoundaryPropsBuilder<((Element,), __handle_error)> {
let children = (children,);
let (_, handle_error) = self.fields;
ErrorBoundaryPropsBuilder {
fields: (children, handle_error),
}
}
}
#[doc(hidden)]
#[allow(dead_code, non_camel_case_types, non_snake_case)]
pub enum ErrorBoundaryPropsBuilder_Error_Repeated_field_children {}
#[doc(hidden)]
#[allow(dead_code, non_camel_case_types, missing_docs)]
impl<__handle_error> ErrorBoundaryPropsBuilder<((Element,), __handle_error)> {
#[deprecated(note = "Repeated field children")]
pub fn children(
self,
_: ErrorBoundaryPropsBuilder_Error_Repeated_field_children,
) -> ErrorBoundaryPropsBuilder<((Element,), __handle_error)> {
self
}
}
#[allow(dead_code, non_camel_case_types, missing_docs)]
impl<__children> ErrorBoundaryPropsBuilder<(__children, ())> {
pub fn handle_error(
self,
handle_error: impl ::core::convert::Into,
) -> ErrorBoundaryPropsBuilder<(__children, (ErrorHandler,))> {
let handle_error = (handle_error.into(),);
let (children, _) = self.fields;
ErrorBoundaryPropsBuilder {
fields: (children, handle_error),
}
}
}
#[doc(hidden)]
#[allow(dead_code, non_camel_case_types, non_snake_case)]
pub enum ErrorBoundaryPropsBuilder_Error_Repeated_field_handle_error {}
#[doc(hidden)]
#[allow(dead_code, non_camel_case_types, missing_docs)]
impl<__children> ErrorBoundaryPropsBuilder<(__children, (ErrorHandler,))> {
#[deprecated(note = "Repeated field handle_error")]
pub fn handle_error(
self,
_: ErrorBoundaryPropsBuilder_Error_Repeated_field_handle_error,
) -> ErrorBoundaryPropsBuilder<(__children, (ErrorHandler,))> {
self
}
}
#[allow(dead_code, non_camel_case_types, missing_docs)]
impl<
__handle_error: ErrorBoundaryPropsBuilder_Optional,
__children: ErrorBoundaryPropsBuilder_Optional,
> ErrorBoundaryPropsBuilder<(__children, __handle_error)>
{
pub fn build(self) -> ErrorBoundaryProps {
let (children, handle_error) = self.fields;
let children = ErrorBoundaryPropsBuilder_Optional::into_value(children, VNode::empty);
let handle_error = ErrorBoundaryPropsBuilder_Optional::into_value(handle_error, || {
ErrorHandler(Rc::new(default_handler))
});
ErrorBoundaryProps {
children,
handle_error,
}
}
}
/// Create a new error boundary component that catches any errors thrown from child components
///
/// ## Details
///
/// Error boundaries handle errors within a specific part of your application. They are similar to `try/catch` in JavaScript, but they only catch errors in the tree below them.
/// Any errors passed up from a child will be caught by the nearest error boundary. Error boundaries are quick to implement, but it can be useful to individually handle errors
/// in your components to provide a better user experience when you know that an error is likely to occur.
///
/// ## Example
///
/// ```rust, no_run
/// use dioxus::prelude::*;
///
/// fn App() -> Element {
/// let mut multiplier = use_signal(|| String::from("2"));
/// rsx! {
/// input {
/// r#type: "text",
/// value: multiplier,
/// oninput: move |e| multiplier.set(e.value())
/// }
/// ErrorBoundary {
/// handle_error: |errors: ErrorContext| {
/// rsx! {
/// div {
/// "Oops, we encountered an error. Please report {errors:?} to the developer of this application"
/// }
/// }
/// },
/// Counter {
/// multiplier
/// }
/// }
/// }
/// }
///
/// #[component]
/// fn Counter(multiplier: ReadOnlySignal) -> Element {
/// let multiplier_parsed = multiplier().parse::()?;
/// let mut count = use_signal(|| multiplier_parsed);
/// rsx! {
/// button {
/// onclick: move |_| {
/// let multiplier_parsed = multiplier().parse::()?;
/// *count.write() *= multiplier_parsed;
/// Ok(())
/// },
/// "{count}x{multiplier}"
/// }
/// }
/// }
/// ```
///
/// ## Resetting the error boundary
///
/// Once the error boundary catches an error, it will render the rsx returned from the handle_error function instead of the children. To reset the error boundary,
/// you can call the [`ErrorContext::clear_errors`] method. This will clear all errors and re-render the children.
///
/// ```rust, no_run
/// # use dioxus::prelude::*;
/// fn App() -> Element {
/// let mut multiplier = use_signal(|| String::new());
/// rsx! {
/// input {
/// r#type: "text",
/// value: multiplier,
/// oninput: move |e| multiplier.set(e.value())
/// }
/// ErrorBoundary {
/// handle_error: |errors: ErrorContext| {
/// rsx! {
/// div {
/// "Oops, we encountered an error. Please report {errors:?} to the developer of this application"
/// }
/// button {
/// onclick: move |_| {
/// errors.clear_errors();
/// },
/// "try again"
/// }
/// }
/// },
/// Counter {
/// multiplier
/// }
/// }
/// }
/// }
///
/// #[component]
/// fn Counter(multiplier: ReadOnlySignal) -> Element {
/// let multiplier_parsed = multiplier().parse::()?;
/// let mut count = use_signal(|| multiplier_parsed);
/// rsx! {
/// button {
/// onclick: move |_| {
/// let multiplier_parsed = multiplier().parse::()?;
/// *count.write() *= multiplier_parsed;
/// Ok(())
/// },
/// "{count}x{multiplier}"
/// }
/// }
/// }
/// ```
#[allow(non_upper_case_globals, non_snake_case)]
pub fn ErrorBoundary(props: ErrorBoundaryProps) -> Element {
let error_boundary = use_hook(provide_error_boundary);
let errors = error_boundary.errors();
let has_errors = !errors.is_empty();
// Drop errors before running user code that might borrow the error lock
drop(errors);
if has_errors {
(props.handle_error.0)(error_boundary.clone())
} else {
std::result::Result::Ok({
static TEMPLATE: Template = Template {
roots: &[TemplateNode::Dynamic { id: 0usize }],
node_paths: &[&[0u8]],
attr_paths: &[],
};
VNode::new(
None,
TEMPLATE,
Box::new([(props.children).into_dyn_node()]),
Default::default(),
)
})
}
}