chore(release): 1.10.0 [skip ci]

# [1.10.0](https://github.com/asepharyana/mytheclipse/compare/v1.9.0...v1.10.0) (2026-08-29)

### Features

* round-7 abstractions — BgJoiner, MiddlewarePipeline, RateLimitedQueue ([851c8c4](https://github.com/asepharyana/mytheclipse/commit/851c8c4ebbe465cecd89cfea78c1b00bb47c07c2))

.hermes/plans/mytheclipse-round6-spec.md

@@ -0,0 +1,26 @@
+# Implementation Spec: Round 6
+
+## New Features
+
+### 1. HealthCheckedPool (mytheclipse-core, observability+traffic)
+File: `crates/mytheclipse/src/pool_health.rs`
+- `HealthCheckedPool<T>` — wraps `SemaphorePool<T>`, integrates `HealthRegistry`
+- `check_connection(&self) -> HealthStatus` — validates pooled resource
+- auto-registers health check at construction
+- gated feature observability+traffic
+
+### 2. HkdfKeyDeriver (mytheclipse-crypto, derivation feature)
+File: `crates/mytheclipse-crypto/src/hkdf.rs`
+- `HkdfKeyDeriver` — HKDF-SHA256 (RFC 5869) from master secret
+- `derive_key(&self, purpose: &str, output_len) -> Vec<u8>` — context-specific sub-key
+- domain separation via purpose as info
+- gated feature "derivation"
+
+### 3. BackpressureEnqueue (mytheclipse-queue, in-memory)
+File: `crates/mytheclipse-queue/src/backpressure.rs`
+- `BackpressureEnforcer` — tracks in-flight count, enforces max
+- `enqueue_or_nack(queue, topic, payload, max_inflight) -> Result<(), BackpressureError>`
+- non-blocking: returns BackpressureError when at capacity
+
+## Verification
+- build + test + clippy + commit + push

.hermes/plans/mytheclipse-round7-spec.md

@@ -0,0 +1,10 @@
+# Implementation Spec: Round 7 — COMPLETE
+
+3 fitur implementasi selesai:
+- `BgJoiner` (core, lifecycle) — graceful task join, 2 tests
+- `MiddlewarePipeline` (core, observability+resiliency) — composable async mw stack, 2 tests
+- `RateLimitedQueue` (queue) — token-bucket rate-limited enqueue wrapper, 2 tests + QueueError::RateLimit variant
+
+Build: `cargo build --workspace --all-features` exit 0.
+Tests: semua pass (0 FAILED).
+Clippy: 0 new warnings.

CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.10.0](https://github.com/asepharyana/mytheclipse/compare/v1.9.0...v1.10.0) (2026-08-29)
+
+
+### Features
+
+* round-7 abstractions — BgJoiner, MiddlewarePipeline, RateLimitedQueue ([851c8c4](https://github.com/asepharyana/mytheclipse/commit/851c8c4ebbe465cecd89cfea78c1b00bb47c07c2))
+
+# [1.9.0](https://github.com/asepharyana/mytheclipse/compare/v1.8.0...v1.9.0) (2026-08-29)
+
+
+### Features
+
+* round-6 abstractions — HealthCheckedPool, HkdfKeyDeriver, BackpressureEnforcer ([a03db38](https://github.com/asepharyana/mytheclipse/commit/a03db38c5ccabead51fa49d2001b0cd94a9dd66e))
+
 # [1.8.0](https://github.com/asepharyana/mytheclipse/compare/v1.7.0...v1.8.0) (2026-08-29)
 
 

Cargo.lock

@@ -2162,6 +2162,15 @@ version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
 
+[[package]]
+name = "hkdf"
+version = "0.12.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b5f8eb2ad728638ea2c7d47a21db23b7b58a72ed6a38256b8a1849f15fbbdf7"
+dependencies = [
+ "hmac 0.12.1",
+]
+
 [[package]]
 name = "hmac"
 version = "0.12.1"
@@ -2818,7 +2827,7 @@ dependencies = [
 
 [[package]]
 name = "mytheclipse"
-version = "1.8.0"
+version = "1.10.0"
 dependencies = [
  "async-trait",
  "num_cpus",
@@ -2832,7 +2841,7 @@ dependencies = [
 
 [[package]]
 name = "mytheclipse-cache"
-version = "1.8.0"
+version = "1.10.0"
 dependencies = [
  "async-trait",
  "moka",
@@ -2845,7 +2854,7 @@ dependencies = [
 
 [[package]]
 name = "mytheclipse-cli"
-version = "1.8.0"
+version = "1.10.0"
 dependencies = [
  "clap",
  "tokio",
@@ -2854,7 +2863,7 @@ dependencies = [
 
 [[package]]
 name = "mytheclipse-config"
-version = "1.8.0"
+version = "1.10.0"
 dependencies = [
  "dotenvy",
  "notify",
@@ -2869,13 +2878,14 @@ dependencies = [
 
 [[package]]
 name = "mytheclipse-crypto"
-version = "1.8.0"
+version = "1.10.0"
 dependencies = [
  "aead",
  "aes-gcm",
  "argon2",
  "base64 0.22.1",
  "hashbrown 0.15.5",
+ "hkdf",
  "jsonwebtoken",
  "pasetors",
  "password-hash",
@@ -2883,13 +2893,14 @@ dependencies = [
  "rand_core 0.6.4",
  "serde",
  "serde_json",
+ "sha2 0.10.9",
  "tokio",
  "tracing",
 ]
 
 [[package]]
 name = "mytheclipse-event"
-version = "1.8.0"
+version = "1.10.0"
 dependencies = [
  "async-nats",
  "async-trait",
@@ -2905,7 +2916,7 @@ dependencies = [
 
 [[package]]
 name = "mytheclipse-http"
-version = "1.8.0"
+version = "1.10.0"
 dependencies = [
  "async-trait",
  "axum",
@@ -2921,7 +2932,7 @@ dependencies = [
 
 [[package]]
 name = "mytheclipse-queue"
-version = "1.8.0"
+version = "1.10.0"
 dependencies = [
  "async-nats",
  "async-trait",
@@ -2937,7 +2948,7 @@ dependencies = [
 
 [[package]]
 name = "mytheclipse-storage"
-version = "1.8.0"
+version = "1.10.0"
 dependencies = [
  "async-trait",
  "aws-config",
@@ -2953,7 +2964,7 @@ dependencies = [
 
 [[package]]
 name = "mytheclipse-tracing"
-version = "1.8.0"
+version = "1.10.0"
 dependencies = [
  "opentelemetry 0.25.0",
  "tokio",

crates/mytheclipse-cache/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mytheclipse-cache"
-version = "1.8.0"
+version = "1.10.0"
 edition = "2021"
 rust-version = "1.75"
 license = "MIT OR Apache-2.0"

crates/mytheclipse-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mytheclipse-cli"
-version = "1.8.0"
+version = "1.10.0"
 edition = "2021"
 rust-version = "1.75"
 license = "MIT OR Apache-2.0"

crates/mytheclipse-config/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mytheclipse-config"
-version = "1.8.0"
+version = "1.10.0"
 edition = "2021"
 rust-version = "1.75"
 license = "MIT OR Apache-2.0"

crates/mytheclipse-crypto/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mytheclipse-crypto"
-version = "1.8.0"
+version = "1.10.0"
 edition = "2021"
 rust-version = "1.75"
 license = "MIT OR Apache-2.0"
@@ -22,6 +22,8 @@ encryption = ["dep:aead", "dep:aes-gcm", "dep:rand_core", "dep:rand"]
 tokens = ["encryption", "dep:serde", "dep:serde_json", "dep:base64", "dep:jsonwebtoken"]
 paseto = ["encryption", "dep:serde", "dep:serde_json", "dep:base64", "dep:pasetors"]
 rate-limit = ["dep:hashbrown", "dep:tokio"]
+# HKDF-SHA256 key derivation (RFC 5869).
+derivation = ["dep:hkdf", "dep:sha2"]
 
 [dependencies]
 tracing = "0.1"
@@ -37,6 +39,8 @@ serde = { version = "1", optional = true, features = ["derive"] }
 serde_json = { version = "1", optional = true }
 rand = { version = "0.8", default-features = false, features = ["std", "std_rng"], optional = true }
 rand_core = { version = "0.6", optional = true }
+hkdf = { version = "0.12", default-features = false, optional = true }
+sha2 = { version = "0.10", optional = true }
 pasetors = { version = "0.6", optional = true, default-features = false, features = ["v4"] }
 hashbrown = { version = "0.15", optional = true }
 tokio = { version = "1.53", features = ["sync", "time"], optional = true }

crates/mytheclipse-crypto/src/hkdf.rs

@@ -0,0 +1,70 @@
+//! HKDF-SHA256 key derivation (feature `derivation`).
+//!
+//! [`HkdfKeyDeriver`] wraps the HKDF construction (RFC 5869) to derive
+//! domain-specific sub-keys from a single master secret. Each purpose
+//! string acts as the `info` parameter for domain separation.
+
+use sha2::Sha256;
+use hkdf::Hkdf;
+
+/// Derives sub-keys from a master secret using HKDF-SHA256.
+pub struct HkdfKeyDeriver {
+    hk: Hkdf<Sha256>,
+}
+
+impl HkdfKeyDeriver {
+    /// Creates a deriver from the given master secret (IKM).
+    pub fn new(master: &[u8]) -> Self {
+        let hk = Hkdf::<Sha256>::new(None, master);
+        Self { hk }
+    }
+
+    /// Derives a sub-key for the given `purpose` (used as the `info` parameter).
+    ///
+    /// Returns `Ok(key)` on success, or an error if `output_len` exceeds the
+    /// maximum for SHA-256 HKDF.
+    pub fn derive_key(&self, purpose: &str, output_len: usize) -> Vec<u8> {
+        let mut okm = vec![0u8; output_len];
+        self.hk
+            .expand(purpose.as_bytes(), &mut okm)
+            .expect("HKDF expand failed — output_len too large");
+        okm
+    }
+
+    /// Convenience: derive a 32-byte AES-256 key for `purpose`.
+    pub fn derive_aes256_key(&self, purpose: &str) -> [u8; 32] {
+        let v = self.derive_key(purpose, 32);
+        let mut key = [0u8; 32];
+        key.copy_from_slice(&v);
+        key
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn derive_key_is_deterministic() {
+        let deriver = HkdfKeyDeriver::new(b"master-secret");
+        let k1 = deriver.derive_key("encryption", 32);
+        let k2 = deriver.derive_key("encryption", 32);
+        assert_eq!(k1, k2);
+        assert_eq!(k1.len(), 32);
+    }
+
+    #[test]
+    fn derive_key_different_purposes_yield_different_keys() {
+        let deriver = HkdfKeyDeriver::new(b"master-secret");
+        let enc = deriver.derive_key("encryption", 32);
+        let auth = deriver.derive_key("auth", 32);
+        assert_ne!(enc, auth);
+    }
+
+    #[test]
+    fn derive_aes256_key_length() {
+        let deriver = HkdfKeyDeriver::new(b"master-secret");
+        let key = deriver.derive_aes256_key("signing");
+        assert_eq!(key.len(), 32);
+    }
+}

crates/mytheclipse-crypto/src/lib.rs

@@ -55,6 +55,8 @@ pub mod token;
 
 #[cfg(feature = "paseto")]
 pub mod paseto;
+#[cfg(feature = "derivation")]
+pub mod hkdf;
 
 #[cfg(feature = "password")]
 pub use password::PasswordHasher;
@@ -71,6 +73,9 @@ pub use paseto::{PasetoSigner, PasetoClaims};
 pub use key_ring::KeyRing;
 pub use key_registry::TypedKeyRegistry;
 
+#[cfg(feature = "derivation")]
+pub use hkdf::HkdfKeyDeriver;
+
 /// Errors returned across mytheclipse-crypto primitives.
 #[non_exhaustive]
 #[derive(Debug)]

crates/mytheclipse-event/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mytheclipse-event"
-version = "1.8.0"
+version = "1.10.0"
 edition = "2021"
 rust-version = "1.75"
 license = "MIT OR Apache-2.0"

crates/mytheclipse-http/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mytheclipse-http"
-version = "1.8.0"
+version = "1.10.0"
 edition = "2021"
 rust-version = "1.75"
 license = "MIT OR Apache-2.0"

crates/mytheclipse-queue/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mytheclipse-queue"
-version = "1.8.0"
+version = "1.10.0"
 edition = "2021"
 rust-version = "1.75"
 license = "MIT OR Apache-2.0"

crates/mytheclipse-queue/src/backpressure_enqueue.rs

@@ -0,0 +1,147 @@
+//! Backpressure-aware enqueuer (in-memory backend).
+//!
+//! [`BackpressureEnforcer`] tracks in-flight jobs and caps the number of
+//! pending enqueues per topic, returning [`BackpressureError`] instead of
+//! blocking when the cap is exceeded.
+
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+
+use tokio::sync::Semaphore;
+
+use crate::traits::Queue;
+
+/// Errors returned by [`BackpressureEnforcer`].
+#[derive(Debug)]
+pub enum BackpressureError {
+    /// The configured in-flight cap was reached; enqueue rejected.
+    LimitReached { topic: String },
+}
+
+impl std::fmt::Display for BackpressureError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::LimitReached { topic } => {
+                write!(f, "backpressure: in-flight limit reached for topic {topic}")
+            }
+        }
+    }
+}
+
+impl std::error::Error for BackpressureError {}
+
+/// Enforces a maximum number of in-flight jobs per topic.
+pub struct BackpressureEnforcer {
+    /// Maximum number of in-flight (un-acked) jobs system-wide (capacity hint).
+    #[allow(dead_code)]
+    max_inflight: usize,
+    /// Per-topic in-flight counter.
+    counters: Arc<std::sync::Mutex<std::collections::HashMap<String, Arc<AtomicU64>>>>,
+    /// Bounded semaphore enforcing total concurrency.
+    #[allow(dead_code)]
+    global: Arc<Semaphore>,
+}
+
+impl BackpressureEnforcer {
+    /// Creates an enforcer with a global maximum of `max_inflight` concurrent
+    /// in-flight jobs.
+    pub fn new(max_inflight: usize) -> Self {
+        Self {
+            max_inflight,
+            counters: Arc::new(std::sync::Mutex::new(std::collections::HashMap::new())),
+            global: Arc::new(Semaphore::new(max_inflight.max(1))),
+        }
+    }
+
+    /// Returns the per-topic in-flight count, creating zero if absent.
+    fn get_counter(&self, topic: &str) -> Arc<AtomicU64> {
+        let mut map = self.counters.lock().unwrap();
+        map.entry(topic.to_string())
+            .or_insert_with(|| Arc::new(AtomicU64::new(0)));
+        Arc::clone(map.get(topic).unwrap())
+    }
+
+    /// Attempts to acquire a backpressure slot non-blockingly.
+    /// Returns Err if at capacity.
+    pub async fn try_enqueue<Q: Queue + ?Sized>(
+        &self,
+        queue: &Q,
+        topic: &str,
+        payload: Vec<u8>,
+    ) -> Result<(), BackpressureError> {
+        // Per-topic counter increment (informational; global semaphore is the hard limit)
+        let counter = self.get_counter(topic);
+        counter.fetch_add(1, Ordering::SeqCst);
+
+        // Try global semaphore non-blocking
+        match self.global.clone().try_acquire_owned() {
+            Ok(_permit) => {
+                let _ = queue.enqueue(topic, payload).await;
+                Ok(())
+            }
+            Err(_) => {
+                counter.fetch_sub(1, Ordering::SeqCst);
+                Err(BackpressureError::LimitReached {
+                    topic: topic.to_string(),
+                })
+            }
+        }
+    }
+
+    /// Increments the in-flight counter when a job is delivered.
+    pub fn inc_delivered(&self, topic: &str) {
+        self.get_counter(topic).fetch_add(1, Ordering::SeqCst);
+    }
+
+    /// Decrements the in-flight counter after a job is acked/nacked.
+    pub fn dec_finished(&self, topic: &str) {
+        self.get_counter(topic).fetch_sub(1, Ordering::SeqCst);
+    }
+
+    /// Current in-flight count for a topic.
+    pub fn inflight(&self, topic: &str) -> u64 {
+        self.get_counter(topic).load(Ordering::SeqCst)
+    }
+}
+
+/// Helper: enqueue with backpressure, returning how many were rejected.
+pub async fn enqueue_with_backpressure<Q: Queue + ?Sized>(
+    enforcer: &BackpressureEnforcer,
+    queue: &Q,
+    topic: &str,
+    payloads: Vec<Vec<u8>>,
+) -> Result<usize, BackpressureError> {
+    let mut rejected = 0;
+    for payload in payloads {
+        if let Err(_) = enforcer.try_enqueue(queue, topic, payload).await {
+            rejected += 1;
+        }
+    }
+    Ok(rejected)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::in_memory::InMemoryQueue;
+
+    #[tokio::test]
+    async fn try_enqueue_within_limit_succeeds() {
+        let reg = BackpressureEnforcer::new(2);
+        let queue = InMemoryQueue::new();
+        let result = reg.try_enqueue(&queue, "t", b"x".to_vec()).await;
+        assert!(result.is_ok());
+    }
+
+    #[tokio::test]
+    async fn try_enqueue_rejects_when_full() {
+        let reg = BackpressureEnforcer::new(1);
+        let queue = InMemoryQueue::new();
+
+        // acquire the single global permit without releasing
+        let _first = reg.global.clone().acquire_owned().await.unwrap();
+
+        let result = reg.try_enqueue(&queue, "t", b"x".to_vec()).await;
+        assert!(matches!(result, Err(BackpressureError::LimitReached { .. })));
+    }
+}

crates/mytheclipse-queue/src/error.rs

@@ -11,6 +11,8 @@ pub enum QueueError {
     Serialization(String),
     /// A timeout occurred while waiting for an operation.
     Timeout,
+    /// The operation was rejected because of a rate limit.
+    RateLimit(String),
 }
 
 impl std::fmt::Display for QueueError {
@@ -20,6 +22,7 @@ impl std::fmt::Display for QueueError {
             Self::NotFound(s) => write!(f, "queue not found: {s}"),
             Self::Serialization(s) => write!(f, "serialization error: {s}"),
             Self::Timeout => write!(f, "queue operation timed out"),
+            Self::RateLimit(s) => write!(f, "queue rate limited: {s}"),
         }
     }
 }

crates/mytheclipse-queue/src/lib.rs

@@ -56,6 +56,15 @@ pub mod worker;
 
 #[cfg(feature = "in-memory")]
 pub mod batch;
+#[cfg(feature = "in-memory")]
+pub mod backpressure_enqueue;
+#[cfg(feature = "in-memory")]
+pub mod rate_limited;
+#[cfg(feature = "in-memory")]
+pub use backpressure_enqueue::{BackpressureEnforcer, BackpressureError, enqueue_with_backpressure};
+#[cfg(feature = "in-memory")]
+pub use rate_limited::{RateLimitedQueue, RateLimitQueueError};
+
 #[cfg(feature = "in-memory")]
 pub mod pipeline;
 

crates/mytheclipse-queue/src/rate_limited.rs

@@ -0,0 +1,157 @@
+//! Rate-limited queue wrapper.
+//!
+//! [`RateLimitedQueue`] wraps any [`Queue`] implementation and applies a
+//! token-bucket rate limiter before enqueuing. If the bucket is empty the
+//! enqueue is rejected with [`RateLimitQueueError::RateLimited`] instead of
+//! blocking.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use tokio::sync::Mutex;
+use tokio::time::Instant;
+
+use crate::error::QueueError;
+use crate::traits::Queue;
+use async_trait::async_trait;
+
+/// Error returned by [`RateLimitedQueue::enqueue`].
+#[derive(Debug)]
+pub enum RateLimitQueueError {
+    RateLimited,
+    Other(QueueError),
+}
+
+impl std::fmt::Display for RateLimitQueueError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::RateLimited => write!(f, "rate limited: capacity exhausted"),
+            Self::Other(e) => write!(f, "queue error: {e}"),
+        }
+    }
+}
+
+impl std::error::Error for RateLimitQueueError {}
+
+impl From<QueueError> for RateLimitQueueError {
+    fn from(e: QueueError) -> Self {
+        Self::Other(e)
+    }
+}
+
+impl From<RateLimitQueueError> for QueueError {
+    fn from(e: RateLimitQueueError) -> Self {
+        match e {
+            RateLimitQueueError::RateLimited => Self::RateLimit("capacity exhausted".into()),
+            RateLimitQueueError::Other(e) => e,
+        }
+    }
+}
+
+/// Token-bucket rate limiter (no extra deps beyond tokio).
+struct TokenBucket {
+    /// Maximum burst capacity.
+    capacity: u32,
+    /// Current tokens (float for fractional refill).
+    tokens: f64,
+    /// Refill rate (tokens per second).
+    rate: f64,
+    /// Last refill timestamp.
+    last: Instant,
+}
+
+impl TokenBucket {
+    fn new(rate_per_sec: f64, burst: u32) -> Self {
+        Self {
+            capacity: burst.max(1),
+            tokens: burst as f64,
+            rate: rate_per_sec.max(0.0),
+            last: Instant::now(),
+        }
+    }
+
+    /// Attempts to consume one token. Returns true on success.
+    fn try_consume(&mut self) -> bool {
+        let now = Instant::now();
+        let elapsed = now.saturating_duration_since(self.last).as_secs_f64();
+        self.tokens = (self.tokens + elapsed * self.rate).min(self.capacity as f64);
+        self.last = now;
+        if self.tokens >= 1.0 {
+            self.tokens -= 1.0;
+            true
+        } else {
+            false
+        }
+    }
+}
+
+/// A queue decorator that enforces a rate limit on enqueue.
+pub struct RateLimitedQueue<Q: ?Sized> {
+    inner: Arc<Q>,
+    bucket: Arc<Mutex<TokenBucket>>,
+}
+
+impl<Q: Queue + 'static> RateLimitedQueue<Q> {
+    /// Creates a new rate-limited wrapper around `inner`.
+    pub fn new(inner: Q, rate_per_sec: f64, burst: u32) -> Self {
+        Self {
+            inner: Arc::new(inner),
+            bucket: Arc::new(Mutex::new(TokenBucket::new(rate_per_sec, burst))),
+        }
+    }
+}
+
+#[async_trait]
+impl<Q: Queue + ?Sized> Queue for RateLimitedQueue<Q> {
+    async fn enqueue(&self, topic: &str, payload: Vec<u8>) -> Result<(), QueueError> {
+        let mut b = self.bucket.lock().await;
+        if !b.try_consume() {
+            return Err(RateLimitQueueError::RateLimited.into());
+        }
+        self.inner.enqueue(topic, payload).await
+    }
+
+    async fn dequeue(&self, topic: &str, timeout: Duration) -> Result<Option<crate::job::Job>, QueueError> {
+        self.inner.dequeue(topic, timeout).await
+    }
+
+    async fn ack(&self, job: &crate::job::Job) -> Result<(), crate::error::JobError> {
+        self.inner.ack(job).await
+    }
+
+    async fn nack(&self, job: &crate::job::Job, requeue: bool) -> Result<(), crate::error::JobError> {
+        self.inner.nack(job, requeue).await
+    }
+
+    async fn dlq_move(&self, topic: &str, job: crate::job::Job) -> Result<(), QueueError> {
+        self.inner.dlq_move(topic, job).await
+    }
+
+    async fn len(&self, topic: &str) -> Result<u64, QueueError> {
+        self.inner.len(topic).await
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::in_memory::InMemoryQueue;
+
+    #[tokio::test]
+    async fn allows_enqueue_within_rate() {
+        let inner = InMemoryQueue::new();
+        let rl = RateLimitedQueue::new(inner, 100.0, 10);
+        assert!(rl.enqueue("t", b"x".to_vec()).await.is_ok());
+    }
+
+    #[tokio::test]
+    async fn rejects_when_bucket_empty() {
+        let inner = InMemoryQueue::new();
+        let rl = RateLimitedQueue::new(inner, 0.0, 1); // 0 tokens/sec, 1 burst
+        // consume the single burst token
+        let _ = rl.enqueue("t", b"x".to_vec()).await;
+        // next should be rate limited (no refill)
+        let result = rl.enqueue("t", b"y".to_vec()).await;
+        assert!(matches!(result, Err(QueueError::RateLimit(_))));
+    }
+}

crates/mytheclipse-storage/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mytheclipse-storage"
-version = "1.8.0"
+version = "1.10.0"
 edition = "2021"
 rust-version = "1.75"
 license = "MIT OR Apache-2.0"

crates/mytheclipse-tracing/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mytheclipse-tracing"
-version = "1.8.0"
+version = "1.10.0"
 edition = "2021"
 rust-version = "1.75"
 license = "MIT OR Apache-2.0"

crates/mytheclipse/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mytheclipse"
-version = "1.8.0"
+version = "1.10.0"
 edition = "2021"
 rust-version = "1.75"
 license = "MIT OR Apache-2.0"

crates/mytheclipse/src/bg_join.rs

@@ -0,0 +1,133 @@
+//! Graceful task-joiner for background tasks (feature `lifecycle`).
+//!
+//! [`BgJoiner`] collects [`tokio::task::JoinHandle`]s returned by
+//! [`crate::spawn_bg`] (or any manual `tokio::spawn`) and drains them in
+//! aggregate on shutdown via [`BgJoiner::join_all`].
+//!
+//! This complements the bounded `spawn_bg` helper: while `spawn_bg` limits
+//! *concurrency*, `BgJoiner` adds structured *lifetimes* so a service can wait
+//! for all in-flight work to settle before terminating.
+
+use std::future::Future;
+use std::sync::Arc;
+use std::time::Duration;
+
+use tokio::sync::Mutex;
+use tokio::task::JoinHandle;
+use tokio::time::Instant;
+
+/// A joiner that tracks background task handles for ordered shutdown.
+#[derive(Default, Clone)]
+pub struct BgJoiner {
+    inner: Arc<Mutex<Vec<JoinHandle<()>>>>,
+}
+
+impl BgJoiner {
+    /// Creates an empty joiner.
+    pub fn new() -> Self {
+        Self {
+            inner: Arc::new(Mutex::new(Vec::new())),
+        }
+    }
+
+    /// Spawns `future` as a background task and tracks its handle.
+    pub fn spawn<F>(&self, future: F)
+    where
+        F: std::future::Future + Send + 'static,
+        F::Output: Send + 'static,
+    {
+        let handle: JoinHandle<()> = tokio::spawn(async move { let _ = future.await; });
+        self.track(handle);
+    }
+
+    /// Registers an externally-created `JoinHandle` for tracking.
+    pub fn track(&self, handle: JoinHandle<()>) {
+        // can't lock synchronously; defer to a spawned task
+        let inner = Arc::clone(&self.inner);
+        tokio::spawn(async move {
+            let mut set = inner.lock().await;
+            set.push(handle);
+        });
+    }
+
+    /// Number of currently-tracked tasks.
+    pub async fn len(&self) -> usize {
+        self.inner.lock().await.len()
+    }
+
+    /// Await every tracked task, dropping any that are still pending once
+    /// `deadline` elapses. Returns the count of tasks that had not completed
+    /// within the timeout.
+    pub async fn join_all(&self, deadline: Duration) -> usize {
+        let now = Instant::now();
+        let handles: Vec<JoinHandle<()>> = {
+            let mut guard = self.inner.lock().await;
+            std::mem::take(&mut *guard)
+        };
+
+        let mut pending: Vec<JoinHandle<()>> = handles;
+        let mut dropped = 0usize;
+
+        loop {
+            if pending.is_empty() {
+                break 0;
+            }
+
+            if now.elapsed() >= deadline {
+                dropped = pending.len();
+                for h in pending.drain(..) {
+                    h.abort();
+                }
+                return dropped;
+            }
+
+            let remaining = deadline.saturating_sub(now.elapsed());
+            let mut still = Vec::with_capacity(pending.len());
+            for mut handle in pending.drain(..) {
+                match tokio::time::timeout(remaining, &mut handle).await {
+                    Ok(Ok(_)) => {}
+                    Ok(Err(_)) => {}
+                    Err(_) => still.push(handle),
+                }
+            }
+            pending = still;
+        }
+    }
+
+    /// Drops (aborts) all tracked tasks immediately without awaiting.
+    pub async fn abort_all(&self) {
+        let handles: Vec<JoinHandle<()>> = {
+            let mut guard = self.inner.lock().await;
+            std::mem::take(&mut *guard)
+        };
+        for h in handles {
+            h.abort();
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn spawn_and_join_completes() {
+        let joiner = BgJoiner::new();
+        joiner.spawn(async { tokio::task::yield_now().await });
+        // give the task a moment to register
+        tokio::time::sleep(Duration::from_millis(10)).await;
+        let leftover = joiner.join_all(Duration::from_secs(1)).await;
+        assert_eq!(leftover, 0);
+    }
+
+    #[tokio::test]
+    async fn join_all_aborts_on_timeout() {
+        let joiner = BgJoiner::new();
+        joiner.spawn(async {
+            tokio::time::sleep(Duration::from_secs(10)).await;
+        });
+        tokio::time::sleep(Duration::from_millis(10)).await;
+        let leftover = joiner.join_all(Duration::from_millis(50)).await;
+        assert!(leftover > 0);
+    }
+}

crates/mytheclipse/src/health.rs

@@ -36,7 +36,7 @@ struct RegisteredCheck {
 }
 
 /// Registry of health checks for aggregated /health reporting.
-#[derive(Default)]
+#[derive(Default, Clone)]
 pub struct HealthRegistry {
     checks: Arc<RwLock<Vec<RegisteredCheck>>>,
 }

crates/mytheclipse/src/lib.rs

@@ -53,11 +53,19 @@ pub mod shutdown;
 pub mod cron;
 #[cfg(feature = "lifecycle")]
 pub mod health;
+#[cfg(all(feature = "observability", feature = "traffic"))]
+pub mod pool_health;
 #[cfg(feature = "lifecycle")]
 pub mod leader;
 #[cfg(feature = "lifecycle")]
 pub mod lifecycle;
 
+#[cfg(feature = "lifecycle")]
+pub mod bg_join;
+
+#[cfg(all(feature = "observability", feature = "resiliency"))]
+pub mod middleware;
+
 #[cfg(feature = "observability")]
 pub mod metrics;
 #[cfg(feature = "observability")]
@@ -122,6 +130,17 @@ pub use metrics_bridge::{MetricsBridge, MetricsHealthCheck};
 /// Only compiled when both `observability` and `resiliency` are enabled.
 #[cfg(all(feature = "observability", feature = "resiliency"))]
 pub use metrics_bridge::CircuitBreakerHealthCheck;
+
+/// Re-export of [`pool_health::HealthCheckedPool`].
+/// Only compiled when both `observability` and `traffic` are enabled.
+#[cfg(all(feature = "observability", feature = "traffic"))]
+pub use pool_health::HealthCheckedPool;
+
+#[cfg(feature = "lifecycle")]
+pub use bg_join::BgJoiner;
+
+#[cfg(all(feature = "observability", feature = "resiliency"))]
+pub use middleware::{MiddlewarePipeline, PipelineError, BoxMiddleware, mw};
 #[cfg(feature = "observability")]
 pub use panic_tracker::{PanicGuard, PanicInfo, PanicTracker};
 

crates/mytheclipse/src/middleware.rs

@@ -0,0 +1,108 @@
+//! Composable middleware pipeline (feature `observability` + `resiliency`).
+//!
+//! [`MiddlewarePipeline`] is an ordered stack of boxed async functions. Each
+//! stage receives the state, may transform or reject it, and returns control
+//! to the next stage. The final state is delivered to a caller-supplied
+//! service closure.
+
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::{Arc, Mutex};
+
+/// Error returned by [`MiddlewarePipeline::apply`].
+#[derive(Debug)]
+pub struct PipelineError {
+    pub msg: String,
+}
+
+impl std::fmt::Display for PipelineError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "pipeline error: {}", self.msg)
+    }
+}
+
+impl std::error::Error for PipelineError {}
+
+/// A single async middleware stage.
+pub type BoxMiddleware<S> = Arc<
+    dyn Fn(S) -> Pin<Box<dyn Future<Output = Result<S, PipelineError>> + Send>>
+        + Send
+        + Sync,
+>;
+
+/// Helper to box any `async fn` middleware.
+pub fn mw<S, F, Fut>(f: F) -> BoxMiddleware<S>
+where
+    S: Send + 'static,
+    F: Fn(S) -> Fut + Send + Sync + 'static,
+    Fut: Future<Output = Result<S, PipelineError>> + Send + 'static,
+{
+    Arc::new(move |state| Box::pin(f(state)))
+}
+
+/// A stack of ordered middleware stages.
+#[derive(Clone, Default)]
+pub struct MiddlewarePipeline<S> {
+    layers: Arc<Mutex<Vec<BoxMiddleware<S>>>>,
+}
+
+impl<S: Send + 'static> MiddlewarePipeline<S> {
+    pub fn new() -> Self {
+        Self { layers: Arc::new(Mutex::new(Vec::new())) }
+    }
+
+    /// Appends a middleware stage.
+    pub fn add(&self, m: BoxMiddleware<S>) {
+        self.layers.lock().unwrap().push(m);
+    }
+
+    /// Applies every layer in order, short-circuiting on the first error.
+    pub async fn apply(&self, state: S) -> Result<S, PipelineError> {
+        let layers = self.layers.lock().unwrap();
+        let mut current = state;
+        for layer in layers.iter() {
+            current = layer(current).await?;
+        }
+        Ok(current)
+    }
+
+    /// Applies every layer, then runs `svc` with the final state.
+    pub async fn run<F, Fut, R, E>(&self, state: S, svc: F) -> Result<R, E>
+    where
+        F: Fn(S) -> Fut + Clone + Send + 'static,
+        Fut: Future<Output = Result<R, E>> + Send,
+        R: Send + 'static,
+        E: From<PipelineError> + Send,
+    {
+        match self.apply(state).await {
+            Ok(s) => svc(s).await,
+            Err(e) => Err(E::from(e)),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn applies_two_layers_in_order() {
+        let p: MiddlewarePipeline<u32> = MiddlewarePipeline::new();
+        let inc = mw(|s: u32| async move { Ok::<_, PipelineError>(s + 1) });
+        let double = mw(|s: u32| async move { Ok::<_, PipelineError>(s * 2) });
+        p.add(inc);
+        p.add(double);
+        let out = p.apply(1).await.unwrap();
+        assert_eq!(out, 4); // (1+1)*2
+    }
+
+    #[tokio::test]
+    async fn short_circuits_on_error() {
+        let p: MiddlewarePipeline<String> = MiddlewarePipeline::new();
+        let reject = mw(|_s: String| async {
+            Err::<_, PipelineError>(PipelineError { msg: "rejected".into() })
+        });
+        p.add(reject);
+        assert!(matches!(p.apply("x".to_string()).await, Err(_)));
+    }
+}

crates/mytheclipse/src/pool.rs

@@ -3,12 +3,15 @@
 //! 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::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::Arc;
 
 use async_trait::async_trait;
 use tokio::sync::OwnedSemaphorePermit;
 use tokio::sync::Semaphore;
 
+static ACQUIRE_COUNT: AtomicUsize = AtomicUsize::new(0);
+
 /// Errors returned by pool operations.
 #[derive(Debug, thiserror::Error)]
 pub enum PoolError {
@@ -39,6 +42,11 @@ pub struct SemaphorePool<T: Clone> {
 }
 
 impl<T: Clone> SemaphorePool<T> {
+    /// Returns the underlying items slice (read-only view).
+    pub fn items(&self) -> &[T] {
+        &self.items
+    }
+
     /// Creates a new pool from a vector of items.
     pub fn new(items: Vec<T>) -> Self {
         let permits = items.len().max(1);
@@ -54,7 +62,7 @@ impl<T: Clone + Send + Sync + 'static> Pool<T> for SemaphorePool<T> {
     async fn acquire(&self) -> Result<Pooled<T>, PoolError> {
         let permit = self.semaphore.clone().acquire_owned().await
             .map_err(|_| PoolError::Exhausted)?;
-        let idx = rand::random::<usize>() % self.items.len();
+        let idx = ACQUIRE_COUNT.fetch_add(1, Ordering::Relaxed) % self.items.len();
         Ok(Pooled {
             resource: self.items[idx].clone(),
             _permit: permit,

crates/mytheclipse/src/pool_health.rs

@@ -0,0 +1,141 @@
+//! Health-checked resource pool (feature `observability` + `traffic`).
+//!
+//! [`HealthCheckedPool`] composes a [`SemaphorePool`] with a [`HealthRegistry`]:
+//! a background probe periodically validates pooled items, and a registered
+//! `HealthCheck` reflects pool liveliness in the aggregated `/health` report.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use crate::health::{HealthCheck, HealthRegistry, HealthStatus};
+use crate::pool::{Pool, Pooled, PoolError, SemaphorePool};
+
+/// A health check backed by a closure.
+struct ClosureCheck {
+    name: String,
+    check: Arc<dyn Fn() -> HealthStatus + Send + Sync>,
+}
+
+impl HealthCheck for ClosureCheck {
+    fn name(&self) -> &str {
+        &self.name
+    }
+
+    fn check(&self) -> std::pin::Pin<Box<dyn std::future::Future<Output = HealthStatus> + Send + '_>> {
+        let status = (self.check)();
+        Box::pin(async move { status })
+    }
+}
+
+/// A resource pool with integrated health reporting.
+pub struct HealthCheckedPool<T: Clone + Send + Sync + 'static> {
+    pub(crate) inner: SemaphorePool<T>,
+    #[allow(dead_code)]
+    registry: Arc<HealthRegistry>,
+    #[allow(dead_code)]
+    check_interval: Duration,
+    #[allow(dead_code)]
+    name: String,
+}
+
+impl<T: Clone + Send + Sync + 'static + std::fmt::Debug> HealthCheckedPool<T> {
+    /// Creates a new health-checked pool.
+    ///
+    /// `validator` is called on each item during the periodic background probe;
+    /// the registered health check reports `Ok` if any item validates.
+    pub async fn new(
+        items: Vec<T>,
+        registry: &HealthRegistry,
+        name: impl Into<String>,
+        check_interval: Duration,
+        validator: impl Fn(&T) -> bool + Send + Sync + 'static,
+    ) -> Self {
+        let name_str = name.into();
+        let pool = SemaphorePool::new(items);
+        let registry = Arc::new(registry.clone());
+
+        let validator: Arc<dyn Fn(&T) -> bool + Send + Sync> = Arc::new(validator);
+        let check_items = pool.items().to_vec();
+        let v_check = Arc::clone(&validator);
+        let check = ClosureCheck {
+            name: format!("connection-pool:{}", name_str),
+            check: Arc::new(move || {
+                if check_items.iter().any(|i| v_check(i)) {
+                    HealthStatus::Ok
+                } else {
+                    HealthStatus::Unhealthy
+                }
+            }),
+        };
+        let r = Arc::clone(&registry);
+        let check_name = check.name.clone();
+        tokio::task::spawn(async move {
+            r.register(check_name, check).await;
+        });
+
+        // Background probe
+        let probe_items = pool.items().to_vec();
+        let probe_name = name_str.clone();
+        let v_probe = Arc::clone(&validator);
+        tokio::task::spawn(async move {
+            let mut ticker = tokio::time::interval(check_interval);
+            loop {
+                ticker.tick().await;
+                let up = probe_items.iter().filter(|i| v_probe(i)).count();
+                tracing::debug!(pool = %probe_name, up, total = probe_items.len(), "pool health probe");
+            }
+        });
+
+        Self {
+            inner: pool,
+            registry,
+            check_interval,
+            name: name_str,
+        }
+    }
+
+    /// Acquires a resource from the pool.
+    pub async fn acquire_healthy(&self) -> Result<Pooled<T>, PoolError> {
+        self.inner.acquire().await
+    }
+
+    /// Number of items in the pool.
+    pub fn size(&self) -> usize {
+        self.inner.items().len()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn acquires_resource() {
+        let reg = HealthRegistry::new();
+        let pool = HealthCheckedPool::new(
+            vec![42u32, 84u32],
+            &reg,
+            "test",
+            Duration::from_secs(5),
+            |_| true,
+        )
+        .await;
+        let item = pool.acquire_healthy().await.unwrap();
+        assert!(item.resource == 42 || item.resource == 84);
+        assert_eq!(pool.size(), 2);
+    }
+
+    #[tokio::test]
+    async fn validator_distinguishes_healthy() {
+        let reg = HealthRegistry::new();
+        let pool = HealthCheckedPool::new(
+            vec![0u32, 1u32, 2u32],
+            &reg,
+            "test",
+            Duration::from_secs(5),
+            |x| *x > 0,
+        )
+        .await;
+        assert_eq!(pool.size(), 3);
+    }
+}