use dashmap::DashMap;
use std::hash::Hash;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;
use std::time::{Duration, Instant};
use tokio::sync::broadcast;
pub const STALE_TIMEOUT: Duration = Duration::from_secs(120);
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CoalesceSignal {
Completed {
success: bool,
},
Purged,
}
#[derive(Debug)]
struct InFlightEntry<L> {
started_at: Instant,
leader: L,
sender: broadcast::Sender<CoalesceSignal>,
generation: u64,
}
#[derive(Debug)]
pub enum CoalesceResult<K: Eq + Hash + Clone, L> {
Proceed(CoalesceGuard<K, L>),
Wait(broadcast::Receiver<CoalesceSignal>, L),
}
#[derive(Debug)]
pub struct CoalesceGuard<K: Eq + Hash + Clone, L> {
key: K,
generation: u64,
success: bool,
in_flight: Arc<DashMap<K, InFlightEntry<L>>>,
}
impl<K: Eq + Hash + Clone, L> CoalesceGuard<K, L> {
pub fn mark_success(&mut self) {
self.success = true;
}
pub fn release(self) {
drop(self);
}
#[cfg(test)]
pub fn key(&self) -> &K {
&self.key
}
}
impl<K: Eq + Hash + Clone, L> Drop for CoalesceGuard<K, L> {
fn drop(&mut self) {
if let Some((_, entry)) = self
.in_flight
.remove_if(&self.key, |_, entry| entry.generation == self.generation)
{
if let Err(e) = entry.sender.send(CoalesceSignal::Completed {
success: self.success,
}) {
log::debug!("Coalesce broadcast failed: {} (no active waiters)", e);
}
}
}
}
#[derive(Debug, Clone)]
pub struct RequestCoalescer<K: Eq + Hash + Clone, L> {
in_flight: Arc<DashMap<K, InFlightEntry<L>>>,
next_generation: Arc<AtomicU64>,
}
impl<K: Eq + Hash + Clone, L: Clone> Default for RequestCoalescer<K, L> {
fn default() -> Self {
Self::new()
}
}
impl<K: Eq + Hash + Clone, L: Clone> RequestCoalescer<K, L> {
pub fn new() -> Self {
Self {
in_flight: Arc::new(DashMap::new()),
next_generation: Arc::new(AtomicU64::new(0)),
}
}
fn next_generation(&self) -> u64 {
self.next_generation.fetch_add(1, Ordering::Relaxed) + 1
}
pub fn try_start(&self, key: &K, leader: L) -> CoalesceResult<K, L> {
use dashmap::mapref::entry::Entry;
match self.in_flight.entry(key.clone()) {
Entry::Occupied(o) => {
let entry = o.get();
let rx = entry.sender.subscribe();
CoalesceResult::Wait(rx, entry.leader.clone())
}
Entry::Vacant(v) => {
let (tx, _rx) = broadcast::channel(1);
let generation = self.next_generation();
let entry = InFlightEntry {
started_at: Instant::now(),
leader,
sender: tx,
generation,
};
v.insert(entry);
CoalesceResult::Proceed(CoalesceGuard {
key: key.clone(),
generation,
success: false,
in_flight: self.in_flight.clone(),
})
}
}
}
pub fn purge_stale(&self) -> usize {
let now = Instant::now();
let stale: Vec<(K, u64)> = self
.in_flight
.iter()
.filter(|entry| now.duration_since(entry.started_at) > STALE_TIMEOUT)
.map(|entry| (entry.key().clone(), entry.generation))
.collect();
let mut purged = 0;
for (key, generation) in stale {
if let Some((_, entry)) = self
.in_flight
.remove_if(&key, |_, entry| entry.generation == generation)
{
purged += 1;
let _ = entry.sender.send(CoalesceSignal::Purged);
}
}
purged
}
#[cfg(test)]
pub fn in_flight_count(&self) -> usize {
self.in_flight.len()
}
#[cfg(test)]
pub fn is_in_flight(&self, key: &K) -> bool {
self.in_flight.contains_key(key)
}
#[cfg(test)]
pub(crate) fn purge_key(&self, key: &K) {
if let Some((_, entry)) = self.in_flight.remove(key) {
let _ = entry.sender.send(CoalesceSignal::Purged);
}
}
#[cfg(test)]
pub(crate) fn drop_entry_silently(&self, key: &K) {
self.in_flight.remove(key);
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::Arc;
use std::thread;
fn key(url: &str) -> String {
url.to_string()
}
#[test]
fn try_start_first_call_returns_proceed() {
let coalescer: RequestCoalescer<String, u64> = RequestCoalescer::new();
let result = coalescer.try_start(&key("https://example.com/page1"), 1);
assert!(matches!(result, CoalesceResult::Proceed(_)));
assert!(coalescer.is_in_flight(&key("https://example.com/page1")));
}
#[test]
fn try_start_second_call_same_key_returns_wait() {
let coalescer: RequestCoalescer<String, u64> = RequestCoalescer::new();
let _guard = coalescer.try_start(&key("https://example.com/page2"), 1);
let result = coalescer.try_start(&key("https://example.com/page2"), 2);
assert!(matches!(result, CoalesceResult::Wait(..)));
}
#[test]
fn try_start_different_keys_both_proceed() {
let coalescer: RequestCoalescer<String, u64> = RequestCoalescer::new();
let _g1 = coalescer.try_start(&key("https://a.com"), 1);
let _g2 = coalescer.try_start(&key("https://b.com"), 2);
assert_eq!(coalescer.in_flight_count(), 2);
}
#[test]
fn guard_drop_removes_entry_and_allows_retry() {
let coalescer: RequestCoalescer<String, u64> = RequestCoalescer::new();
{
let _guard = coalescer.try_start(&key("https://example.com/temp"), 1);
assert!(coalescer.is_in_flight(&key("https://example.com/temp")));
}
assert!(!coalescer.is_in_flight(&key("https://example.com/temp")));
let result = coalescer.try_start(&key("https://example.com/temp"), 2);
assert!(matches!(result, CoalesceResult::Proceed(_)));
}
#[test]
fn release_is_equivalent_to_drop() {
let coalescer: RequestCoalescer<String, u64> = RequestCoalescer::new();
let guard = match coalescer.try_start(&key("https://example.com/release"), 1) {
CoalesceResult::Proceed(g) => g,
_ => panic!("expected Proceed"),
};
assert!(coalescer.is_in_flight(&key("https://example.com/release")));
guard.release();
assert!(!coalescer.is_in_flight(&key("https://example.com/release")));
}
#[test]
fn guard_key_matches_inserted_key() {
let coalescer: RequestCoalescer<String, u64> = RequestCoalescer::new();
let inserted = key("https://example.com/key-test");
let guard = match coalescer.try_start(&inserted, 1) {
CoalesceResult::Proceed(g) => g,
_ => panic!("expected Proceed"),
};
assert_eq!(guard.key(), &inserted);
}
#[test]
fn purge_stale_removes_timed_out_entries() {
let coalescer: RequestCoalescer<String, u64> = RequestCoalescer::new();
let (tx, _rx) = broadcast::channel(1);
coalescer.in_flight.insert(
key("https://example.com/stale"),
InFlightEntry {
started_at: Instant::now() - Duration::from_secs(200),
leader: 1,
sender: tx,
generation: coalescer.next_generation(),
},
);
let guard = match coalescer.try_start(&key("https://example.com/fresh"), 2) {
CoalesceResult::Proceed(g) => g,
_ => panic!("expected Proceed"),
};
assert_eq!(coalescer.in_flight_count(), 2);
let purged = coalescer.purge_stale();
assert_eq!(purged, 1, "should purge 1 stale entry");
assert!(!coalescer.is_in_flight(&key("https://example.com/stale")));
assert!(coalescer.is_in_flight(&key("https://example.com/fresh")));
guard.release();
}
#[test]
fn purge_stale_returns_zero_when_no_stale() {
let coalescer: RequestCoalescer<String, u64> = RequestCoalescer::new();
let _guard = coalescer.try_start(&key("https://example.com/active"), 1);
assert_eq!(coalescer.purge_stale(), 0);
assert!(coalescer.is_in_flight(&key("https://example.com/active")));
}
#[test]
fn purge_stale_empty_returns_zero() {
let coalescer: RequestCoalescer<String, u64> = RequestCoalescer::new();
assert_eq!(coalescer.purge_stale(), 0);
}
#[test]
fn concurrent_try_start_same_key_only_one_proceed() {
let coalescer = Arc::new(RequestCoalescer::<String, u64>::new());
let url = "https://example.com/concurrent";
let proceeds = Arc::new(std::sync::Mutex::new(0usize));
let waits = Arc::new(std::sync::Mutex::new(0usize));
let guards: Arc<std::sync::Mutex<Vec<CoalesceGuard<String, u64>>>> =
Arc::new(std::sync::Mutex::new(Vec::new()));
let barrier = Arc::new(std::sync::Barrier::new(8));
let handles: Vec<_> = (0..8)
.map(|i| {
let c = coalescer.clone();
let p = proceeds.clone();
let w = waits.clone();
let g = guards.clone();
let b = barrier.clone();
thread::spawn(move || {
b.wait();
let result = c.try_start(&key(url), i as u64);
match result {
CoalesceResult::Proceed(guard) => {
g.lock().unwrap().push(guard);
*p.lock().unwrap() += 1;
}
CoalesceResult::Wait(..) => *w.lock().unwrap() += 1,
}
})
})
.collect();
for h in handles {
h.join().expect("thread panicked");
}
assert_eq!(*proceeds.lock().unwrap(), 1, "exactly one Proceed");
assert_eq!(*waits.lock().unwrap(), 7, "seven Wait");
}
#[test]
fn default_equals_new() {
let a: RequestCoalescer<String, u64> = RequestCoalescer::new();
let b: RequestCoalescer<String, u64> = RequestCoalescer::default();
assert_eq!(a.in_flight_count(), 0);
assert_eq!(b.in_flight_count(), 0);
}
#[test]
fn clone_shares_in_flight_state() {
let a: RequestCoalescer<String, u64> = RequestCoalescer::new();
let b = a.clone();
let _guard = a.try_start(&key("https://example.com/shared"), 1);
assert!(b.is_in_flight(&key("https://example.com/shared")));
assert_eq!(b.in_flight_count(), 1);
}
#[tokio::test]
async fn waiter_receives_success_broadcast_after_guard_drop() {
let coalescer = Arc::new(RequestCoalescer::<String, u64>::new());
let url = "https://example.com/async-wait";
let mut guard = match coalescer.try_start(&key(url), 1) {
CoalesceResult::Proceed(g) => g,
_ => panic!("expected Proceed"),
};
guard.mark_success();
let mut rx = match coalescer.try_start(&key(url), 2) {
CoalesceResult::Wait(rx, _) => rx,
_ => panic!("expected Wait"),
};
let coalescer_clone = coalescer.clone();
tokio::spawn(async move {
tokio::time::sleep(Duration::from_millis(50)).await;
drop(guard);
let _ = coalescer_clone;
});
let signal = rx.recv().await.expect("waiter should receive broadcast");
assert_eq!(signal, CoalesceSignal::Completed { success: true });
}
#[tokio::test]
async fn unmarked_guard_broadcasts_failure_signal() {
let coalescer = RequestCoalescer::<String, u64>::new();
let url = "https://example.com/failed";
let guard = match coalescer.try_start(&key(url), 1) {
CoalesceResult::Proceed(g) => g,
_ => panic!("expected Proceed"),
};
let mut rx = match coalescer.try_start(&key(url), 2) {
CoalesceResult::Wait(rx, _) => rx,
_ => panic!("expected Wait"),
};
drop(guard);
let signal = rx.recv().await.expect("waiter should receive broadcast");
assert_eq!(
signal,
CoalesceSignal::Completed { success: false },
"unmarked guard must report failure"
);
}
#[tokio::test]
async fn purge_stale_broadcasts_purged_signal() {
let coalescer: RequestCoalescer<String, u64> = RequestCoalescer::new();
let (tx, _rx) = broadcast::channel(1);
coalescer.in_flight.insert(
key("https://example.com/stale-signal"),
InFlightEntry {
started_at: Instant::now() - Duration::from_secs(200),
leader: 1,
sender: tx,
generation: coalescer.next_generation(),
},
);
let mut rx = match coalescer.try_start(&key("https://example.com/stale-signal"), 2) {
CoalesceResult::Wait(rx, _) => rx,
_ => panic!("expected Wait"),
};
assert_eq!(coalescer.purge_stale(), 1);
let signal = rx.recv().await.expect("should receive purge signal");
assert_eq!(signal, CoalesceSignal::Purged);
}
#[test]
fn wait_carries_leader_identity() {
let coalescer: RequestCoalescer<String, u64> = RequestCoalescer::new();
let leader_id = 0xDEAD_BEEF_u64;
let url = "https://example.com/leader-id";
let _guard = match coalescer.try_start(&key(url), leader_id) {
CoalesceResult::Proceed(g) => g,
_ => panic!("expected Proceed"),
};
let waiter_id = 42_u64;
match coalescer.try_start(&key(url), waiter_id) {
CoalesceResult::Wait(_rx, got_leader_id) => {
assert_eq!(
got_leader_id, leader_id,
"waiter should see leader identity"
);
assert_ne!(got_leader_id, waiter_id);
}
_ => panic!("expected Wait"),
}
}
#[tokio::test]
async fn purge_key_broadcasts_purged_regardless_of_age() {
let coalescer: RequestCoalescer<String, u64> = RequestCoalescer::new();
let url = "https://example.com/force-purge";
let _guard = match coalescer.try_start(&key(url), 1) {
CoalesceResult::Proceed(g) => g,
_ => panic!("expected Proceed"),
};
let mut rx = match coalescer.try_start(&key(url), 2) {
CoalesceResult::Wait(rx, _) => rx,
_ => panic!("expected Wait"),
};
coalescer.purge_key(&key(url));
assert!(!coalescer.is_in_flight(&key(url)));
let signal = rx.recv().await.expect("should receive signal");
assert_eq!(signal, CoalesceSignal::Purged);
}
#[tokio::test]
async fn drop_entry_silently_causes_closed() {
let coalescer: RequestCoalescer<String, u64> = RequestCoalescer::new();
let url = "https://example.com/silent";
let _guard = match coalescer.try_start(&key(url), 1) {
CoalesceResult::Proceed(g) => g,
_ => panic!("expected Proceed"),
};
let mut rx = match coalescer.try_start(&key(url), 2) {
CoalesceResult::Wait(rx, _) => rx,
_ => panic!("expected Wait"),
};
coalescer.drop_entry_silently(&key(url));
assert!(!coalescer.is_in_flight(&key(url)));
let err = rx.recv().await.expect_err("channel should be closed");
assert!(matches!(err, broadcast::error::RecvError::Closed));
}
#[test]
fn stale_guard_drop_does_not_remove_replacement_entry() {
let coalescer: RequestCoalescer<String, u64> = RequestCoalescer::new();
let url = "https://example.com/generation";
let coalesce_key = key(url);
let old_guard = match coalescer.try_start(&coalesce_key, 1) {
CoalesceResult::Proceed(g) => g,
_ => panic!("expected Proceed"),
};
coalescer.purge_key(&coalesce_key);
assert!(!coalescer.is_in_flight(&coalesce_key));
let new_guard = match coalescer.try_start(&coalesce_key, 2) {
CoalesceResult::Proceed(g) => g,
_ => panic!("expected Proceed"),
};
let mut rx_new = match coalescer.try_start(&coalesce_key, 3) {
CoalesceResult::Wait(rx, _) => rx,
_ => panic!("expected Wait"),
};
drop(old_guard);
assert!(
coalescer.is_in_flight(&coalesce_key),
"stale guard must not remove replacement entry"
);
assert_eq!(coalescer.in_flight_count(), 1);
assert!(
matches!(
rx_new.try_recv(),
Err(broadcast::error::TryRecvError::Empty)
),
"new waiters must not receive stale Completed"
);
drop(new_guard);
assert!(!coalescer.is_in_flight(&coalesce_key));
assert!(
matches!(
rx_new.try_recv().expect("new guard must broadcast"),
CoalesceSignal::Completed { .. }
),
"new guard must broadcast a completion signal"
);
}
}