zc2 0.0.48

P2P compute broker with yen-denominated billing, WAL, and broker mesh support
//! Whether this broker is registered with its hub — and, above all, why not.
//!
//! A broker only appears on the hub's mesh (`/clusters`, the roster, other
//! brokers' peer lists) after its node-sync loop has called
//! `POST /api/broker/node/register`. That loop runs only when the broker has
//! BOTH a hub URL and an API key. Without either it used to skip silently: the
//! broker served `/health` as "healthy", answered on its port, and was simply
//! absent from the mesh with no log line anywhere saying so. An operator could
//! (and did) spend an afternoon looking for a network fault.
//!
//! This module makes that state impossible to miss:
//! - [`disabled_reason`] decides, once, at startup, whether registration can
//!   run at all, and `start_server` prints [`warning_text`] loudly when not;
//! - the node-sync tick repeats the warning at most every
//!   [`DISABLED_WARN_INTERVAL_SECS`] (so a log tail started later still sees it)
//!   and records every register outcome here;
//! - `/health` serves [`HubRegistration::health_json`] as `hub_registration`,
//!   the machine-readable answer to "is this node on the mesh?".
//!
//! Standalone brokers (no hub, self-exec only) remain a supported mode: this
//! never refuses to start, it only refuses to be quiet about it.

use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Mutex;

/// How often the "not registering" warning is repeated while it persists.
pub(crate) const DISABLED_WARN_INTERVAL_SECS: u64 = 600;

/// Why registration cannot run with this configuration, or `None` when it can.
/// Blank values count as unset: an empty `ZAKURO_API_KEY=` is still no key.
pub fn disabled_reason(api_url: Option<&str>, api_key: Option<&str>) -> Option<&'static str> {
    let set = |v: Option<&str>| v.map(|s| !s.trim().is_empty()).unwrap_or(false);
    match (set(api_url), set(api_key)) {
        (true, true) => None,
        (false, false) => Some("no hub URL and no API key"),
        (false, true) => Some("no hub URL (ZAKURO_API_URL / api_url=)"),
        (true, false) => Some("no API key (ZAKURO_API_KEY / api_key=)"),
    }
}

