didbot_serve/

tree_reload.rs

//! The timer that re-reads `[tree]`'s bounds from the configuration file.
//!
//! The bounds a create is judged by are the ones an operator most needs to
//! change while the server is busy: a cap that is refusing work is the worst
//! moment to take the server down. So they are held in a
//! [`didbot_pds::LiveTreeLimits`] the registry reads per create, and this is
//! the clock that replaces what it holds.
//!
//! A pass reads and parses the file whole and installs what it found only if
//! every bound is in range. Anything else — the file gone, the TOML bad, a
//! bound out of range — installs nothing and leaves the bounds that were
//! already live in place. The built-in defaults are never reinstated by a
//! failure: a configuration file that disappears must not widen or narrow
//! what the operator last asked for.

use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::Duration;

use didbot_pds::{LiveTreeLimits, TreeLimits};
use tokio::sync::Notify;
use tokio::task::JoinHandle;
use tokio::time::MissedTickBehavior;
use tracing::{info, warn};

/// How often the bounds are re-read, absent `[intervals] tree_reload_secs`.
///
/// Thirty seconds: an operator raising a cap that is refusing work waits
/// about as long as a page reload, and a pass costs one read of one local
/// file.
pub const DEFAULT_TREE_RELOAD_INTERVAL: Duration = Duration::from_secs(30);

/// Why a pass installed nothing. The live bounds keep their values.
#[derive(Debug, thiserror::Error)]
pub enum TreeReloadError {
    /// The file could not be read, or could not be parsed.
    #[error(transparent)]
    Config(#[from] didbot_config::ConfigError),
    /// A bound was written outside the range it is documented with.
    #[error(transparent)]
    Range(#[from] didbot_pds::TreeLimitError),
}

/// The `[tree]` bounds `config` asks for, each falling back to
/// [`TreeLimits`]'s own default where the key is absent.
///
/// Shared with the startup path so that a reload resolves a file exactly the
/// way the process that started against it did.
#[must_use]
pub fn tree_limits_of(config: &didbot_config::Config) -> TreeLimits {
    let defaults = TreeLimits::default();
    let section = config.tree.as_ref();
    TreeLimits {
        max_depth: section
            .and_then(|tree| tree.max_depth)
            .unwrap_or(defaults.max_depth),
        max_children: section
            .and_then(|tree| tree.max_children)
            .unwrap_or(defaults.max_children),
        creates_per_hour: section
            .and_then(|tree| tree.creates_per_hour)
            .unwrap_or(defaults.creates_per_hour),
    }
}

/// One pass: read `path`, and install its bounds into `live` if they are
/// whole and in range.
///
/// Public and separate from the timer for the reason
/// [`crate::blob_collect::collect_once`] is: a caller can run exactly one
/// pass without waiting on a clock. Answers the bounds now live on success,
/// whether or not they changed.
pub fn reload_once(path: &Path, live: &LiveTreeLimits) -> Result<TreeLimits, TreeReloadError> {
    let config = didbot_config::Config::load(path)?;
    let limits = tree_limits_of(&config);
    limits.check()?;
    let before = live.get();
    if before != limits {
        // Installed as one value, so a create judged during this swap sees
        // either every old bound or every new one.
        live.set(limits);
        info!(
            path = %path.display(),
            max_depth = limits.max_depth,
            max_children = limits.max_children,
            creates_per_hour = limits.creates_per_hour,
            "[tree] changed; every later create is judged by these bounds"
        );
    }
    Ok(limits)
}

/// A running reloader, stopped by [`TreeReloader::stop`] or by dropping it.
pub struct TreeReloader {
    handle: JoinHandle<()>,
    stop: Arc<Notify>,
}

impl TreeReloader {
    /// Starts re-reading `path` into `live` every `interval`.
    ///
    /// The first tick fires after one interval, not immediately: the bounds
    /// were resolved from this same file moments ago, at startup, so a pass
    /// at zero would only read it twice.
    pub fn spawn(path: PathBuf, live: Arc<LiveTreeLimits>, interval: Duration) -> Self {
        let stop = Arc::new(Notify::new());
        let notified = stop.clone();
        let handle = tokio::spawn(async move {
            let mut ticker = tokio::time::interval(interval);
            ticker.set_missed_tick_behavior(MissedTickBehavior::Delay);
            ticker.tick().await;
            // What the last pass complained about, so a file left broken
            // warns once rather than once per tick.
            let mut complained: Option<String> = None;
            loop {
                tokio::select! {
                    biased;
                    () = notified.notified() => break,
                    _ = ticker.tick() => {}
                }
                let file = path.clone();
                let live = live.clone();
                let outcome = tokio::task::spawn_blocking(move || reload_once(&file, &live)).await;
                match outcome {
                    Ok(Ok(_)) => complained = None,
                    Ok(Err(err)) => {
                        let said = err.to_string();
                        if complained.as_deref() != Some(said.as_str()) {
                            warn!(
                                path = %path.display(),
                                error = %said,
                                "could not re-read [tree]; the bounds already live still stand"
                            );
                            complained = Some(said);
                        }
                    }
                    Err(error) => warn!(
                        %error,
                        "the [tree] reload did not finish; the next tick tries again"
                    ),
                }
            }
        });
        Self { handle, stop }
    }

    /// Stops the reloader and waits for the task to finish.
    pub async fn stop(mut self) {
        self.stop.notify_one();
        let _ = (&mut self.handle).await;
    }
}

impl Drop for TreeReloader {
    fn drop(&mut self) {
        self.handle.abort();
    }
}