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:   BUSL-1.1
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 = "tls")]
161#[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
162pub mod tls;
163
164#[cfg(feature = "scaling")]
165#[cfg_attr(docsrs, doc(cfg(feature = "scaling")))]
166pub mod scaling;
167
168#[cfg(any(feature = "worker-pool", feature = "worker-batch", feature = "worker"))]
169#[cfg_attr(
170    docsrs,
171    doc(cfg(any(feature = "worker-pool", feature = "worker-batch", feature = "worker")))
172)]
173pub mod worker;
174
175#[cfg(feature = "cli")]
176#[cfg_attr(docsrs, doc(cfg(feature = "cli")))]
177pub mod cli;
178
179#[cfg(feature = "top")]
180#[cfg_attr(docsrs, doc(cfg(feature = "top")))]
181pub mod top;
182
183#[cfg(feature = "io")]
184#[cfg_attr(docsrs, doc(cfg(feature = "io")))]
185pub mod io;
186
187#[cfg(feature = "dlq")]
188#[cfg_attr(docsrs, doc(cfg(feature = "dlq")))]
189pub mod dlq;
190
191#[cfg(feature = "output-file")]
192#[cfg_attr(docsrs, doc(cfg(feature = "output-file")))]
193pub mod output;
194
195#[cfg(feature = "expression")]
196#[cfg_attr(docsrs, doc(cfg(feature = "expression")))]
197pub mod expression;
198
199#[cfg(feature = "deployment")]
200#[cfg_attr(docsrs, doc(cfg(feature = "deployment")))]
201pub mod deployment;
202
203#[cfg(feature = "version-check")]
204#[cfg_attr(docsrs, doc(cfg(feature = "version-check")))]
205pub mod version_check;
206
207#[cfg(feature = "concurrency")]
208#[cfg_attr(docsrs, doc(cfg(feature = "concurrency")))]
209pub mod concurrency;
210
211#[cfg(feature = "strmatch")]
212#[cfg_attr(docsrs, doc(cfg(feature = "strmatch")))]
213pub mod strmatch;
214
215// Re-export common types at crate root
216pub use env::{Environment, RuntimeContext, runtime_context};
217pub use kafka_config::{
218    DfeSource, KafkaConfigError, KafkaConfigResult, ServiceRole, TOPIC_SUFFIX_LAND,
219    TOPIC_SUFFIX_LOAD, config_from_file, config_from_properties_str,
220};
221pub use sensitive::{SensitiveString, expose_during};
222
223#[cfg(feature = "runtime")]
224#[cfg_attr(docsrs, doc(cfg(feature = "runtime")))]
225pub use runtime::RuntimePaths;
226
227#[cfg(feature = "health")]
228#[cfg_attr(docsrs, doc(cfg(feature = "health")))]
229pub use health::{HealthRegistry, HealthStatus};
230
231#[cfg(feature = "config")]
232#[cfg_attr(docsrs, doc(cfg(feature = "config")))]
233pub use config::{Config, ConfigError, ConfigOptions};
234
235#[cfg(feature = "config")]
236#[cfg_attr(docsrs, doc(cfg(feature = "config")))]
237pub use config::flat_env::{ApplyFlatEnv, EnvVarDoc, Normalize};
238
239#[cfg(feature = "config-reload")]
240#[cfg_attr(docsrs, doc(cfg(feature = "config-reload")))]
241pub use config::reloader::{ConfigReloader, ReloaderConfig};
242
243#[cfg(feature = "config-reload")]
244#[cfg_attr(docsrs, doc(cfg(feature = "config-reload")))]
245pub use config::shared::SharedConfig;
246
247#[cfg(feature = "config-postgres")]
248#[cfg_attr(docsrs, doc(cfg(feature = "config-postgres")))]
249pub use config::postgres::{
250    FallbackMode, PostgresConfig, PostgresConfigError, PostgresConfigSource,
251};
252
253#[cfg(feature = "logger")]
254#[cfg_attr(docsrs, doc(cfg(feature = "logger")))]
255pub use logger::{
256    LogFormat, LoggerError, LoggerOptions, SecurityEvent, SecurityOutcome, ThrottleConfig,
257};
258
259#[cfg(any(feature = "metrics", feature = "otel-metrics"))]
260#[cfg_attr(docsrs, doc(cfg(any(feature = "metrics", feature = "otel-metrics"))))]
261pub use metrics::{DfeMetrics, MetricsConfig, MetricsError, MetricsManager};
262
263#[cfg(feature = "otel-metrics")]
264#[cfg_attr(docsrs, doc(cfg(feature = "otel-metrics")))]
265pub use metrics::{OtelMetricsConfig, OtelProtocol};
266
267#[cfg(feature = "transport")]
268#[cfg_attr(docsrs, doc(cfg(feature = "transport")))]
269pub use transport::{
270    CommitToken, Message, PayloadFormat, SendResult, Transport, TransportConfig, TransportError,
271    TransportResult, TransportType,
272};
273
274#[cfg(feature = "http-server")]
275#[cfg_attr(docsrs, doc(cfg(feature = "http-server")))]
276pub use http_server::{HttpServer, HttpServerConfig, HttpServerError};
277
278#[cfg(feature = "spool")]
279#[cfg_attr(docsrs, doc(cfg(feature = "spool")))]
280pub use spool::{Spool, SpoolConfig, SpoolError};
281
282#[cfg(feature = "tiered-sink")]
283#[cfg_attr(docsrs, doc(cfg(feature = "tiered-sink")))]
284pub use tiered_sink::{
285    CircuitBreaker, CircuitState, CompressionCodec, DrainStrategy, OrderingMode, Sink, SinkError,
286    TieredSink, TieredSinkConfig, TieredSinkError,
287};
288
289#[cfg(feature = "secrets")]
290#[cfg_attr(docsrs, doc(cfg(feature = "secrets")))]
291pub use secrets::{
292    CacheConfig, FileProvider, RotationEvent, SecretMetadata, SecretProvider, SecretSource,
293    SecretValue, SecretsConfig, SecretsError, SecretsManager, SecretsResult,
294};
295
296#[cfg(feature = "secrets-vault")]
297#[cfg_attr(docsrs, doc(cfg(feature = "secrets-vault")))]
298pub use secrets::{OpenBaoAuth, OpenBaoConfig, OpenBaoProvider};
299
300#[cfg(feature = "secrets-aws")]
301#[cfg_attr(docsrs, doc(cfg(feature = "secrets-aws")))]
302pub use secrets::{AwsConfig, AwsProvider};
303
304#[cfg(feature = "directory-config")]
305#[cfg_attr(docsrs, doc(cfg(feature = "directory-config")))]
306pub use directory_config::{
307    ChangeEvent, ChangeOperation, DirectoryConfigError, DirectoryConfigResult,
308    DirectoryConfigStore, DirectoryConfigStoreConfig, WriteMode, WriteResult,
309};
310
311#[cfg(feature = "memory")]
312#[cfg_attr(docsrs, doc(cfg(feature = "memory")))]
313pub use memory::{MemoryGuard, MemoryGuardConfig, MemoryPressure, detect_memory_limit};
314
315#[cfg(feature = "scaling")]
316#[cfg_attr(docsrs, doc(cfg(feature = "scaling")))]
317pub use scaling::{
318    ComponentSnapshot, GateType, PressureSnapshot, RateWindow, ScalingComponent, ScalingPressure,
319    ScalingPressureConfig,
320};
321
322#[cfg(any(feature = "worker-pool", feature = "worker-batch", feature = "worker"))]
323#[cfg_attr(
324    docsrs,
325    doc(cfg(any(feature = "worker-pool", feature = "worker-batch", feature = "worker")))
326)]
327pub use worker::{
328    AccumulatorConfig, AccumulatorFull, AdaptiveWorkerPool, BatchAccumulator, BatchDrainer,
329    BatchPipeline, BatchProcessor, PipelineStats, PipelineStatsSnapshot, ScalingDecision,
330    ScalingInput, WorkerPoolConfig,
331};
332
333#[cfg(feature = "cli")]
334#[cfg_attr(docsrs, doc(cfg(feature = "cli")))]
335pub use cli::{CliError, CommonArgs, StandardCommand, VersionInfo};
336
337#[cfg(feature = "cli-service")]
338#[cfg_attr(docsrs, doc(cfg(feature = "cli-service")))]
339pub use cli::{DfeApp, ServiceRuntime};
340
341#[cfg(feature = "io")]
342#[cfg_attr(docsrs, doc(cfg(feature = "io")))]
343pub use io::{AsyncNdjsonWriter, FileWriterConfig, NdjsonWriter, RotationPeriod};
344
345#[cfg(feature = "dlq")]
346#[cfg_attr(docsrs, doc(cfg(feature = "dlq")))]
347pub use dlq::{Dlq, DlqBackend, DlqConfig, DlqEntry, DlqError, DlqMode, DlqSource, FileDlqConfig};
348
349#[cfg(feature = "dlq-kafka")]
350#[cfg_attr(docsrs, doc(cfg(feature = "dlq-kafka")))]
351pub use dlq::{DlqRouting, KafkaDlqConfig};
352
353#[cfg(feature = "dlq-http")]
354#[cfg_attr(docsrs, doc(cfg(feature = "dlq-http")))]
355pub use dlq::HttpDlqConfig;
356
357#[cfg(feature = "dlq-redis")]
358#[cfg_attr(docsrs, doc(cfg(feature = "dlq-redis")))]
359pub use dlq::RedisDlqConfig;
360
361#[cfg(feature = "output-file")]
362#[cfg_attr(docsrs, doc(cfg(feature = "output-file")))]
363pub use output::{FileOutput, FileOutputConfig, OutputError};
364
365#[cfg(feature = "expression")]
366#[cfg_attr(docsrs, doc(cfg(feature = "expression")))]
367pub use expression::{
368    ALLOWED_FUNCTIONS, DISALLOWED_FUNCTIONS, ExpressionError, ExpressionResult, build_context,
369    compile, evaluate, evaluate_condition, validate,
370};
371
372#[cfg(feature = "deployment")]
373#[cfg_attr(docsrs, doc(cfg(feature = "deployment")))]
374pub use deployment::{
375    ContractMismatch, DeploymentContract, DeploymentError, HealthContract, KedaConfig, KedaContract,
376};
377
378#[cfg(feature = "version-check")]
379#[cfg_attr(docsrs, doc(cfg(feature = "version-check")))]
380pub use version_check::{VersionCheck, VersionCheckConfig, VersionCheckResponse};
381
382#[cfg(feature = "concurrency")]
383#[cfg_attr(docsrs, doc(cfg(feature = "concurrency")))]
384pub use concurrency::{
385    Actor, ActorConfig, ActorError, ActorHandle, ActorJoinHandle, BackgroundSink,
386    BackgroundSinkConfig, BackgroundSinkHandle, DrainError, Overflow, PeriodicTask, PeriodicWorker,
387    SinkDrain, TickError,
388};
389
390/// Library version
391pub const VERSION: &str = env!("CARGO_PKG_VERSION");
392
393/// Initialise all library components with default settings.
394///
395/// This is a convenience function that:
396/// 1. Detects the runtime environment
397/// 2. Sets up the logger with auto-detection
398/// 3. Loads configuration with the given env prefix
399///
400/// # Errors
401///
402/// Returns an error if logger or config initialisation fails.
403#[cfg(all(feature = "config", feature = "logger"))]
404pub fn init(env_prefix: &str) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
405    logger::setup_default()?;
406    config::setup(config::ConfigOptions {
407        env_prefix: env_prefix.to_string(),
408        ..Default::default()
409    })?;
410    Ok(())
411}
hyperi_rustlib/lib.rs

hyperi_rustlib/
lib.rs
