Skip to main content

rightkit_sync/
schedule.rs

1//! Platform-neutral scheduler surface: one bounded sync pass and a suggested next delay.
2//!
3//! The host owns the clock and the process (Android WorkManager, a desktop timer, an iOS
4//! background task); this module owns what a *pass* means for scheduling. [`sync_once`] runs the
5//! engine for at most [`SyncBudget::max_passes`] passes inside [`SyncBudget::max_elapsed`], and
6//! returns a [`SyncReport`] with what happened, how the host should map it ([`WorkOutcome`]) and
7//! when to run next ([`SyncReport::next_delay_secs`]).
8//!
9//! It never sleeps and never spawns a thread: it cannot interrupt a pass already running (the
10//! backend's own HTTP timeouts bound that), so the elapsed budget is checked between passes only.
11//! Failure backoff is the engine's own, kept in the ledger (`consecutive_failures`,
12//! `retry_after_ms`), so it survives the process being killed between WorkManager runs; this module
13//! only turns the pass outcome into a delay the OS scheduler can use.
14//!
15//! The pure decision functions ([`next_delay`], [`work_outcome`], [`should_continue`]) take plain
16//! values and are unit tested without an engine.
17
18use std::time::{Duration, Instant};
19
20use crate::backoff::BackoffPolicy;
21use crate::engine::{PassOutcome, PassReport, SyncEngine};
22use crate::ledger::ConsentRequest;
23use crate::traits::RecordMapper;
24
25/// What one [`sync_once`] call may spend.
26#[derive(Debug, Clone, PartialEq)]
27pub struct SyncBudget {
28    /// Most passes in one call. `1` (the default) is one pass.
29    pub max_passes: u32,
30    /// Wall-clock allowance, checked between passes (a running pass is not interrupted).
31    pub max_elapsed: Duration,
32    /// Another pass runs only after a `Pending` pass that made progress, and only when the engine
33    /// asks to wait no longer than this. The default `0.0` never re-runs (the engine's pending
34    /// floor is 30 s), so a host that wants a drain loop raises it knowingly. This function never
35    /// sleeps: a re-run that the engine would defer is reported as `Deferred` and ends the call.
36    pub max_inline_delay_secs: f64,
37}
38
39impl Default for SyncBudget {
40    fn default() -> Self {
41        Self {
42            max_passes: 1,
43            max_elapsed: Duration::from_secs(60),
44            max_inline_delay_secs: 0.0,
45        }
46    }
47}
48
49/// Delays the scheduler suggests. `backoff` should match the engine's `SyncConfig::backoff`.
50#[derive(Debug, Clone, PartialEq)]
51pub struct SchedulePolicy {
52    pub backoff: BackoffPolicy,
53    /// Delay after a fully synced pass. Android's periodic WorkManager minimum is 15 minutes.
54    pub idle_secs: f64,
55    /// No suggested delay is shorter than this.
56    pub min_secs: f64,
57    /// Suggested delay after a pass that could not give an engine delay (cancelled).
58    pub cancelled_secs: f64,
59}
60
61impl Default for SchedulePolicy {
62    fn default() -> Self {
63        Self {
64            backoff: BackoffPolicy::default(),
65            idle_secs: 900.0,
66            min_secs: 15.0,
67            cancelled_secs: 30.0,
68        }
69    }
70}
71
72/// How the host should report the run to its scheduler.
73///
74/// WorkManager mapping: `Success` -> `Result.success()`, `Retry` -> `Result.retry()`,
75/// `Failure` -> `Result.failure()` (do not retry; the host decides how to surface it).
76#[derive(Debug, Clone, Copy, PartialEq, Eq)]
77pub enum WorkOutcome {
78    /// Nothing for the scheduler to redo before the next regular run.
79    Success,
80    /// Run again after `next_delay_secs` (pending work, a deferral, or a transient failure).
81    Retry,
82    /// Do not retry on its own: sync is off, or the app must act first (see
83    /// [`SyncReport::consent_required`]).
84    Failure,
85}
86
87/// What [`sync_once`] did, in plain data a host can pass across an FFI boundary.
88#[derive(Debug, Clone, PartialEq)]
89pub struct SyncReport {
90    /// Passes actually run (a deferred pass counts: it was attempted and did nothing).
91    pub passes: u32,
92    /// The last pass's outcome.
93    pub outcome: PassOutcome,
94    pub uploaded: usize,
95    pub downloaded: usize,
96    pub tombstones_applied: usize,
97    pub tombstones_written: usize,
98    pub quarantined: usize,
99    pub elapsed_ms: u64,
100    pub work: WorkOutcome,
101    /// Seconds until the host should run again; `None` when no run should be scheduled
102    /// (sync disabled, or waiting on the app).
103    pub next_delay_secs: Option<f64>,
104    /// Set when the signed-in account changed and the app must call
105    /// `SyncEngine::grant_consent`.
106    pub consent_required: Option<ConsentRequest>,
107}
108
109/// Runs the engine for one bounded unit of work. Never sleeps; see the module docs.
110pub fn sync_once<M: RecordMapper + 'static>(
111    engine: &mut SyncEngine<M>,
112    budget: &SyncBudget,
113    policy: &SchedulePolicy,
114) -> SyncReport {
115    let started = Instant::now();
116    let mut passes = 0u32;
117    let mut total = PassReport {
118        outcome: PassOutcome::Synced,
119        uploaded: 0,
120        downloaded: 0,
121        tombstones_applied: 0,
122        tombstones_written: 0,
123        quarantined: 0,
124        blocked_reuploads: 0,
125        retry_after_secs: None,
126    };
127    let max_passes = budget.max_passes.max(1);
128    loop {
129        let rep = engine.run_pass();
130        passes += 1;
131        total.uploaded += rep.uploaded;
132        total.downloaded += rep.downloaded;
133        total.tombstones_applied += rep.tombstones_applied;
134        total.tombstones_written += rep.tombstones_written;
135        total.quarantined += rep.quarantined;
136        total.blocked_reuploads += rep.blocked_reuploads;
137        let progress =
138            rep.uploaded + rep.downloaded + rep.tombstones_applied + rep.tombstones_written;
139        total.outcome = rep.outcome;
140        total.retry_after_secs = rep.retry_after_secs;
141        if !should_continue(
142            &total.outcome,
143            total.retry_after_secs,
144            progress,
145            passes,
146            max_passes,
147            started.elapsed(),
148            budget,
149        ) {
150            break;
151        }
152    }
153    let failures = engine.ledger().consecutive_failures;
154    let consent_required = match &total.outcome {
155        PassOutcome::ConsentRequired(req) => Some(req.clone()),
156        _ => None,
157    };
158    SyncReport {
159        passes,
160        work: work_outcome(&total.outcome),
161        next_delay_secs: next_delay(&total.outcome, total.retry_after_secs, failures, policy),
162        outcome: total.outcome,
163        uploaded: total.uploaded,
164        downloaded: total.downloaded,
165        tombstones_applied: total.tombstones_applied,
166        tombstones_written: total.tombstones_written,
167        quarantined: total.quarantined,
168        elapsed_ms: started.elapsed().as_millis() as u64,
169        consent_required,
170    }
171}
172
173/// Whether another pass should run inside the same call.
174pub fn should_continue(
175    outcome: &PassOutcome,
176    retry_after_secs: Option<f64>,
177    progress: usize,
178    passes_run: u32,
179    max_passes: u32,
180    elapsed: Duration,
181    budget: &SyncBudget,
182) -> bool {
183    if passes_run >= max_passes || elapsed >= budget.max_elapsed {
184        return false;
185    }
186    if !matches!(outcome, PassOutcome::Pending(_)) || progress == 0 {
187        return false;
188    }
189    match retry_after_secs {
190        Some(s) => s.is_finite() && s <= budget.max_inline_delay_secs,
191        None => true,
192    }
193}
194
195/// How the host reports `outcome` to its scheduler.
196pub fn work_outcome(outcome: &PassOutcome) -> WorkOutcome {
197    match outcome {
198        PassOutcome::Synced => WorkOutcome::Success,
199        PassOutcome::Pending(_)
200        | PassOutcome::Deferred { .. }
201        | PassOutcome::Unavailable(_)
202        | PassOutcome::Cancelled
203        | PassOutcome::Failed(_) => WorkOutcome::Retry,
204        PassOutcome::Disabled | PassOutcome::ConsentRequired(_) => WorkOutcome::Failure,
205    }
206}
207
208/// Seconds until the next run, never below `policy.min_secs`; `None` when nothing should be
209/// scheduled (disabled, or waiting for the app's consent answer).
210///
211/// `retry_after_secs` is the engine's own figure for the pass (its backoff, server hint and
212/// pending floor already applied); `failures` is the ledger's consecutive failure count and is
213/// used only when a failed pass carries no engine figure.
214pub fn next_delay(
215    outcome: &PassOutcome,
216    retry_after_secs: Option<f64>,
217    failures: u32,
218    policy: &SchedulePolicy,
219) -> Option<f64> {
220    let engine = retry_after_secs.filter(|s| s.is_finite() && *s > 0.0);
221    let secs = match outcome {
222        PassOutcome::Disabled | PassOutcome::ConsentRequired(_) => return None,
223        PassOutcome::Synced => policy.idle_secs,
224        PassOutcome::Pending(_) => engine.unwrap_or(policy.backoff.pending_floor_secs),
225        PassOutcome::Deferred { secs } => {
226            if secs.is_finite() && *secs > 0.0 {
227                *secs
228            } else {
229                policy.min_secs
230            }
231        }
232        PassOutcome::Cancelled => engine.unwrap_or(policy.cancelled_secs),
233        PassOutcome::Unavailable(_) | PassOutcome::Failed(_) => {
234            engine.unwrap_or_else(|| policy.backoff.delay_secs(failures.max(1), None))
235        }
236    };
237    Some(secs.max(policy.min_secs))
238}