ntp-timer 0.2.0

A lightweight NTP time synchronization library for Rust applications. Provides in-process cached global time with background sync and clock-jump detection.
Documentation
use crate::config::Config;
use crate::error::TimerError;
use std::net::UdpSocket;
use std::time::Duration;
use tracing::{debug, warn};

/// 计算指数退避延迟时间(秒)
/// 第 n 次重试的延迟 = 2^(n-1) 秒
fn calculate_retry_delay(attempt: usize, initial_interval: u64) -> u64 {
    if attempt == 0 {
        0
    } else {
        initial_interval * 2_u64.saturating_pow((attempt - 1) as u32)
    }
}

/// 尝试从单个 NTP 服务器获取时间,带指数退避重试
fn fetch_ntp_time_with_retry(
    server: &str,
    max_retries: usize,
    socket_timeout_secs: u64,
    initial_retry_interval_secs: u64,
) -> Result<i64, TimerError> {
    for attempt in 0..max_retries {
        match fetch_ntp_time(server, socket_timeout_secs) {
            Ok(timestamp) => {
                debug!(server = %server, attempt = attempt + 1, "成功从 NTP 服务器获取时间戳");
                return Ok(timestamp);
            }
            Err(e) => {
                if attempt < max_retries - 1 {
                    let delay = calculate_retry_delay(attempt + 1, initial_retry_interval_secs);
                    warn!(
                        server = %server,
                        attempt = attempt + 1,
                        max_retries = max_retries,
                        retry_delay_secs = delay,
                        error = %e,
                        "NTP 请求失败,准备重试"
                    );
                    std::thread::sleep(Duration::from_secs(delay));
                } else {
                    warn!(
                        server = %server,
                        attempt = attempt + 1,
                        error = %e,
                        "NTP 服务器所有重试均失败"
                    );
                }
            }
        }
    }

    Err(TimerError::NtpError(format!(
        "NTP 服务器 {} 所有重试次数已耗尽",
        server
    )))
}

/// 从 NTP 服务器获取秒级时间戳(死循环模式:持续重试直到成功)
pub fn get_ntp_timestamp(config: &Config) -> Result<i64, TimerError> {
    debug!("开始从 NTP 服务器获取时间戳(死循环重试模式)");

    loop {
        for (idx, server) in config.ntp_servers.iter().enumerate() {
            debug!(server = %server, index = idx, "尝试连接 NTP 服务器");

            match fetch_ntp_time_with_retry(
                server,
                config.max_retries,
                config.socket_timeout_secs,
                config.initial_retry_interval_secs,
            ) {
                Ok(timestamp) => {
                    debug!(server = %server, timestamp = timestamp, "成功获取 NTP 时间戳");
                    return Ok(timestamp);
                }
                Err(_) => {
                    debug!(server = %server, "该 NTP 服务器获取失败,继续尝试下一个");
                }
            }
        }

        warn!("一轮重试所有 NTP 服务器均失败,继续下一轮循环");
    }
}

fn fetch_ntp_time(server: &str, timeout_secs: u64) -> Result<i64, TimerError> {
    let server_addr = format!("{}:123", server);
    let socket = UdpSocket::bind("0.0.0.0:0")
        .map_err(|e| TimerError::SocketError(format!("创建套接字失败: {}", e)))?;

    let timeout = Duration::from_secs(timeout_secs);
    socket
        .set_read_timeout(Some(timeout))
        .map_err(|e| TimerError::SocketError(format!("设置读超时失败: {}", e)))?;
    socket
        .set_write_timeout(Some(timeout))
        .map_err(|e| TimerError::SocketError(format!("设置写超时失败: {}", e)))?;

    let mut ntp_request = [0u8; 48];
    ntp_request[0] = 0x1b;

    socket
        .send_to(&ntp_request, &server_addr)
        .map_err(|e| TimerError::SocketError(format!("发送 NTP 请求失败: {}", e)))?;

    let mut ntp_response = [0u8; 48];
    socket
        .recv(&mut ntp_response)
        .map_err(|e| TimerError::SocketError(format!("接收 NTP 响应失败: {}", e)))?;

    let seconds = u32::from_be_bytes([
        ntp_response[40],
        ntp_response[41],
        ntp_response[42],
        ntp_response[43],
    ]);

    const NTP_UNIX_EPOCH_DELTA: u32 = 2208988800;
    if seconds < NTP_UNIX_EPOCH_DELTA {
        return Err(TimerError::NtpError("NTP 时间戳异常".to_string()));
    }

    let unix_timestamp = (seconds - NTP_UNIX_EPOCH_DELTA) as i64;
    debug!(server = %server, ntp_secs = seconds, unix_timestamp = unix_timestamp, "从 NTP 服务器获取时间戳成功");

    Ok(unix_timestamp)
}

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

    #[test]
    fn test_ntp_config() {
        let config = Config::default();
        assert!(!config.ntp_servers.is_empty());
        assert_eq!(config.socket_timeout_secs, 5);
    }

    #[test]
    fn test_calculate_retry_delay() {
        // 第0次(首次尝试):无延迟
        assert_eq!(calculate_retry_delay(0, 1), 0);
        
        // 第1次重试后延迟:2^0 = 1秒
        assert_eq!(calculate_retry_delay(1, 1), 1);
        
        // 第2次重试后延迟:2^1 = 2秒
        assert_eq!(calculate_retry_delay(2, 1), 2);
        
        // 第3次重试后延迟:2^2 = 4秒
        assert_eq!(calculate_retry_delay(3, 1), 4);
        
        // 第4次重试后延迟:2^3 = 8秒
        assert_eq!(calculate_retry_delay(4, 1), 8);
        
        // 第5次重试后延迟:2^4 = 16秒
        assert_eq!(calculate_retry_delay(5, 1), 16);
    }

    #[test]
    fn test_calculate_retry_delay_with_custom_interval() {
        // 使用初始间隔2秒
        assert_eq!(calculate_retry_delay(0, 2), 0);
        assert_eq!(calculate_retry_delay(1, 2), 2);
        assert_eq!(calculate_retry_delay(2, 2), 4);
        assert_eq!(calculate_retry_delay(3, 2), 8);
        
        // 使用初始间隔5秒
        assert_eq!(calculate_retry_delay(0, 5), 0);
        assert_eq!(calculate_retry_delay(1, 5), 5);
        assert_eq!(calculate_retry_delay(2, 5), 10);
        assert_eq!(calculate_retry_delay(3, 5), 20);
    }
}