use serde::{Deserialize, Serialize};
#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq)]
pub struct SampleReport {
pub offset_s: f64,
pub delay_s: f64,
pub stratum: u8,
pub root_delay_s: f64,
pub root_dispersion_s: f64,
}
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub enum ControlEndpoint {
UnixPath(String),
Loopback(u16),
}
const DERIVED_PORT_BASE: u16 = 49_200;
const DERIVED_PORT_SPAN: u16 = 300;
pub fn default_control_spec() -> String {
#[cfg(windows)]
{
"rusty_time".to_string()
}
#[cfg(not(windows))]
{
match std::env::var("XDG_RUNTIME_DIR") {
Ok(dir) if !dir.is_empty() => format!("{dir}/rusty_time.sock"),
_ => "/tmp/rusty_time.sock".to_string(),
}
}
}
pub fn control_endpoint(spec: &str) -> ControlEndpoint {
if let Some((_, port)) = spec.rsplit_once(':')
&& let Ok(port) = port.parse::<u16>()
{
return ControlEndpoint::Loopback(port);
}
if cfg!(windows) {
ControlEndpoint::Loopback(derive_port(spec))
} else {
ControlEndpoint::UnixPath(spec.to_string())
}
}
fn derive_port(spec: &str) -> u16 {
let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
for byte in spec.as_bytes() {
hash ^= *byte as u64;
hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
}
DERIVED_PORT_BASE + (hash % DERIVED_PORT_SPAN as u64) as u16
}
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
pub struct NtsReport {
pub ke_host: String,
pub ntp_server: String,
pub ntp_port: u16,
pub authenticated: u32,
pub rejected: u32,
pub cookies_after: usize,
}
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
pub struct QueryReport {
pub server: String,
pub address: String,
pub sent: u32,
pub received: u32,
pub samples: Vec<SampleReport>,
pub best_offset_s: Option<f64>,
pub best_delay_s: Option<f64>,
pub regress_offset_s: Option<f64>,
pub regress_freq_ppm: Option<f64>,
pub regress_sd_s: Option<f64>,
pub reference_id: String,
pub leap: String,
#[serde(skip_serializing_if = "Option::is_none", default)]
pub nts: Option<NtsReport>,
}
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
pub struct TrackingReport {
pub synchronized: bool,
pub offset_s: f64,
pub freq_ppm: f64,
pub error_bound_s: f64,
pub poll_log2: i8,
}
#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct ServerStatsReport {
pub ntp_requests: u64,
pub ntp_responses: u64,
pub dropped_rate_limit: u64,
pub kiss_of_death: u64,
pub interleaved_responses: u64,
pub refused: u64,
pub clients_tracked: usize,
pub clients_evicted: u64,
pub uptime_s: u64,
pub stratum: u8,
}
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
pub struct ClientRow {
pub address: String,
pub last_seen_ago_s: f64,
pub requests: u64,
pub responses: u64,
pub dropped: u64,
pub interleaved: bool,
}
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
#[serde(tag = "op", rename_all = "snake_case")]
pub enum ControlRequest {
ServerStats,
Clients { limit: usize },
NtsData,
Tracking,
Ping,
}
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
#[serde(tag = "result", rename_all = "snake_case")]
pub enum ControlResponse {
ServerStats(ServerStatsReport),
Clients {
rows: Vec<ClientRow>,
},
NtsData {
master_key_ids: Vec<u32>,
},
Tracking(TrackingReport),
Pong {
version: String,
},
Error {
message: String,
},
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn query_report_json_shape_is_stable() {
let r = QueryReport {
server: "pool.ntp.org".into(),
address: "1.2.3.4:123".into(),
sent: 4,
received: 4,
samples: vec![SampleReport {
offset_s: 0.0012,
delay_s: 0.031,
stratum: 2,
root_delay_s: 0.01,
root_dispersion_s: 0.002,
}],
best_offset_s: Some(0.0012),
best_delay_s: Some(0.031),
regress_offset_s: None,
regress_freq_ppm: None,
regress_sd_s: None,
reference_id: "c0a80101".into(),
leap: "no-warning".into(),
nts: None,
};
let json = serde_json::to_string(&r).expect("serialize");
let back: QueryReport = serde_json::from_str(&json).expect("deserialize");
assert_eq!(r, back);
assert!(json.contains("\"best_offset_s\""));
assert!(!json.contains("\"nts\""));
}
#[test]
fn the_default_spec_resolves_the_same_way_for_everyone() {
let a = control_endpoint(&default_control_spec());
let b = control_endpoint(&default_control_spec());
assert_eq!(a, b);
}
#[test]
fn an_explicit_port_is_honoured_on_every_platform() {
assert_eq!(
control_endpoint("127.0.0.1:9999"),
ControlEndpoint::Loopback(9999)
);
}
#[test]
fn the_same_path_resolves_identically_in_both_processes() {
let a = control_endpoint("/run/rusty_time.sock");
let b = control_endpoint("/run/rusty_time.sock");
assert_eq!(a, b, "resolution must be deterministic");
}
#[test]
fn different_names_get_different_endpoints() {
let mut seen = std::collections::HashSet::new();
let names = [
"/run/rusty_time.sock",
"/tmp/a.sock",
"/tmp/b.sock",
"rusty_time",
"test-rig-1",
"test-rig-2",
];
for name in names {
seen.insert(control_endpoint(name));
}
assert!(
seen.len() >= names.len() - 1,
"control names collided: {seen:?}"
);
}
#[test]
fn derived_ports_stay_in_the_intended_range() {
for name in ["a", "b", "/very/long/path/to/a/socket", ""] {
let port = derive_port(name);
assert!(
(DERIVED_PORT_BASE..DERIVED_PORT_BASE + DERIVED_PORT_SPAN).contains(&port),
"{name} derived out-of-range port {port}"
);
}
}
#[cfg(unix)]
#[test]
fn a_path_stays_a_unix_socket_on_unix() {
assert_eq!(
control_endpoint("/run/rusty_time.sock"),
ControlEndpoint::UnixPath("/run/rusty_time.sock".into())
);
}
#[test]
fn control_ops_round_trip_over_the_wire() {
let requests = vec![
ControlRequest::Ping,
ControlRequest::ServerStats,
ControlRequest::Clients { limit: 10 },
ControlRequest::NtsData,
];
for req in requests {
let json = serde_json::to_string(&req).expect("serialize");
let back: ControlRequest = serde_json::from_str(&json).expect("deserialize");
assert_eq!(req, back, "op did not survive the wire: {json}");
}
let responses = vec![
ControlResponse::Pong {
version: "0.1.0".into(),
},
ControlResponse::ServerStats(ServerStatsReport {
ntp_requests: 10,
ntp_responses: 8,
dropped_rate_limit: 2,
..ServerStatsReport::default()
}),
ControlResponse::Clients {
rows: vec![ClientRow {
address: "192.0.2.1:123".into(),
last_seen_ago_s: 1.5,
requests: 3,
responses: 3,
dropped: 0,
interleaved: true,
}],
},
ControlResponse::NtsData {
master_key_ids: vec![1, 2],
},
ControlResponse::Error {
message: "nope".into(),
},
];
for resp in responses {
let json = serde_json::to_string(&resp).expect("serialize");
let back: ControlResponse = serde_json::from_str(&json).expect("deserialize");
assert_eq!(resp, back);
}
}
#[test]
fn nts_data_never_carries_key_material() {
let resp = ControlResponse::NtsData {
master_key_ids: vec![0xDEAD_BEEF],
};
let json = serde_json::to_string(&resp).expect("serialize");
assert!(json.contains("master_key_ids"));
assert!(!json.contains("key\":\"") && !json.to_lowercase().contains("secret"));
}
#[test]
fn nts_report_round_trips() {
let mut r = QueryReport {
server: "time.cloudflare.com".into(),
address: "1.1.1.1:123".into(),
sent: 4,
received: 4,
samples: Vec::new(),
best_offset_s: Some(-0.002),
best_delay_s: Some(0.02),
regress_offset_s: None,
regress_freq_ppm: None,
regress_sd_s: None,
reference_id: "0a0a0a0a".into(),
leap: "no-warning".into(),
nts: Some(NtsReport {
ke_host: "time.cloudflare.com".into(),
ntp_server: "time.cloudflare.com".into(),
ntp_port: 123,
authenticated: 4,
rejected: 0,
cookies_after: 8,
}),
};
let json = serde_json::to_string(&r).expect("serialize");
assert!(json.contains("\"authenticated\":4"));
let back: QueryReport = serde_json::from_str(&json).expect("deserialize");
assert_eq!(r, back);
r.nts = None;
assert_ne!(r, back);
}
}