ntp_client/
lib.rs

1// Copyright 2026 U.S. Federal Government (in countries where recognized)
2// SPDX-License-Identifier: Apache-2.0
3
4/*!
5# Example
6Shows how to use the ntp_client library to fetch the current time according
7to the requested ntp server.
8
9```rust,no_run
10extern crate chrono;
11extern crate ntp_client;
12
13use chrono::TimeZone;
14
15fn main() {
16    let address = "time.nist.gov:123";
17    let result = ntp_client::request(address).unwrap();
18    let unix_time = ntp_client::unix_time::Instant::from(result.transmit_timestamp);
19    let local_time = chrono::Local.timestamp_opt(unix_time.secs(), unix_time.subsec_nanos() as _).unwrap();
20    println!("{}", local_time);
21    println!("Offset: {:.6} seconds", result.offset_seconds);
22}
23```
24*/
25
26#![warn(missing_docs)]
27
28// Re-export protocol types from ntp_proto for convenience.
29pub use ntp_proto::{error, extension, protocol, unix_time};
30
31/// Shared NTS logic re-exported from `ntp_proto`.
32#[cfg(any(feature = "nts", feature = "nts-smol"))]
33pub(crate) use ntp_proto::nts_common;
34
35/// TLS configuration for NTS (crypto provider selection).
36#[cfg(any(feature = "nts", feature = "nts-smol"))]
37pub(crate) mod tls_config;
38
39/// Clock sample filtering for the continuous NTP client.
40///
41/// Implements a simplified version of the RFC 5905 Section 10 clock filter
42/// algorithm.
43#[cfg(any(feature = "tokio", feature = "smol-runtime"))]
44pub mod filter;
45
46/// Peer selection, clustering, and combining algorithms per RFC 5905 Section 11.2.
47#[cfg(any(feature = "tokio", feature = "smol-runtime"))]
48pub mod selection;
49
50/// Shared types and logic for the continuous NTP client.
51#[cfg(any(feature = "tokio", feature = "smol-runtime"))]
52pub mod client_common;
53
54/// Continuous NTP client with adaptive poll interval management and interleaved mode.
55#[cfg(feature = "tokio")]
56pub mod client;
57
58/// Network Time Security (NTS) client (RFC 8915).
59///
60/// Provides authenticated NTP using TLS 1.3 key establishment and AEAD
61/// per-packet authentication.
62#[cfg(feature = "nts")]
63pub mod nts;
64
65/// System clock adjustment utilities for applying NTP corrections.
66///
67/// Provides platform-specific functions for slewing (gradual) and stepping
68/// (immediate) the system clock. Requires elevated privileges (root/admin).
69#[cfg(feature = "clock")]
70pub mod clock;
71
72/// Clock discipline algorithm (PLL/FLL) per RFC 5905 Section 11.3.
73///
74/// Converts raw offset measurements into phase and frequency corrections
75/// using a hybrid phase-locked / frequency-locked loop state machine.
76#[cfg(feature = "discipline")]
77pub mod discipline;
78
79/// Periodic clock adjustment process per RFC 5905 Section 12.
80///
81/// Drains residual phase error and applies frequency corrections on a
82/// 1-second tick cycle.
83#[cfg(feature = "discipline")]
84pub mod clock_adjust;
85
86/// Symmetric active/passive mode support per RFC 5905 Sections 8-9.
87///
88/// Enables peer-to-peer time synchronization using NTP modes 1 and 2.
89#[cfg(feature = "symmetric")]
90pub mod symmetric;
91
92/// NTP broadcast client support per RFC 5905 Section 8.
93///
94/// Parses and validates mode-5 broadcast packets and computes clock offset
95/// using a calibrated one-way delay. Deprecated by BCP 223 (RFC 8633).
96#[cfg(feature = "broadcast")]
97pub mod broadcast_client;
98
99/// Reference clock abstraction layer for hardware time sources.
100///
101/// Provides a unified interface for GPS receivers, PPS signals, and other
102/// precision time sources that can serve as Stratum 1 references.
103#[cfg(any(feature = "refclock", feature = "gps", feature = "pps"))]
104pub mod refclock;
105
106/// Simple Network Time Protocol (SNTP) client per RFC 4330.
107///
108/// SNTP is a simplified subset of NTP for clients that perform single-shot
109/// time queries without the full NTP discipline algorithms. This module provides
110/// an RFC 4330 compliant SNTP API that wraps the underlying NTP implementation.
111///
112/// See [`sntp`] module documentation for usage examples.
113pub mod sntp;
114
115/// Async NTP client functions using the Tokio runtime.
116///
117/// See [`async_ntp::request`] and [`async_ntp::request_with_timeout`] for details.
118#[cfg(feature = "tokio")]
119pub mod async_ntp;
120
121/// Async NTP client functions using the smol runtime.
122///
123/// See [`smol_ntp::request`] and [`smol_ntp::request_with_timeout`] for details.
124#[cfg(feature = "smol-runtime")]
125pub mod smol_ntp;
126
127/// Continuous NTP client using the smol runtime.
128#[cfg(feature = "smol-runtime")]
129pub mod smol_client;
130
131/// Network Time Security (NTS) client using the smol runtime (RFC 8915).
132///
133/// Provides the same NTS functionality as the `nts` module but using smol
134/// and futures-rustls instead of tokio and tokio-rustls.
135#[cfg(feature = "nts-smol")]
136pub mod smol_nts;
137
138/// Roughtime client for authenticated coarse time (draft-ietf-ntp-roughtime-15).
139///
140/// Provides sync and async (tokio) APIs for querying Roughtime servers with
141/// Ed25519 signature verification and SHA-512 Merkle tree proofs.
142#[cfg(feature = "roughtime")]
143pub mod roughtime;
144
145/// Socket options for `IPV6_V6ONLY` and DSCP/Traffic Class control.
146///
147/// When the `socket-opts` feature is enabled, uses `socket2` for cross-platform
148/// socket option control. Always compiled (zero-sized type when disabled).
149#[cfg(any(feature = "tokio", feature = "smol-runtime"))]
150mod socket_opts;
151
152// Core request types and blocking networking functions.
153mod request;
154
155pub use request::{KissOfDeathError, NtpResult, request, request_with_timeout};
ntp_client/lib.rs

ntp_client/
lib.rs
