Skip to main content

wordval_scheduler/
lib.rs

1//! # wordval-scheduler
2//!
3//! Wordval 定时任务插件:cron 表达式调度。
4//!
5//! ## 特性
6//!
7//! - 采用 6 字段 cron 语法:`秒 分 时 日 月 周`
8//! - 定时器驱动:最小堆按下次触发时间排序,睡到最近触发点,无任务时完全休眠
9//! - 任务表变更(注册/移除)通过 `Notify` 即时唤醒调度循环重建堆
10//! - 支持注册/移除/手动触发/列举任务
11//!
12//! ## Cron 语法
13//!
14//! 每个字段支持:`*`、`a`、`a-b`、`*/n`、`a-b/n`、`a/n`(≡ `a-max/n`)、`a,b,c`
15//! 周字段 `0-6`(0=周日)。日与周同时受限时按 Vixie cron 语义取“或”。
16//!
17//! ## 快速开始
18//!
19//! ```ignore
20//! use wordval_scheduler::SchedulerPlugin;
21//!
22//! let scheduler = SchedulerPlugin::new();
23//! scheduler.register("hourly-job", "0 0 * * * *", "每小时执行的任务", || {
24//!     tokio::spawn(async {
25//!         println!("每小时执行");
26//!     })
27//! });
28//! ```
29
30use async_trait::async_trait;
31use chrono::{DateTime, Datelike, Local, LocalResult, NaiveDateTime, TimeZone, Timelike};
32use parking_lot::{Mutex, RwLock};
33use std::cmp::Reverse;
34use std::collections::{BinaryHeap, HashMap};
35use std::sync::Arc;
36use tokio::sync::Notify;
37use wordval_core::{Plugin, Result};
38
39mod clock;
40pub use clock::{Clock, SystemClock, TestClock};
41
42/// chrono 时长(与 std Duration 区分)
43type ChronoDuration = chrono::Duration;
44
45/// 任务闭包:仅负责 spawn,不允许阻塞。用 Arc 包装以便在锁外克隆后调用。
46type JobFn = Arc<dyn Fn() -> tokio::task::JoinHandle<()> + Send + Sync>;
47
48/// 定时任务插件:cron 表达式调度
49///
50/// 支持注册/移除/手动触发/列举任务。后台调度循环采用定时器堆驱动:
51/// 睡到最近一个任务的触发时刻再唤醒,而非每秒轮询。
52///
53/// 时间来源通过 [`Clock`] 注入:默认 [`SystemClock`] 读系统时间;
54/// 测试可传入 [`TestClock`] 虚拟时钟,使触发时刻完全确定。
55pub struct SchedulerPlugin {
56    /// 任务注册表(name → ScheduledJob)
57    jobs: Arc<RwLock<HashMap<String, ScheduledJob>>>,
58    /// 后台调度循环句柄(stop 时中止)
59    task: Arc<Mutex<Option<tokio::task::JoinHandle<()>>>>,
60    /// 任务表变更通知:注册/移除后唤醒调度循环重建触发堆
61    notify: Arc<Notify>,
62    /// 时间来源(生产 SystemClock / 测试 TestClock)
63    clock: Arc<dyn Clock>,
64}
65
66struct ScheduledJob {
67    cron: String,
68    description: String,
69    runner: JobFn,
70    /// 解析后的 cron 计划;解析失败为 None(不参与自动调度,仅可手动触发)
71    schedule: Option<CronSchedule>,
72}
73
74impl SchedulerPlugin {
75    /// 创建空的调度器(默认使用系统时钟)
76    pub fn new() -> Self {
77        Self::with_clock(Arc::new(SystemClock))
78    }
79
80    /// 创建调度器并注入自定义时钟(测试用 [`TestClock`])
81    pub fn with_clock(clock: Arc<dyn Clock>) -> Self {
82        Self {
83            jobs: Arc::new(RwLock::new(HashMap::new())),
84            task: Arc::new(Mutex::new(None)),
85            notify: Arc::new(Notify::new()),
86            clock,
87        }
88    }
89
90    /// 注册定时任务
91    ///
92    /// `cron` 为 6 字段表达式:`秒 分 时 日 月 周`。解析失败时任务仍会登记
93    /// (可手动 `trigger`),但不会参与自动调度,并打印告警日志。
94    /// 同名重复注册会覆盖旧任务。
95    ///
96    /// ```ignore
97    /// scheduler.register("cleanup", "0 */5 * * * *", "每5分钟清理", || {
98    ///     tokio::spawn(async { cleanup_task().await })
99    /// });
100    /// ```
101    pub fn register<F>(&self, name: &str, cron: &str, desc: &str, runner: F)
102    where
103        F: Fn() -> tokio::task::JoinHandle<()> + Send + Sync + 'static,
104    {
105        let schedule = match CronSchedule::parse(cron) {
106            Ok(s) => {
107                if s.next_after(&self.clock.now()).is_none() {
108                    tracing::warn!(
109                        "定时任务 {} 的 cron 表达式 '{}' 在未来 8 年内无触发时间,将不会自动调度",
110                        name,
111                        cron
112                    );
113                }
114                Some(s)
115            }
116            Err(e) => {
117                tracing::warn!(
118                    "定时任务 {} 的 cron 表达式 '{}' 解析失败: {},将不会自动调度",
119                    name,
120                    cron,
121                    e
122                );
123                None
124            }
125        };
126        self.jobs.write().insert(
127            name.to_string(),
128            ScheduledJob {
129                cron: cron.to_string(),
130                description: desc.to_string(),
131                runner: Arc::new(runner),
132                schedule,
133            },
134        );
135        // 唤醒调度循环重建触发堆,新任务即时生效
136        self.notify.notify_one();
137    }
138
139    /// 移除定时任务
140    pub fn remove(&self, name: &str) {
141        self.jobs.write().remove(name);
142        self.notify.notify_one();
143    }
144
145    /// 列出所有注册的任务
146    pub fn list(&self) -> Vec<(String, String, String)> {
147        self.jobs
148            .read()
149            .iter()
150            .map(|(k, v)| (k.clone(), v.cron.clone(), v.description.clone()))
151            .collect()
152    }
153
154    /// 手动触发指定的定时任务
155    ///
156    /// runner 在锁外克隆并调用,闭包内可安全地调用 register/remove/trigger。
157    pub fn trigger(&self, name: &str) -> Option<tokio::task::JoinHandle<()>> {
158        let runner = self.jobs.read().get(name).map(|j| Arc::clone(&j.runner));
159        runner.map(|r| r())
160    }
161
162    /// 拉起后台调度循环(定时器堆驱动)。
163    ///
164    /// 每轮:重建最小堆(基准取 now-1s,使当前秒到期的任务入堆)→
165    /// 锁内克隆到期任务的 runner → 锁外执行 → 触发过的任务回推下一次
166    /// 触发时刻 → 睡到堆顶时刻或等变更通知。
167    /// 整体重建而非增量维护,使增删改天然生效,无陈旧堆项问题。
168    fn spawn_loop(&self) {
169        let jobs = Arc::clone(&self.jobs);
170        let notify = Arc::clone(&self.notify);
171        let clock = Arc::clone(&self.clock);
172        let handle = tokio::spawn(async move {
173            // 任务名 → 上次已触发的时刻(秒):重建时防同秒重复触发
174            let mut last_fired: HashMap<String, i64> = HashMap::new();
175            loop {
176                let now = clock.now();
177                let now_sec = now.timestamp();
178                // 基准取上一秒:保证“当前秒到期”的任务也进入堆中
179                let base = now - ChronoDuration::seconds(1);
180
181                // 堆元素:(触发时间戳秒, 任务名);同时快照 runner 以便锁外执行
182                let mut heap: BinaryHeap<Reverse<(i64, String)>> = BinaryHeap::new();
183                let mut runners: HashMap<String, JobFn> = HashMap::new();
184                {
185                    let guard = jobs.read();
186                    // 已移除任务的痕迹顺手清掉,last_fired 不随任务增删膨胀
187                    last_fired.retain(|name, _| guard.contains_key(name));
188                    for (name, job) in guard.iter() {
189                        let Some(sched) = &job.schedule else { continue };
190                        // 触发基准:取「上一秒」与「该任务上次触发时刻」中较晚者,
191                        // 同秒重建时既不重复触发已触发的秒,也不丢其后的正常触发
192                        let from = task_base(&base, last_fired.get(name).copied());
193                        if let Some(ts) = sched.next_after(&from) {
194                            heap.push(Reverse((ts, name.clone())));
195                            runners.insert(name.clone(), Arc::clone(&job.runner));
196                        }
197                    }
198                }
199
200                // 弹出所有到期任务,收集 runner 后在锁外执行
201                // (锁内执行用户闭包有死锁风险:闭包可能回調 register/remove)
202                let mut fired: Vec<String> = Vec::new();
203                while let Some(Reverse((ts, _))) = heap.peek() {
204                    if *ts > now_sec {
205                        break;
206                    }
207                    let Reverse((ts, name)) = heap.pop().expect("peek 已确认非空");
208                    last_fired.insert(name.clone(), ts);
209                    if let Some(runner) = runners.get(&name) {
210                        let runner = Arc::clone(runner);
211                        tracing::debug!("触发定时任务: {}", name);
212                        // runner 契约:内部仅 spawn,不阻塞调度循环;
213                        // JoinHandle 直接 drop 即分离运行
214                        drop(runner());
215                    }
216                    fired.push(name);
217                }
218
219                // 触发后回推下一次触发时刻:防止堆空长睡漏掉后续触发
220                // (单任务每秒/每分钟的 cron 若只 pop 不回推,会退化为长周期)
221                if !fired.is_empty() {
222                    let guard = jobs.read();
223                    for name in &fired {
224                        if let Some(sched) = guard.get(name).and_then(|j| j.schedule.as_ref()) {
225                            if let Some(ts) = sched.next_after(&now) {
226                                heap.push(Reverse((ts, name.clone())));
227                            }
228                        }
229                    }
230                }
231
232                // 睡到堆顶触发时刻;无任务时以 1 小时为空闲周期,
233                // 等 next_after 临近或任务表变更唤醒
234                let target_sec = match heap.peek() {
235                    Some(Reverse((ts, _))) => *ts,
236                    None => now_sec + 3600,
237                };
238                // 时钟睡到目标秒;注册/移除的 notify_one 会留存 permit,
239                // 变更不会丢失唤醒
240                tokio::select! {
241                    _ = clock.sleep_until(target_sec) => {}
242                    _ = notify.notified() => {}
243                }
244            }
245        });
246        *self.task.lock() = Some(handle);
247    }
248}
249
250#[async_trait]
251impl Plugin for SchedulerPlugin {
252    fn name(&self) -> &str {
253        "scheduler"
254    }
255
256    fn priority(&self) -> i32 {
257        50
258    }
259
260    async fn start(&self) -> Result<()> {
261        // 幂等保护:重复 start 不拉起第二个调度循环
262        if let Some(h) = self.task.lock().as_ref() {
263            if !h.is_finished() {
264                tracing::warn!("定时任务插件: 调度循环已在运行,忽略重复启动");
265                return Ok(());
266            }
267        }
268        let count = self.jobs.read().len();
269        tracing::info!("定时任务插件: {} 个任务已注册,启动后台调度循环", count);
270        for (name, job) in self.jobs.read().iter() {
271            tracing::info!("  - {} [{}] {}", name, job.cron, job.description);
272        }
273        self.spawn_loop();
274        Ok(())
275    }
276
277    async fn stop(&self) -> Result<()> {
278        if let Some(h) = self.task.lock().take() {
279            h.abort();
280        }
281        tracing::info!("定时任务插件: 已停止");
282        Ok(())
283    }
284}
285
286impl Default for SchedulerPlugin {
287    fn default() -> Self {
288        Self::new()
289    }
290}
291
292/// 单任务重建堆时的基准时刻:取 `base` 与该任务上次已触发时刻中较晚者。
293///
294/// 调度循环每轮整体重建堆;若任务在本轮已触发过(last_fired 为本秒),
295/// 直接以 `now-1s` 为基准会把已触发的秒重新入堆造成重复触发。改以
296/// 「上次触发时刻」为基准可严格取其后第一次触发,重复与漏触发都不发生。
297fn task_base(base: &DateTime<Local>, last_fired: Option<i64>) -> DateTime<Local> {
298    match last_fired.and_then(|ts| Local.timestamp_opt(ts, 0).single()) {
299        Some(t) if t > *base => t,
300        _ => *base,
301    }
302}
303
304// ──── cron 解析与匹配 ──────────────────────────────────
305
306/// 已解析的 6 字段 cron 计划。每个字段用位掩码表示允许的取值。
307struct CronSchedule {
308    sec: u64,       // 0-59
309    min: u64,       // 0-59
310    hour: u64,      // 0-23
311    dom: u64,       // 1-31
312    month: u64,     // 1-12
313    dow: u64,       // 0-6 (0=Sun)
314    dom_star: bool, // 日字段是否为 '*'
315    dow_star: bool, // 周字段是否为 '*'
316}
317
318impl CronSchedule {
319    /// 解析 6 字段 cron 表达式:`秒 分 时 日 月 周`
320    fn parse(expr: &str) -> std::result::Result<Self, String> {
321        let fields: Vec<&str> = expr.split_whitespace().collect();
322        if fields.len() != 6 {
323            return Err(format!(
324                "需要 6 个字段(秒 分 时 日 月 周),实际 {} 个",
325                fields.len()
326            ));
327        }
328        Ok(Self {
329            sec: parse_field(fields[0], 0, 59)?,
330            min: parse_field(fields[1], 0, 59)?,
331            hour: parse_field(fields[2], 0, 23)?,
332            dom: parse_field(fields[3], 1, 31)?,
333            month: parse_field(fields[4], 1, 12)?,
334            dow: parse_field(fields[5], 0, 6)?,
335            dom_star: fields[3].trim() == "*",
336            dow_star: fields[5].trim() == "*",
337        })
338    }
339
340    /// 判断给定时刻是否命中该 cron 计划
341    #[cfg(test)]
342    fn matches(&self, now: &chrono::DateTime<Local>) -> bool {
343        if !bit_set(self.sec, now.second() as u64)
344            || !bit_set(self.min, now.minute() as u64)
345            || !bit_set(self.hour, now.hour() as u64)
346            || !bit_set(self.month, now.month() as u64)
347        {
348            return false;
349        }
350        self.day_matches(now)
351    }
352
353    /// 日/周匹配:Vixie cron 语义,两者都受限时取“或”,否则用受限的那个。
354    fn day_matches(&self, t: &DateTime<Local>) -> bool {
355        let dom_hit = bit_set(self.dom, t.day() as u64);
356        let dow_hit = bit_set(self.dow, t.weekday().num_days_from_sunday() as u64);
357        match (self.dom_star, self.dow_star) {
358            (true, true) => true,
359            (false, true) => dom_hit,
360            (true, false) => dow_hit,
361            (false, false) => dom_hit || dow_hit,
362        }
363    }
364
365    /// 计算严格晚于 `from` 的下一次触发时间(本地时间)。
366    ///
367    /// 按 月→日→时→分→秒 层级快进,每步 naive 时间严格递增,无需逐秒迭代。
368    /// 8 年内无命中返回 None(如 `0 0 0 31 2 *` 这类永不满足的组合)。
369    fn next_after(&self, from: &DateTime<Local>) -> Option<i64> {
370        let mut t = from.with_nanosecond(0)? + ChronoDuration::seconds(1);
371        let limit = *from + ChronoDuration::days(366 * 8);
372        while t <= limit {
373            if !bit_set(self.month, t.month() as u64) {
374                t = next_month_start(&t)?;
375                continue;
376            }
377            if !self.day_matches(&t) {
378                t = next_day_start(&t)?;
379                continue;
380            }
381            if !bit_set(self.hour, t.hour() as u64) {
382                t = next_hour_start(&t)?;
383                continue;
384            }
385            if !bit_set(self.min, t.minute() as u64) {
386                t = next_minute_start(&t)?;
387                continue;
388            }
389            if !bit_set(self.sec, t.second() as u64) {
390                t += ChronoDuration::seconds(1);
391                continue;
392            }
393            return Some(t.timestamp());
394        }
395        None
396    }
397}
398
399/// 将 naive 本地时间解析为 DateTime<Local>:
400/// 歧义(DST 回拨)取较早一次;不存在(DST 空洞)则顺移到首个存在的时刻。
401fn resolve_local(mut nd: NaiveDateTime) -> Option<DateTime<Local>> {
402    // DST 空洞一般不超过数小时,240 次分钟步进足够
403    for _ in 0..240 {
404        match Local.from_local_datetime(&nd) {
405            LocalResult::Single(dt) => return Some(dt),
406            LocalResult::Ambiguous(a, _) => return Some(a),
407            LocalResult::None => nd += ChronoDuration::minutes(1),
408        }
409    }
410    None
411}
412
413fn next_month_start(t: &DateTime<Local>) -> Option<DateTime<Local>> {
414    let (y, m) = (t.year(), t.month());
415    let (ny, nm) = if m == 12 { (y + 1, 1) } else { (y, m + 1) };
416    let nd = chrono::NaiveDate::from_ymd_opt(ny, nm, 1)?.and_hms_opt(0, 0, 0)?;
417    resolve_local(nd)
418}
419
420fn next_day_start(t: &DateTime<Local>) -> Option<DateTime<Local>> {
421    let nd = t.date_naive().succ_opt()?.and_hms_opt(0, 0, 0)?;
422    resolve_local(nd)
423}
424
425fn next_hour_start(t: &DateTime<Local>) -> Option<DateTime<Local>> {
426    let nd = t.naive_local().with_minute(0)?.with_second(0)? + ChronoDuration::hours(1);
427    resolve_local(nd)
428}
429
430fn next_minute_start(t: &DateTime<Local>) -> Option<DateTime<Local>> {
431    let nd = t.naive_local().with_second(0)? + ChronoDuration::minutes(1);
432    resolve_local(nd)
433}
434
435#[inline]
436fn bit_set(mask: u64, v: u64) -> bool {
437    v < 64 && (mask & (1u64 << v)) != 0
438}
439
440/// 解析单个 cron 字段为位掩码。支持 `*`、`a`、`a-b`、`*/n`、`a-b/n`、`a/n`、逗号列表。
441fn parse_field(field: &str, min: u64, max: u64) -> std::result::Result<u64, String> {
442    let mut mask = 0u64;
443    for part in field.split(',') {
444        let part = part.trim();
445        if part.is_empty() {
446            return Err(format!("空的字段片段: '{}'", field));
447        }
448        // 拆分步长 a-b/n、*/n 或 a/n
449        let (range_part, step, has_step) = match part.split_once('/') {
450            Some((r, s)) => {
451                let step: u64 = s.parse().map_err(|_| format!("非法步长: '{}'", s))?;
452                if step == 0 {
453                    return Err(format!("步长不能为 0: '{}'", part));
454                }
455                (r, step, true)
456            }
457            None => (part, 1, false),
458        };
459
460        let (lo, hi) = if range_part == "*" {
461            (min, max)
462        } else if let Some((a, b)) = range_part.split_once('-') {
463            let a: u64 = a.parse().map_err(|_| format!("非法范围起点: '{}'", a))?;
464            let b: u64 = b.parse().map_err(|_| format!("非法范围终点: '{}'", b))?;
465            (a, b)
466        } else {
467            let v: u64 = range_part
468                .parse()
469                .map_err(|_| format!("非法数值: '{}'", range_part))?;
470            // Vixie cron 语义:N/step ≡ N-max/step;无步长即单点
471            if has_step {
472                (v, max)
473            } else {
474                (v, v)
475            }
476        };
477
478        if lo < min || hi > max || lo > hi {
479            return Err(format!("字段值越界 [{},{}]: '{}'", min, max, part));
480        }
481
482        let mut v = lo;
483        while v <= hi {
484            mask |= 1u64 << v;
485            v += step;
486        }
487    }
488    Ok(mask)
489}
490
491#[cfg(test)]
492mod tests {
493    use super::*;
494    use crate::clock::duration_until;
495    use std::time::Duration;
496
497    /// 构造本地时间(取 DST 歧义中的较早值,测试日期均避开切换点)
498    fn ldt(y: i32, mo: u32, d: u32, h: u32, mi: u32, s: u32) -> DateTime<Local> {
499        Local
500            .with_ymd_and_hms(y, mo, d, h, mi, s)
501            .earliest()
502            .expect("测试时间应存在")
503    }
504
505    #[test]
506    fn test_parse_star() {
507        let s = CronSchedule::parse("* * * * * *").unwrap();
508        assert!(s.dom_star && s.dow_star);
509        assert!(bit_set(s.sec, 0) && bit_set(s.sec, 59));
510    }
511
512    #[test]
513    fn test_parse_step_and_range() {
514        // 每 5 分钟:0,5,10,...,55
515        let s = CronSchedule::parse("0 */5 * * * *").unwrap();
516        assert!(bit_set(s.min, 0) && bit_set(s.min, 5) && bit_set(s.min, 55));
517        assert!(!bit_set(s.min, 1));
518        assert!(bit_set(s.sec, 0) && !bit_set(s.sec, 1));
519    }
520
521    #[test]
522    fn test_parse_list_and_dash() {
523        let s = CronSchedule::parse("0 0 9-17 * * 1,3,5").unwrap();
524        assert!(bit_set(s.hour, 9) && bit_set(s.hour, 17) && !bit_set(s.hour, 8));
525        assert!(bit_set(s.dow, 1) && bit_set(s.dow, 3) && bit_set(s.dow, 5));
526        assert!(!bit_set(s.dow, 2));
527    }
528
529    #[test]
530    fn test_parse_value_with_step() {
531        // Vixie 语义:5/15 ≡ 5-59/15 → 5,20,35,50
532        let s = CronSchedule::parse("0 5/15 * * * *").unwrap();
533        assert!(bit_set(s.min, 5) && bit_set(s.min, 20) && bit_set(s.min, 35) && bit_set(s.min, 50));
534        assert!(!bit_set(s.min, 0) && !bit_set(s.min, 55));
535    }
536
537    #[test]
538    fn test_parse_errors() {
539        assert!(CronSchedule::parse("* * * * *").is_err()); // 字段不足
540        assert!(CronSchedule::parse("60 * * * * *").is_err()); // 越界
541        assert!(CronSchedule::parse("* */0 * * * *").is_err()); // 步长 0
542    }
543
544    #[test]
545    fn test_next_after_every_second() {
546        let s = CronSchedule::parse("* * * * * *").unwrap();
547        let t = ldt(2024, 6, 15, 10, 30, 41);
548        assert_eq!(s.next_after(&t), Some(ldt(2024, 6, 15, 10, 30, 42).timestamp()));
549    }
550
551    #[test]
552    fn test_next_after_step_minutes() {
553        let s = CronSchedule::parse("0 */5 * * * *").unwrap();
554        let t = ldt(2024, 6, 15, 10, 3, 0);
555        assert_eq!(s.next_after(&t), Some(ldt(2024, 6, 15, 10, 5, 0).timestamp()));
556        // 跨小时:10:58 → 11:00
557        let t = ldt(2024, 6, 15, 10, 58, 30);
558        assert_eq!(s.next_after(&t), Some(ldt(2024, 6, 15, 11, 0, 0).timestamp()));
559    }
560
561    #[test]
562    fn test_next_after_daily_cross_day() {
563        let s = CronSchedule::parse("30 0 9 * * *").unwrap();
564        let t = ldt(2024, 6, 15, 9, 0, 30); // 恰好命中,须取“严格晚于”的下一次
565        assert_eq!(s.next_after(&t), Some(ldt(2024, 6, 16, 9, 0, 30).timestamp()));
566    }
567
568    #[test]
569    fn test_next_after_leap_day() {
570        let s = CronSchedule::parse("0 0 0 29 2 *").unwrap();
571        // 2024 是闰年
572        let t = ldt(2024, 1, 1, 0, 0, 0);
573        assert_eq!(s.next_after(&t), Some(ldt(2024, 2, 29, 0, 0, 0).timestamp()));
574        // 2025 之后下一个 2/29 是 2028
575        let t = ldt(2025, 1, 1, 0, 0, 0);
576        assert_eq!(s.next_after(&t), Some(ldt(2028, 2, 29, 0, 0, 0).timestamp()));
577    }
578
579    #[test]
580    fn test_next_after_never() {
581        // 2 月 31 日永不存在
582        let s = CronSchedule::parse("0 0 0 31 2 *").unwrap();
583        let t = ldt(2024, 1, 1, 0, 0, 0);
584        assert_eq!(s.next_after(&t), None);
585    }
586
587    #[test]
588    fn test_next_after_vixie_dom_dow_or() {
589        // 日与周都受限取“或”:每月 15 号 或 每周三,中午 12 点
590        let s = CronSchedule::parse("0 0 12 15 * 3").unwrap();
591        // 从周三 2024-06-12 凌晨出发:周三即命中(dow=3)
592        let t = ldt(2024, 6, 12, 0, 0, 0);
593        assert_eq!(s.next_after(&t), Some(ldt(2024, 6, 12, 12, 0, 0).timestamp()));
594        // 从周四 2024-06-13 出发:下一命中是 15 号(周六,dom 命中)
595        let t = ldt(2024, 6, 13, 0, 0, 0);
596        assert_eq!(s.next_after(&t), Some(ldt(2024, 6, 15, 12, 0, 0).timestamp()));
597    }
598
599    #[test]
600    fn test_matches_consistent_with_next_after() {
601        let s = CronSchedule::parse("0 30 9-17 * * 1,3,5").unwrap();
602        let hit = ldt(2024, 6, 12, 10, 30, 0); // 周三
603        assert!(s.matches(&hit));
604        assert!(!s.matches(&ldt(2024, 6, 11, 10, 30, 0))); // 周二
605        assert_eq!(
606            s.next_after(&ldt(2024, 6, 12, 9, 0, 0)),
607            Some(ldt(2024, 6, 12, 9, 30, 0).timestamp())
608        );
609    }
610
611    #[test]
612    fn test_duration_until() {
613        let now = ldt(2024, 6, 15, 10, 0, 0);
614        let target = now.timestamp() + 90;
615        let d = duration_until(&now, target);
616        // 整秒边界出发:恰好 90 秒
617        assert_eq!(d, Duration::from_secs(90));
618    }
619
620    #[test]
621    fn test_task_base_same_second_dedup() {
622        // 本秒(10:30:42)已触发:重建基准应推进到 42s,next_after 取 43s 而非重复 42s
623        let base = ldt(2024, 6, 15, 10, 30, 41);
624        let fired_at = ldt(2024, 6, 15, 10, 30, 42).timestamp();
625        let s = CronSchedule::parse("* * * * * *").unwrap();
626        let from = task_base(&base, Some(fired_at));
627        assert_eq!(
628            s.next_after(&from),
629            Some(ldt(2024, 6, 15, 10, 30, 43).timestamp())
630        );
631        // 未触发过:保持 base 语义(当前秒 42s 到期即入堆)
632        let from = task_base(&base, None);
633        assert_eq!(
634            s.next_after(&from),
635            Some(ldt(2024, 6, 15, 10, 30, 42).timestamp())
636        );
637        // 上次触发早于 base 一秒以上:不改变原有行为
638        let old_fired = ldt(2024, 6, 15, 10, 30, 0).timestamp();
639        let from = task_base(&base, Some(old_fired));
640        assert_eq!(
641            s.next_after(&from),
642            Some(ldt(2024, 6, 15, 10, 30, 42).timestamp())
643        );
644    }
645
646    /// 回归:每秒任务触发后必须回推下一次触发。旧实现 pop 后不回填,
647    /// 堆空长睡 3600s,本测试 3.2s 窗口内只会触发 1 次(漏触发)。
648    #[tokio::test]
649    async fn test_recurring_task_refires_without_gap() {
650        let sched = SchedulerPlugin::new();
651        let counter = Arc::new(std::sync::atomic::AtomicUsize::new(0));
652        let c = Arc::clone(&counter);
653        sched.register("every-sec", "* * * * * *", "每秒", move || {
654            let c = Arc::clone(&c);
655            tokio::spawn(async move {
656                c.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
657            })
658        });
659        sched.start().await.unwrap();
660        tokio::time::sleep(Duration::from_millis(3200)).await;
661        sched.stop().await.unwrap();
662        let n = counter.load(std::sync::atomic::Ordering::SeqCst);
663        assert!(
664            n >= 2,
665            "每秒任务 3.2s 内应至少触发 2 次,实际 {n} 次(漏触发回归)"
666        );
667    }
668
669    // ──── 虚拟时钟(TestClock)驱动的确定性调度测试 ──────────
670
671    /// 轮询等待计数达到期望值(runner 是分离 spawn,需让出执行权等其跑完)
672    async fn wait_for_count(counter: &std::sync::atomic::AtomicUsize, expected: usize) {
673        let deadline = tokio::time::Instant::now() + Duration::from_secs(2);
674        while tokio::time::Instant::now() < deadline {
675            if counter.load(std::sync::atomic::Ordering::SeqCst) >= expected {
676                return;
677            }
678            tokio::time::sleep(Duration::from_millis(5)).await;
679        }
680        panic!(
681            "等待任务触发超时:期望 {},实际 {}",
682            expected,
683            counter.load(std::sync::atomic::Ordering::SeqCst)
684        );
685    }
686
687    /// 真实时间流逝不应引起任何触发;虚拟时钟逐秒推进时精确触发
688    #[tokio::test]
689    async fn test_testclock_deterministic_firing() {
690        let t0 = ldt(2024, 6, 15, 10, 30, 0).timestamp();
691        let clock = Arc::new(TestClock::new_at_secs(t0));
692        let sched = SchedulerPlugin::with_clock(Arc::clone(&clock) as Arc<dyn Clock>);
693        let counter = Arc::new(std::sync::atomic::AtomicUsize::new(0));
694        let c = Arc::clone(&counter);
695        sched.register("tick", "* * * * * *", "每秒", move || {
696            let c = Arc::clone(&c);
697            tokio::spawn(async move {
698                c.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
699            })
700        });
701        sched.start().await.unwrap();
702
703        // 真实时间流逝 150ms:虚拟时钟静止,不应产生额外触发
704        tokio::time::sleep(Duration::from_millis(150)).await;
705        // 启动瞬间会对「当前虚拟秒」触发一次(与生产语义一致:base=now-1s)
706        wait_for_count(&counter, 1).await;
707        tokio::time::sleep(Duration::from_millis(100)).await;
708        assert_eq!(
709            counter.load(std::sync::atomic::Ordering::SeqCst),
710            1,
711            "虚拟时钟未推进时真实时间流逝不应引起触发"
712        );
713
714        // 逐秒推进 5 次:每次恰好 +1,无重复无遗漏
715        for i in 1..=5i64 {
716            clock.advance_to_secs(t0 + i);
717            wait_for_count(&counter, (1 + i) as usize).await;
718        }
719        tokio::time::sleep(Duration::from_millis(100)).await;
720        assert_eq!(
721            counter.load(std::sync::atomic::Ordering::SeqCst),
722            6,
723            "逐秒推进 5 次后应恰好累计触发 6 次(含启动当前秒 1 次)"
724        );
725        sched.stop().await.unwrap();
726    }
727
728    /// 虚拟时钟大幅跨越多个触发点时只触发「下一时刻」,不补发跳过的时刻
729    /// (与生产语义一致:调度器无追补机制)
730    #[tokio::test]
731    async fn test_testclock_skip_ahead_no_catchup() {
732        let t0 = ldt(2024, 6, 15, 10, 30, 0).timestamp();
733        let clock = Arc::new(TestClock::new_at_secs(t0));
734        let sched = SchedulerPlugin::with_clock(Arc::clone(&clock) as Arc<dyn Clock>);
735        let counter = Arc::new(std::sync::atomic::AtomicUsize::new(0));
736        let c = Arc::clone(&counter);
737        sched.register("tick", "* * * * * *", "每秒", move || {
738            let c = Arc::clone(&c);
739            tokio::spawn(async move {
740                c.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
741            })
742        });
743        sched.start().await.unwrap();
744        wait_for_count(&counter, 1).await; // 启动当前秒
745
746        // 一次推进 10 秒:只应触发目标秒一次,不补发中间 9 秒
747        clock.advance_to_secs(t0 + 10);
748        wait_for_count(&counter, 2).await;
749        tokio::time::sleep(Duration::from_millis(100)).await;
750        assert_eq!(
751            counter.load(std::sync::atomic::Ordering::SeqCst),
752            2,
753            "大幅推进应只触发下一时刻一次,不追补跳过的秒"
754        );
755        sched.stop().await.unwrap();
756    }
757
758    /// 指定分钟触发的任务:未到点不触发,推进到点精确触发一次
759    #[tokio::test]
760    async fn test_testclock_minute_boundary_job() {
761        let t0 = ldt(2024, 6, 15, 10, 30, 0).timestamp();
762        let clock = Arc::new(TestClock::new_at_secs(t0));
763        let sched = SchedulerPlugin::with_clock(Arc::clone(&clock) as Arc<dyn Clock>);
764        let counter = Arc::new(std::sync::atomic::AtomicUsize::new(0));
765        let c = Arc::clone(&counter);
766        // 每分钟第 0 秒触发;启动时当前秒 10:30:00 恰好命中,触发一次
767        sched.register("minute-job", "0 * * * * *", "每分钟", move || {
768            let c = Arc::clone(&c);
769            tokio::spawn(async move {
770                c.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
771            })
772        });
773        sched.start().await.unwrap();
774        wait_for_count(&counter, 1).await; // 启动当前秒 10:30:00 命中
775        tokio::time::sleep(Duration::from_millis(100)).await;
776        assert_eq!(
777            counter.load(std::sync::atomic::Ordering::SeqCst),
778            1,
779            "仅启动命中一次,中间秒不应触发"
780        );
781
782        // 推进到 10:31:00 再触发;中间 59 秒不触发
783        clock.advance_to_secs(t0 + 60);
784        wait_for_count(&counter, 2).await;
785        tokio::time::sleep(Duration::from_millis(100)).await;
786        assert_eq!(
787            counter.load(std::sync::atomic::Ordering::SeqCst),
788            2,
789            "整分钟任务应精确触发一次,无重复"
790        );
791        sched.stop().await.unwrap();
792    }
793}