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

hyperi_rustlib/
lib.rs
