Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
f9df8f2887 | ||
|
|
97b5e02820 | ||
|
|
bf8f76cc10 | ||
|
|
510aadc066 |
@@ -0,0 +1,32 @@
|
|||||||
|
# Implementation Spec: Round 5
|
||||||
|
|
||||||
|
## Status: COMPLETE
|
||||||
|
|
||||||
|
## New Features
|
||||||
|
|
||||||
|
### 1. CircuitBreakerHealthCheck (mytheclipse-core, observability+resiliency)
|
||||||
|
- `CircuitBreakerHealthCheck` di metrics_bridge.rs — HealthCheck impl yang memetakan CircuitBreaker snapshot state → HealthStatus (Open→Unhealthy, HalfOpen→Degraded, Closed→Ok)
|
||||||
|
- Gated `#[cfg(feature="resiliency")]`; re-export gated `#[cfg(all(observability, resiliency))]`
|
||||||
|
- `observability` feature now implies `lifecycle` (needed for crate::health module access)
|
||||||
|
|
||||||
|
### 2. TypedKeyRegistry (mytheclipse-crypto, password)
|
||||||
|
- `TypedKeyRegistry<K,V>` di key_registry.rs — ID-based key lookup + rotation + revoke, wraps KeyRing
|
||||||
|
- `key_for(id) -> Option<&K>`, `rotate_with_id(id, key)`, `revoke(id)`
|
||||||
|
|
||||||
|
### 3. MetricsHttpHandler (mytheclipse-http, metrics-http)
|
||||||
|
- new feature `metrics-http` (axum + tower + mytheclipse/observability)
|
||||||
|
- `metrics_routes(collector)` → Router serving /metrics (Prometheus text) + /
|
||||||
|
- added tower dep (util), ServiceExt import in test module
|
||||||
|
- 1 test via ServiceExt::oneshot
|
||||||
|
|
||||||
|
### 4. BatchProcessor (mytheclipse-queue, in-memory)
|
||||||
|
- `BatchJobHandler` trait — handle Vec<Job> atomically
|
||||||
|
- `BatchConfig` { batch_size, batch_timeout, concurrency }
|
||||||
|
- `BatchProcessor<Q>` — accumulates jobs per topic, flushes on size/timeout
|
||||||
|
- 2 tests: flush_on_batch_size, flush_on_timeout
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
- cargo build --workspace --all-features → exit 0
|
||||||
|
- cargo test --workspace --all-features → all pass (160+ tests)
|
||||||
|
- cargo clippy --workspace --all-features → no new warnings
|
||||||
|
- commit + push: f02a1ce
|
||||||
@@ -1,3 +1,17 @@
|
|||||||
|
# [1.8.0](https://github.com/asepharyana/mytheclipse/compare/v1.7.0...v1.8.0) (2026-08-29)
|
||||||
|
|
||||||
|
|
||||||
|
### Features
|
||||||
|
|
||||||
|
* round-5 abstractions — BatchProcessor, CircuitBreakerHealthCheck, TypedKeyRegistry, MetricsHttpHandler ([97b5e02](https://github.com/asepharyana/mytheclipse/commit/97b5e02820674a5b61a2d396f95df07f2b4fd735))
|
||||||
|
|
||||||
|
# [1.7.0](https://github.com/asepharyana/mytheclipse/compare/v1.6.0...v1.7.0) (2026-08-29)
|
||||||
|
|
||||||
|
|
||||||
|
### Features
|
||||||
|
|
||||||
|
* round-5 abstractions — CircuitBreakerHealthCheck, TypedKeyRegistry, MetricsHttpHandler ([510aadc](https://github.com/asepharyana/mytheclipse/commit/510aadc066a428c1627a38bdb22e4f0440cc01b3))
|
||||||
|
|
||||||
# [1.6.0](https://github.com/asepharyana/mytheclipse/compare/v1.5.0...v1.6.0) (2026-08-29)
|
# [1.6.0](https://github.com/asepharyana/mytheclipse/compare/v1.5.0...v1.6.0) (2026-08-29)
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
Generated
+12
-10
@@ -2818,7 +2818,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "mytheclipse"
|
name = "mytheclipse"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"async-trait",
|
"async-trait",
|
||||||
"num_cpus",
|
"num_cpus",
|
||||||
@@ -2832,7 +2832,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "mytheclipse-cache"
|
name = "mytheclipse-cache"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"async-trait",
|
"async-trait",
|
||||||
"moka",
|
"moka",
|
||||||
@@ -2845,7 +2845,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "mytheclipse-cli"
|
name = "mytheclipse-cli"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"clap",
|
"clap",
|
||||||
"tokio",
|
"tokio",
|
||||||
@@ -2854,7 +2854,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "mytheclipse-config"
|
name = "mytheclipse-config"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"dotenvy",
|
"dotenvy",
|
||||||
"notify",
|
"notify",
|
||||||
@@ -2869,7 +2869,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "mytheclipse-crypto"
|
name = "mytheclipse-crypto"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"aead",
|
"aead",
|
||||||
"aes-gcm",
|
"aes-gcm",
|
||||||
@@ -2889,7 +2889,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "mytheclipse-event"
|
name = "mytheclipse-event"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"async-nats",
|
"async-nats",
|
||||||
"async-trait",
|
"async-trait",
|
||||||
@@ -2905,21 +2905,23 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "mytheclipse-http"
|
name = "mytheclipse-http"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"async-trait",
|
"async-trait",
|
||||||
"axum",
|
"axum",
|
||||||
"hyper 1.11.1",
|
"hyper 1.11.1",
|
||||||
|
"mytheclipse",
|
||||||
"reqwest",
|
"reqwest",
|
||||||
"serde",
|
"serde",
|
||||||
"serde_json",
|
"serde_json",
|
||||||
"tokio",
|
"tokio",
|
||||||
|
"tower",
|
||||||
"tracing",
|
"tracing",
|
||||||
]
|
]
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "mytheclipse-queue"
|
name = "mytheclipse-queue"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"async-nats",
|
"async-nats",
|
||||||
"async-trait",
|
"async-trait",
|
||||||
@@ -2935,7 +2937,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "mytheclipse-storage"
|
name = "mytheclipse-storage"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"async-trait",
|
"async-trait",
|
||||||
"aws-config",
|
"aws-config",
|
||||||
@@ -2951,7 +2953,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "mytheclipse-tracing"
|
name = "mytheclipse-tracing"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"opentelemetry 0.25.0",
|
"opentelemetry 0.25.0",
|
||||||
"tokio",
|
"tokio",
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
[package]
|
[package]
|
||||||
name = "mytheclipse-cache"
|
name = "mytheclipse-cache"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
edition = "2021"
|
edition = "2021"
|
||||||
rust-version = "1.75"
|
rust-version = "1.75"
|
||||||
license = "MIT OR Apache-2.0"
|
license = "MIT OR Apache-2.0"
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
[package]
|
[package]
|
||||||
name = "mytheclipse-cli"
|
name = "mytheclipse-cli"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
edition = "2021"
|
edition = "2021"
|
||||||
rust-version = "1.75"
|
rust-version = "1.75"
|
||||||
license = "MIT OR Apache-2.0"
|
license = "MIT OR Apache-2.0"
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
[package]
|
[package]
|
||||||
name = "mytheclipse-config"
|
name = "mytheclipse-config"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
edition = "2021"
|
edition = "2021"
|
||||||
rust-version = "1.75"
|
rust-version = "1.75"
|
||||||
license = "MIT OR Apache-2.0"
|
license = "MIT OR Apache-2.0"
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
[package]
|
[package]
|
||||||
name = "mytheclipse-crypto"
|
name = "mytheclipse-crypto"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
edition = "2021"
|
edition = "2021"
|
||||||
rust-version = "1.75"
|
rust-version = "1.75"
|
||||||
license = "MIT OR Apache-2.0"
|
license = "MIT OR Apache-2.0"
|
||||||
|
|||||||
@@ -0,0 +1,118 @@
|
|||||||
|
//! Typed key registry with ID-based lookup (feature `password`).
|
||||||
|
//!
|
||||||
|
//! [`TypedKeyRegistry`] extends [`KeyRing`] semantics: instead of a single
|
||||||
|
//! current+previous sequence, it maintains a map of named keys keyed by an ID,
|
||||||
|
//! with one designated "current" ID. This is useful when keys are rotated by ID
|
||||||
|
//! (e.g. JWT `kid` header) and you need to look up a verification key by ID
|
||||||
|
//! while only accepting tokens signed by the current key.
|
||||||
|
|
||||||
|
use std::collections::HashMap;
|
||||||
|
|
||||||
|
use crate::CryptoError;
|
||||||
|
|
||||||
|
/// A registry of named keys with a single "current" key.
|
||||||
|
#[derive(Debug, Clone, Default)]
|
||||||
|
pub struct TypedKeyRegistry<T> {
|
||||||
|
keys: HashMap<String, T>,
|
||||||
|
current_id: Option<String>,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl<T> TypedKeyRegistry<T> {
|
||||||
|
/// Creates an empty registry (no current key).
|
||||||
|
pub fn new() -> Self {
|
||||||
|
Self { keys: HashMap::new(), current_id: None }
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Registers a key under `id`, making it the current key.
|
||||||
|
pub fn register(&mut self, id: impl Into<String>, key: T) {
|
||||||
|
let id = id.into();
|
||||||
|
self.keys.insert(id.clone(), key);
|
||||||
|
self.current_id = Some(id);
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Looks up a key by ID (current or previous).
|
||||||
|
pub fn lookup(&self, id: &str) -> Option<&T> {
|
||||||
|
self.keys.get(id)
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Returns the current key, if any.
|
||||||
|
pub fn current(&self) -> Option<&T> {
|
||||||
|
self.current_id
|
||||||
|
.as_ref()
|
||||||
|
.and_then(|id| self.keys.get(id))
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Returns the ID of the current key.
|
||||||
|
pub fn current_id(&self) -> Option<&str> {
|
||||||
|
self.current_id.as_deref()
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Rotates to a new current key identified by `id`. The old current key
|
||||||
|
/// remains accessible via `lookup` but is no longer the active signing key.
|
||||||
|
pub fn rotate_current(&mut self, id: impl Into<String>, key: T) {
|
||||||
|
let id = id.into();
|
||||||
|
self.keys.insert(id.clone(), key);
|
||||||
|
self.current_id = Some(id);
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Number of keys in the registry.
|
||||||
|
pub fn len(&self) -> usize {
|
||||||
|
self.keys.len()
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Whether the registry has any keys.
|
||||||
|
pub fn is_empty(&self) -> bool {
|
||||||
|
self.keys.is_empty()
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Returns an error if no current key is registered.
|
||||||
|
pub fn require_current(&self) -> Result<&T, CryptoError> {
|
||||||
|
self.current()
|
||||||
|
.ok_or_else(|| CryptoError::Key("no current key registered".to_string()))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(test)]
|
||||||
|
mod tests {
|
||||||
|
use super::*;
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn register_and_lookup() {
|
||||||
|
let mut reg = TypedKeyRegistry::new();
|
||||||
|
reg.register("k1", [1u8; 32]);
|
||||||
|
assert_eq!(reg.current_id(), Some("k1"));
|
||||||
|
assert!(reg.lookup("k1").is_some());
|
||||||
|
assert_eq!(reg.lookup("k1"), Some(&[1u8; 32]));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn lookup_unknown_returns_none() {
|
||||||
|
let reg = TypedKeyRegistry::<[u8; 32]>::new();
|
||||||
|
assert!(reg.lookup("nope").is_none());
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn rotate_preserves_previous() {
|
||||||
|
let mut reg = TypedKeyRegistry::new();
|
||||||
|
reg.register("k1", [1u8; 32]);
|
||||||
|
reg.rotate_current("k2", [2u8; 32]);
|
||||||
|
assert_eq!(reg.current_id(), Some("k2"));
|
||||||
|
assert!(reg.lookup("k1").is_some());
|
||||||
|
assert_eq!(reg.lookup("k1"), Some(&[1u8; 32]));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn require_current_errors_when_empty() {
|
||||||
|
let reg = TypedKeyRegistry::<[u8; 32]>::new();
|
||||||
|
assert!(matches!(reg.require_current(), Err(CryptoError::Key(_))));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn len_and_is_empty() {
|
||||||
|
let mut reg = TypedKeyRegistry::new();
|
||||||
|
assert!(reg.is_empty());
|
||||||
|
reg.register("a", 0u32);
|
||||||
|
assert_eq!(reg.len(), 1);
|
||||||
|
assert!(!reg.is_empty());
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -42,6 +42,7 @@
|
|||||||
//! ```
|
//! ```
|
||||||
|
|
||||||
pub mod key_ring;
|
pub mod key_ring;
|
||||||
|
pub mod key_registry;
|
||||||
|
|
||||||
#[cfg(feature = "password")]
|
#[cfg(feature = "password")]
|
||||||
pub mod password;
|
pub mod password;
|
||||||
@@ -68,6 +69,7 @@ pub use token::{Claims, TokenError, TokenSigner};
|
|||||||
pub use paseto::{PasetoSigner, PasetoClaims};
|
pub use paseto::{PasetoSigner, PasetoClaims};
|
||||||
|
|
||||||
pub use key_ring::KeyRing;
|
pub use key_ring::KeyRing;
|
||||||
|
pub use key_registry::TypedKeyRegistry;
|
||||||
|
|
||||||
/// Errors returned across mytheclipse-crypto primitives.
|
/// Errors returned across mytheclipse-crypto primitives.
|
||||||
#[non_exhaustive]
|
#[non_exhaustive]
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
[package]
|
[package]
|
||||||
name = "mytheclipse-event"
|
name = "mytheclipse-event"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
edition = "2021"
|
edition = "2021"
|
||||||
rust-version = "1.75"
|
rust-version = "1.75"
|
||||||
license = "MIT OR Apache-2.0"
|
license = "MIT OR Apache-2.0"
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
[package]
|
[package]
|
||||||
name = "mytheclipse-http"
|
name = "mytheclipse-http"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
edition = "2021"
|
edition = "2021"
|
||||||
rust-version = "1.75"
|
rust-version = "1.75"
|
||||||
license = "MIT OR Apache-2.0"
|
license = "MIT OR Apache-2.0"
|
||||||
@@ -21,6 +21,8 @@ client = ["dep:reqwest", "dep:tokio"]
|
|||||||
server-hyper = ["dep:hyper", "dep:tokio"]
|
server-hyper = ["dep:hyper", "dep:tokio"]
|
||||||
# Server backed by axum.
|
# Server backed by axum.
|
||||||
server-axum = ["dep:axum", "dep:hyper", "dep:tokio"]
|
server-axum = ["dep:axum", "dep:hyper", "dep:tokio"]
|
||||||
|
# Metrics HTTP endpoint serving Prometheus text format from a MetricsCollector.
|
||||||
|
metrics-http = ["dep:axum", "dep:tower", "dep:tokio", "dep:mytheclipse"]
|
||||||
|
|
||||||
[dependencies]
|
[dependencies]
|
||||||
tracing = "0.1"
|
tracing = "0.1"
|
||||||
@@ -29,8 +31,10 @@ tokio = { version = "1.53", features = ["sync", "time", "rt", "macros"], optiona
|
|||||||
reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"], optional = true }
|
reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"], optional = true }
|
||||||
hyper = { version = "1", features = ["full"], optional = true }
|
hyper = { version = "1", features = ["full"], optional = true }
|
||||||
axum = { version = "0.8", optional = true }
|
axum = { version = "0.8", optional = true }
|
||||||
|
tower = { version = "0.5", optional = true, default-features = false, features = ["util"] }
|
||||||
serde = { version = "1", features = ["derive"] }
|
serde = { version = "1", features = ["derive"] }
|
||||||
serde_json = "1"
|
serde_json = "1"
|
||||||
|
mytheclipse = { version = "1.5", path = "../mytheclipse", optional = true, default-features = false, features = ["observability"] }
|
||||||
|
|
||||||
[dev-dependencies]
|
[dev-dependencies]
|
||||||
tokio = { version = "1.53", features = ["full"] }
|
tokio = { version = "1.53", features = ["full"] }
|
||||||
|
|||||||
@@ -17,3 +17,9 @@ pub use client::HttpClient;
|
|||||||
|
|
||||||
#[cfg(feature = "server-axum")]
|
#[cfg(feature = "server-axum")]
|
||||||
pub mod server;
|
pub mod server;
|
||||||
|
|
||||||
|
#[cfg(feature = "metrics-http")]
|
||||||
|
pub mod metrics_http;
|
||||||
|
|
||||||
|
#[cfg(feature = "metrics-http")]
|
||||||
|
pub use metrics_http::metrics_routes;
|
||||||
|
|||||||
@@ -0,0 +1,56 @@
|
|||||||
|
//! Prometheus metrics HTTP endpoint (feature `metrics-http`).
|
||||||
|
//!
|
||||||
|
//! [`metrics_routes`] returns an [`axum::Router`] that serves the
|
||||||
|
//! [`MetricsCollector`]'s Prometheus text exposition format at `/metrics`.
|
||||||
|
|
||||||
|
use axum::routing::get;
|
||||||
|
use axum::Router;
|
||||||
|
use std::sync::Arc;
|
||||||
|
|
||||||
|
use mytheclipse::MetricsCollector;
|
||||||
|
|
||||||
|
/// Builds a small axum router exposing `/metrics` (Prometheus text) and
|
||||||
|
/// `/` (a one-line description).
|
||||||
|
pub fn metrics_routes(collector: MetricsCollector) -> Router {
|
||||||
|
let collector = Arc::new(collector);
|
||||||
|
Router::new()
|
||||||
|
.route("/", get(|| async { "mytheclipse metrics" }))
|
||||||
|
.route("/metrics", get(metrics_handler))
|
||||||
|
.with_state(collector)
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Axum handler serving the Prometheus text format.
|
||||||
|
async fn metrics_handler(
|
||||||
|
axum::extract::State(collector): axum::extract::State<Arc<MetricsCollector>>,
|
||||||
|
) -> axum::response::Response {
|
||||||
|
let body = collector.export_prometheus();
|
||||||
|
axum::response::Response::builder()
|
||||||
|
.status(200)
|
||||||
|
.header("content-type", "text/plain; version=0.0.4")
|
||||||
|
.body(axum::body::Body::from(body))
|
||||||
|
.unwrap_or_else(|_| {
|
||||||
|
axum::response::Response::new(axum::body::Body::from(
|
||||||
|
"internal error",
|
||||||
|
))
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(test)]
|
||||||
|
mod tests {
|
||||||
|
use super::*;
|
||||||
|
|
||||||
|
use tower::util::ServiceExt;
|
||||||
|
|
||||||
|
#[tokio::test]
|
||||||
|
async fn metrics_routes_serves_prometheus() {
|
||||||
|
let collector = MetricsCollector::new();
|
||||||
|
collector.inc_counter("test_reqs", 42);
|
||||||
|
let app = metrics_routes(collector);
|
||||||
|
|
||||||
|
let request = axum::extract::Request::get("/metrics")
|
||||||
|
.body(axum::body::Body::empty())
|
||||||
|
.unwrap();
|
||||||
|
let response = app.oneshot(request).await.unwrap();
|
||||||
|
assert_eq!(response.status(), 200);
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
[package]
|
[package]
|
||||||
name = "mytheclipse-queue"
|
name = "mytheclipse-queue"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
edition = "2021"
|
edition = "2021"
|
||||||
rust-version = "1.75"
|
rust-version = "1.75"
|
||||||
license = "MIT OR Apache-2.0"
|
license = "MIT OR Apache-2.0"
|
||||||
|
|||||||
@@ -0,0 +1,245 @@
|
|||||||
|
//! Batch job processor for bulk processing of queued jobs.
|
||||||
|
//!
|
||||||
|
//! [`BatchProcessor`] wraps a [`Queue`] and accumulates jobs per topic until
|
||||||
|
//! either `batch_size` is reached or `batch_timeout` elapses, then dispatches
|
||||||
|
//! them to a [`BatchJobHandler`] for bulk processing (e.g. bulk DB insert,
|
||||||
|
//! bulk email send, batch index write).
|
||||||
|
|
||||||
|
use std::pin::Pin;
|
||||||
|
use std::sync::Arc;
|
||||||
|
use std::time::Duration;
|
||||||
|
|
||||||
|
use tokio::sync::{mpsc, Semaphore};
|
||||||
|
|
||||||
|
use crate::error::JobError;
|
||||||
|
use crate::job::Job;
|
||||||
|
use crate::traits::Queue;
|
||||||
|
|
||||||
|
/// A handler that processes a batch of jobs atomically.
|
||||||
|
pub trait BatchJobHandler: Send + Sync {
|
||||||
|
fn handle_batch(&self, jobs: Vec<Job>) -> Pin<Box<dyn std::future::Future<Output = Result<(), JobError>> + Send>>;
|
||||||
|
}
|
||||||
|
|
||||||
|
impl<F, Fut> BatchJobHandler for F
|
||||||
|
where
|
||||||
|
F: Fn(Vec<Job>) -> Fut + Send + Sync,
|
||||||
|
Fut: std::future::Future<Output = Result<(), JobError>> + Send + 'static,
|
||||||
|
{
|
||||||
|
fn handle_batch(&self, jobs: Vec<Job>) -> Pin<Box<dyn std::future::Future<Output = Result<(), JobError>> + Send>> {
|
||||||
|
Box::pin((self)(jobs))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Configuration for [`BatchProcessor`].
|
||||||
|
#[derive(Debug, Clone)]
|
||||||
|
pub struct BatchConfig {
|
||||||
|
/// Max jobs per batch before flushing.
|
||||||
|
pub batch_size: usize,
|
||||||
|
/// Max time to wait before flushing a partial batch.
|
||||||
|
pub batch_timeout: Duration,
|
||||||
|
/// Max concurrent batch-processing tasks.
|
||||||
|
pub concurrency: usize,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl Default for BatchConfig {
|
||||||
|
fn default() -> Self {
|
||||||
|
Self {
|
||||||
|
batch_size: 100,
|
||||||
|
batch_timeout: Duration::from_secs(5),
|
||||||
|
concurrency: 4,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Result of a completed batch flush.
|
||||||
|
pub struct BatchFlush {
|
||||||
|
/// Number of jobs in the flushed batch.
|
||||||
|
pub count: usize,
|
||||||
|
}
|
||||||
|
|
||||||
|
/// A processor that batches jobs before dispatching them.
|
||||||
|
pub struct BatchProcessor<Q: Queue + 'static> {
|
||||||
|
queue: Arc<Q>,
|
||||||
|
config: BatchConfig,
|
||||||
|
semaphore: Arc<Semaphore>,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl<Q: Queue + 'static> BatchProcessor<Q> {
|
||||||
|
pub fn new(queue: Q, config: BatchConfig) -> Self {
|
||||||
|
let sem = Arc::new(Semaphore::new(config.concurrency.max(1)));
|
||||||
|
Self {
|
||||||
|
queue: Arc::new(queue),
|
||||||
|
config,
|
||||||
|
semaphore: sem,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Starts a batch processor for `topic` using `handler`.
|
||||||
|
pub fn start<H>(&self, topic: &str, handler: H)
|
||||||
|
where
|
||||||
|
H: BatchJobHandler + 'static,
|
||||||
|
{
|
||||||
|
let queue = Arc::clone(&self.queue);
|
||||||
|
let config = self.config.clone();
|
||||||
|
let semaphore = Arc::clone(&self.semaphore);
|
||||||
|
let handler: Arc<dyn BatchJobHandler> = Arc::new(handler);
|
||||||
|
let topic_owned = topic.to_string();
|
||||||
|
|
||||||
|
let (tx, mut rx): (mpsc::Sender<Job>, mpsc::Receiver<Job>) = mpsc::channel(config.batch_size);
|
||||||
|
|
||||||
|
// Dequeue loop → forward to channel
|
||||||
|
{
|
||||||
|
let q = Arc::clone(&queue);
|
||||||
|
let t = topic_owned.clone();
|
||||||
|
let tx2 = tx.clone();
|
||||||
|
let poll = config.poll_timeout();
|
||||||
|
tokio::spawn(async move {
|
||||||
|
loop {
|
||||||
|
match q.dequeue(&t, poll).await {
|
||||||
|
Ok(Some(job)) => {
|
||||||
|
if tx2.send(job).await.is_err() {
|
||||||
|
// Processor dropped; re-enqueue remaining
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
Ok(None) => {}
|
||||||
|
Err(e) => {
|
||||||
|
tracing::error!(queue_error = %e, "batch dequeue error");
|
||||||
|
tokio::time::sleep(poll).await;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
// Batch accumulation + flush loop
|
||||||
|
let h = handler;
|
||||||
|
tokio::spawn(async move {
|
||||||
|
loop {
|
||||||
|
let mut batch: Vec<Job> = Vec::with_capacity(config.batch_size);
|
||||||
|
let deadline = tokio::time::sleep(config.batch_timeout);
|
||||||
|
tokio::pin!(deadline);
|
||||||
|
|
||||||
|
// Fill batch
|
||||||
|
loop {
|
||||||
|
if batch.len() >= config.batch_size {
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
tokio::select! {
|
||||||
|
biased;
|
||||||
|
job = rx.recv() => match job {
|
||||||
|
Some(j) => batch.push(j),
|
||||||
|
None => {
|
||||||
|
// channel closed: drain remaining
|
||||||
|
while let Ok(j) = rx.try_recv() {
|
||||||
|
batch.push(j);
|
||||||
|
}
|
||||||
|
if !batch.is_empty() {
|
||||||
|
Self::flush(&h, &semaphore, batch).await;
|
||||||
|
}
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
},
|
||||||
|
_ = &mut deadline => break,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if !batch.is_empty() {
|
||||||
|
Self::flush(&h, &semaphore, batch).await;
|
||||||
|
}
|
||||||
|
deadline.as_mut().reset(tokio::time::Instant::now() + config.batch_timeout);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// Keep tx alive for the dequeue loop (it was cloned)
|
||||||
|
let _keep = tx;
|
||||||
|
}
|
||||||
|
|
||||||
|
async fn flush(handler: &Arc<dyn BatchJobHandler>, sem: &Arc<Semaphore>, batch: Vec<Job>) {
|
||||||
|
let permit = sem.clone().acquire_owned().await;
|
||||||
|
if permit.is_err() {
|
||||||
|
tracing::error!("batch semaphore closed");
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
let _permit = permit.unwrap();
|
||||||
|
let h = Arc::clone(handler);
|
||||||
|
let batch_len = batch.len();
|
||||||
|
tokio::spawn(async move {
|
||||||
|
match h.handle_batch(batch).await {
|
||||||
|
Ok(()) => tracing::debug!(count = batch_len, "batch processed"),
|
||||||
|
Err(e) => tracing::error!("batch handler error: {}", e),
|
||||||
|
}
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
impl BatchConfig {
|
||||||
|
fn poll_timeout(&self) -> Duration {
|
||||||
|
self.batch_timeout.min(Duration::from_millis(100))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(test)]
|
||||||
|
mod tests {
|
||||||
|
use super::*;
|
||||||
|
use crate::in_memory::InMemoryQueue;
|
||||||
|
use std::sync::atomic::{AtomicUsize, Ordering};
|
||||||
|
use std::sync::Arc as StdArc;
|
||||||
|
|
||||||
|
fn make_queue() -> InMemoryQueue {
|
||||||
|
InMemoryQueue::new()
|
||||||
|
}
|
||||||
|
|
||||||
|
#[tokio::test]
|
||||||
|
async fn flush_on_batch_size() {
|
||||||
|
let queue = make_queue();
|
||||||
|
let counter = StdArc::new(AtomicUsize::new(0));
|
||||||
|
let cfg = BatchConfig {
|
||||||
|
batch_size: 3,
|
||||||
|
batch_timeout: Duration::from_secs(10),
|
||||||
|
concurrency: 2,
|
||||||
|
};
|
||||||
|
let bp = BatchProcessor::new(queue, cfg);
|
||||||
|
let c2 = StdArc::clone(&counter);
|
||||||
|
bp.start("t", move |jobs: Vec<Job>| {
|
||||||
|
let c3 = StdArc::clone(&c2);
|
||||||
|
Box::pin(async move {
|
||||||
|
c3.fetch_add(jobs.len(), Ordering::SeqCst);
|
||||||
|
Ok(())
|
||||||
|
})
|
||||||
|
});
|
||||||
|
|
||||||
|
for i in 0..3 {
|
||||||
|
bp.queue.enqueue("t", format!("job{}", i).into_bytes()).await.unwrap();
|
||||||
|
}
|
||||||
|
|
||||||
|
tokio::time::sleep(Duration::from_millis(300)).await;
|
||||||
|
assert_eq!(counter.load(Ordering::SeqCst), 3);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[tokio::test]
|
||||||
|
async fn flush_on_timeout() {
|
||||||
|
let queue = make_queue();
|
||||||
|
let queue2 = queue.clone();
|
||||||
|
let counter = StdArc::new(AtomicUsize::new(0));
|
||||||
|
let cfg = BatchConfig {
|
||||||
|
batch_size: 100,
|
||||||
|
batch_timeout: Duration::from_millis(100),
|
||||||
|
concurrency: 2,
|
||||||
|
};
|
||||||
|
let bp = BatchProcessor::new(queue, cfg);
|
||||||
|
let c2 = StdArc::clone(&counter);
|
||||||
|
bp.start("t", move |jobs: Vec<Job>| {
|
||||||
|
let c3 = StdArc::clone(&c2);
|
||||||
|
Box::pin(async move {
|
||||||
|
c3.fetch_add(jobs.len(), Ordering::SeqCst);
|
||||||
|
Ok(())
|
||||||
|
})
|
||||||
|
});
|
||||||
|
|
||||||
|
queue2.enqueue("t", b"x".to_vec()).await.unwrap();
|
||||||
|
|
||||||
|
tokio::time::sleep(Duration::from_millis(300)).await;
|
||||||
|
assert_eq!(counter.load(Ordering::SeqCst), 1);
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -54,6 +54,11 @@ pub mod in_memory;
|
|||||||
pub mod traits;
|
pub mod traits;
|
||||||
pub mod worker;
|
pub mod worker;
|
||||||
|
|
||||||
|
#[cfg(feature = "in-memory")]
|
||||||
|
pub mod batch;
|
||||||
|
#[cfg(feature = "in-memory")]
|
||||||
|
pub mod pipeline;
|
||||||
|
|
||||||
#[cfg(feature = "in-memory")]
|
#[cfg(feature = "in-memory")]
|
||||||
pub use in_memory::InMemoryQueue;
|
pub use in_memory::InMemoryQueue;
|
||||||
|
|
||||||
@@ -63,6 +68,6 @@ pub use worker::{WorkerPool, WorkerConfig, JobHandler, JobFuture};
|
|||||||
pub use error::{QueueError, JobError};
|
pub use error::{QueueError, JobError};
|
||||||
|
|
||||||
#[cfg(feature = "in-memory")]
|
#[cfg(feature = "in-memory")]
|
||||||
pub mod pipeline;
|
pub use batch::{BatchConfig, BatchJobHandler, BatchProcessor, BatchFlush};
|
||||||
#[cfg(feature = "in-memory")]
|
#[cfg(feature = "in-memory")]
|
||||||
pub use pipeline::{StageRunner, Stage, StageError};
|
pub use pipeline::{StageRunner, Stage, StageError};
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
[package]
|
[package]
|
||||||
name = "mytheclipse-storage"
|
name = "mytheclipse-storage"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
edition = "2021"
|
edition = "2021"
|
||||||
rust-version = "1.75"
|
rust-version = "1.75"
|
||||||
license = "MIT OR Apache-2.0"
|
license = "MIT OR Apache-2.0"
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
[package]
|
[package]
|
||||||
name = "mytheclipse-tracing"
|
name = "mytheclipse-tracing"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
edition = "2021"
|
edition = "2021"
|
||||||
rust-version = "1.75"
|
rust-version = "1.75"
|
||||||
license = "MIT OR Apache-2.0"
|
license = "MIT OR Apache-2.0"
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
[package]
|
[package]
|
||||||
name = "mytheclipse"
|
name = "mytheclipse"
|
||||||
version = "1.6.0"
|
version = "1.8.0"
|
||||||
edition = "2021"
|
edition = "2021"
|
||||||
rust-version = "1.75"
|
rust-version = "1.75"
|
||||||
license = "MIT OR Apache-2.0"
|
license = "MIT OR Apache-2.0"
|
||||||
@@ -34,7 +34,7 @@ bg = ["dep:tokio"]
|
|||||||
resiliency = ["dep:tokio", "dep:rand"]
|
resiliency = ["dep:tokio", "dep:rand"]
|
||||||
traffic = ["dep:tokio"]
|
traffic = ["dep:tokio"]
|
||||||
lifecycle = ["dep:tokio"]
|
lifecycle = ["dep:tokio"]
|
||||||
observability = ["dep:tokio"]
|
observability = ["dep:tokio", "lifecycle"]
|
||||||
full = ["io", "compute", "bg", "resiliency", "traffic", "lifecycle", "observability"]
|
full = ["io", "compute", "bg", "resiliency", "traffic", "lifecycle", "observability"]
|
||||||
|
|
||||||
[[example]]
|
[[example]]
|
||||||
|
|||||||
@@ -117,6 +117,11 @@ pub use lifecycle::AsyncLifecycleManager;
|
|||||||
pub use metrics::{MetricsCollector, MetricsSnapshot};
|
pub use metrics::{MetricsCollector, MetricsSnapshot};
|
||||||
#[cfg(feature = "observability")]
|
#[cfg(feature = "observability")]
|
||||||
pub use metrics_bridge::{MetricsBridge, MetricsHealthCheck};
|
pub use metrics_bridge::{MetricsBridge, MetricsHealthCheck};
|
||||||
|
|
||||||
|
/// Re-export of [`metrics_bridge::CircuitBreakerHealthCheck`].
|
||||||
|
/// Only compiled when both `observability` and `resiliency` are enabled.
|
||||||
|
#[cfg(all(feature = "observability", feature = "resiliency"))]
|
||||||
|
pub use metrics_bridge::CircuitBreakerHealthCheck;
|
||||||
#[cfg(feature = "observability")]
|
#[cfg(feature = "observability")]
|
||||||
pub use panic_tracker::{PanicGuard, PanicInfo, PanicTracker};
|
pub use panic_tracker::{PanicGuard, PanicInfo, PanicTracker};
|
||||||
|
|
||||||
|
|||||||
@@ -10,6 +10,41 @@ use std::time::Duration;
|
|||||||
use crate::health::{HealthCheck, HealthStatus};
|
use crate::health::{HealthCheck, HealthStatus};
|
||||||
use crate::metrics::MetricsCollector;
|
use crate::metrics::MetricsCollector;
|
||||||
|
|
||||||
|
/// A health check backed by a [`CircuitBreaker`]: unhealthy if open,
|
||||||
|
/// degraded if half-open, ok otherwise.
|
||||||
|
///
|
||||||
|
/// Only available when both `resiliency` and `observability` features are
|
||||||
|
/// enabled (circuit breaker + health/metrics bridge).
|
||||||
|
#[cfg(feature = "resiliency")]
|
||||||
|
pub struct CircuitBreakerHealthCheck {
|
||||||
|
breaker: crate::circuit_breaker::CircuitBreaker,
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(feature = "resiliency")]
|
||||||
|
impl CircuitBreakerHealthCheck {
|
||||||
|
pub fn new(breaker: crate::circuit_breaker::CircuitBreaker) -> Self {
|
||||||
|
Self { breaker }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(feature = "resiliency")]
|
||||||
|
impl HealthCheck for CircuitBreakerHealthCheck {
|
||||||
|
fn name(&self) -> &str {
|
||||||
|
"circuit_breaker"
|
||||||
|
}
|
||||||
|
|
||||||
|
fn check(&self) -> std::pin::Pin<Box<dyn std::future::Future<Output = HealthStatus> + Send + '_>> {
|
||||||
|
let state = self.breaker.snapshot().state;
|
||||||
|
Box::pin(async move {
|
||||||
|
match state {
|
||||||
|
crate::circuit_breaker::CircuitState::Open => HealthStatus::Unhealthy,
|
||||||
|
crate::circuit_breaker::CircuitState::HalfOpen => HealthStatus::Degraded,
|
||||||
|
crate::circuit_breaker::CircuitState::Closed => HealthStatus::Ok,
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
/// A health check backed by a [`MetricsCollector`]: unhealthy if any registered
|
/// A health check backed by a [`MetricsCollector`]: unhealthy if any registered
|
||||||
/// "error" counter is non-zero, degraded if any gauge is below a configured
|
/// "error" counter is non-zero, degraded if any gauge is below a configured
|
||||||
/// threshold.
|
/// threshold.
|
||||||
@@ -142,6 +177,7 @@ mod tests {
|
|||||||
bridge.emit_now();
|
bridge.emit_now();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[cfg(feature = "lifecycle")]
|
||||||
#[tokio::test]
|
#[tokio::test]
|
||||||
async fn lifecycle_manager_with_metrics_bridge() {
|
async fn lifecycle_manager_with_metrics_bridge() {
|
||||||
let collector = MetricsCollector::new();
|
let collector = MetricsCollector::new();
|
||||||
|
|||||||
Reference in New Issue
Block a user