rootcause 0.12.1

A flexible, ergonomic, and inspectable error reporting library for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

//! Migrating an application from anyhow to rootcause
//!
//! This example shows how to gradually adopt rootcause in an existing
//! anyhow-based codebase. We'll migrate a small application that uses
//! a key-value store with metrics collection.
//!
//! # Migration Strategies
//!
//! You can migrate in any order that makes sense for your codebase:
//!
//! - **Top-down** (application first): Use rootcause features immediately in
//!   your business logic. Call anyhow dependencies with `.into_rootcause()`.
//!
//! - **Bottom-up** (libraries first): Adopt rootcause internally while keeping
//!   anyhow-compatible public APIs using `.into_anyhow()`.
//!
//! - **Middle-out**: Not recommended - requires conversions in both directions.
//!
//! **Which to choose?** Start where you'll get the most value from rootcause's
//! features, and prefer loosely-connected code (leaf libraries or top-level
//! binaries). For most users, **starting top-down** is easiest - you get
//! immediate benefits and only need `.into_rootcause()` conversions.
//!
//! # This Example's Approach
//!
//! We demonstrate a **combination approach**: start top-down with the
//! application, then gradually convert dependencies. This is realistic when
//! you control all the code but want to be cautious about breaking changes.
//!
//! The example treats each component as if it came from a separate crate:
//! - `metrics`: A metrics collection library (pretend you depend on this)
//! - `kv_store`: A key-value store (pretend you depend on this too)
//! - Your application: The code you're migrating
//!
//! # Migration Stages
//!
//! Each stage is in its own file so you can open them side-by-side for
//! comparison:
//!
//! 1. **Stage 1** (`stage1.rs`): Everything uses anyhow (starting point)
//! 2. **Stage 2** (`stage2.rs`): Application converted to rootcause
//! 3. **Stage 3** (`stage3.rs`): Metrics library converted internally
//! 4. **Stage 4** (`stage4.rs`): KV store converted internally
//! 5. **Stage 5** (`stage5.rs`): Full migration complete (breaking change to
//!    public APIs)

// =============================================================================
// Stage 1: Everything uses anyhow
// =============================================================================
#[path = "anyhow_migration/stage1.rs"]
pub mod v1_original_anyhow;

// =============================================================================
// Stage 2: Application converted to rootcause
// =============================================================================
#[path = "anyhow_migration/stage2.rs"]
pub mod v2_main_converted;

// =============================================================================
// Stage 3: Metrics library converted internally
// =============================================================================
#[path = "anyhow_migration/stage3.rs"]
pub mod v3_metrics_converted;

// =============================================================================
// Stage 4: KV store converted internally
// =============================================================================
#[path = "anyhow_migration/stage4.rs"]
pub mod v4_kvstore_converted;

// =============================================================================
// Stage 5: Full migration complete
// =============================================================================
#[path = "anyhow_migration/stage5.rs"]
pub mod v5_trait_converted;

// =============================================================================
// Main - run all stages
// =============================================================================

fn main() {
    println!("Anyhow to Rootcause Migration Example");
    println!("======================================\n");

    println!("=== Stage 1: Original anyhow code ===\n");
    if let Err(e) = v1_original_anyhow::main::run() {
        eprintln!("Error: {:#}\n", e);
    }

    println!("\n=== Stage 2: Application converted (top-down) ===\n");
    if let Err(e) = v2_main_converted::main::run() {
        eprintln!("Error: {}\n", e);
    }

    println!("\n=== Stage 3: Metrics library converted internally ===\n");
    if let Err(e) = v3_metrics_converted::main::run() {
        eprintln!("Error: {}\n", e);
    }

    println!("\n=== Stage 4: KV store converted internally ===\n");
    if let Err(e) = v4_kvstore_converted::main::run() {
        eprintln!("Error: {}\n", e);
    }

    println!("\n=== Stage 5: Full conversion (breaking change) ===\n");
    if let Err(e) = v5_trait_converted::main::run() {
        eprintln!("Error: {}\n", e);
    }

    println!("\n=== Migration complete! ===");
    println!("\nKey takeaways:");
    println!("  • Start top-down for immediate benefits");
    println!("  • Use .into_rootcause() when calling dependencies");
    println!("  • Use .into_anyhow() when exposing anyhow-compatible APIs");
    println!("  • Convert public interfaces last (breaking change)");
    println!("  • Migration can be gradual - you don't have to do it all at once!");
}