hyperi_rustlib/
lib.rs

1// Project:   hyperi-rustlib
2// File:      src/lib.rs
3// Purpose:   Main library entry point and public API exports
4// Language:  Rust
5//
6// License:   FSL-1.1-ALv2
7// Copyright: (c) 2026 HYPERI PTY LIMITED
8
9//! # hyperi-rustlib
10//!
11//! There's plenty of sage advice out there about how to run Rust services in production at scale -- config cascades, structured logging, masking secrets, multi-backend secrets management, Prometheus, OpenTelemetry, Kafka transports, tiered disk-spillover sinks, adaptive worker pools, graceful shutdown -- but almost none of it as code you can just install and use.
12//!
13//! This is that code.
14//!
15//! Opinionated, drop-in, working out of the box. The patterns from blog posts, watercooler chats and beers with your Google mates as actual library -- not a framework you assemble from twenty crates and 8 weeks of munging.
16//!
17//! Built as the foundation for HyperI's PB/hr data services. Generic enough
18//! that you don't need to be at HyperI to use it.
19//!
20//! Full reference docs live under [`docs/`](https://github.com/hyperi-io/hyperi-rustlib/tree/main/docs).
21//! Start at [`docs/README.md`](https://github.com/hyperi-io/hyperi-rustlib/blob/main/docs/README.md)
22//! for the entry-point index.
23//!
24//! ## Quick Start
25//!
26//! ```rust,no_run
27//! use hyperi_rustlib::{env, config, logger, metrics};
28//!
29//! fn main() -> Result<(), Box<dyn std::error::Error>> {
30//!     // Detect runtime environment
31//!     let environment = env::Environment::detect();
32//!     println!("Running in: {:?}", environment);
33//!
34//!     // Initialise logger (respects LOG_LEVEL env var)
35//!     logger::setup_default()?;
36//!
37//!     // Load configuration with 7-layer cascade
38//!     config::setup(config::ConfigOptions {
39//!         env_prefix: "MYAPP".into(),
40//!         ..Default::default()
41//!     })?;
42//!
43//!     // Access config
44//!     let cfg = config::get();
45//!     let db_host = cfg.get_string("database.host").unwrap_or_default();
46//!
47//!     // Create metrics
48//!     let metrics_mgr = metrics::MetricsManager::new("myapp");
49//!     let _counter = metrics_mgr.counter("requests_total", "Total requests processed");
50//!
51//!     tracing::info!(db_host = %db_host, "Application started");
52//!     Ok(())
53//! }
54//! ```
55//!
56//! See `docs/CORE-PILLARS.md` in the repository for the auto-wiring architecture.
57
58#![deny(unsafe_code)]
59#![cfg_attr(docsrs, feature(doc_cfg))]
60#![warn(clippy::pedantic)]
61// Crate-wide hard-deny for the most pernicious async footgun. Holding a
62// sync `Mutex`/`RwLock` guard across `.await` is the canonical way to
63// deadlock a tokio runtime under contention. The lint catches this at
64// compile time. Integration tests that legitimately serialise via a
65// sync mutex opt out file-locally with `#![allow(...)]` and a comment
66// explaining the safety reasoning.
67#![deny(clippy::await_holding_lock)]
68#![warn(rustdoc::broken_intra_doc_links)]
69#![warn(rustdoc::private_intra_doc_links)]
70#![warn(rustdoc::invalid_codeblock_attributes)]
71#![warn(rustdoc::bare_urls)]
72#![allow(clippy::module_name_repetitions)]
73#![allow(clippy::doc_markdown)] // Allow brand names without backticks
74#![allow(clippy::cast_precision_loss)] // Metrics values are fine with f64 precision
75#![allow(clippy::missing_panics_doc)] // MVP does not require exhaustive docs
76#![allow(clippy::missing_errors_doc)] // MVP does not require exhaustive docs
77#![allow(clippy::double_must_use)] // Return types already marked must_use
78#![allow(clippy::unused_async)] // Async for future compatibility
79#![allow(clippy::redundant_closure_for_method_calls)] // Clearer with explicit closure
80#![allow(clippy::result_large_err)] // figment::Error is large by design
81#![allow(clippy::needless_pass_by_value)]
82// API cleaner with owned values
83// Test code allowances - unwrap is acceptable in tests for cleaner assertions
84#![cfg_attr(test, allow(clippy::unwrap_used))]
85#![cfg_attr(test, allow(clippy::field_reassign_with_default))]
86
87// Core modules (always available)
88pub mod env;
89pub mod kafka_config;
90pub mod sensitive;
91
92#[cfg(feature = "runtime")]
93#[cfg_attr(docsrs, doc(cfg(feature = "runtime")))]
94pub mod runtime;
95
96#[cfg(feature = "shutdown")]
97#[cfg_attr(docsrs, doc(cfg(feature = "shutdown")))]
98pub mod shutdown;
99
100#[cfg(feature = "health")]
101#[cfg_attr(docsrs, doc(cfg(feature = "health")))]
102pub mod health;
103
104#[cfg(feature = "config")]
105#[cfg_attr(docsrs, doc(cfg(feature = "config")))]
106pub mod config;
107
108#[cfg(feature = "logger")]
109#[cfg_attr(docsrs, doc(cfg(feature = "logger")))]
110pub mod logger;
111
112#[cfg(any(feature = "metrics", feature = "otel-metrics"))]
113#[cfg_attr(docsrs, doc(cfg(any(feature = "metrics", feature = "otel-metrics"))))]
114pub mod metrics;
115
116#[cfg(feature = "otel-tracing")]
117#[cfg_attr(docsrs, doc(cfg(feature = "otel-tracing")))]
118pub mod otel_tracing;
119
120#[cfg(feature = "transport")]
121#[cfg_attr(docsrs, doc(cfg(feature = "transport")))]
122pub mod transport;
123
124#[cfg(feature = "http")]
125#[cfg_attr(docsrs, doc(cfg(feature = "http")))]
126pub mod http_client;
127
128#[cfg(feature = "http-server")]
129#[cfg_attr(docsrs, doc(cfg(feature = "http-server")))]
130pub mod http_server;
131
132#[cfg(feature = "database")]
133#[cfg_attr(docsrs, doc(cfg(feature = "database")))]
134pub mod database;
135
136#[cfg(feature = "cache")]
137#[cfg_attr(docsrs, doc(cfg(feature = "cache")))]
138pub mod cache;
139
140#[cfg(feature = "spool")]
141#[cfg_attr(docsrs, doc(cfg(feature = "spool")))]
142pub mod spool;
143
144#[cfg(feature = "tiered-sink")]
145#[cfg_attr(docsrs, doc(cfg(feature = "tiered-sink")))]
146pub mod tiered_sink;
147
148#[cfg(feature = "secrets")]
149#[cfg_attr(docsrs, doc(cfg(feature = "secrets")))]
150pub mod secrets;
151
152#[cfg(feature = "directory-config")]
153#[cfg_attr(docsrs, doc(cfg(feature = "directory-config")))]
154pub mod directory_config;
155
156#[cfg(feature = "memory")]
157#[cfg_attr(docsrs, doc(cfg(feature = "memory")))]
158pub mod memory;
159
160#[cfg(feature = "scaling")]
161#[cfg_attr(docsrs, doc(cfg(feature = "scaling")))]
162pub mod scaling;
163
164#[cfg(any(feature = "worker-pool", feature = "worker-batch", feature = "worker"))]
165#[cfg_attr(
166    docsrs,
167    doc(cfg(any(feature = "worker-pool", feature = "worker-batch", feature = "worker")))
168)]
169pub mod worker;
170
171#[cfg(feature = "cli")]
172#[cfg_attr(docsrs, doc(cfg(feature = "cli")))]
173pub mod cli;
174
175#[cfg(feature = "top")]
176#[cfg_attr(docsrs, doc(cfg(feature = "top")))]
177pub mod top;
178
179#[cfg(feature = "io")]
180#[cfg_attr(docsrs, doc(cfg(feature = "io")))]
181pub mod io;
182
183#[cfg(feature = "dlq")]
184#[cfg_attr(docsrs, doc(cfg(feature = "dlq")))]
185pub mod dlq;
186
187#[cfg(feature = "output-file")]
188#[cfg_attr(docsrs, doc(cfg(feature = "output-file")))]
189pub mod output;
190
191#[cfg(feature = "expression")]
192#[cfg_attr(docsrs, doc(cfg(feature = "expression")))]
193pub mod expression;
194
195#[cfg(feature = "deployment")]
196#[cfg_attr(docsrs, doc(cfg(feature = "deployment")))]
197pub mod deployment;
198
199#[cfg(feature = "version-check")]
200#[cfg_attr(docsrs, doc(cfg(feature = "version-check")))]
201pub mod version_check;
202
203#[cfg(feature = "concurrency")]
204#[cfg_attr(docsrs, doc(cfg(feature = "concurrency")))]
205pub mod concurrency;
206
207#[cfg(feature = "strmatch")]
208#[cfg_attr(docsrs, doc(cfg(feature = "strmatch")))]
209pub mod strmatch;
210
211// Re-export common types at crate root
212pub use env::{Environment, RuntimeContext, runtime_context};
213pub use kafka_config::{
214    DfeSource, KafkaConfigError, KafkaConfigResult, ServiceRole, TOPIC_SUFFIX_LAND,
215    TOPIC_SUFFIX_LOAD, config_from_file, config_from_properties_str,
216};
217pub use sensitive::{SensitiveString, expose_during};
218
219#[cfg(feature = "runtime")]
220#[cfg_attr(docsrs, doc(cfg(feature = "runtime")))]
221pub use runtime::RuntimePaths;
222
223#[cfg(feature = "health")]
224#[cfg_attr(docsrs, doc(cfg(feature = "health")))]
225pub use health::{HealthRegistry, HealthStatus};
226
227#[cfg(feature = "config")]
228#[cfg_attr(docsrs, doc(cfg(feature = "config")))]
229pub use config::{Config, ConfigError, ConfigOptions};
230
231#[cfg(feature = "config")]
232#[cfg_attr(docsrs, doc(cfg(feature = "config")))]
233pub use config::flat_env::{ApplyFlatEnv, EnvVarDoc, Normalize};
234
235#[cfg(feature = "config-reload")]
236#[cfg_attr(docsrs, doc(cfg(feature = "config-reload")))]
237pub use config::reloader::{ConfigReloader, ReloaderConfig};
238
239#[cfg(feature = "config-reload")]
240#[cfg_attr(docsrs, doc(cfg(feature = "config-reload")))]
241pub use config::shared::SharedConfig;
242
243#[cfg(feature = "config-postgres")]
244#[cfg_attr(docsrs, doc(cfg(feature = "config-postgres")))]
245pub use config::postgres::{
246    FallbackMode, PostgresConfig, PostgresConfigError, PostgresConfigSource,
247};
248
249#[cfg(feature = "logger")]
250#[cfg_attr(docsrs, doc(cfg(feature = "logger")))]
251pub use logger::{
252    LogFormat, LoggerError, LoggerOptions, SecurityEvent, SecurityOutcome, ThrottleConfig,
253};
254
255#[cfg(any(feature = "metrics", feature = "otel-metrics"))]
256#[cfg_attr(docsrs, doc(cfg(any(feature = "metrics", feature = "otel-metrics"))))]
257pub use metrics::{DfeMetrics, MetricsConfig, MetricsError, MetricsManager};
258
259#[cfg(feature = "otel-metrics")]
260#[cfg_attr(docsrs, doc(cfg(feature = "otel-metrics")))]
261pub use metrics::{OtelMetricsConfig, OtelProtocol};
262
263#[cfg(feature = "transport")]
264#[cfg_attr(docsrs, doc(cfg(feature = "transport")))]
265pub use transport::{
266    CommitToken, Message, PayloadFormat, SendResult, Transport, TransportConfig, TransportError,
267    TransportResult, TransportType,
268};
269
270#[cfg(feature = "http-server")]
271#[cfg_attr(docsrs, doc(cfg(feature = "http-server")))]
272pub use http_server::{HttpServer, HttpServerConfig, HttpServerError};
273
274#[cfg(feature = "spool")]
275#[cfg_attr(docsrs, doc(cfg(feature = "spool")))]
276pub use spool::{Spool, SpoolConfig, SpoolError};
277
278#[cfg(feature = "tiered-sink")]
279#[cfg_attr(docsrs, doc(cfg(feature = "tiered-sink")))]
280pub use tiered_sink::{
281    CircuitBreaker, CircuitState, CompressionCodec, DrainStrategy, OrderingMode, Sink, SinkError,
282    TieredSink, TieredSinkConfig, TieredSinkError,
283};
284
285#[cfg(feature = "secrets")]
286#[cfg_attr(docsrs, doc(cfg(feature = "secrets")))]
287pub use secrets::{
288    CacheConfig, FileProvider, RotationEvent, SecretMetadata, SecretProvider, SecretSource,
289    SecretValue, SecretsConfig, SecretsError, SecretsManager, SecretsResult,
290};
291
292#[cfg(feature = "secrets-vault")]
293#[cfg_attr(docsrs, doc(cfg(feature = "secrets-vault")))]
294pub use secrets::{OpenBaoAuth, OpenBaoConfig, OpenBaoProvider};
295
296#[cfg(feature = "secrets-aws")]
297#[cfg_attr(docsrs, doc(cfg(feature = "secrets-aws")))]
298pub use secrets::{AwsConfig, AwsProvider};
299
300#[cfg(feature = "directory-config")]
301#[cfg_attr(docsrs, doc(cfg(feature = "directory-config")))]
302pub use directory_config::{
303    ChangeEvent, ChangeOperation, DirectoryConfigError, DirectoryConfigResult,
304    DirectoryConfigStore, DirectoryConfigStoreConfig, WriteMode, WriteResult,
305};
306
307#[cfg(feature = "memory")]
308#[cfg_attr(docsrs, doc(cfg(feature = "memory")))]
309pub use memory::{MemoryGuard, MemoryGuardConfig, MemoryPressure, detect_memory_limit};
310
311#[cfg(feature = "scaling")]
312#[cfg_attr(docsrs, doc(cfg(feature = "scaling")))]
313pub use scaling::{
314    ComponentSnapshot, GateType, PressureSnapshot, RateWindow, ScalingComponent, ScalingPressure,
315    ScalingPressureConfig,
316};
317
318#[cfg(any(feature = "worker-pool", feature = "worker-batch", feature = "worker"))]
319#[cfg_attr(
320    docsrs,
321    doc(cfg(any(feature = "worker-pool", feature = "worker-batch", feature = "worker")))
322)]
323pub use worker::{
324    AccumulatorConfig, AccumulatorFull, AdaptiveWorkerPool, BatchAccumulator, BatchDrainer,
325    BatchPipeline, BatchProcessor, PipelineStats, PipelineStatsSnapshot, ScalingDecision,
326    ScalingInput, WorkerPoolConfig,
327};
328
329#[cfg(feature = "cli")]
330#[cfg_attr(docsrs, doc(cfg(feature = "cli")))]
331pub use cli::{CliError, CommonArgs, StandardCommand, VersionInfo};
332
333#[cfg(feature = "cli-service")]
334#[cfg_attr(docsrs, doc(cfg(feature = "cli-service")))]
335pub use cli::{DfeApp, ServiceRuntime};
336
337#[cfg(feature = "io")]
338#[cfg_attr(docsrs, doc(cfg(feature = "io")))]
339pub use io::{AsyncNdjsonWriter, FileWriterConfig, NdjsonWriter, RotationPeriod};
340
341#[cfg(feature = "dlq")]
342#[cfg_attr(docsrs, doc(cfg(feature = "dlq")))]
343pub use dlq::{Dlq, DlqBackend, DlqConfig, DlqEntry, DlqError, DlqMode, DlqSource, FileDlqConfig};
344
345#[cfg(feature = "dlq-kafka")]
346#[cfg_attr(docsrs, doc(cfg(feature = "dlq-kafka")))]
347pub use dlq::{DlqRouting, KafkaDlqConfig};
348
349#[cfg(feature = "dlq-http")]
350#[cfg_attr(docsrs, doc(cfg(feature = "dlq-http")))]
351pub use dlq::HttpDlqConfig;
352
353#[cfg(feature = "dlq-redis")]
354#[cfg_attr(docsrs, doc(cfg(feature = "dlq-redis")))]
355pub use dlq::RedisDlqConfig;
356
357#[cfg(feature = "output-file")]
358#[cfg_attr(docsrs, doc(cfg(feature = "output-file")))]
359pub use output::{FileOutput, FileOutputConfig, OutputError};
360
361#[cfg(feature = "expression")]
362#[cfg_attr(docsrs, doc(cfg(feature = "expression")))]
363pub use expression::{
364    ALLOWED_FUNCTIONS, DISALLOWED_FUNCTIONS, ExpressionError, ExpressionResult, build_context,
365    compile, evaluate, evaluate_condition, validate,
366};
367
368#[cfg(feature = "deployment")]
369#[cfg_attr(docsrs, doc(cfg(feature = "deployment")))]
370pub use deployment::{
371    ContractMismatch, DeploymentContract, DeploymentError, HealthContract, KedaConfig, KedaContract,
372};
373
374#[cfg(feature = "version-check")]
375#[cfg_attr(docsrs, doc(cfg(feature = "version-check")))]
376pub use version_check::{VersionCheck, VersionCheckConfig, VersionCheckResponse};
377
378#[cfg(feature = "concurrency")]
379#[cfg_attr(docsrs, doc(cfg(feature = "concurrency")))]
380pub use concurrency::{
381    Actor, ActorConfig, ActorError, ActorHandle, ActorJoinHandle, BackgroundSink,
382    BackgroundSinkConfig, BackgroundSinkHandle, DrainError, Overflow, PeriodicTask, PeriodicWorker,
383    SinkDrain, TickError,
384};
385
386/// Library version
387pub const VERSION: &str = env!("CARGO_PKG_VERSION");
388
389/// Initialise all library components with default settings.
390///
391/// This is a convenience function that:
392/// 1. Detects the runtime environment
393/// 2. Sets up the logger with auto-detection
394/// 3. Loads configuration with the given env prefix
395///
396/// # Errors
397///
398/// Returns an error if logger or config initialisation fails.
399#[cfg(all(feature = "config", feature = "logger"))]
400pub fn init(env_prefix: &str) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
401    logger::setup_default()?;
402    config::setup(config::ConfigOptions {
403        env_prefix: env_prefix.to_string(),
404        ..Default::default()
405    })?;
406    Ok(())
407}
hyperi_rustlib/lib.rs

hyperi_rustlib/
lib.rs
