use crate::dao::repository::make_statement;
use crate::error::{GarrisonError, GarrisonResult};
use dbnexus::sea_orm::{ConnectionTrait, QueryResult, Value};
use dbnexus::DbPool;
pub const STATUS_PENDING: &str = "pending";
pub const STATUS_DELIVERED: &str = "delivered";
pub const STATUS_FAILED: &str = "failed";
pub const DEFAULT_RETRY_BACKOFF_MILLIS: i64 = 5_000;
pub const RETRY_BACKOFF_CAP_MILLIS: i64 = 600_000;
pub fn retry_backoff_millis(base_millis: i64, cap_millis: i64, retries: i64) -> i64 {
let mut delay = base_millis.max(0);
for _ in 1..retries.max(1) {
delay = delay.saturating_mul(2);
if delay >= cap_millis {
return cap_millis.max(0);
}
}
delay.min(cap_millis.max(0))
}
#[derive(Debug, Clone)]
pub struct QueueEntry {
pub id: String,
pub client_id: String,
pub logout_token: String,
pub status: String,
pub pending_retries: i64,
pub created_at: i64,
pub next_attempt_at: i64,
pub max_ttl_at: i64,
}
pub struct BackChannelQueue {
pool: DbPool,
max_ttl_secs: i64,
retry_backoff_base_millis: i64,
retry_backoff_cap_millis: i64,
}
impl BackChannelQueue {
pub fn new(pool: DbPool, max_ttl_secs: i64) -> Self {
Self {
pool,
max_ttl_secs,
retry_backoff_base_millis: DEFAULT_RETRY_BACKOFF_MILLIS,
retry_backoff_cap_millis: RETRY_BACKOFF_CAP_MILLIS,
}
}
pub fn with_backoff(mut self, base_millis: i64, cap_millis: i64) -> Self {
self.retry_backoff_base_millis = base_millis;
self.retry_backoff_cap_millis = cap_millis;
self
}
pub async fn enqueue(&self, client_id: &str, logout_token: &str) -> GarrisonResult<String> {
let id = uuid::Uuid::now_v7().to_string();
let now = unix_now_millis()?;
let max_ttl_at = now
.checked_add(self.max_ttl_secs.saturating_mul(1000))
.ok_or_else(|| GarrisonError::InvalidParam("backchannel-ttl-overflow".to_string()))?;
self.execute(
"INSERT INTO oauth2_backchannel_queue (id, client_id, logout_token, status, pending_retries, created_at, next_attempt_at, max_ttl_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
vec![
Value::String(Some(id.clone())),
Value::String(Some(client_id.to_string())),
Value::String(Some(logout_token.to_string())),
Value::String(Some(STATUS_PENDING.to_string())),
Value::BigInt(Some(0)),
Value::BigInt(Some(now)),
Value::BigInt(Some(now)),
Value::BigInt(Some(max_ttl_at)),
],
"enqueue",
)
.await?;
Ok(id)
}
pub async fn pending_batch(&self, limit: i64) -> GarrisonResult<Vec<QueueEntry>> {
let session = self
.pool
.get_session("admin")
.await
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-get-session::{}", e)))?;
let conn = session
.connection()
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-connection::{}", e)))?;
let now = unix_now_millis()?;
let stmt = make_statement(
conn,
"SELECT id, client_id, logout_token, status, pending_retries, created_at, next_attempt_at, max_ttl_at FROM oauth2_backchannel_queue WHERE status = ? AND next_attempt_at <= ? ORDER BY next_attempt_at ASC, created_at ASC, id ASC LIMIT ?",
vec![
Value::String(Some(STATUS_PENDING.to_string())),
Value::BigInt(Some(now)),
Value::BigInt(Some(limit)),
],
);
let rows = conn
.query_all_raw(stmt)
.await
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-pending::{}", e)))?;
rows.iter().map(parse_entry).collect()
}
pub async fn find_by_id(&self, id: &str) -> GarrisonResult<Option<QueueEntry>> {
let session = self
.pool
.get_session("admin")
.await
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-get-session::{}", e)))?;
let conn = session
.connection()
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-connection::{}", e)))?;
let stmt = make_statement(
conn,
"SELECT id, client_id, logout_token, status, pending_retries, created_at, next_attempt_at, max_ttl_at FROM oauth2_backchannel_queue WHERE id = ?",
vec![Value::String(Some(id.to_string()))],
);
let row = conn
.query_one_raw(stmt)
.await
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-find::{}", e)))?;
row.map(|r| parse_entry(&r)).transpose()
}
pub async fn mark_delivered(&self, id: &str) -> GarrisonResult<()> {
self.transition(id, STATUS_DELIVERED).await
}
pub async fn mark_failed(&self, id: &str) -> GarrisonResult<()> {
self.transition(id, STATUS_FAILED).await
}
pub async fn increment_retries(&self, id: &str) -> GarrisonResult<i64> {
let current = self
.find_by_id(id)
.await?
.ok_or_else(|| GarrisonError::Dao(format!("backchannel-queue-missing-row::{id}")))?
.pending_retries;
let next_retries = current + 1;
let now = unix_now_millis()?;
let delay = retry_backoff_millis(
self.retry_backoff_base_millis,
self.retry_backoff_cap_millis,
next_retries,
);
let next_attempt_at = now.checked_add(delay).ok_or_else(|| {
GarrisonError::InvalidParam("backchannel-backoff-overflow".to_string())
})?;
self.execute(
"UPDATE oauth2_backchannel_queue SET pending_retries = pending_retries + 1, next_attempt_at = ? WHERE id = ?",
vec![
Value::BigInt(Some(next_attempt_at)),
Value::String(Some(id.to_string())),
],
"increment-retries",
)
.await?;
Ok(next_retries)
}
pub async fn count_by_status(&self, status: &str) -> GarrisonResult<i64> {
let session = self
.pool
.get_session("admin")
.await
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-get-session::{}", e)))?;
let conn = session
.connection()
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-connection::{}", e)))?;
let stmt = make_statement(
conn,
"SELECT count(*) AS cnt FROM oauth2_backchannel_queue WHERE status = ?",
vec![Value::String(Some(status.to_string()))],
);
let row = conn
.query_one_raw(stmt)
.await
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-count::{}", e)))?
.ok_or_else(|| GarrisonError::Dao("backchannel-queue-count-missing-row".to_string()))?;
row.try_get::<i64>("", "cnt")
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-parse-count::{}", e)))
}
async fn transition(&self, id: &str, status: &str) -> GarrisonResult<()> {
self.execute(
"UPDATE oauth2_backchannel_queue SET status = ? WHERE id = ?",
vec![
Value::String(Some(status.to_string())),
Value::String(Some(id.to_string())),
],
"transition",
)
.await?;
Ok(())
}
async fn execute(&self, sql: &str, values: Vec<Value>, op: &str) -> GarrisonResult<u64> {
let session = self
.pool
.get_session("admin")
.await
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-get-session::{}", e)))?;
let conn = session
.connection()
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-connection::{}", e)))?;
let stmt = make_statement(conn, sql, values);
let result = conn
.execute_raw(stmt)
.await
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-{op}::{}", e)))?;
Ok(result.rows_affected())
}
}
fn parse_entry(row: &QueryResult) -> GarrisonResult<QueueEntry> {
Ok(QueueEntry {
id: get_string(row, "id")?,
client_id: get_string(row, "client_id")?,
logout_token: get_string(row, "logout_token")?,
status: get_string(row, "status")?,
pending_retries: get_i64(row, "pending_retries")?,
created_at: get_i64(row, "created_at")?,
next_attempt_at: get_i64(row, "next_attempt_at")?,
max_ttl_at: get_i64(row, "max_ttl_at")?,
})
}
fn get_string(row: &QueryResult, col: &str) -> GarrisonResult<String> {
row.try_get::<Option<String>>("", col)
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-parse-{col}::{}", e)))?
.ok_or_else(|| GarrisonError::Dao(format!("backchannel-queue-null-{col}")))
}
fn get_i64(row: &QueryResult, col: &str) -> GarrisonResult<i64> {
row.try_get::<Option<i64>>("", col)
.map_err(|e| GarrisonError::Dao(format!("backchannel-queue-parse-{col}::{}", e)))?
.ok_or_else(|| GarrisonError::Dao(format!("backchannel-queue-null-{col}")))
}
pub(crate) fn unix_now_millis() -> GarrisonResult<i64> {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_millis() as i64)
.map_err(|e| GarrisonError::Internal(format!("system-clock-error::{}", e)))
}
#[cfg(all(test, feature = "db-sqlite"))]
mod tests {
use super::*;
use crate::dao::repository::sqlite::test_support::setup_db;
async fn setup_queue(max_ttl_secs: i64) -> (DbPool, BackChannelQueue) {
let pool = setup_db().await;
let queue = BackChannelQueue::new(pool.clone(), max_ttl_secs);
(pool, queue)
}
#[tokio::test]
async fn enqueue_then_pending_batch_roundtrip() {
let (_pool, queue) = setup_queue(3600).await;
let id = queue
.enqueue("client-a", "token-jwt")
.await
.expect("入队应成功");
assert!(!id.is_empty(), "应返回生成的行 ID");
let parsed = uuid::Uuid::parse_str(&id).expect("行 ID 应为合法 UUID");
assert_eq!(
parsed.get_version(),
Some(uuid::Version::SortRand),
"行 ID 应为 UUID v7(时间有序 tiebreaker)"
);
let batch = queue.pending_batch(10).await.expect("批次查询应成功");
assert_eq!(batch.len(), 1, "pending 批次应恰有一行");
let row = &batch[0];
assert_eq!(row.id, id);
assert_eq!(row.client_id, "client-a");
assert_eq!(row.logout_token, "token-jwt");
assert_eq!(row.status, STATUS_PENDING);
assert_eq!(row.pending_retries, 0);
assert_eq!(
row.next_attempt_at, row.created_at,
"入队行初始即到期,不得自带退避"
);
assert!(
row.max_ttl_at >= row.created_at + 3_600_000 - 1_000,
"max_ttl_at 应为入队时刻 + 窗口,实际: {:?}",
row
);
assert_eq!(queue.count_by_status(STATUS_PENDING).await.unwrap(), 1);
}
#[test]
fn enqueue_generates_time_ordered_v7_ids() {
let a = uuid::Uuid::now_v7();
let b = uuid::Uuid::now_v7();
for id in [a, b] {
assert_eq!(id.get_version(), Some(uuid::Version::SortRand));
}
}
#[tokio::test]
async fn pending_batch_is_fifo_and_respects_limit() {
let (_pool, queue) = setup_queue(3600).await;
for i in 0..3 {
queue
.enqueue(&format!("client-{i}"), "t")
.await
.expect("入队应成功");
tokio::time::sleep(std::time::Duration::from_millis(5)).await;
}
let batch = queue.pending_batch(2).await.expect("批次查询应成功");
assert_eq!(batch.len(), 2, "LIMIT 应截断批次");
assert_eq!(batch[0].client_id, "client-0", "FIFO 应先取最早入队行");
assert_eq!(batch[1].client_id, "client-1");
}
#[tokio::test]
async fn deferred_failed_row_does_not_block_later_rows() {
let (_pool, queue) = setup_queue(3600).await;
let dead = queue.enqueue("client-dead", "t").await.unwrap();
queue.increment_retries(&dead).await.unwrap();
queue.enqueue("client-fresh", "t").await.unwrap();
let batch = queue.pending_batch(10).await.unwrap();
let clients: Vec<&str> = batch.iter().map(|r| r.client_id.as_str()).collect();
assert_eq!(
clients,
vec!["client-fresh"],
"退避未到期的行不得进批,更不得阻塞其后入队行"
);
}
#[tokio::test]
async fn increment_retries_schedules_exponential_backoff() {
let pool = setup_db().await;
let queue = BackChannelQueue::new(pool.clone(), 3600).with_backoff(2_000, 600_000);
let slow_id = queue.enqueue("client-slow", "t").await.unwrap();
let before = unix_now_millis().unwrap();
assert_eq!(queue.increment_retries(&slow_id).await.unwrap(), 1);
let entry = queue.find_by_id(&slow_id).await.unwrap().unwrap();
assert!(
entry.next_attempt_at - before >= 2_000,
"退避至少推后一个基数,实际 {}ms",
entry.next_attempt_at - before
);
assert!(
queue.pending_batch(10).await.unwrap().is_empty(),
"退避期内行不得进批"
);
let queue = BackChannelQueue::new(pool.clone(), 3600).with_backoff(50, 200);
let id = queue.enqueue("client-fast", "t").await.unwrap();
let before = unix_now_millis().unwrap();
assert_eq!(queue.increment_retries(&id).await.unwrap(), 1);
let entry = queue.find_by_id(&id).await.unwrap().unwrap();
assert!(
entry.next_attempt_at - before >= 50,
"第 1 次退避下界 50ms,实际 {}ms",
entry.next_attempt_at - before
);
tokio::time::sleep(std::time::Duration::from_millis(120)).await;
assert_eq!(
queue.pending_batch(10).await.unwrap().len(),
1,
"到期后行应重新进批"
);
let before = unix_now_millis().unwrap();
assert_eq!(queue.increment_retries(&id).await.unwrap(), 2);
let entry = queue.find_by_id(&id).await.unwrap().unwrap();
assert!(
entry.next_attempt_at - before >= 100,
"第 2 次退避下界 100ms(2 倍增),实际 {}ms",
entry.next_attempt_at - before
);
for _ in 0..4 {
tokio::time::sleep(std::time::Duration::from_millis(210)).await;
queue.increment_retries(&id).await.unwrap();
}
let before = unix_now_millis().unwrap();
assert_eq!(queue.increment_retries(&id).await.unwrap(), 7);
let entry = queue.find_by_id(&id).await.unwrap().unwrap();
assert_eq!(entry.pending_retries, 7, "计数应逐次落库");
assert!(
entry.next_attempt_at - before >= 200,
"退避应在 200ms 封顶,实际 {}ms",
entry.next_attempt_at - before
);
}
#[test]
fn retry_backoff_millis_grows_exponentially_and_caps() {
let base = 5_000;
let cap = 600_000;
assert_eq!(retry_backoff_millis(base, cap, 1), 5_000);
assert_eq!(retry_backoff_millis(base, cap, 2), 10_000);
assert_eq!(retry_backoff_millis(base, cap, 3), 20_000);
assert_eq!(retry_backoff_millis(base, cap, 8), 600_000, "超过 cap 截断");
assert_eq!(
retry_backoff_millis(i64::MAX / 2, cap, 40),
cap,
"大指数溢出安全"
);
assert_eq!(retry_backoff_millis(0, cap, 3), 0, "零基数不产生退避");
}
#[tokio::test]
async fn terminal_states_leave_pending_batch() {
let (_pool, queue) = setup_queue(3600).await;
let a = queue.enqueue("client-a", "t").await.unwrap();
let b = queue.enqueue("client-b", "t").await.unwrap();
queue.mark_delivered(&a).await.expect("标记投递应成功");
queue.mark_failed(&b).await.expect("标记退役应成功");
assert!(
queue.pending_batch(10).await.unwrap().is_empty(),
"终态行不得留在 pending 批次"
);
assert_eq!(queue.count_by_status(STATUS_DELIVERED).await.unwrap(), 1);
assert_eq!(queue.count_by_status(STATUS_FAILED).await.unwrap(), 1);
}
}
#[cfg(all(test, feature = "db-postgres"))]
mod postgres_tests {
use super::*;
#[tokio::test]
#[serial_test::serial]
#[ignore = "requires postgres DATABASE_URL (set SINNAN_TEST_DATABASE_URL to run)"]
async fn queue_roundtrip_on_postgres_backend() {
let url = std::env::var("DATABASE_URL")
.or_else(|_| std::env::var("SINNAN_TEST_DATABASE_URL"))
.expect("DATABASE_URL 或 SINNAN_TEST_DATABASE_URL 必须设置才能运行此测试");
let pool = crate::dao::init_dbnexus(&url)
.await
.expect("init_dbnexus 应成功(数据库可达)");
let migration = crate::dao::GarrisonMigration::with_base_dir(
pool.clone(),
std::path::PathBuf::from("migrations/postgres"),
);
migration
.migrate_core()
.await
.expect("目录迁移(含 017)应成功");
let queue = BackChannelQueue::new(pool, 3600);
let id = queue.enqueue("client-pg", "token-pg").await.unwrap();
let batch = queue.pending_batch(100).await.unwrap();
let mine = batch
.iter()
.find(|row| row.id == id)
.expect("刚入队的行应出现在 pending 批次");
assert_eq!(mine.client_id, "client-pg");
queue.mark_delivered(&id).await.unwrap();
let after = queue.pending_batch(100).await.unwrap();
assert!(
after.iter().all(|row| row.id != id),
"已投递行不得再出现在 pending 批次"
);
}
}