use std::sync::atomic::{AtomicU64, Ordering};
use std::time::Duration;
use tokio::time::Instant;
use dashmap::DashMap;
pub const ACTIVITY_THROTTLE_MAX_SIZE: usize = 1_000;
pub const ACTIVITY_THROTTLE_DEBOUNCE: Duration = Duration::from_secs(10);
pub const ACTIVITY_THROTTLE_TIMEOUT: Duration = Duration::from_secs(3);
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RecordOutcome {
Recorded,
Deduplicated,
Dropped,
}
struct ThrottleEntry<W> {
payload: W,
deadline: Instant,
}
pub struct ActivityWriteThrottle<W> {
entries: DashMap<String, ThrottleEntry<W>>,
max_size: usize,
debounce: Duration,
timeout: Duration,
dropped: AtomicU64,
}
impl<W: std::fmt::Display + Send + Sync + 'static> ActivityWriteThrottle<W> {
pub fn new() -> Self {
Self::with_limits(
ACTIVITY_THROTTLE_MAX_SIZE,
ACTIVITY_THROTTLE_DEBOUNCE,
ACTIVITY_THROTTLE_TIMEOUT,
)
}
pub fn with_limits(max_size: usize, debounce: Duration, timeout: Duration) -> Self {
Self {
entries: DashMap::new(),
max_size,
debounce,
timeout,
dropped: AtomicU64::new(0),
}
}
pub fn record(&self, key: &str, payload: W) -> RecordOutcome {
if self.entries.contains_key(key) {
return RecordOutcome::Deduplicated;
}
if self.entries.len() >= self.max_size {
let total = self.dropped.fetch_add(1, Ordering::Relaxed) + 1;
tracing::warn!(
key = %key,
payload = %payload,
max_size = self.max_size,
dropped_total = total,
"{}",
crate::i18n::translate_detail("logs-credit-throttle-capacity-full", &[])
);
return RecordOutcome::Dropped;
}
self.entries.insert(
key.to_string(),
ThrottleEntry {
payload,
deadline: Instant::now() + self.debounce,
},
);
RecordOutcome::Recorded
}
pub async fn flush_due<F, Fut, E>(&self, write: F) -> usize
where
F: Fn(String, W) -> Fut,
Fut: std::future::Future<Output = Result<(), E>>,
E: std::fmt::Display,
{
let now = Instant::now();
let due_keys: Vec<String> = self
.entries
.iter()
.filter(|item| item.value().deadline <= now)
.map(|item| item.key().clone())
.collect();
if due_keys.is_empty() {
return 0;
}
let mut handled = 0usize;
for key in due_keys {
let Some((_, entry)) = self.entries.remove(&key) else {
continue;
};
handled += 1;
let write = write(key.clone(), entry.payload);
match tokio::time::timeout(self.timeout, write).await {
Ok(Ok(())) => {},
Ok(Err(e)) => {
tracing::warn!(
key = %key,
error = %e,
timeout_secs = self.timeout.as_secs(),
"{}",
crate::i18n::translate_detail("logs-credit-throttle-write-failed", &[])
);
},
Err(_) => {
tracing::warn!(
key = %key,
timeout_secs = self.timeout.as_secs(),
"{}",
crate::i18n::translate_detail("logs-credit-throttle-write-timeout", &[])
);
},
}
}
handled
}
pub async fn run_flush_loop<F, Fut, E>(&self, write: F)
where
F: Fn(String, W) -> Fut,
Fut: std::future::Future<Output = Result<(), E>>,
E: std::fmt::Display,
{
let mut interval = tokio::time::interval(self.debounce);
let mut reported_dropped = 0u64;
interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
loop {
interval.tick().await;
self.flush_due(&write).await;
let dropped = self.dropped.load(Ordering::Relaxed);
if dropped > reported_dropped {
tracing::warn!(
dropped_total = dropped,
new_dropped = dropped - reported_dropped,
debounce_secs = self.debounce.as_secs(),
"{}",
crate::i18n::translate_detail("logs-credit-throttle-window-dropped", &[])
);
reported_dropped = dropped;
}
}
}
pub fn pending_len(&self) -> usize {
self.entries.len()
}
pub fn dropped_total(&self) -> u64 {
self.dropped.load(Ordering::Relaxed)
}
}
impl<W: std::fmt::Display + Send + Sync + 'static> Default for ActivityWriteThrottle<W> {
fn default() -> Self {
Self::new()
}
}
#[cfg(test)]
mod tests {
use super::ActivityWriteThrottle;
use super::RecordOutcome;
use super::ACTIVITY_THROTTLE_DEBOUNCE;
use super::ACTIVITY_THROTTLE_MAX_SIZE;
use super::ACTIVITY_THROTTLE_TIMEOUT;
use parking_lot::Mutex;
use std::sync::Arc;
use std::time::Duration;
const DEBOUNCE: Duration = Duration::from_secs(10);
const TIMEOUT: Duration = Duration::from_secs(3);
type TestLog = Mutex<Vec<(String, i32)>>;
fn infallible_writer(
log: Arc<TestLog>,
) -> impl Fn(String, i32) -> std::future::Ready<Result<(), std::convert::Infallible>> {
move |key, payload| {
std::future::ready({
log.lock().push((key, payload));
Ok(())
})
}
}
async fn settle() {
for _ in 0..64 {
tokio::task::yield_now().await;
}
}
#[derive(Clone)]
struct LogCapture(Arc<Mutex<Vec<String>>>);
impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for LogCapture {
type Writer = LogCaptureWriter;
fn make_writer(&'a self) -> Self::Writer {
LogCaptureWriter(self.0.clone())
}
}
struct LogCaptureWriter(Arc<Mutex<Vec<String>>>);
impl std::io::Write for LogCaptureWriter {
fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
self.0.lock().push(String::from_utf8_lossy(buf).to_string());
Ok(buf.len())
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
#[tokio::test(start_paused = true)]
async fn debounce_window_persists_once_then_rewrites_outside_window() {
let throttle = ActivityWriteThrottle::with_limits(10, DEBOUNCE, TIMEOUT);
let log = Arc::new(TestLog::new(Vec::new()));
assert_eq!(throttle.record("k", 1), RecordOutcome::Recorded);
assert_eq!(throttle.record("k", 2), RecordOutcome::Deduplicated);
assert_eq!(throttle.record("k", 3), RecordOutcome::Deduplicated);
let flushed = throttle.flush_due(infallible_writer(log.clone())).await;
assert_eq!(flushed, 0, "截止时间前不得落库");
assert_eq!(log.lock().len(), 0);
tokio::time::advance(DEBOUNCE).await;
let flushed = throttle.flush_due(infallible_writer(log.clone())).await;
assert_eq!(flushed, 1, "到期应批量落库");
{
let entries = log.lock();
assert_eq!(entries.len(), 1, "窗口内落库调用计数应为 1");
assert_eq!(
entries[0],
("k".to_string(), 1),
"落库应为窗口内首次入队的快照"
);
}
assert_eq!(throttle.pending_len(), 0, "落库后条目应清理防泄漏");
assert_eq!(throttle.record("k", 9), RecordOutcome::Recorded);
tokio::time::advance(DEBOUNCE).await;
let flushed = throttle.flush_due(infallible_writer(log.clone())).await;
assert_eq!(flushed, 1);
let entries = log.lock();
assert_eq!(entries.len(), 2, "窗口外应再次落库");
assert_eq!(entries[1], ("k".to_string(), 9));
}
#[tokio::test(start_paused = true)]
async fn dedup_does_not_slide_window_anchor() {
let throttle = ActivityWriteThrottle::with_limits(10, DEBOUNCE, TIMEOUT);
let log = Arc::new(TestLog::new(Vec::new()));
throttle.record("k", 1);
tokio::time::advance(Duration::from_secs(1)).await;
assert_eq!(throttle.record("k", 2), RecordOutcome::Deduplicated);
tokio::time::advance(Duration::from_secs(4)).await;
assert_eq!(throttle.record("k", 3), RecordOutcome::Deduplicated);
tokio::time::advance(Duration::from_secs(5)).await;
assert_eq!(throttle.record("k", 4), RecordOutcome::Deduplicated);
let flushed = throttle.flush_due(infallible_writer(log.clone())).await;
assert_eq!(flushed, 1, "去重不刷新窗口,t=10s 应按首次入队锚点落库");
assert_eq!(log.lock()[0].1, 1, "落库为窗口内首次快照");
}
#[tokio::test(start_paused = true)]
async fn capacity_full_drops_new_key_and_recovers_outside_window() {
let throttle = ActivityWriteThrottle::with_limits(2, DEBOUNCE, TIMEOUT);
let log = Arc::new(TestLog::new(Vec::new()));
assert_eq!(throttle.record("k1", 1), RecordOutcome::Recorded);
assert_eq!(throttle.record("k2", 2), RecordOutcome::Recorded);
assert_eq!(throttle.record("k3", 3), RecordOutcome::Dropped);
assert_eq!(throttle.dropped_total(), 1, "丢弃计数应递增");
assert_eq!(throttle.record("k3", 3), RecordOutcome::Dropped);
assert_eq!(throttle.dropped_total(), 2, "重复丢弃应继续递增");
tokio::time::advance(DEBOUNCE).await;
let flushed = throttle.flush_due(infallible_writer(log.clone())).await;
assert_eq!(flushed, 2, "被丢弃的 k3 不得落库");
assert_eq!(log.lock().len(), 2);
assert_eq!(throttle.record("k3", 3), RecordOutcome::Recorded);
tokio::time::advance(DEBOUNCE).await;
let flushed = throttle.flush_due(infallible_writer(log.clone())).await;
assert_eq!(flushed, 1);
assert_eq!(log.lock().len(), 3, "窗口外被丢弃 key 应恢复落库");
}
#[tokio::test(start_paused = true)]
#[serial_test::serial]
async fn capacity_drop_emits_structured_warning() {
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;
let logs = Arc::new(Mutex::new(Vec::<String>::new()));
let _guard = tracing_subscriber::registry()
.with(
tracing_subscriber::fmt::layer()
.with_ansi(false)
.with_writer(LogCapture(logs.clone())),
)
.set_default();
tracing::callsite::rebuild_interest_cache();
let mut lines = Vec::<String>::new();
let dropped_msg = crate::i18n::translate_detail("logs-credit-throttle-capacity-full", &[]);
for _ in 0..3 {
let throttle = ActivityWriteThrottle::with_limits(1, DEBOUNCE, TIMEOUT);
assert_eq!(throttle.record("first", 1), RecordOutcome::Recorded);
assert_eq!(throttle.record("second", 2), RecordOutcome::Dropped);
assert_eq!(throttle.dropped_total(), 1);
lines = logs.lock().clone();
if lines
.iter()
.any(|l| l.contains(&dropped_msg) && l.contains("second") && l.contains("WARN"))
{
break;
}
tracing::callsite::rebuild_interest_cache();
}
assert!(
lines
.iter()
.any(|l| l.contains(&dropped_msg) && l.contains("second") && l.contains("WARN")),
"容量丢弃应输出含 key 的 warn,实际: {:?}",
lines
);
}
#[tokio::test(start_paused = true)]
async fn flush_loop_batch_persists_due_keys() {
let throttle = Arc::new(ActivityWriteThrottle::with_limits(10, DEBOUNCE, TIMEOUT));
let log = Arc::new(TestLog::new(Vec::new()));
let loop_throttle = throttle.clone();
let loop_log = log.clone();
tokio::spawn(async move {
loop_throttle
.run_flush_loop(move |key, payload| {
let log = loop_log.clone();
async move {
log.lock().push((key, payload));
Ok::<(), std::convert::Infallible>(())
}
})
.await;
});
throttle.record("k1", 1);
throttle.record("k2", 2);
settle().await;
assert_eq!(log.lock().len(), 0, "条目未到期时后台循环不得提前落库");
tokio::time::advance(DEBOUNCE).await;
settle().await;
assert_eq!(log.lock().len(), 2, "到期 key 应由后台循环批量落库");
assert_eq!(throttle.pending_len(), 0, "落库后条目应清理防泄漏");
}
#[tokio::test(start_paused = true)]
#[serial_test::serial]
async fn flush_loop_summarizes_dropped_count() {
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;
let logs = Arc::new(Mutex::new(Vec::<String>::new()));
let subscriber = tracing_subscriber::registry().with(
tracing_subscriber::fmt::layer()
.with_ansi(false)
.with_writer(LogCapture(logs.clone())),
);
let _guard = subscriber.set_default();
let throttle = Arc::new(ActivityWriteThrottle::with_limits(1, DEBOUNCE, TIMEOUT));
let loop_throttle = throttle.clone();
tokio::spawn(async move {
loop_throttle
.run_flush_loop(|_key, _payload| {
std::future::ready(Ok::<(), std::convert::Infallible>(()))
})
.await;
});
throttle.record("kept", 1);
assert_eq!(throttle.record("dropped", 2), RecordOutcome::Dropped);
tokio::time::advance(DEBOUNCE).await;
settle().await;
let lines = logs.lock();
let dropped_msg = crate::i18n::translate_detail("logs-credit-throttle-window-dropped", &[]);
assert!(
lines
.iter()
.any(|l| l.contains(&dropped_msg) && l.contains("WARN")),
"后台循环应汇总窗口内丢弃,实际: {:?}",
*lines
);
}
#[tokio::test(start_paused = true)]
async fn flush_write_timeout_bounds_each_write() {
let throttle = ActivityWriteThrottle::with_limits(4, DEBOUNCE, TIMEOUT);
throttle.record("slow", 1);
tokio::time::advance(DEBOUNCE).await;
let hang = |_key: String, _payload: i32| async {
tokio::time::sleep(Duration::from_secs(60)).await;
Ok::<(), std::convert::Infallible>(())
};
let (flushed, _) = tokio::join!(throttle.flush_due(hang), tokio::time::advance(TIMEOUT));
assert_eq!(flushed, 1, "超时写也计为已处理(条目清理)");
assert_eq!(throttle.pending_len(), 0, "超时条目应被清理防泄漏");
}
#[tokio::test(start_paused = true)]
async fn flush_write_error_does_not_block_batch() {
let throttle = ActivityWriteThrottle::with_limits(4, DEBOUNCE, TIMEOUT);
throttle.record("bad", 1);
throttle.record("good", 2);
tokio::time::advance(DEBOUNCE).await;
let succeeded = Arc::new(Mutex::new(Vec::<i32>::new()));
let sink = succeeded.clone();
let writer = move |key: String, payload: i32| {
let succeeded = sink.clone();
async move {
if key == "bad" {
Err("injected-failure".to_string())
} else {
succeeded.lock().push(payload);
Ok(())
}
}
};
let flushed = throttle.flush_due(writer).await;
assert_eq!(flushed, 2, "失败条目不阻断批次其余落库");
assert_eq!(succeeded.lock().len(), 1, "失败条目不落库,其余应成功");
assert_eq!(
throttle.pending_len(),
0,
"失败条目同样清理(显性化后不占用容量)"
);
}
#[test]
fn constants_align_with_pomerium_access_tracker() {
assert_eq!(
ACTIVITY_THROTTLE_MAX_SIZE, 1_000,
"max_size 对齐 accessTrackerMaxSize(access_tracker.go:22)"
);
assert_eq!(
ACTIVITY_THROTTLE_DEBOUNCE,
Duration::from_secs(10),
"debounce 对齐 accessTrackerDebouncePeriod(access_tracker.go:23)"
);
assert_eq!(
ACTIVITY_THROTTLE_TIMEOUT,
Duration::from_secs(3),
"timeout 对齐 accessTrackerUpdateTimeout(access_tracker.go:24)"
);
}
}