rootcause_internals/lib.rs
1#![no_std]
2#![forbid(
3 missing_docs,
4 clippy::alloc_instead_of_core,
5 clippy::std_instead_of_alloc,
6 clippy::std_instead_of_core,
7 clippy::missing_safety_doc,
8 clippy::missing_docs_in_private_items,
9 clippy::undocumented_unsafe_blocks,
10 clippy::multiple_unsafe_ops_per_block,
11 clippy::as_ptr_cast_mut,
12 clippy::ptr_as_ptr,
13 rustdoc::invalid_rust_codeblocks,
14 rustdoc::broken_intra_doc_links,
15 missing_copy_implementations,
16 unused_doc_comments
17)]
18#![allow(rustdoc::private_intra_doc_links)]
19//! Internal implementation crate for [`rootcause`].
20//!
21//! # Overview
22//!
23//! This crate contains the low-level, type-erased data structures and unsafe
24//! operations that power the [`rootcause`] error reporting library. It provides
25//! the foundation for zero-cost type erasure through vtable-based dispatch.
26//!
27//! **This crate is an implementation detail.** No semantic versioning guarantees
28//! are provided. Users should depend on the [`rootcause`] crate, not this one.
29//!
30//! # Architecture
31//!
32//! The crate is organized around two parallel type hierarchies for attachments
33//! and reports:
34//!
35//! - **[`attachment`]**: Type-erased attachment storage
36//! - [`RawAttachment`]: Owned attachment with [`Box`]-based allocation
37//! - [`RawAttachmentRef`]: Borrowed reference to an attachment
38//! - [`AttachmentData`]: `#[repr(C)]` wrapper enabling field access on erased types
39//! - [`AttachmentVtable`]: Function pointers for type-erased dispatch
40//!
41//! - **[`report`]**: Type-erased report storage (similar structure)
42//! - [`RawReport`]: Owned report with [`Arc`]-based allocation
43//! - [`RawReportRef`]/[`RawReportMut`]: Borrowed references (shared/mutable)
44//! - [`ReportData`]: `#[repr(C)]` wrapper for field access
45//! - [`ReportVtable`]: Function pointers for dispatch
46//!
47//! - **[`handlers`]**: Trait definitions for formatting and behavior
48//! - [`ContextHandler`]: Defines how error contexts are formatted
49//! - [`AttachmentHandler`]: Defines how attachments are formatted
50//!
51//! # Safety Strategy
52//!
53//! Type erasure requires careful handling to maintain Rust's type safety
54//! guarantees. When we erase a type like `AttachmentData<MyError>` to
55//! `AttachmentData<Erased>`, we must ensure that the vtable function pointers
56//! still match the actual concrete type stored in memory.
57//!
58//! This crate maintains safety through:
59//!
60//! - **Module-based encapsulation**: Safety-critical types keep fields
61//! module-private, making invariants locally verifiable within a single file
62//! - **`#[repr(C)]` layout**: Enables safe field projection on type-erased
63//! pointers without constructing invalid references
64//! - **Documented vtable contracts**: Each vtable method specifies exactly when
65//! it can be safely called
66//!
67//! See the individual module documentation ([`attachment`], [`report`]) for
68//! detailed explanations of how these patterns are applied.
69//!
70//! [`rootcause`]: https://docs.rs/rootcause/latest/rootcause/
71//! [`AttachmentData`]: attachment::data::AttachmentData
72//! [`AttachmentVtable`]: attachment::vtable::AttachmentVtable
73//! [`ReportData`]: report::data::ReportData
74//! [`ReportVtable`]: report::vtable::ReportVtable
75//! [`ContextHandler`]: handlers::ContextHandler
76//! [`AttachmentHandler`]: handlers::AttachmentHandler
77//! [`Box`]: alloc::boxed::Box
78//! [`Arc`]: triomphe::Arc
79
80extern crate alloc;
81
82mod attachment;
83pub mod handlers;
84mod report;
85mod util;
86
87pub use attachment::{RawAttachment, RawAttachmentRef};
88pub use report::{RawReport, RawReportMut, RawReportRef};