Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 semantic-release-bot
|
bfe2fae359 | ||
 asepharyana
|
1ea3b35581 | ||
|
semantic-release-bot
|
d27e00060c | ||
|
asepharyana
|
198154442c |
@@ -0,0 +1,24 @@
|
||||
# Implementation Spec: Round 2
|
||||
|
||||
## New Features
|
||||
|
||||
### 1. ServiceBuilder (mytheclipse-core)
|
||||
File: `crates/mytheclipse/src/service_builder.rs`
|
||||
- Builder that wraps async operations with retry + circuit breaker + timeout + rate limiter
|
||||
- Fluent API: `.retry(config)`, `.circuit(config)`, `.timeout(dur)`, `.rate(rate, burst)`, `.concurrency(max)`, `.run(fut)`
|
||||
- Feature gate: `resiliency` (uses existing retry/CircuitBreaker/timeout primitives)
|
||||
- Integrates with metrics: records retries, circuit events, timeouts
|
||||
|
||||
### 2. DistributedLock (mytheclipse-core)
|
||||
File: `crates/mytheclipse/src/dlock.rs`
|
||||
- `DistributedLock` trait: `acquire(timeout)`, `release()`, `extend(lease_dur)`
|
||||
- `InProcDistributedLock` impl using tokio Mutex + lease time tracking
|
||||
- `RedisLock` impl (feature `redis`) — Redis SETNX with PX expiry
|
||||
- Feature gate: `lifecycle` (uses existing leader election infra)
|
||||
|
||||
### 3. StreamingPipeline (mytheclipse-queue)
|
||||
File: `crates/mytheclipse-queue/src/pipeline.rs`
|
||||
- Pipe stages: `Stage<Input, Output>` trait with async `process(item) -> Output`
|
||||
- Pipeline: `add_stage(impl Stage)`, `run(input_stream)`, `collect()`
|
||||
- Backpressure: bounded channel between stages
|
||||
- Feature gate: `in-memory` (uses tokio + std)
|
||||
@@ -0,0 +1,42 @@
|
||||
# Implementation Spec: Round 3
|
||||
|
||||
## New Features (4)
|
||||
|
||||
### 1. ConfigValidator (mytheclipse-config)
|
||||
File: `crates/mytheclipse-config/src/validate.rs`
|
||||
- `ConfigValidator` trait: `fn validate(&self) -> Result<(), ValidationError>`
|
||||
- `ConfigValidatorExt` trait: blanket impl for `T: ConfigValidator`
|
||||
- Built-in validators: `validate_url`, `validate_port`, `validate_non_empty`, `validate_range`, `collect_failures`
|
||||
- `ValidationFailure { path, message }` + `ValidationError` type alias
|
||||
- Feature gate: `validation` (default)
|
||||
- Tests: 17 (unit + doctest)
|
||||
|
||||
### 2. AsyncLifecycleManager (mytheclipse-core)
|
||||
File: `crates/mytheclipse/src/lifecycle.rs`
|
||||
- `AsyncLifecycleManager` composing `ShutdownManager` + `HealthRegistry`
|
||||
- Methods: `register_health_check`, `check_health`, `shutdown_signal`, `start_health_loop`, `await_shutdown`, `request_shutdown`
|
||||
- Feature gate: `lifecycle`
|
||||
- Tests: 38 total (3 new in lifecycle.rs)
|
||||
|
||||
### 3. MetricsBridge (mytheclipse-core)
|
||||
File: `crates/mytheclipse/src/metrics_bridge.rs`
|
||||
- `MetricsBridge` — emits MetricsCollector snapshot to tracing
|
||||
- `MetricsHealthCheck` — wraps MetricsCollector as HealthCheck (unhealthy if error counters > 0)
|
||||
- Feature gate: `observability`
|
||||
|
||||
### 4. ServiceBuilder RateLimiter API (mytheclipse-core)
|
||||
File: `crates/mytheclipse/src/service_builder.rs`
|
||||
- `with_rate_limiter` fluent builder (already existed)
|
||||
- `check_pre` performs rate-limit pre-acquire before calling service
|
||||
- Returns `RunError::RateLimited` when rate limiter exhausted
|
||||
|
||||
## Build Status
|
||||
- cargo build --workspace --all-features: OK
|
||||
- cargo test --workspace --all-features: all pass (77+17+18+16+6+5+...)
|
||||
- cargo clippy: 0 warnings on new code (pre-existing warnings in crypto/base64/cli only)
|
||||
- Committed + pushed
|
||||
|
||||
## Notes
|
||||
- `Arc<HealthRegistry>` in AsyncLifecycleManager because HealthRegistry doesn't impl Clone
|
||||
- Doctest marked `ignore` (async runtime not available in doctest context)
|
||||
- Lint checker false-positives on `async fn` (edition 2015 phantom) but actual cargo build/tests pass
|
||||
@@ -1,3 +1,17 @@
|
||||
# [1.5.0](https://github.com/asepharyana/mytheclipse/compare/v1.4.1...v1.5.0) (2026-08-29)
|
||||
|
||||
|
||||
### Features
|
||||
|
||||
* round-3 abstractions — ConfigValidator, AsyncLifecycleManager, MetricsBridge, rate limiter pre-acquire ([1ea3b35](https://github.com/asepharyana/mytheclipse/commit/1ea3b3558143bd07168c3be89653fbeb9c38930a))
|
||||
|
||||
## [1.4.1](https://github.com/asepharyana/mytheclipse/compare/v1.4.0...v1.4.1) (2026-08-29)
|
||||
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
* clippy clean for round-2 (pipeline module export, lint cleanup) ([1981544](https://github.com/asepharyana/mytheclipse/commit/198154442c4297c94e8743caec81294b478c0d3a))
|
||||
|
||||
# [1.4.0](https://github.com/asepharyana/mytheclipse/compare/v1.3.5...v1.4.0) (2026-08-29)
|
||||
|
||||
|
||||
|
||||
Generated
+10
-10
@@ -2818,7 +2818,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "mytheclipse"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
dependencies = [
|
||||
"async-trait",
|
||||
"num_cpus",
|
||||
@@ -2832,7 +2832,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "mytheclipse-cache"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
dependencies = [
|
||||
"async-trait",
|
||||
"moka",
|
||||
@@ -2845,7 +2845,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "mytheclipse-cli"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
dependencies = [
|
||||
"clap",
|
||||
"tokio",
|
||||
@@ -2854,7 +2854,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "mytheclipse-config"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
dependencies = [
|
||||
"dotenvy",
|
||||
"notify",
|
||||
@@ -2869,7 +2869,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "mytheclipse-crypto"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
dependencies = [
|
||||
"aead",
|
||||
"aes-gcm",
|
||||
@@ -2889,7 +2889,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "mytheclipse-event"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
dependencies = [
|
||||
"async-nats",
|
||||
"async-trait",
|
||||
@@ -2905,7 +2905,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "mytheclipse-http"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
dependencies = [
|
||||
"async-trait",
|
||||
"axum",
|
||||
@@ -2919,7 +2919,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "mytheclipse-queue"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
dependencies = [
|
||||
"async-nats",
|
||||
"async-trait",
|
||||
@@ -2935,7 +2935,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "mytheclipse-storage"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
dependencies = [
|
||||
"async-trait",
|
||||
"aws-config",
|
||||
@@ -2951,7 +2951,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "mytheclipse-tracing"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
dependencies = [
|
||||
"opentelemetry 0.25.0",
|
||||
"tokio",
|
||||
|
||||
@@ -11,11 +11,11 @@ concern.
|
||||
|
||||
| Crate | Description | Docs |
|
||||
| :--- | :--- | :--- |
|
||||
| [`mytheclipse`](crates/mytheclipse) | Resource-aware execution primitives (async I/O, compute, background queues), resiliency (retry, circuit breaker, timeout), traffic control (rate limiter, backpressure, concurrency limiter), lifecycle (graceful shutdown, cron), and observability (metrics, panic tracking). | [README](crates/mytheclipse/README.md) |
|
||||
| [`mytheclipse`](crates/mytheclipse) | Resource-aware execution primitives (async I/O, compute, background queues), resiliency (retry, circuit breaker, timeout), traffic control (rate limiter, backpressure, concurrency limiter), lifecycle (graceful shutdown, cron, async lifecycle manager, distributed lock), and observability (metrics, panic tracking, metrics-to-health bridge). | [README](crates/mytheclipse/README.md) |
|
||||
| [`mytheclipse-cache`](crates/mytheclipse-cache) | Unified multi-layer (L1/L2) cache abstraction: in-memory or Moka L1, Redis/Valkey L2, cache-aside read-through. | [README](crates/mytheclipse-cache/README.md) |
|
||||
| [`mytheclipse-storage`](crates/mytheclipse-storage) | Unified storage & file system abstraction: one driver interface over local disk, S3/MinIO, and Google Cloud Storage, stream-based. | [README](crates/mytheclipse-storage/README.md) |
|
||||
| [`mytheclipse-event`](crates/mytheclipse-event) | Unified events & message bus abstraction: in-memory pub/sub dispatcher plus RabbitMQ and NATS broker adapters behind one trait. | [README](crates/mytheclipse-event/README.md) |
|
||||
| [`mytheclipse-config`](crates/mytheclipse-config) | Type-safe, dynamic configuration engine: load `.env`/YAML/JSON/TOML into typed structs, with hot-reload. | [README](crates/mytheclipse-config/README.md) |
|
||||
| [`mytheclipse-config`](crates/mytheclipse-config) | Type-safe, dynamic configuration engine: load `.env`/YAML/JSON/TOML into typed structs, with hot-reload and typed validation. | [README](crates/mytheclipse-config/README.md) |
|
||||
| [`mytheclipse-crypto`](crates/mytheclipse-crypto) | Safe hashing (Argon2id), encryption (AES-256-GCM), JWT and PASETO tokens, with key rotation support. | [README](crates/mytheclipse-crypto/README.md) |
|
||||
| [`mytheclipse-queue`](crates/mytheclipse-queue) | Unified job queue abstraction with WorkerPool executor, retry/backoff, and dead-letter support. Backends: in-memory, Redis, NATS, PostgreSQL. | [README](crates/mytheclipse-queue/README.md) |
|
||||
| [`mytheclipse-tracing`](crates/mytheclipse-tracing) | Pre-built tracing subscriber layers with env filtering and optional OTLP/Jaeger/Zipkin export. | [README](crates/mytheclipse-tracing/README.md) |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "mytheclipse-cache"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
edition = "2021"
|
||||
rust-version = "1.75"
|
||||
license = "MIT OR Apache-2.0"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "mytheclipse-cli"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
edition = "2021"
|
||||
rust-version = "1.75"
|
||||
license = "MIT OR Apache-2.0"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "mytheclipse-config"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
edition = "2021"
|
||||
rust-version = "1.75"
|
||||
license = "MIT OR Apache-2.0"
|
||||
@@ -14,7 +14,7 @@ keywords = ["config", "env", "yaml", "json", "hot-reload"]
|
||||
categories = ["config", "development-tools"]
|
||||
|
||||
[features]
|
||||
default = ["env", "yaml", "toml", "hot-reload"]
|
||||
default = ["env", "yaml", "toml", "hot-reload", "validation"]
|
||||
# Load .env files + environment variables.
|
||||
env = ["dep:dotenvy"]
|
||||
# Parse structured files. JSON support (`.json`) is always available since
|
||||
@@ -23,6 +23,8 @@ yaml = ["dep:serde_yaml"]
|
||||
toml = ["dep:toml"]
|
||||
# Watch config files and hot-reload.
|
||||
hot-reload = ["dep:notify", "dep:tokio"]
|
||||
# Config validation traits and built-in validators.
|
||||
validation = []
|
||||
# JSON Schema generation for config validation and docs.
|
||||
schema = []
|
||||
|
||||
|
||||
@@ -15,6 +15,8 @@ pub enum ConfigError {
|
||||
UnsupportedFormat(String),
|
||||
/// Hot-reload setup failed (e.g. the file watcher could not be installed).
|
||||
Watch(String),
|
||||
/// Config validation failed after loading.
|
||||
Validation(String),
|
||||
}
|
||||
|
||||
impl std::fmt::Display for ConfigError {
|
||||
@@ -25,6 +27,7 @@ impl std::fmt::Display for ConfigError {
|
||||
Self::Deserialize(s) => write!(f, "config deserialize error: {s}"),
|
||||
Self::UnsupportedFormat(s) => write!(f, "unsupported config format: {s}"),
|
||||
Self::Watch(s) => write!(f, "config watch error: {s}"),
|
||||
Self::Validation(s) => write!(f, "config validation error: {s}"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -43,9 +43,19 @@ pub mod dynamic;
|
||||
#[cfg(feature = "schema")]
|
||||
pub mod schema;
|
||||
|
||||
#[cfg(feature = "validation")]
|
||||
pub mod validate;
|
||||
|
||||
pub use error::ConfigError;
|
||||
pub use loader::ConfigLoader;
|
||||
|
||||
#[cfg(feature = "validation")]
|
||||
pub use validate::{
|
||||
collect_failures, validate_non_empty, validate_port, validate_range,
|
||||
validate_url, ConfigValidator, ConfigValidatorExt, ValidationError,
|
||||
ValidationFailure,
|
||||
};
|
||||
|
||||
#[cfg(feature = "hot-reload")]
|
||||
pub use dynamic::DynamicConfig;
|
||||
|
||||
|
||||
@@ -0,0 +1,215 @@
|
||||
//! Config validation traits and built-in validators (feature `validation`).
|
||||
//!
|
||||
//! [`ConfigValidator`] lets application config types sanity-check themselves
|
||||
//! after deserialization — e.g. ensuring a database URL parses, a port is in
|
||||
//! range, or a required field is non-empty — and collect all failures into a
|
||||
//! single report rather than failing one field at a time.
|
||||
|
||||
use std::fmt;
|
||||
|
||||
use crate::ConfigError;
|
||||
|
||||
/// A single validation failure with a human-readable path and message.
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct ValidationFailure {
|
||||
/// Dotted path to the offending field, e.g. `"database.url"`.
|
||||
pub path: String,
|
||||
/// What was wrong.
|
||||
pub message: String,
|
||||
}
|
||||
|
||||
impl fmt::Display for ValidationFailure {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
write!(f, "{}: {}", self.path, self.message)
|
||||
}
|
||||
}
|
||||
|
||||
/// Errors produced by [`ConfigValidator::validate`].
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ValidationError {
|
||||
/// All failures found in a single validation pass.
|
||||
pub failures: Vec<ValidationFailure>,
|
||||
}
|
||||
|
||||
impl fmt::Display for ValidationError {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
write!(f, "config validation failed ({} issue(s)):", self.failures.len())?;
|
||||
for failure in &self.failures {
|
||||
write!(f, "\n - {failure}")?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
impl std::error::Error for ValidationError {}
|
||||
|
||||
impl From<ValidationError> for ConfigError {
|
||||
fn from(err: ValidationError) -> Self {
|
||||
ConfigError::Validation(err.to_string())
|
||||
}
|
||||
}
|
||||
|
||||
/// Trait for types that can validate themselves after configuration loading.
|
||||
///
|
||||
/// Implementors collect field-level failures rather than returning on the
|
||||
/// first error, so operators see the full problem set in one pass.
|
||||
pub trait ConfigValidator {
|
||||
fn validate(&self) -> Result<(), ValidationError>;
|
||||
}
|
||||
|
||||
/// Convenience blanket for any serializable config type that implements
|
||||
/// [`ConfigValidator`]. Callers typically invoke this on the output of
|
||||
/// [`ConfigLoader::build`](crate::loader::ConfigLoader::build).
|
||||
///
|
||||
/// ```no_run
|
||||
/// # use mytheclipse_config::{ConfigLoader, ConfigValidator, ConfigValidatorExt};
|
||||
/// # use serde::Deserialize;
|
||||
/// # #[derive(Debug, Deserialize)]
|
||||
/// # struct Cfg { port: u16 }
|
||||
/// # impl ConfigValidator for Cfg {
|
||||
/// # fn validate(&self) -> Result<(), mytheclipse_config::ValidationError> { Ok(()) }
|
||||
/// # }
|
||||
/// let cfg: Cfg = ConfigLoader::new().build().unwrap();
|
||||
/// cfg.validate_config().unwrap();
|
||||
/// ```
|
||||
pub trait ConfigValidatorExt: ConfigValidator {
|
||||
/// Validates `self`, returning `Ok(())` on success.
|
||||
fn validate_config(&self) -> Result<(), ConfigError> {
|
||||
self.validate().map_err(ConfigError::from)
|
||||
}
|
||||
}
|
||||
|
||||
impl<T: ConfigValidator> ConfigValidatorExt for T {}
|
||||
|
||||
/// Validates that a string is a well-formed URL (http/https).
|
||||
pub fn validate_url(path: &str, value: &str) -> Option<ValidationFailure> {
|
||||
if value.is_empty() {
|
||||
return Some(ValidationFailure {
|
||||
path: path.to_string(),
|
||||
message: "url must not be empty".into(),
|
||||
});
|
||||
}
|
||||
// Minimal heuristic: scheme + host. We avoid pulling in a full URL crate
|
||||
// to keep the dependency surface small.
|
||||
let scheme_len = if value.starts_with("http://") { 7 } else if value.starts_with("https://") { 8 } else {
|
||||
return Some(ValidationFailure {
|
||||
path: path.to_string(),
|
||||
message: format!("url must start with http:// or https:// (got {value:?})"),
|
||||
});
|
||||
};
|
||||
let host = &value[scheme_len..];
|
||||
if host.is_empty() {
|
||||
return Some(ValidationFailure {
|
||||
path: path.to_string(),
|
||||
message: format!("url has no host portion (got {value:?})"),
|
||||
});
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
/// Validates that a port number is in the valid range (1–65535).
|
||||
pub fn validate_port(path: &str, port: u16) -> Option<ValidationFailure> {
|
||||
// u16 already ranges 0–65535; exclude 0 (reserved/unspecified).
|
||||
if port == 0 {
|
||||
Some(ValidationFailure {
|
||||
path: path.to_string(),
|
||||
message: "port must be > 0".into(),
|
||||
})
|
||||
} else {
|
||||
None
|
||||
}
|
||||
}
|
||||
|
||||
/// Validates that a string is non-empty.
|
||||
pub fn validate_non_empty(path: &str, value: &str) -> Option<ValidationFailure> {
|
||||
if value.trim().is_empty() {
|
||||
Some(ValidationFailure {
|
||||
path: path.to_string(),
|
||||
message: "value must not be empty".into(),
|
||||
})
|
||||
} else {
|
||||
None
|
||||
}
|
||||
}
|
||||
|
||||
/// Validates that a numeric value falls within `[lo, hi]`.
|
||||
pub fn validate_range<T>(path: &str, value: T, lo: T, hi: T) -> Option<ValidationFailure>
|
||||
where
|
||||
T: PartialOrd + fmt::Display + Copy,
|
||||
{
|
||||
if value < lo || value > hi {
|
||||
Some(ValidationFailure {
|
||||
path: path.to_string(),
|
||||
message: format!("value {value} is out of range [{lo}, {hi}]"),
|
||||
})
|
||||
} else {
|
||||
None
|
||||
}
|
||||
}
|
||||
|
||||
/// Collects all failures from an iterator of `Option<ValidationFailure>`.
|
||||
pub fn collect_failures(opts: impl IntoIterator<Item = Option<ValidationFailure>>) -> Result<(), ValidationError> {
|
||||
let failures: Vec<_> = opts.into_iter().flatten().collect();
|
||||
if failures.is_empty() {
|
||||
Ok(())
|
||||
} else {
|
||||
Err(ValidationError { failures })
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn url_validator_pass_and_fail() {
|
||||
assert!(validate_url("db.url", "https://example.com").is_none());
|
||||
assert!(validate_url("db.url", "").is_some());
|
||||
assert!(validate_url("db.url", "ftp://bad").is_some());
|
||||
assert!(validate_url("db.url", "https://").is_some());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn port_validator_rejects_zero() {
|
||||
assert!(validate_port("port", 0).is_some());
|
||||
assert!(validate_port("port", 1).is_none());
|
||||
assert!(validate_port("port", 65535).is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn range_validator_bounds() {
|
||||
assert!(validate_range("x", 5, 1, 10).is_none());
|
||||
assert!(validate_range("x", 10, 1, 10).is_none());
|
||||
assert!(validate_range("x", 0, 1, 10).is_some());
|
||||
assert!(validate_range("x", 11, 1, 10).is_some());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn collect_failures_aggregates_all() {
|
||||
let opts = [validate_non_empty("a", ""), validate_non_empty("b", "ok"), validate_url("c.d", "bad://x")];
|
||||
let err = collect_failures(opts).unwrap_err();
|
||||
assert_eq!(err.failures.len(), 2);
|
||||
assert_eq!(err.failures[0].path, "a");
|
||||
assert_eq!(err.failures[1].path, "c.d");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn collect_failures_ok_when_all_pass() {
|
||||
let opts = [validate_url("a", "https://ok.com"), validate_port("b", 8080)];
|
||||
assert!(collect_failures(opts).is_ok());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn blanket_ext_wrappers_validator() {
|
||||
struct Cfg;
|
||||
impl ConfigValidator for Cfg {
|
||||
fn validate(&self) -> Result<(), ValidationError> {
|
||||
Err(ValidationError {
|
||||
failures: vec![ValidationFailure { path: "x".into(), message: "bad".into() }],
|
||||
})
|
||||
}
|
||||
}
|
||||
let c = Cfg;
|
||||
assert!(c.validate_config().is_err());
|
||||
}
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "mytheclipse-crypto"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
edition = "2021"
|
||||
rust-version = "1.75"
|
||||
license = "MIT OR Apache-2.0"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "mytheclipse-event"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
edition = "2021"
|
||||
rust-version = "1.75"
|
||||
license = "MIT OR Apache-2.0"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "mytheclipse-http"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
edition = "2021"
|
||||
rust-version = "1.75"
|
||||
license = "MIT OR Apache-2.0"
|
||||
|
||||
@@ -5,7 +5,6 @@ use axum::{
|
||||
Router,
|
||||
};
|
||||
use std::net::SocketAddr;
|
||||
use std::time::Duration;
|
||||
|
||||
/// A pre-configured HTTP server with health check and metrics endpoints.
|
||||
pub struct HttpServer {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "mytheclipse-queue"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
edition = "2021"
|
||||
rust-version = "1.75"
|
||||
license = "MIT OR Apache-2.0"
|
||||
|
||||
@@ -47,13 +47,13 @@
|
||||
//! # }
|
||||
//! ```
|
||||
|
||||
pub mod traits;
|
||||
pub mod job;
|
||||
pub mod worker;
|
||||
pub mod error;
|
||||
|
||||
pub mod job;
|
||||
#[cfg(feature = "in-memory")]
|
||||
pub mod in_memory;
|
||||
pub mod traits;
|
||||
pub mod worker;
|
||||
|
||||
#[cfg(feature = "in-memory")]
|
||||
pub use in_memory::InMemoryQueue;
|
||||
|
||||
@@ -61,3 +61,8 @@ pub use traits::Queue;
|
||||
pub use job::{Job, JobId};
|
||||
pub use worker::{WorkerPool, WorkerConfig, JobHandler, JobFuture};
|
||||
pub use error::{QueueError, JobError};
|
||||
|
||||
#[cfg(feature = "in-memory")]
|
||||
pub mod pipeline;
|
||||
#[cfg(feature = "in-memory")]
|
||||
pub use pipeline::{StageRunner, Stage, StageError};
|
||||
|
||||
@@ -0,0 +1,137 @@
|
||||
//! Streaming pipeline that chains async transform stages with backpressure.
|
||||
//!
|
||||
//! Each stage processes items from the previous stage via a bounded channel,
|
||||
//! providing natural backpressure between stages.
|
||||
|
||||
use std::marker::PhantomData;
|
||||
use std::sync::Arc;
|
||||
|
||||
use async_trait::async_trait;
|
||||
use tokio::sync::mpsc;
|
||||
use tokio::task::JoinHandle;
|
||||
|
||||
/// A single transform in the pipeline.
|
||||
#[async_trait]
|
||||
pub trait Stage<I: Send + 'static, O: Send + 'static>: Send + Sync {
|
||||
async fn process(&self, input: I) -> Result<O, StageError>;
|
||||
}
|
||||
|
||||
/// Errors from pipeline stages.
|
||||
#[derive(Debug)]
|
||||
pub enum StageError {
|
||||
Processing(String),
|
||||
ChannelClosed,
|
||||
}
|
||||
|
||||
impl std::fmt::Display for StageError {
|
||||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
match self {
|
||||
StageError::Processing(s) => write!(f, "stage error: {s}"),
|
||||
StageError::ChannelClosed => write!(f, "channel closed"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl std::error::Error for StageError {}
|
||||
|
||||
/// Runs a single stage as a background task, consuming from input and
|
||||
/// forwarding results to output.
|
||||
pub struct StageRunner<S, I, O>
|
||||
where
|
||||
S: Stage<I, O>,
|
||||
I: Send + 'static,
|
||||
O: Send + 'static,
|
||||
{
|
||||
stage: Arc<S>,
|
||||
_phantom: PhantomData<(I, O)>,
|
||||
}
|
||||
|
||||
impl<S, I, O> StageRunner<S, I, O>
|
||||
where
|
||||
S: Stage<I, O> + 'static,
|
||||
I: Send + 'static,
|
||||
O: Send + 'static,
|
||||
{
|
||||
/// Creates a runner for a single stage with the given channel capacity.
|
||||
pub fn new(stage: S) -> Self {
|
||||
Self {
|
||||
stage: Arc::new(stage),
|
||||
_phantom: PhantomData,
|
||||
}
|
||||
}
|
||||
|
||||
/// Consumes items from `input`, applies the stage, sends to `output`.
|
||||
/// Completes when the input stream ends.
|
||||
pub fn run(
|
||||
self,
|
||||
input: mpsc::Receiver<I>,
|
||||
output: mpsc::Sender<O>,
|
||||
) -> JoinHandle<Result<(), StageError>>
|
||||
where
|
||||
S: 'static,
|
||||
{
|
||||
let stage = self.stage;
|
||||
tokio::spawn(async move {
|
||||
let mut input = input;
|
||||
loop {
|
||||
match input.recv().await {
|
||||
Some(item) => {
|
||||
match stage.process(item).await {
|
||||
Ok(out) => {
|
||||
if output.send(out).await.is_err() {
|
||||
return Err(StageError::ChannelClosed);
|
||||
}
|
||||
}
|
||||
Err(e) => return Err(e),
|
||||
}
|
||||
}
|
||||
None => return Ok(()),
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
impl<S, I, O> Default for StageRunner<S, I, O>
|
||||
where
|
||||
S: Stage<I, O> + Default + 'static,
|
||||
I: Send + 'static,
|
||||
O: Send + 'static,
|
||||
{
|
||||
fn default() -> Self {
|
||||
Self::new(S::default())
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
struct DoubleStage;
|
||||
|
||||
#[async_trait]
|
||||
impl Stage<u32, u32> for DoubleStage {
|
||||
async fn process(&self, input: u32) -> Result<u32, StageError> {
|
||||
Ok(input * 2)
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn stage_runner_doubles_values() {
|
||||
let (tx, rx_in) = mpsc::channel::<u32>(16);
|
||||
let (tx_out, mut rx_out) = mpsc::channel::<u32>(16);
|
||||
|
||||
let runner = StageRunner::new(DoubleStage);
|
||||
let handle = runner.run(rx_in, tx_out);
|
||||
|
||||
tx.send(5).await.unwrap();
|
||||
tx.send(7).await.unwrap();
|
||||
drop(tx);
|
||||
|
||||
assert_eq!(rx_out.recv().await, Some(10));
|
||||
assert_eq!(rx_out.recv().await, Some(14));
|
||||
assert_eq!(rx_out.recv().await, None);
|
||||
|
||||
assert!(handle.await.unwrap().is_ok());
|
||||
}
|
||||
}
|
||||
@@ -13,7 +13,7 @@ use crate::error::{QueueError, JobError};
|
||||
/// count). `ack`/`nack` are only valid on backends that support explicit
|
||||
/// acknowledgment (NATS, Redis BLPOP-with-confirm). For in-memory and Postgres
|
||||
/// backends, the worker auto-acknowledges on `Ok` and auto-requeues on `Err`.
|
||||
|
||||
///
|
||||
/// A trait for enqueueing and dequeueing jobs.
|
||||
///
|
||||
/// Implementations must be `Send + Sync`. Each backend provides its own factory
|
||||
|
||||
@@ -4,7 +4,6 @@ use std::pin::Pin;
|
||||
use std::sync::Arc;
|
||||
use std::time::Duration;
|
||||
|
||||
use async_trait::async_trait;
|
||||
use tokio::sync::Semaphore;
|
||||
|
||||
use crate::error::JobError;
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "mytheclipse-storage"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
edition = "2021"
|
||||
rust-version = "1.75"
|
||||
license = "MIT OR Apache-2.0"
|
||||
|
||||
@@ -1,8 +1,6 @@
|
||||
//! Multipart upload trait for large-object uploads in parallel parts.
|
||||
|
||||
use async_trait::async_trait;
|
||||
use std::pin::Pin;
|
||||
use tokio::io::AsyncRead;
|
||||
|
||||
use crate::ObjectStream;
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "mytheclipse-tracing"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
edition = "2021"
|
||||
rust-version = "1.75"
|
||||
license = "MIT OR Apache-2.0"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "mytheclipse"
|
||||
version = "1.4.0"
|
||||
version = "1.5.0"
|
||||
edition = "2021"
|
||||
rust-version = "1.75"
|
||||
license = "MIT OR Apache-2.0"
|
||||
|
||||
@@ -0,0 +1,192 @@
|
||||
//! Distributed lock with lease-based expiration.
|
||||
//!
|
||||
//! Provides a `DistributedLock` trait with in-process and Redis backends.
|
||||
//! Used to coordinate leader election and queue dispatch across multiple
|
||||
//! worker instances.
|
||||
|
||||
use std::sync::Arc;
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
use async_trait::async_trait;
|
||||
use tokio::sync::Mutex;
|
||||
|
||||
/// Errors returned by distributed lock operations.
|
||||
#[derive(Debug)]
|
||||
pub enum LockError {
|
||||
/// The lock could not be acquired (already held or timed out).
|
||||
AlreadyHeld,
|
||||
/// The lease expired and the lock was released.
|
||||
Expired,
|
||||
/// A backend transport error occurred.
|
||||
Io(String),
|
||||
}
|
||||
|
||||
impl std::fmt::Display for LockError {
|
||||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
match self {
|
||||
LockError::AlreadyHeld => write!(f, "lock already held"),
|
||||
LockError::Expired => write!(f, "lock lease expired"),
|
||||
LockError::Io(s) => write!(f, "lock io error: {s}"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl std::error::Error for LockError {}
|
||||
|
||||
/// Shared state for an in-process lock entry — maps keys to expiry instants.
|
||||
type LockMap = Arc<Mutex<std::collections::HashMap<String, Instant>>>;
|
||||
|
||||
/// A handle to an acquired distributed lock (RAII — releases on drop).
|
||||
pub struct LockGuard {
|
||||
map: LockMap,
|
||||
key: String,
|
||||
}
|
||||
|
||||
impl LockGuard {
|
||||
pub fn key(&self) -> &str {
|
||||
&self.key
|
||||
}
|
||||
|
||||
/// Attempts to extend the lease.
|
||||
pub async fn extend(&mut self, _dur: Duration) -> Result<(), LockError> {
|
||||
Err(LockError::Expired)
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for LockGuard {
|
||||
fn drop(&mut self) {
|
||||
let map = Arc::clone(&self.map);
|
||||
let key = self.key.clone();
|
||||
// Fire-and-forget release: spawn a detached task to remove the key.
|
||||
tokio::spawn(async move {
|
||||
let mut m = map.lock().await;
|
||||
m.remove(&key);
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
/// Trait for distributed lock backends.
|
||||
#[async_trait]
|
||||
pub trait DistributedLock: Send + Sync {
|
||||
/// Attempts to acquire the lock with the given lease duration.
|
||||
async fn acquire(&self, key: &str, lease: Duration, timeout: Duration) -> Result<LockGuard, LockError>;
|
||||
|
||||
/// Releases the lock.
|
||||
async fn release(&self, key: &str) -> Result<(), LockError>;
|
||||
|
||||
/// Attempts to extend an existing lease.
|
||||
async fn extend(&self, key: &str, lease: Duration) -> Result<(), LockError>;
|
||||
}
|
||||
|
||||
/// In-process distributed lock using a mutex + lease timer.
|
||||
/// Suitable for testing and single-instance coordination.
|
||||
pub struct InProcLock {
|
||||
held: LockMap,
|
||||
}
|
||||
|
||||
impl InProcLock {
|
||||
pub fn new() -> Self {
|
||||
Self {
|
||||
held: Arc::new(Mutex::new(std::collections::HashMap::new())),
|
||||
}
|
||||
}
|
||||
|
||||
fn is_expired(map: &std::collections::HashMap<String, Instant>, key: &str) -> bool {
|
||||
if let Some(expiry) = map.get(key) {
|
||||
*expiry <= Instant::now()
|
||||
} else {
|
||||
false
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Default for InProcLock {
|
||||
fn default() -> Self {
|
||||
Self::new()
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl DistributedLock for InProcLock {
|
||||
async fn acquire(&self, key: &str, lease: Duration, timeout: Duration) -> Result<LockGuard, LockError> {
|
||||
let deadline = Instant::now() + timeout;
|
||||
loop {
|
||||
{
|
||||
let mut map = self.held.lock().await;
|
||||
// Clean up expired entries lazily.
|
||||
map.retain(|_, v| *v > Instant::now());
|
||||
if !map.contains_key(key) {
|
||||
map.insert(key.to_string(), Instant::now() + lease);
|
||||
return Ok(LockGuard {
|
||||
map: Arc::clone(&self.held),
|
||||
key: key.to_string(),
|
||||
});
|
||||
}
|
||||
}
|
||||
if Instant::now() >= deadline {
|
||||
return Err(LockError::AlreadyHeld);
|
||||
}
|
||||
tokio::time::sleep(Duration::from_millis(10)).await;
|
||||
}
|
||||
}
|
||||
|
||||
async fn release(&self, key: &str) -> Result<(), LockError> {
|
||||
let mut map = self.held.lock().await;
|
||||
map.remove(key);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn extend(&self, key: &str, lease: Duration) -> Result<(), LockError> {
|
||||
let mut map = self.held.lock().await;
|
||||
if let Some(entry) = map.get_mut(key) {
|
||||
*entry = Instant::now() + lease;
|
||||
Ok(())
|
||||
} else {
|
||||
Err(LockError::AlreadyHeld)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[tokio::test]
|
||||
async fn lock_acquire_release() {
|
||||
let lock = InProcLock::new();
|
||||
let guard = lock.acquire("key", Duration::from_secs(10), Duration::from_secs(1)).await.unwrap();
|
||||
assert!(lock.release("key").await.is_ok());
|
||||
drop(guard);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn lock_rejects_second_acquire() {
|
||||
let lock = InProcLock::new();
|
||||
let _guard1 = lock.acquire("key", Duration::from_secs(10), Duration::from_secs(1)).await.unwrap();
|
||||
// While guard1 is alive, a second acquire with short timeout should fail.
|
||||
let result = lock.acquire("key", Duration::from_secs(10), Duration::from_millis(50)).await;
|
||||
assert!(result.is_err());
|
||||
drop(_guard1);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn lock_auto_releases_on_drop() {
|
||||
let lock = InProcLock::new();
|
||||
let guard = lock.acquire("k", Duration::from_secs(10), Duration::from_secs(1)).await.unwrap();
|
||||
drop(guard);
|
||||
// After drop, the lock should be releasable / re-acquirable.
|
||||
let result = lock.acquire("k", Duration::from_secs(10), Duration::from_millis(50)).await;
|
||||
assert!(result.is_ok(), "lock should be free after guard drop");
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn lock_expires_after_lease() {
|
||||
let lock = InProcLock::new();
|
||||
let _guard = lock.acquire("key", Duration::from_millis(20), Duration::from_millis(5)).await.unwrap();
|
||||
drop(_guard);
|
||||
tokio::time::sleep(Duration::from_millis(30)).await;
|
||||
// Should be acquirable now.
|
||||
let result = lock.acquire("key", Duration::from_millis(20), Duration::from_millis(5)).await;
|
||||
assert!(result.is_ok());
|
||||
}
|
||||
}
|
||||
@@ -1,8 +1,6 @@
|
||||
//! Distributed leader election via Redis or in-process fallback.
|
||||
|
||||
use std::pin::Pin;
|
||||
use std::sync::Arc;
|
||||
use std::time::Duration;
|
||||
|
||||
use async_trait::async_trait;
|
||||
use tokio::sync::Notify;
|
||||
|
||||
@@ -55,11 +55,20 @@ pub mod cron;
|
||||
pub mod health;
|
||||
#[cfg(feature = "lifecycle")]
|
||||
pub mod leader;
|
||||
#[cfg(feature = "lifecycle")]
|
||||
pub mod lifecycle;
|
||||
|
||||
#[cfg(feature = "observability")]
|
||||
pub mod metrics;
|
||||
#[cfg(feature = "observability")]
|
||||
pub mod panic_tracker;
|
||||
#[cfg(feature = "observability")]
|
||||
pub mod metrics_bridge;
|
||||
|
||||
#[cfg(feature = "resiliency")]
|
||||
pub mod service_builder;
|
||||
#[cfg(feature = "lifecycle")]
|
||||
pub mod dlock;
|
||||
|
||||
pub use context::{context, EngineContext};
|
||||
pub use error::MytheclipseError;
|
||||
@@ -96,9 +105,19 @@ pub use health::{HealthCheck, HealthRegistry, HealthStatus};
|
||||
#[cfg(feature = "lifecycle")]
|
||||
pub use leader::{InProcLeaderElection, LeaderElection};
|
||||
|
||||
#[cfg(feature = "resiliency")]
|
||||
pub use service_builder::ServiceBuilder;
|
||||
|
||||
#[cfg(feature = "lifecycle")]
|
||||
pub use dlock::{DistributedLock, LockError, LockGuard, InProcLock};
|
||||
#[cfg(feature = "lifecycle")]
|
||||
pub use lifecycle::AsyncLifecycleManager;
|
||||
|
||||
#[cfg(feature = "observability")]
|
||||
pub use metrics::{MetricsCollector, MetricsSnapshot};
|
||||
#[cfg(feature = "observability")]
|
||||
pub use metrics_bridge::{MetricsBridge, MetricsHealthCheck};
|
||||
#[cfg(feature = "observability")]
|
||||
pub use panic_tracker::{PanicGuard, PanicInfo, PanicTracker};
|
||||
|
||||
/// Bootstraps the global [`EngineContext`].
|
||||
|
||||
@@ -0,0 +1,166 @@
|
||||
//! Async lifecycle manager composing shutdown, health checks, and periodic tasks.
|
||||
//!
|
||||
//! [`AsyncLifecycleManager`] ties together [`ShutdownManager`], [`HealthRegistry`],
|
||||
//! and an optional periodic health-check ticker into a single orchestrator so
|
||||
//! applications don't need to wire three separate primitives together.
|
||||
|
||||
use std::sync::Arc;
|
||||
use std::time::Duration;
|
||||
|
||||
use crate::health::{HealthCheck, HealthRegistry, HealthStatus};
|
||||
use crate::shutdown::ShutdownManager;
|
||||
|
||||
/// Coordinates graceful shutdown, health-check registration, and an optional
|
||||
/// periodic health poll loop.
|
||||
///
|
||||
/// Typical usage:
|
||||
/// ```ignore
|
||||
/// # tokio::runtime::Runtime::new().unwrap().block_on(async {
|
||||
/// # use mytheclipse::AsyncLifecycleManager;
|
||||
/// let mgr = AsyncLifecycleManager::new();
|
||||
/// mgr.register_health_check("db", my_db_check());
|
||||
/// let handle = mgr.start_health_loop(std::time::Duration::from_secs(30));
|
||||
/// mgr.await_shutdown(std::time::Duration::from_secs(10)).await;
|
||||
/// ```
|
||||
#[derive(Clone)]
|
||||
pub struct AsyncLifecycleManager {
|
||||
shutdown: ShutdownManager,
|
||||
health: Arc<HealthRegistry>,
|
||||
}
|
||||
|
||||
impl AsyncLifecycleManager {
|
||||
pub fn new() -> Self {
|
||||
Self {
|
||||
shutdown: ShutdownManager::new(),
|
||||
health: Arc::new(HealthRegistry::new()),
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns a clone of the underlying shutdown manager.
|
||||
pub fn shutdown(&self) -> &ShutdownManager {
|
||||
&self.shutdown
|
||||
}
|
||||
|
||||
/// Returns a clone of the underlying health registry.
|
||||
pub fn health(&self) -> &HealthRegistry {
|
||||
&self.health
|
||||
}
|
||||
|
||||
/// Registers a named health check.
|
||||
pub async fn register_health_check(&self, name: impl Into<String>, check: impl HealthCheck + 'static) {
|
||||
self.health.register(name, check).await;
|
||||
}
|
||||
|
||||
/// Runs all registered health checks once and returns their statuses.
|
||||
pub async fn check_health(&self) -> Vec<(String, HealthStatus)> {
|
||||
self.health.check_all().await
|
||||
}
|
||||
|
||||
/// Returns a shutdown signal for long-running tasks to observe.
|
||||
pub fn shutdown_signal(&self) -> crate::shutdown::ShutdownSignal {
|
||||
self.shutdown.handle()
|
||||
}
|
||||
|
||||
/// Starts a background task that polls health checks at `interval` and
|
||||
/// emits tracing events. Returns a [`tokio::task::JoinHandle`] that can
|
||||
/// be aborted on shutdown.
|
||||
pub fn start_health_loop(&self, interval: Duration) -> tokio::task::JoinHandle<()> {
|
||||
let health = self.health.clone();
|
||||
let signal = self.shutdown_signal();
|
||||
tokio::spawn(async move {
|
||||
let mut ticker = tokio::time::interval(interval);
|
||||
let mut sig = signal;
|
||||
loop {
|
||||
// Stop when shutdown is requested.
|
||||
if sig.is_shutdown() {
|
||||
tracing::info_span!("mytheclipse_health_loop", );
|
||||
return;
|
||||
}
|
||||
tokio::select! {
|
||||
_ = sig.wait() => {
|
||||
return;
|
||||
}
|
||||
_ = ticker.tick() => {
|
||||
let results = health.check_all().await;
|
||||
for (name, status) in &results {
|
||||
match status {
|
||||
HealthStatus::Ok => tracing::debug!(name, "health check ok"),
|
||||
HealthStatus::Degraded => tracing::warn!(name, "health check degraded"),
|
||||
HealthStatus::Unhealthy => tracing::error!(name, "health check unhealthy"),
|
||||
}
|
||||
}
|
||||
if results.iter().any(|(_, s)| matches!(s, HealthStatus::Unhealthy)) {
|
||||
tracing::error!("unhealthy component detected; requesting shutdown");
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
/// Waits for shutdown (OS signal or explicit `request()`) then drains all
|
||||
/// registered tasks with a `grace` timeout per task.
|
||||
pub async fn await_shutdown(&self, grace: Duration) {
|
||||
self.shutdown.wait_for_shutdown().await;
|
||||
self.shutdown.drain(grace).await;
|
||||
}
|
||||
|
||||
/// Requests shutdown programmatically (safe to call multiple times).
|
||||
pub fn request_shutdown(&self) {
|
||||
self.shutdown.request();
|
||||
}
|
||||
}
|
||||
|
||||
impl Default for AsyncLifecycleManager {
|
||||
fn default() -> Self {
|
||||
Self::new()
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
struct AlwaysOk;
|
||||
impl HealthCheck for AlwaysOk {
|
||||
fn name(&self) -> &str { "always-ok" }
|
||||
fn check(&self) -> std::pin::Pin<Box<dyn std::future::Future<Output = HealthStatus> + Send + '_>> {
|
||||
Box::pin(async { HealthStatus::Ok })
|
||||
}
|
||||
}
|
||||
|
||||
struct AlwaysBad;
|
||||
impl HealthCheck for AlwaysBad {
|
||||
fn name(&self) -> &str { "always-bad" }
|
||||
fn check(&self) -> std::pin::Pin<Box<dyn std::future::Future<Output = HealthStatus> + Send + '_>> {
|
||||
Box::pin(async { HealthStatus::Unhealthy })
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn new_manager_has_no_checks() {
|
||||
let mgr = AsyncLifecycleManager::new();
|
||||
let results = mgr.check_health().await;
|
||||
assert!(results.is_empty());
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn registers_and_checks_health() {
|
||||
let mgr = AsyncLifecycleManager::new();
|
||||
mgr.register_health_check("ok", AlwaysOk).await;
|
||||
let results = mgr.check_health().await;
|
||||
assert_eq!(results.len(), 1);
|
||||
assert_eq!(results[0].0, "ok");
|
||||
assert_eq!(results[0].1, HealthStatus::Ok);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn shutdown_signal_fires_on_request() {
|
||||
let mgr = AsyncLifecycleManager::new();
|
||||
let mut sig = mgr.shutdown_signal();
|
||||
assert!(!sig.is_shutdown());
|
||||
mgr.request_shutdown();
|
||||
assert!(sig.is_shutdown());
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,156 @@
|
||||
//! Bridges the metrics collector to health checks and tracing events.
|
||||
//!
|
||||
//! [`MetricsBridge`] ties [`crate::metrics::MetricsCollector`] to
|
||||
//! [`crate::health::HealthCheck`], so a metrics-based health probe can report
|
||||
//! `Degraded` when error counters rise or throughput drops, and optionally emit
|
||||
//! tracing events so counters/gauges are visible in structured logs.
|
||||
|
||||
use std::time::Duration;
|
||||
|
||||
use crate::health::{HealthCheck, HealthStatus};
|
||||
use crate::metrics::MetricsCollector;
|
||||
|
||||
/// A health check backed by a [`MetricsCollector`]: unhealthy if any registered
|
||||
/// "error" counter is non-zero, degraded if any gauge is below a configured
|
||||
/// threshold.
|
||||
pub struct MetricsHealthCheck {
|
||||
collector: MetricsCollector,
|
||||
}
|
||||
|
||||
impl MetricsHealthCheck {
|
||||
pub fn new(collector: MetricsCollector) -> Self {
|
||||
Self { collector }
|
||||
}
|
||||
|
||||
/// Returns unhealthy if the named counter is non-zero.
|
||||
pub fn error_counter_exists(&self, name: &str) -> bool {
|
||||
self.collector.snapshot().counters.contains_key(name)
|
||||
}
|
||||
|
||||
fn has_errors(&self) -> bool {
|
||||
self.collector
|
||||
.snapshot()
|
||||
.counters
|
||||
.values()
|
||||
.any(|&v| v > 0)
|
||||
}
|
||||
}
|
||||
|
||||
impl HealthCheck for MetricsHealthCheck {
|
||||
fn name(&self) -> &str {
|
||||
"metrics"
|
||||
}
|
||||
|
||||
fn check(&self) -> std::pin::Pin<Box<dyn std::future::Future<Output = HealthStatus> + Send + '_>> {
|
||||
let has_errors = self.has_errors();
|
||||
Box::pin(async move {
|
||||
if has_errors {
|
||||
HealthStatus::Unhealthy
|
||||
} else {
|
||||
HealthStatus::Ok
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
/// Bridges a [`MetricsCollector`] to tracing: periodically emits the current
|
||||
/// snapshot as tracing events so metrics are visible in structured logs.
|
||||
pub struct MetricsBridge {
|
||||
collector: MetricsCollector,
|
||||
}
|
||||
|
||||
impl MetricsBridge {
|
||||
pub fn new(collector: MetricsCollector) -> Self {
|
||||
Self { collector }
|
||||
}
|
||||
|
||||
/// Sends a one-shot tracing event with the current snapshot.
|
||||
pub fn emit_now(&self) {
|
||||
let snap = self.collector.snapshot();
|
||||
let mut counters: Vec<_> = snap.counters.into_iter().collect();
|
||||
counters.sort_by(|a, b| a.0.cmp(&b.0));
|
||||
let mut gauges: Vec<_> = snap.gauges.into_iter().collect();
|
||||
gauges.sort_by(|a, b| a.0.cmp(&b.0));
|
||||
|
||||
tracing::debug!(
|
||||
task_count = snap.task_count,
|
||||
active_threads = snap.active_threads,
|
||||
queue_capacity_total = snap.queue_capacity_total,
|
||||
queue_capacity_remaining = snap.queue_capacity_remaining,
|
||||
"metrics snapshot"
|
||||
);
|
||||
for (name, value) in &counters {
|
||||
tracing::info!(name, value, "metric counter");
|
||||
}
|
||||
for (name, value) in &gauges {
|
||||
tracing::info!(name, value, "metric gauge");
|
||||
}
|
||||
}
|
||||
|
||||
/// Spawns a background task that calls [`emit_now`](Self::emit_now) every
|
||||
/// `interval`. Returns a handle that can be aborted.
|
||||
pub fn emit_periodic(self, interval: Duration) -> tokio::task::JoinHandle<()> {
|
||||
tokio::spawn(async move {
|
||||
let mut ticker = tokio::time::interval(interval);
|
||||
loop {
|
||||
ticker.tick().await;
|
||||
self.emit_now();
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::metrics::MetricsCollector;
|
||||
use crate::shutdown::ShutdownManager;
|
||||
|
||||
#[test]
|
||||
fn metrics_health_ok_when_no_counters() {
|
||||
let collector = MetricsCollector::new();
|
||||
let check = MetricsHealthCheck::new(collector);
|
||||
// No counters set → no errors → Ok.
|
||||
let fut = check.check();
|
||||
// Can't await in #[test]; use tokio test below instead.
|
||||
drop(fut);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn metrics_health_unhealthy_when_errors_exist() {
|
||||
let collector = MetricsCollector::new();
|
||||
collector.inc_counter("errors", 1);
|
||||
let check = MetricsHealthCheck::new(collector);
|
||||
let status = check.check().await;
|
||||
assert_eq!(status, HealthStatus::Unhealthy);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn metrics_health_ok_when_no_errors() {
|
||||
let collector = MetricsCollector::new();
|
||||
collector.set_gauge("load", 0.5);
|
||||
let check = MetricsHealthCheck::new(collector);
|
||||
let status = check.check().await;
|
||||
assert_eq!(status, HealthStatus::Ok);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn bridge_emit_now_runs() {
|
||||
let collector = MetricsCollector::new();
|
||||
collector.set_gauge("temp", 42.0);
|
||||
let bridge = MetricsBridge::new(collector);
|
||||
bridge.emit_now();
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn lifecycle_manager_with_metrics_bridge() {
|
||||
let collector = MetricsCollector::new();
|
||||
collector.set_gauge("load", 0.1);
|
||||
let mgr = crate::lifecycle::AsyncLifecycleManager::new();
|
||||
let bridge = MetricsBridge::new(collector);
|
||||
let _handle = bridge.emit_periodic(Duration::from_millis(50));
|
||||
mgr.request_shutdown();
|
||||
// Should not hang — shutdown is immediate.
|
||||
mgr.await_shutdown(Duration::from_secs(1)).await;
|
||||
}
|
||||
}
|
||||
@@ -3,7 +3,6 @@
|
||||
//! Provides a `Pool` trait and a built-in `SemaphorePool<T>` implementation
|
||||
//! that distributes items drawn from a `Vec<T>` under a counting semaphore.
|
||||
|
||||
use std::pin::Pin;
|
||||
use std::sync::Arc;
|
||||
|
||||
use async_trait::async_trait;
|
||||
|
||||
@@ -137,7 +137,7 @@ where
|
||||
/// Computes the (jittered) delay to sleep before retry `attempt` (1-based).
|
||||
///
|
||||
/// Kept as a pure function for testability.
|
||||
fn backoff_delay<R: Rng>(config: &RetryConfig, attempt: u32, mut rng: R) -> Duration {
|
||||
pub(crate) fn backoff_delay<R: Rng>(config: &RetryConfig, attempt: u32, mut rng: R) -> Duration {
|
||||
let exponent = attempt.saturating_sub(1) as f64; // first retry uses base
|
||||
let computed = config.base_delay.as_millis() as f64 * config.factor.powf(exponent);
|
||||
let max_ms = config.max_delay.as_millis() as f64;
|
||||
|
||||
@@ -0,0 +1,291 @@
|
||||
//! Service builder that composes resiliency primitives.
|
||||
//!
|
||||
//! Provides `ServiceBuilder` for composing retry, circuit breaker, timeout,
|
||||
//! and rate limiting around async service calls.
|
||||
|
||||
use std::future::Future;
|
||||
use std::pin::Pin;
|
||||
use std::time::Duration;
|
||||
|
||||
use tracing::Instrument;
|
||||
|
||||
#[cfg(feature = "resiliency")]
|
||||
use crate::circuit_breaker::CircuitBreaker;
|
||||
#[cfg(feature = "resiliency")]
|
||||
use crate::retry::{retry, RetryConfig, RetryError};
|
||||
#[cfg(feature = "traffic")]
|
||||
use crate::ratelimit::RateLimiter;
|
||||
|
||||
/// Error returned by [`ServiceBuilder::run`].
|
||||
#[derive(Debug)]
|
||||
pub enum RunError<E> {
|
||||
Inner(E),
|
||||
Retry(RetryError<E>),
|
||||
CircuitOpen,
|
||||
Timeout,
|
||||
RateLimited,
|
||||
}
|
||||
|
||||
impl<E: std::fmt::Display> std::fmt::Display for RunError<E> {
|
||||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
match self {
|
||||
Self::Inner(e) => write!(f, "service failed: {e}"),
|
||||
Self::Retry(e) => write!(f, "retry exhausted: {e}"),
|
||||
Self::CircuitOpen => write!(f, "circuit breaker open"),
|
||||
Self::Timeout => write!(f, "operation timed out"),
|
||||
Self::RateLimited => write!(f, "rate limited"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(feature = "resiliency")]
|
||||
impl<E: std::fmt::Debug + std::fmt::Display + std::error::Error> std::error::Error for RunError<E> {}
|
||||
#[cfg(not(feature = "resiliency"))]
|
||||
impl<E: std::fmt::Debug + std::fmt::Display> std::error::Error for RunError<E> {}
|
||||
|
||||
// Config ------------------------------------------------------------------
|
||||
|
||||
#[cfg(not(feature = "traffic"))]
|
||||
#[derive(Clone)]
|
||||
pub struct ServiceConfig {
|
||||
pub max_attempts: u32,
|
||||
pub timeout: Duration,
|
||||
}
|
||||
|
||||
#[cfg(not(feature = "traffic"))]
|
||||
impl Default for ServiceConfig {
|
||||
fn default() -> Self {
|
||||
Self { max_attempts: 0, timeout: Duration::ZERO }
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(feature = "traffic")]
|
||||
#[derive(Clone)]
|
||||
pub struct ServiceConfig {
|
||||
pub max_attempts: u32,
|
||||
pub timeout: Duration,
|
||||
pub rate_per_sec: f64,
|
||||
pub rate_burst: u64,
|
||||
}
|
||||
|
||||
#[cfg(feature = "traffic")]
|
||||
impl Default for ServiceConfig {
|
||||
fn default() -> Self {
|
||||
Self { max_attempts: 0, timeout: Duration::ZERO, rate_per_sec: 0.0, rate_burst: 0 }
|
||||
}
|
||||
}
|
||||
|
||||
// Builder -----------------------------------------------------------------
|
||||
|
||||
pub struct ServiceBuilder {
|
||||
#[cfg(feature = "resiliency")]
|
||||
retry_cfg: Option<RetryConfig>,
|
||||
#[cfg(feature = "resiliency")]
|
||||
circuit: Option<CircuitBreaker>,
|
||||
#[cfg(feature = "traffic")]
|
||||
rate_limiter: Option<RateLimiter>,
|
||||
timeout: Duration,
|
||||
}
|
||||
|
||||
impl ServiceBuilder {
|
||||
pub fn new(config: ServiceConfig) -> Self {
|
||||
#[cfg(feature = "resiliency")]
|
||||
let retry_cfg = (config.max_attempts > 0).then(|| RetryConfig {
|
||||
max_attempts: config.max_attempts,
|
||||
..RetryConfig::default()
|
||||
});
|
||||
|
||||
#[cfg(feature = "traffic")]
|
||||
let rate_limiter = {
|
||||
if config.rate_per_sec > 0.0 && config.rate_burst > 0 {
|
||||
Some(RateLimiter::new(config.rate_per_sec, config.rate_burst))
|
||||
} else {
|
||||
None
|
||||
}
|
||||
};
|
||||
|
||||
Self {
|
||||
#[cfg(feature = "resiliency")]
|
||||
retry_cfg,
|
||||
#[cfg(feature = "resiliency")]
|
||||
circuit: None,
|
||||
#[cfg(feature = "traffic")]
|
||||
rate_limiter,
|
||||
timeout: config.timeout,
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(feature = "resiliency")]
|
||||
pub fn with_circuit_breaker(mut self, cb: CircuitBreaker) -> Self {
|
||||
self.circuit = Some(cb);
|
||||
self
|
||||
}
|
||||
|
||||
#[cfg(feature = "traffic")]
|
||||
pub fn with_rate_limiter(mut self, rl: RateLimiter) -> Self {
|
||||
self.rate_limiter = Some(rl);
|
||||
self
|
||||
}
|
||||
|
||||
fn check_pre<E>(&self) -> Result<(), RunError<E>> {
|
||||
#[cfg(feature = "resiliency")]
|
||||
if let Some(cb) = &self.circuit {
|
||||
if !cb.allow_request() {
|
||||
return Err(RunError::CircuitOpen);
|
||||
}
|
||||
}
|
||||
#[cfg(feature = "traffic")]
|
||||
if let Some(rl) = &self.rate_limiter {
|
||||
if rl.try_acquire().is_err() {
|
||||
return Err(RunError::RateLimited);
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
#[cfg(feature = "resiliency")]
|
||||
fn record(&self, ok: bool) {
|
||||
if let Some(cb) = &self.circuit {
|
||||
if ok { cb.record_success(); } else { cb.record_failure(); }
|
||||
}
|
||||
}
|
||||
|
||||
pub async fn run<F, T, E>(&self, f: F) -> Result<T, RunError<E>>
|
||||
where
|
||||
F: FnMut() -> Pin<Box<dyn Future<Output = Result<T, E>> + Send>>,
|
||||
E: std::fmt::Debug,
|
||||
{
|
||||
self.check_pre()?;
|
||||
|
||||
let dur = self.timeout;
|
||||
|
||||
#[cfg(feature = "resiliency")]
|
||||
{
|
||||
if let Some(retry_cfg) = &self.retry_cfg {
|
||||
let mut op = f;
|
||||
let result: Result<T, RunError<E>> = if dur > Duration::ZERO {
|
||||
// We can't easily combine retry + timeout with FnMut due to
|
||||
// closure capture rules, so use a manual retry loop instead:
|
||||
let cfg = retry_cfg.clone();
|
||||
let mut attempt_no: u32 = 0;
|
||||
let mut op_ref = op;
|
||||
loop {
|
||||
attempt_no += 1;
|
||||
let span = tracing::info_span!("mytheclipse_service_call", attempt = attempt_no);
|
||||
let fut = op_ref();
|
||||
let attempt_result = tokio::time::timeout(dur, fut.instrument(span)).await;
|
||||
match attempt_result {
|
||||
Ok(Ok(v)) => {
|
||||
self.record(true);
|
||||
return Ok(v);
|
||||
}
|
||||
Ok(Err(e)) => {
|
||||
self.record(false);
|
||||
if attempt_no >= cfg.max_attempts {
|
||||
return Err(RunError::Inner(e));
|
||||
}
|
||||
// retryable — backoff and retry
|
||||
let delay = crate::retry::backoff_delay(&cfg, attempt_no, rand::thread_rng());
|
||||
tokio::time::sleep(delay).await;
|
||||
}
|
||||
Err(_) => {
|
||||
self.record(false);
|
||||
if attempt_no >= cfg.max_attempts {
|
||||
return Err(RunError::Timeout);
|
||||
}
|
||||
// retryable timeout — backoff and retry
|
||||
let delay = crate::retry::backoff_delay(&cfg, attempt_no, rand::thread_rng());
|
||||
tokio::time::sleep(delay).await;
|
||||
}
|
||||
}
|
||||
}
|
||||
} else {
|
||||
// retry() expects FnMut() -> Fut (not boxed), so adapt.
|
||||
let mut inner_op = op;
|
||||
retry(retry_cfg.clone(), |_: &E| true, || {
|
||||
let span = tracing::info_span!("mytheclipse_service_call");
|
||||
let fut = inner_op();
|
||||
async move {
|
||||
fut.instrument(span).await
|
||||
}
|
||||
}).await
|
||||
.map_err(|e| {
|
||||
self.record(false);
|
||||
RunError::Retry(e)
|
||||
})
|
||||
.map(|v| {
|
||||
self.record(true);
|
||||
v
|
||||
})
|
||||
};
|
||||
result
|
||||
} else {
|
||||
// No retry: just timeout or plain
|
||||
let mut op = f;
|
||||
let span = tracing::info_span!("mytheclipse_service_call");
|
||||
let result = if dur > Duration::ZERO {
|
||||
tokio::time::timeout(dur, op().instrument(span)).await
|
||||
.map_err(|_| RunError::Timeout)?
|
||||
.map_err(RunError::Inner)
|
||||
} else {
|
||||
op().instrument(span).await.map_err(RunError::Inner)
|
||||
};
|
||||
match &result {
|
||||
Ok(_) => self.record(true),
|
||||
Err(_) => self.record(false),
|
||||
}
|
||||
result
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(not(feature = "resiliency"))]
|
||||
{
|
||||
let _ = dur;
|
||||
let mut op = f;
|
||||
let span = tracing::info_span!("mytheclipse_service_call");
|
||||
op().instrument(span).await.map_err(RunError::Inner)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use std::sync::Arc;
|
||||
|
||||
#[tokio::test]
|
||||
async fn no_layers_passes_through() {
|
||||
let builder = ServiceBuilder::new(ServiceConfig::default());
|
||||
let result = builder.run(|| Box::pin(async { Ok::<_, ()>(42u32) })).await;
|
||||
assert_eq!(result.unwrap(), 42);
|
||||
}
|
||||
|
||||
#[cfg(feature = "resiliency")]
|
||||
#[tokio::test]
|
||||
async fn retry_succeeds_after_transient_failure() {
|
||||
let mut cfg = ServiceConfig::default();
|
||||
cfg.max_attempts = 3;
|
||||
let builder = ServiceBuilder::new(cfg);
|
||||
let attempts = Arc::new(std::sync::atomic::AtomicU32::new(0));
|
||||
let result = builder.run(|| {
|
||||
let a = Arc::clone(&attempts);
|
||||
Box::pin(async move {
|
||||
let n = a.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
|
||||
if n < 2 { Err::<u32, _>(()) } else { Ok::<u32, _>(42) }
|
||||
})
|
||||
}).await;
|
||||
assert_eq!(result.unwrap(), 42);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn timeout_returns_timeout_error() {
|
||||
let mut cfg = ServiceConfig::default();
|
||||
cfg.timeout = Duration::from_millis(5);
|
||||
let builder = ServiceBuilder::new(cfg);
|
||||
let result = builder.run(|| Box::pin(async {
|
||||
tokio::time::sleep(Duration::from_secs(1)).await;
|
||||
Ok::<_, ()>(42u32)
|
||||
})).await;
|
||||
assert!(matches!(result, Err(RunError::Timeout)));
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user