/// The operator-facing warning for a broker that will not register.
pub(crate) fn warning_text(reason: &str) -> String {
    format!(
        "  [NODE_SYNC] WARNING: this broker is NOT registering with any hub ({reason}).\n\
         \x20             It will NOT appear on the mesh (hub /clusters, roster, peers' `zc brokers`).\n\
         \x20             Fix: run `zc login` as the user that runs the broker (staging: `zc login --staging`),\n\
         \x20             or set ZAKURO_API_URL and ZAKURO_API_KEY, then restart the broker.\n\
         \x20             Check: `curl -s localhost:<port>/health` → hub_registration.state"
    )
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum RegState {
    /// Registration cannot run with this configuration.
    Disabled { reason: &'static str },
    /// Configured; the first node-sync round has not completed yet.
    Pending,
    /// The last register call succeeded.
    Registered { at_secs: u64 },
    /// The last register call failed; `since_secs` is when the failure run began.
    Failing {
        error: String,
        since_secs: u64,
        at_secs: u64,
    },
}

/// A transition worth one log line (the per-round error line already exists).
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum Transition {
    None,
    /// First success, or success after failures.
    Registered,
}

pub struct HubRegistration {
    /// The hub this broker registers with, for display (never a secret).
    hub_url: Option<String>,
    state: Mutex<RegState>,
    last_disabled_warn_secs: AtomicU64,
}

impl HubRegistration {
    pub(crate) fn new(api_url: Option<&str>, api_key: Option<&str>) -> Self {
        let state = match disabled_reason(api_url, api_key) {
            Some(reason) => RegState::Disabled { reason },
            None => RegState::Pending,
        };
        Self {
            hub_url: api_url
                .map(|u| u.trim_end_matches('/').to_string())
                .filter(|u| !u.is_empty()),
            state: Mutex::new(state),
            last_disabled_warn_secs: AtomicU64::new(0),
        }
    }

    pub(crate) fn state(&self) -> RegState {
        self.state
            .lock()
            .map(|s| s.clone())
            .unwrap_or(RegState::Pending)
    }

    pub(crate) fn hub_url(&self) -> Option<&str> {
        self.hub_url.as_deref()
    }

    /// Mark the startup warning as printed at `now_secs`, so the periodic
    /// repeat waits a full interval after it.
    pub(crate) fn note_warned(&self, now_secs: u64) {
        self.last_disabled_warn_secs
            .store(now_secs, Ordering::SeqCst);
    }

    /// The disabled reason, when it is time to repeat the warning.
    pub(crate) fn due_disabled_warning(&self, now_secs: u64) -> Option<&'static str> {
        let RegState::Disabled { reason } = self.state() else {
            return None;
        };
        let last = self.last_disabled_warn_secs.load(Ordering::SeqCst);
        if now_secs.saturating_sub(last) >= DISABLED_WARN_INTERVAL_SECS {
            self.last_disabled_warn_secs
                .store(now_secs, Ordering::SeqCst);
            Some(reason)
        } else {
            None
        }
    }

    pub(crate) fn record_ok(&self, now_secs: u64) -> Transition {
        let Ok(mut s) = self.state.lock() else {
            return Transition::None;
        };
        if matches!(*s, RegState::Disabled { .. }) {
            return Transition::None;
        }
        let was_ok = matches!(*s, RegState::Registered { .. });
        *s = RegState::Registered { at_secs: now_secs };
        if was_ok {
            Transition::None
        } else {
            Transition::Registered
        }
    }

    pub(crate) fn record_err(&self, error: &str, now_secs: u64) {
        let Ok(mut s) = self.state.lock() else { return };
        // A blank-but-present key/URL still reaches the register call; its
        // failure must not hide the configuration reason behind an HTTP error.
        if matches!(*s, RegState::Disabled { .. }) {
            return;
        }
        let since_secs = match &*s {
            RegState::Failing { since_secs, .. } => *since_secs,
            _ => now_secs,
        };
        *s = RegState::Failing {
            error: error.to_string(),
            since_secs,
            at_secs: now_secs,
        };
    }

    /// `/health`'s `hub_registration` object. `registered` is the one-bit
    /// answer; `state` and `reason`/`error` say what to do about it.
    pub(crate) fn health_json(&self) -> serde_json::Value {
        let hub = self.hub_url.clone();
        match self.state() {
            RegState::Disabled { reason } => serde_json::json!({
                "registered": false, "state": "disabled", "hub": hub, "reason": reason,
            }),
            RegState::Pending => serde_json::json!({
                "registered": false, "state": "pending", "hub": hub,
            }),
            RegState::Registered { at_secs } => serde_json::json!({
                "registered": true, "state": "registered", "hub": hub, "last_ok_secs": at_secs,
            }),
            RegState::Failing {
                error,
                since_secs,
                at_secs,
            } => serde_json::json!({
                "registered": false, "state": "failing", "hub": hub, "error": error,
                "failing_since_secs": since_secs, "last_attempt_secs": at_secs,
            }),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn disabled_reason_covers_every_missing_combination() {
        assert_eq!(disabled_reason(Some("https://h"), Some("zk_1_a")), None);
        assert!(disabled_reason(None, None)
            .unwrap()
            .contains("no hub URL and no API key"));
        assert!(disabled_reason(None, Some("zk_1_a"))
            .unwrap()
            .contains("no hub URL"));
        assert!(disabled_reason(Some("https://h"), None)
            .unwrap()
            .contains("no API key"));
    }

    #[test]
    fn blank_values_count_as_unset() {
        assert!(disabled_reason(Some("  "), Some("zk_1_a")).is_some());
        assert!(disabled_reason(Some("https://h"), Some("")).is_some());
    }

    #[test]
    fn health_says_disabled_with_reason_when_unconfigured() {
        let r = HubRegistration::new(None, Some("zk_1_a"));
        let j = r.health_json();
        assert_eq!(j["registered"], false);
        assert_eq!(j["state"], "disabled");
        assert!(j["reason"].as_str().unwrap().contains("no hub URL"));
        // A blank key still reaches the register call; neither outcome may
        // replace the configuration reason.
        r.record_err("HTTP 401", 5);
        assert_eq!(r.record_ok(6), Transition::None);
        assert_eq!(r.health_json()["state"], "disabled");
        assert!(r.due_disabled_warning(1_000).is_some());
    }

    #[test]
    fn configured_broker_goes_pending_registered_failing_registered() {
        let r = HubRegistration::new(Some("https://stg.hub.zakuro-ai.com/"), Some("zk_1_a"));
        assert_eq!(r.health_json()["state"], "pending");
        assert_eq!(r.hub_url(), Some("https://stg.hub.zakuro-ai.com"));
        assert_eq!(r.record_ok(10), Transition::Registered);
        assert_eq!(r.record_ok(70), Transition::None);
        assert_eq!(r.health_json()["registered"], true);
        r.record_err("HTTP 401", 130);
        r.record_err("HTTP 401", 190);
        let j = r.health_json();
        assert_eq!(j["state"], "failing");
        assert_eq!(j["failing_since_secs"], 130);
        assert_eq!(j["last_attempt_secs"], 190);
        assert_eq!(r.record_ok(250), Transition::Registered);
    }

    #[test]
    fn disabled_warning_is_rate_limited_and_never_fires_when_configured() {
        let r = HubRegistration::new(None, None);
        r.note_warned(100);
        assert_eq!(
            r.due_disabled_warning(100 + DISABLED_WARN_INTERVAL_SECS - 1),
            None
        );
        assert!(r
            .due_disabled_warning(100 + DISABLED_WARN_INTERVAL_SECS)
            .is_some());
        assert_eq!(
            r.due_disabled_warning(100 + DISABLED_WARN_INTERVAL_SECS + 1),
            None
        );

        let ok = HubRegistration::new(Some("https://h"), Some("zk_1_a"));
        assert_eq!(ok.due_disabled_warning(1_000_000), None);
    }

    #[test]
    fn warning_text_names_the_fix() {
        let t = warning_text("no API key");
        assert!(t.contains("NOT registering"));
        assert!(t.contains("zc login"));
        assert!(t.contains("hub_registration"));
    }
}