Skip to main content

next_rust_server/
jobs.rs

1//! Background and scheduled jobs.
2//!
3//! Jobs are independent from the web server: run a [`Scheduler`] inside the
4//! server process, or in a separate binary for horizontally scaled
5//! deployments (so jobs do not run once per replica).
6
7use std::future::Future;
8use std::sync::Arc;
9use std::time::Duration;
10
11use tokio::sync::{Semaphore, mpsc};
12use tokio::task::JoinHandle;
13
14use crate::middleware::BoxFuture;
15
16type JobFn = Arc<dyn Fn() -> BoxFuture<()> + Send + Sync>;
17
18enum Schedule {
19    Every(Duration),
20    DailyAt { hour: u32, minute: u32 },
21}
22
23/// Periodic job scheduler.
24#[derive(Default)]
25pub struct Scheduler {
26    jobs: Vec<(String, Schedule, JobFn)>,
27}
28
29impl Scheduler {
30    pub fn new() -> Self {
31        Self::default()
32    }
33
34    /// Run `job` every `interval` (the first run happens after one interval).
35    pub fn every<F, Fut>(mut self, name: &str, interval: Duration, job: F) -> Self
36    where
37        F: Fn() -> Fut + Send + Sync + 'static,
38        Fut: Future<Output = ()> + Send + 'static,
39    {
40        self.jobs.push((name.to_owned(), Schedule::Every(interval), Arc::new(move || Box::pin(job()))));
41        self
42    }
43
44    /// Run `job` once a day at `hour:minute` UTC.
45    pub fn daily_at<F, Fut>(mut self, name: &str, hour: u32, minute: u32, job: F) -> Self
46    where
47        F: Fn() -> Fut + Send + Sync + 'static,
48        Fut: Future<Output = ()> + Send + 'static,
49    {
50        self.jobs.push((
51            name.to_owned(),
52            Schedule::DailyAt { hour: hour % 24, minute: minute % 60 },
53            Arc::new(move || Box::pin(job())),
54        ));
55        self
56    }
57
58    /// Spawn all jobs on the current Tokio runtime. A job never overlaps with
59    /// itself; panics are contained and logged.
60    pub fn start(self) -> Vec<JoinHandle<()>> {
61        self.jobs
62            .into_iter()
63            .map(|(name, schedule, job)| {
64                tokio::spawn(async move {
65                    loop {
66                        tokio::time::sleep(next_delay(&schedule)).await;
67                        let run = tokio::spawn((job)());
68                        if let Err(e) = run.await {
69                            crate::log::error(&format!("job `{name}` panicked: {e}"));
70                        }
71                    }
72                })
73            })
74            .collect()
75    }
76}
77
78fn next_delay(schedule: &Schedule) -> Duration {
79    match schedule {
80        Schedule::Every(d) => *d,
81        Schedule::DailyAt { hour, minute } => {
82            let now = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap_or_default().as_secs();
83            let target = u64::from(*hour) * 3600 + u64::from(*minute) * 60;
84            let today = now % 86_400;
85            Duration::from_secs(if target > today { target - today } else { 86_400 - today + target })
86        }
87    }
88}
89
90/// A simple in-process work queue with bounded concurrency.
91#[derive(Clone)]
92pub struct Queue<T: Send + 'static> {
93    tx: mpsc::UnboundedSender<T>,
94}
95
96impl<T: Send + 'static> Queue<T> {
97    /// Start a queue whose items are processed by `worker`, at most
98    /// `concurrency` at a time.
99    pub fn start<F, Fut>(concurrency: usize, worker: F) -> Self
100    where
101        F: Fn(T) -> Fut + Send + Sync + 'static,
102        Fut: Future<Output = ()> + Send + 'static,
103    {
104        let (tx, mut rx) = mpsc::unbounded_channel::<T>();
105        let worker = Arc::new(worker);
106        let permits = Arc::new(Semaphore::new(concurrency.max(1)));
107        tokio::spawn(async move {
108            while let Some(item) = rx.recv().await {
109                let Ok(permit) = permits.clone().acquire_owned().await else { break };
110                let worker = worker.clone();
111                tokio::spawn(async move {
112                    worker(item).await;
113                    drop(permit);
114                });
115            }
116        });
117        Queue { tx }
118    }
119
120    /// Enqueue an item. Returns `false` if the queue has shut down.
121    pub fn push(&self, item: T) -> bool {
122        self.tx.send(item).is_ok()
123    }
124}
125
126#[cfg(test)]
127mod tests {
128    use super::*;
129    use std::sync::atomic::{AtomicUsize, Ordering};
130
131    #[tokio::test]
132    async fn queue_processes_items() {
133        let count = Arc::new(AtomicUsize::new(0));
134        let c = count.clone();
135        let q = Queue::start(2, move |n: usize| {
136            let c = c.clone();
137            async move {
138                c.fetch_add(n, Ordering::SeqCst);
139            }
140        });
141        for i in 1..=4 {
142            assert!(q.push(i));
143        }
144        for _ in 0..50 {
145            if count.load(Ordering::SeqCst) == 10 {
146                break;
147            }
148            tokio::time::sleep(Duration::from_millis(5)).await;
149        }
150        assert_eq!(count.load(Ordering::SeqCst), 10);
151    }
152
153    #[tokio::test]
154    async fn scheduler_runs_jobs() {
155        let count = Arc::new(AtomicUsize::new(0));
156        let c = count.clone();
157        let handles = Scheduler::new()
158            .every("tick", Duration::from_millis(5), move || {
159                let c = c.clone();
160                async move {
161                    c.fetch_add(1, Ordering::SeqCst);
162                }
163            })
164            .start();
165        // Generous margin: Windows timers have ~15 ms resolution.
166        tokio::time::sleep(Duration::from_millis(250)).await;
167        for h in handles {
168            h.abort();
169        }
170        assert!(count.load(Ordering::SeqCst) >= 2);
171    }
172}