use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Mutex;
pub(crate) const DISABLED_WARN_INTERVAL_SECS: u64 = 600;
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=)"),
}
}
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 {
Disabled { reason: &'static str },
Pending,
Registered { at_secs: u64 },
Failing {
error: String,
since_secs: u64,
at_secs: u64,
},
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum Transition {
None,
Registered,
}
pub struct HubRegistration {
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()
}
pub(crate) fn note_warned(&self, now_secs: u64) {
self.last_disabled_warn_secs
.store(now_secs, Ordering::SeqCst);
}
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 };
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,
};
}
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"));
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"));
}
}