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
28//! guarantees are provided. Users should depend on the [`rootcause`] crate, not
29//! this one.
30//!
31//! # Architecture
32//!
33//! The crate is organized around two parallel type hierarchies for attachments
34//! and reports:
35//!
36//! - **[`attachment`]**: Type-erased attachment storage
37//! - [`RawAttachment`]: Owned attachment with [`Box`]-based allocation
38//! - [`RawAttachmentRef`]: Borrowed reference to an attachment
39//! - [`AttachmentData`]: `#[repr(C)]` wrapper enabling field access on erased
40//! types
41//! - [`AttachmentVtable`]: Function pointers for type-erased dispatch
42//!
43//! - **[`report`]**: Type-erased report storage (similar structure)
44//! - [`RawReport`]: Owned report with [`Arc`]-based allocation
45//! - [`RawReportRef`]/[`RawReportMut`]: Borrowed references (shared/mutable)
46//! - [`ReportData`]: `#[repr(C)]` wrapper for field access
47//! - [`ReportVtable`]: Function pointers for dispatch
48//!
49//! - **[`handlers`]**: Trait definitions for formatting and behavior
50//! - [`ContextHandler`]: Defines how error contexts are formatted
51//! - [`AttachmentHandler`]: Defines how attachments are formatted
52//!
53//! # Safety Strategy
54//!
55//! Type erasure requires careful handling to maintain Rust's type safety
56//! guarantees. When we erase a type like `AttachmentData<MyError>` to
57//! `AttachmentData<Erased>`, we must ensure that the vtable function pointers
58//! still match the actual concrete type stored in memory.
59//!
60//! This crate maintains safety through:
61//!
62//! - **Module-based encapsulation**: Safety-critical types keep fields
63//! module-private, making invariants locally verifiable within a single file
64//! - **`#[repr(C)]` layout**: Enables safe field projection on type-erased
65//! pointers without constructing invalid references
66//! - **Documented vtable contracts**: Each vtable method specifies exactly when
67//! it can be safely called
68//!
69//! See the individual module documentation ([`attachment`], [`report`]) for
70//! detailed explanations of how these patterns are applied.
71//!
72//! [`rootcause`]: https://docs.rs/rootcause/latest/rootcause/
73//! [`AttachmentData`]: attachment::data::AttachmentData
74//! [`AttachmentVtable`]: attachment::vtable::AttachmentVtable
75//! [`ReportData`]: report::data::ReportData
76//! [`ReportVtable`]: report::vtable::ReportVtable
77//! [`ContextHandler`]: handlers::ContextHandler
78//! [`AttachmentHandler`]: handlers::AttachmentHandler
79//! [`Box`]: alloc::boxed::Box
80//! [`Arc`]: triomphe::Arc
81
82extern crate alloc;
83
84mod attachment;
85pub mod handlers;
86mod report;
87mod util;
88
89pub use attachment::{RawAttachment, RawAttachmentRef};
90pub use report::{RawReport, RawReportMut, RawReportRef};