//! Background synchronisation (roadmap lot 5.9). //! //! [`MeowClient::start`] moves the client into a task that long-polls every server, //! processes what arrives, sends queued deposits when they are due and publishes every //! [`Event`] on the client's broadcast channel. The application keeps full access to //! the client through [`ClientHandle::lock`]. //! //! Network waits never hold the lock: each step is *prepared* under the lock, the //! network calls run without it, and the results are *applied* under the lock. A send //! from the UI therefore never waits for a 30 s long-poll or an unreachable server. use std::sync::Arc; use std::time::Duration; use tokio::sync::{broadcast, watch, Mutex, MutexGuard}; use tokio::task::JoinHandle; use crate::outbox::execute_flush; use crate::{execute_pull, Event, MeowClient}; /// Pace of the background task. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct BackgroundOptions { /// How long each pull may wait on the servers for new messages. It also bounds how /// late a queued deposit can be retried. pub long_poll: Duration, /// First delay after a failed round (all servers unreachable); doubled up to /// [`BackgroundOptions::max_backoff`]. pub backoff: Duration, pub max_backoff: Duration, } impl Default for BackgroundOptions { fn default() -> Self { Self { long_poll: Duration::from_secs(30), backoff: Duration::from_secs(2), max_backoff: Duration::from_secs(60), } } } /// A client running in the background. pub struct ClientHandle { client: Arc>, events: broadcast::Sender, stop: watch::Sender, task: JoinHandle<()>, } impl MeowClient { /// Start background synchronisation. Subscribe with [`ClientHandle::subscribe`]; /// use the client through [`ClientHandle::lock`]; get it back with /// [`ClientHandle::stop`]. pub fn start(self, options: BackgroundOptions) -> ClientHandle { let events = self.events.clone(); let client = Arc::new(Mutex::new(self)); let (stop, stop_rx) = watch::channel(false); let task = tokio::spawn(run(client.clone(), options, stop_rx)); ClientHandle { client, events, stop, task, } } } impl ClientHandle { /// Receive every event from now on. pub fn subscribe(&self) -> broadcast::Receiver { self.events.subscribe() } /// Exclusive access to the client (sending, contacts, history…). Keep it short: /// the background task needs the lock between its network calls. pub async fn lock(&self) -> MutexGuard<'_, MeowClient> { self.client.lock().await } /// Stop the background task (an in-flight long-poll is abandoned; its acks will /// simply be sent again) and give the client back. pub async fn stop(self) -> MeowClient { let _ = self.stop.send(true); if let Err(e) = self.task.await { tracing::error!("background task failed: {e}"); } match Arc::try_unwrap(self.client) { Ok(m) => m.into_inner(), // Unreachable: the task is finished and the handle was consumed. Err(_) => unreachable!("client still shared after the task ended"), } } } /// Wait for `d`, until the client state changes, or until asked to stop. Returns /// `true` when stopping. async fn pause(d: Duration, stop: &mut watch::Receiver, changes: &mut watch::Receiver) -> bool { tokio::select! { _ = tokio::time::sleep(d) => *stop.borrow(), _ = changes.changed() => *stop.borrow(), _ = stop.changed() => true, } } async fn run(client: Arc>, opts: BackgroundOptions, mut stop: watch::Receiver) { let mut wait = opts.long_poll; let mut backoff = opts.backoff; let mut changes = client.lock().await.changes.subscribe(); while !*stop.borrow() { // 1. Due deposits (and expiries). let (plan, transport) = { let mut c = client.lock().await; (c.prepare_flush(false), c.transport.clone()) }; if !plan.is_empty() { let accepted = tokio::select! { a = execute_flush(&transport, &plan) => a, _ = stop.changed() => break, }; let mut c = client.lock().await; if let Err(e) = c.apply_flush(plan, accepted).await { tracing::error!("cannot save the send queue: {e}"); } } { let mut c = client.lock().await; let pending = std::mem::take(&mut c.pending_events); c.emit(&pending); } // 2. Pull (long-poll), without the lock while waiting. The wait ends in time // for the next queued deposit to be retried. let plan = { let mut c = client.lock().await; // Everything up to here (including our own saves) is reflected in the plan. changes.borrow_and_update(); let w = match c.next_retry_in() { Some(d) => wait.min(d.max(Duration::from_secs(1))), None => wait, }; c.prepare_pull(w) }; if plan.is_empty() { // No contact yet: just keep the queue moving. let d = client.lock().await.next_retry_in().unwrap_or(opts.long_poll); if pause(d.clamp(Duration::from_secs(1), opts.long_poll), &mut stop, &mut changes).await { break; } continue; } let results = tokio::select! { r = execute_pull(&transport, &plan) => r, // The state changed under us (new contact, unlocked space, message to send): // restart with an up-to-date request. Abandoned acks are simply resent. _ = changes.changed() => { wait = Duration::ZERO; continue; } _ = stop.changed() => break, }; // 3. Apply and process under the lock. let mut c = client.lock().await; match c.apply_pull(plan, results) { Ok(round) => { backoff = opts.backoff; let got_new = !round.new.is_empty(); if got_new { match c.process(round.new).await { Ok(ev) => c.emit(&ev), Err(e) => tracing::error!("cannot process received messages: {e}"), } } // Something arrived (acks to send, replies to flush) or the servers // held messages back: go again at once. wait = if got_new || round.more { Duration::ZERO } else { opts.long_poll }; } Err(e) => { drop(c); tracing::warn!("background pull failed: {e}; retrying in {backoff:?}"); if pause(backoff, &mut stop, &mut changes).await { break; } backoff = (backoff * 2).min(opts.max_backoff); } } } }