hyperi-rustlib 2.5.4

Opinionated Rust framework for high-throughput data pipelines at PB scale. Auto-wiring config, logging, metrics, tracing, health, and graceful shutdown — built from many years of production infrastructure experience.
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

// Project:   hyperi-rustlib
// File:      src/dlq/mod.rs
// Purpose:   Unified dead letter queue with pluggable backends
// Language:  Rust
//
// License:   FSL-1.1-ALv2
// Copyright: (c) 2026 HYPERI PTY LIMITED

//! Unified dead letter queue (DLQ) with pluggable backends.
//!
//! Provides a shared DLQ abstraction for all DFE services. Failed messages
//! are routed to one or more backends (file, Kafka, or custom) using
//! configurable cascade or fan-out modes.
//!
//! ## Backends
//!
//! - **File** (`FileDlq`): NDJSON files with automatic rotation and cleanup.
//!   Always available, no external dependencies.
//! - **Kafka** (`KafkaDlq`): Routes to Kafka topics with per-table or common
//!   routing. Requires the `dlq-kafka` feature.
//! - **Custom**: Implement [`DlqBackend`] and register via [`Dlq::add_backend`].
//!
//! ## Modes
//!
//! - **Cascade** (default): Try Kafka first, fall back to file on failure.
//! - **Fan-out**: Write to all backends for belt-and-suspenders.
//! - **FileOnly**: File backend only (no Kafka dependency).
//! - **KafkaOnly**: Kafka backend only.
//!
//! ## Example
//!
//! ```rust,no_run
//! use hyperi_rustlib::dlq::{Dlq, DlqConfig, DlqEntry, DlqSource};
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! // File-only DLQ (no Kafka needed)
//! let config = DlqConfig::default();
//! let dlq = Dlq::file_only(&config, "my-service")?;
//!
//! // Route a failed message
//! let entry = DlqEntry::new("my-service", "parse_error", b"bad data".to_vec())
//!     .with_destination("acme.auth")
//!     .with_source(DlqSource::kafka("events", 1, 42));
//!
//! dlq.send(entry).await?;
//! # Ok(())
//! # }
//! ```

mod backend;
mod config;
mod entry;
mod error;
mod file;
mod orchestrator;

#[cfg(feature = "dlq-kafka")]
mod kafka;

#[cfg(feature = "dlq-http")]
mod http;

#[cfg(feature = "dlq-redis")]
mod redis_dlq;

// Core types (always available with `dlq` feature)
pub use backend::DlqBackend;
pub use config::{DlqConfig, DlqMode, FileDlqConfig, RotationPeriod};
pub use entry::{DlqEntry, DlqSource};
pub use error::DlqError;
pub use file::FileDlq;
pub use orchestrator::Dlq;

// Kafka types (only with `dlq-kafka` feature)
#[cfg(feature = "dlq-kafka")]
pub use config::{DlqRouting, KafkaDlqConfig};
#[cfg(feature = "dlq-kafka")]
pub use kafka::KafkaDlq;

// HTTP types (only with `dlq-http` feature)
#[cfg(feature = "dlq-http")]
pub use http::{HttpDlq, HttpDlqConfig};

// Redis types (only with `dlq-redis` feature)
#[cfg(feature = "dlq-redis")]
pub use redis_dlq::{RedisDlq, RedisDlqConfig};

/// Result type for DLQ operations.
pub type Result<T> = std::result::Result<T, DlqError>;