caudal_sdk/lib.rs
1//! # Caudal SDK
2//!
3//! Observability SDK for event-driven distributed systems.
4//!
5//! Caudal is an observability system that records and correlates events
6//! describing how a message flows through a distributed system.
7//!
8//! ## Features
9//!
10//! - **Append-only**: Only records events, never modifies them.
11//! - **Event-only**: Does not transport business payloads.
12//! - **Asynchronous**: Designed not to block production flows.
13//! - **Idempotent**: Safe for retries.
14//! - **Production-safe**: Never breaks the system using it.
15//!
16//! ## Basic Usage
17//!
18//! ```rust,no_run
19//! use caudal_sdk::{
20//! FlowEventBuilder, CaudalEmitter,
21//! NodeType, FlowStage, FlowStatus, AckType,
22//! };
23//!
24//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
25//! // Create an event
26//! let event = FlowEventBuilder::new("order-processing")
27//! .group_flow("siscom")
28//! .node("api-gateway", NodeType::Producer)
29//! .stage(FlowStage::Emit)
30//! .status(FlowStatus::Sent)
31//! .ack(AckType::Implicit)
32//! .payload_bytes(190)
33//! .output_bytes(210)
34//! .meta("endpoint", "/api/users")
35//! .meta("method", "POST")
36//! .build()?;
37//!
38//! // Emit the event (requires a CaudalTransport implementation)
39//! // let emitter = CaudalEmitter::new(my_transport);
40//! // emitter.emit(event)?;
41//! # Ok(())
42//! # }
43//! ```
44//!
45//! ## Architecture
46//!
47//! - **event**: Definition of the FlowEvent v1 contract.
48//! - **builder**: Ergonomic builder for creating events.
49//! - **transport**: Abstract trait for transport backends.
50//! - **emitter**: Main component for emitting events.
51
52/// Error module
53pub mod error;
54
55/// Event module
56pub mod event;
57
58/// Builder module
59pub mod builder;
60
61/// Transport module
62pub mod transport;
63
64/// Emitter module
65pub mod emitter;
66
67// Re-export main types for ergonomic API
68pub use builder::FlowEventBuilder;
69pub use emitter::{buffered::BufferedEmitter, CaudalEmitter};
70pub use error::{CaudalError, Result};
71pub use event::{AckInfo, AckType, FlowError, FlowEvent, FlowStage, FlowStatus, NodeType};
72pub use transport::CaudalTransport;
73
74#[cfg(feature = "async-runtime")]
75pub use transport::async_transport::CaudalTransportAsync;