chrony_confile/ast/

mod.rs

//! Chrony configuration AST types.
//!
//! This module defines the core data structures representing chrony configuration files:
//! [`ChronyConfig`], [`ConfigNode`], [`Directive`], [`DirectiveKind`] (all 96 variants),
//! and [`DirectiveCategory`].
//!
//! The sub-modules group configuration types by functional area:
//! - [`source`] -- NTP source configuration (`server`, `pool`, `peer`, `refclock`, etc.)
//! - [`selection`] -- Source selection tuning (`minsources`, `maxdistance`, etc.)
//! - [`clock`] -- System clock configuration (`driftfile`, `makestep`, etc.)
//! - [`log`] -- Logging configuration (`log`, `logdir`, etc.)
//! - [`rtc`] -- RTC configuration (`rtcfile`, `rtcdevice`, etc.)
//! - [`ntp`] -- NTP server configuration (`port`, `bindaddress`, etc.)
//! - [`cmd`] -- Command access configuration (`cmdport`, `cmdallow`, etc.)
//! - [`hw`] -- Hardware timestamping configuration (`hwtimestamp`, etc.)
//! - [`nts`] -- NTS configuration (`ntsaeads`)
//! - [`misc`] -- Miscellaneous directives (`include`, `confdir`, `user`, etc.)
//! - [`source_file`] -- `.sources` file parsing types

pub mod source;
pub mod selection;
pub mod clock;
pub mod log;
pub mod rtc;
pub mod ntp;
pub mod cmd;
pub mod hw;
pub mod nts;
pub mod misc;
pub mod source_file;

pub use source::*;
pub use selection::*;
pub use clock::*;
pub use log::*;
pub use rtc::*;
pub use ntp::*;
pub use cmd::*;
pub use hw::*;
pub use nts::*;
pub use misc::*;
pub use source_file::*;

use crate::span::Span;

/// Every chrony directive as a single enum variant.
#[derive(Debug, Clone, PartialEq)]
pub enum DirectiveKind {
    // Source
    Server(ServerConfig),
    Pool(PoolConfig),
    Peer(PeerConfig),
    InitStepSlew(InitStepSlewConfig),
    RefClock(RefClockConfig),
    Manual,
    AcquisitionPort(AcquisitionPortConfig),
    BindAcqAddress(BindAddressConfig),
    BindAcqDevice(BindDeviceConfig),
    Dscp(DscpConfig),
    DumpDir(DumpDirConfig),
    MaxSamples(MaxSamplesConfig),
    MinSamples(MinSamplesConfig),
    NtsDumpDir(NtsDumpDirConfig),
    NtsRefresh(NtsRefreshConfig),
    NtsTrustedCerts(NtsTrustedCertsConfig),
    NoSystemCert,
    NoCertTimeCheck(NoCertTimeCheckConfig),
    Refresh(RefreshConfig),

    // Selection
    AuthSelectMode(AuthSelectMode),
    CombineLimit(CombineLimitConfig),
    MaxDistance(MaxDistanceConfig),
    MaxJitter(MaxJitterConfig),
    MinSources(MinSourcesConfig),
    ReselectDist(ReselectDistConfig),
    StratumWeight(StratumWeightConfig),

    // System clock
    ClockPrecision(ClockPrecisionConfig),
    CorrTimeRatio(CorrTimeRatioConfig),
    DriftFile(DriftFileConfig),
    FallbackDrift(FallbackDriftConfig),
    LeapSecMode(LeapSecMode),
    LeapSecTz(LeapSecTzConfig),
    LeapSecList(LeapSecListConfig),
    MakeStep(MakeStepConfig),
    MaxChange(MaxChangeConfig),
    MaxClockError(MaxClockErrorConfig),
    MaxDrift(MaxDriftConfig),
    MaxUpdateSkew(MaxUpdateSkewConfig),
    MaxSlewRate(MaxSlewRateConfig),
    TempComp(TempCompConfig),

    // NTP server
    Allow(AllowDenyConfig),
    Deny(AllowDenyConfig),
    BindAddress(BindAddressConfig),
    BindDevice(BindDeviceConfig),
    Broadcast(BroadcastConfig),
    ClientLogLimit(ClientLogLimitConfig),
    NoClientLog,
    Local(LocalConfig),
    NtpSignDSocket(NtpSignDSocketConfig),
    NtsPort(NtsPortConfig),
    NtsServerCert(NtsServerCertConfig),
    NtsServerKey(NtsServerKeyConfig),
    NtsProcesses(NtsProcessesConfig),
    MaxNtsConnections(MaxNtsConnectionsConfig),
    NtsNtpServer(NtsNtpServerConfig),
    NtsRotate(NtsRotateConfig),
    Port(PortConfig),
    RateLimit(RateLimitConfig),
    NtsRateLimit(NtsRateLimitConfig),
    SmoothTime(SmoothTimeConfig),

    // Command access
    BindCmdAddress(BindCmdAddressConfig),
    BindCmdDevice(BindCmdDeviceConfig),
    CmdAllow(AllowDenyConfig),
    CmdDeny(AllowDenyConfig),
    CmdPort(CmdPortConfig),
    CmdRateLimit(CmdRateLimitConfig),
    OpenCommands(OpenCommandsConfig),

    // RTC
    HwClockFile(HwClockFileConfig),
    RtcAutoTrim(RtcAutoTrimConfig),
    RtcDevice(RtcDeviceConfig),
    RtcFile(RtcFileConfig),
    RtcOnUtc,
    RtcSync,

    // Log
    Log(LogConfig),
    LogBanner(LogBannerConfig),
    LogChange(LogChangeConfig),
    LogDir(LogDirConfig),

    // Hardware timestamping
    HwTimestamp(HwTimestampConfig),
    HwTsTimeout(HwTsTimeoutConfig),
    MaxTxBuffers(MaxTxBuffersConfig),
    PtpPort(PtpPortConfig),
    PtpDomain(PtpDomainConfig),

    // NTS
    NtsAeads(NtsAeadsConfig),

    // Miscellaneous
    ConfDir(ConfDirConfig),
    Include(IncludeConfig),
    SourceDir(SourceDirConfig),
    LockAll,
    MailOnChange(MailOnChangeConfig),
    PidFile(PidFileConfig),
    SchedPriority(SchedPriorityConfig),
    User(UserConfig),
    KeyFile(KeyFileConfig),
    DumpOnExit,
}

/// A single chrony directive with its source location and comments.
///
/// Each directive carries its original source location ([`Span`]), any leading comments
/// (comment lines immediately preceding the directive), an optional trailing comment
/// (inline comment after the directive), and the parsed directive body ([`DirectiveKind`]).
///
/// Comments are preserved for lossless round-trip serialization.
///
/// # Examples
///
/// ```rust
/// use chrony_confile::ChronyConfig;
///
/// let config: ChronyConfig = "# My NTP server\nserver ntp.example.com iburst  # preferred\n".parse()?;
///
/// let directive = config.directives().next().unwrap();
/// assert_eq!(directive.leading_comments[0], "My NTP server");
/// assert_eq!(directive.trailing_comment.as_deref(), Some("preferred"));
/// # Ok::<_, chrony_confile::ParseError>(())
/// ```
#[derive(Debug, Clone, PartialEq)]
pub struct Directive {
    /// Source location of the directive.
    pub span: Span,
    /// Comments on lines immediately preceding the directive.
    pub leading_comments: Vec<String>,
    /// An inline comment after the directive, if present.
    pub trailing_comment: Option<String>,
    /// The parsed directive body.
    pub kind: DirectiveKind,
}

impl Directive {
    /// Creates a new directive with the given kind and source span.
    pub fn new(kind: DirectiveKind, span: Span) -> Self {
        Self { span, leading_comments: Vec::new(), trailing_comment: None, kind }
    }

    /// Builder-style method to add a leading comment.
    #[must_use]
    pub fn with_leading_comment(mut self, comment: impl Into<String>) -> Self {
        self.leading_comments.push(comment.into());
        self
    }

    /// Builder-style method to add a trailing comment.
    #[must_use]
    pub fn with_trailing_comment(mut self, comment: impl Into<String>) -> Self {
        self.trailing_comment = Some(comment.into());
        self
    }
}

impl From<DirectiveKind> for Directive {
    fn from(kind: DirectiveKind) -> Self {
        Self::new(kind, Span::new(None, 0, 0, 0))
    }
}

/// A single element in a chrony configuration file.
///
/// Each line in a config file is either a directive, a comment, or a blank line.
///
/// # Examples
///
/// Comments preceding a directive are attached as leading comments to that directive
/// and do not produce a separate [`ConfigNode::Comment`]. Standalone comments (separated
/// by blank lines) produce [`ConfigNode::Comment`] nodes.
///
/// ```rust
/// use chrony_confile::{ChronyConfig, ConfigNode};
///
/// let config: ChronyConfig = "server ntp.example.com\n\n".parse()?;
///
/// assert!(matches!(config.nodes[0], ConfigNode::Directive(_)));
/// assert!(matches!(config.nodes[1], ConfigNode::BlankLine));
/// # Ok::<_, chrony_confile::ParseError>(())
/// ```
#[derive(Debug, Clone, PartialEq)]
pub enum ConfigNode {
    /// A parsed directive with its metadata.
    Directive(Box<Directive>),
    /// A comment line (excluding the leading `#` or `;`).
    Comment(String),
    /// An empty or whitespace-only line.
    BlankLine,
}

impl From<Directive> for ConfigNode {
    fn from(d: Directive) -> Self {
        Self::Directive(Box::new(d))
    }
}

impl From<DirectiveKind> for ConfigNode {
    fn from(kind: DirectiveKind) -> Self {
        Self::Directive(Box::new(Directive::from(kind)))
    }
}

/// A complete chrony configuration file.
///
/// Represents the parsed content of a `chrony.conf` file (or equivalent configuration).
/// The configuration is stored as an ordered list of [`ConfigNode`] values, preserving
/// comments, blank lines, and directives in their original order.
///
/// # Parsing
///
/// ```rust
/// use chrony_confile::ChronyConfig;
///
/// let config = ChronyConfig::parse("\
/// server ntp.example.com iburst
/// pool pool.ntp.org
/// ")?;
/// assert_eq!(config.directives().count(), 2);
/// # Ok::<_, chrony_confile::ParseError>(())
/// ```
///
/// # FromStr
///
/// ```rust
/// use chrony_confile::ChronyConfig;
///
/// let config: ChronyConfig = "server ntp.example.com\n".parse()?;
/// assert!(config.find("server").next().is_some());
/// # Ok::<_, chrony_confile::ParseError>(())
/// ```
///
/// # Serialization
///
/// ```rust
/// use chrony_confile::ChronyConfig;
///
/// let input = "server ntp.example.com iburst\n";
/// let config = ChronyConfig::parse(input)?;
/// let output = config.to_string();
/// assert_eq!(input, output);
/// # Ok::<_, chrony_confile::ParseError>(())
/// ```
#[derive(Debug, Clone, Default, PartialEq)]
pub struct ChronyConfig {
    /// The ordered list of configuration nodes (directives, comments, blank lines).
    pub nodes: Vec<ConfigNode>,
}

impl ChronyConfig {
    /// Creates a new, empty configuration.
    pub fn new() -> Self {
        Self { nodes: Vec::new() }
    }

    /// Adds a directive to the configuration.
    ///
    /// The directive kind is converted into a full [`Directive`] with default metadata
    /// (no source span, no comments).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use chrony_confile::{ChronyConfig, DirectiveKind};
    ///
    /// let mut config = ChronyConfig::new();
    /// config.push(DirectiveKind::RtcOnUtc);
    /// config.push(DirectiveKind::LockAll);
    /// assert_eq!(config.directives().count(), 2);
    /// ```
    pub fn push(&mut self, kind: DirectiveKind) {
        self.nodes.push(ConfigNode::Directive(Box::new(Directive::from(kind))));
    }

    /// Adds a fully-formed directive node to the configuration.
    pub fn push_directive(&mut self, directive: Directive) {
        self.nodes.push(ConfigNode::Directive(Box::new(directive)));
    }

    /// Adds a comment line to the configuration.
    pub fn add_comment(&mut self, comment: impl Into<String>) {
        self.nodes.push(ConfigNode::Comment(comment.into()));
    }

    /// Adds a blank line to the configuration.
    pub fn add_blank(&mut self) {
        self.nodes.push(ConfigNode::BlankLine);
    }

    /// Returns an iterator over all directives in the configuration.
    ///
    /// This excludes comments and blank lines; only [`ConfigNode::Directive`] nodes are yielded.
    pub fn directives(&self) -> impl Iterator<Item = &Directive> {
        self.nodes.iter().filter_map(|n| match n {
            ConfigNode::Directive(d) => Some(d.as_ref()),
            _ => None,
        })
    }

    /// Returns a mutable iterator over all directives in the configuration.
    ///
    /// This allows modifying directives in place while preserving their order relative
    /// to comments and blank lines.
    pub fn directives_mut(&mut self) -> impl Iterator<Item = &mut Directive> {
        self.nodes.iter_mut().filter_map(|n| match n {
            ConfigNode::Directive(d) => Some(d.as_mut()),
            _ => None,
        })
    }

    /// Find all directives with the given directive name.
    ///
    /// The name is compared case-sensitively against the directive's canonical name
    /// (lowercase). Common values include `"server"`, `"pool"`, `"driftfile"`,
    /// `"allow"`, and `"deny"`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use chrony_confile::ChronyConfig;
    ///
    /// let config: ChronyConfig = "\
    /// server ntp1.example.com
    /// server ntp2.example.com
    /// pool pool.ntp.org
    /// ".parse()?;
    ///
    /// assert_eq!(config.find("server").count(), 2);
    /// assert_eq!(config.find("pool").count(), 1);
    /// # Ok::<_, chrony_confile::ParseError>(())
    /// ```
    pub fn find(&self, name: &str) -> impl Iterator<Item = &Directive> {
        self.directives().filter(move |d| d.kind.name() == name)
    }
}

/// Categorizes directives by their functional area in chrony.
///
/// Each [`DirectiveKind`] variant maps to one category via [`DirectiveKind::category`].
/// This is useful for grouping directives when displaying or filtering configuration.
///
/// # Examples
///
/// ```rust
/// use chrony_confile::{DirectiveKind, DirectiveCategory, ServerConfig};
/// use chrony_confile::values::UdpPort;
///
/// let kind = DirectiveKind::Server(ServerConfig::default());
/// assert_eq!(kind.category(), DirectiveCategory::Source);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DirectiveCategory {
    /// NTP source configuration (`server`, `pool`, `peer`, `refclock`, etc.)
    Source,
    /// Source selection tuning (`minsources`, `maxdistance`, etc.)
    Selection,
    /// System clock configuration (`driftfile`, `makestep`, etc.)
    SystemClock,
    /// NTP server configuration (`allow`, `port`, `bindaddress`, etc.)
    NtpServer,
    /// Command access configuration (`cmdallow`, `cmdport`, etc.)
    CommandAccess,
    /// RTC configuration (`rtcfile`, `rtcdevice`, etc.)
    Rtc,
    /// Logging configuration (`log`, `logdir`, etc.)
    Log,
    /// Hardware timestamping configuration (`hwtimestamp`, etc.)
    HardwareTimestamping,
    /// NTS (Network Time Security) configuration
    Nts,
    /// Miscellaneous directives (`include`, `confdir`, `user`, etc.)
    Miscellaneous,
    /// Deprecated directives silently accepted for compatibility
    Deprecated,
}

impl DirectiveKind {
    /// Returns the canonical directive name (e.g. `"server"`, `"driftfile"`, `"allow"`).
    ///
    /// This is the lower-case name used in chrony configuration files.
    pub fn name(&self) -> &'static str {
        match self {
            Self::Server(_) => "server",
            Self::Pool(_) => "pool",
            Self::Peer(_) => "peer",
            Self::InitStepSlew(_) => "initstepslew",
            Self::RefClock(_) => "refclock",
            Self::Manual => "manual",
            Self::AcquisitionPort(_) => "acquisitionport",
            Self::BindAcqAddress(_) => "bindacqaddress",
            Self::BindAcqDevice(_) => "bindacqdevice",
            Self::Dscp(_) => "dscp",
            Self::DumpDir(_) => "dumpdir",
            Self::MaxSamples(_) => "maxsamples",
            Self::MinSamples(_) => "minsamples",
            Self::NtsDumpDir(_) => "ntsdumpdir",
            Self::NtsRefresh(_) => "ntsrefresh",
            Self::NtsTrustedCerts(_) => "ntstrustedcerts",
            Self::NoSystemCert => "nosystemcert",
            Self::NoCertTimeCheck(_) => "nocerttimecheck",
            Self::Refresh(_) => "refresh",
            Self::AuthSelectMode(_) => "authselectmode",
            Self::CombineLimit(_) => "combinelimit",
            Self::MaxDistance(_) => "maxdistance",
            Self::MaxJitter(_) => "maxjitter",
            Self::MinSources(_) => "minsources",
            Self::ReselectDist(_) => "reselectdist",
            Self::StratumWeight(_) => "stratumweight",
            Self::ClockPrecision(_) => "clockprecision",
            Self::CorrTimeRatio(_) => "corrtimeratio",
            Self::DriftFile(_) => "driftfile",
            Self::FallbackDrift(_) => "fallbackdrift",
            Self::LeapSecMode(_) => "leapsecmode",
            Self::LeapSecTz(_) => "leapsectz",
            Self::LeapSecList(_) => "leapseclist",
            Self::MakeStep(_) => "makestep",
            Self::MaxChange(_) => "maxchange",
            Self::MaxClockError(_) => "maxclockerror",
            Self::MaxDrift(_) => "maxdrift",
            Self::MaxUpdateSkew(_) => "maxupdateskew",
            Self::MaxSlewRate(_) => "maxslewrate",
            Self::TempComp(_) => "tempcomp",
            Self::Allow(_) => "allow",
            Self::Deny(_) => "deny",
            Self::BindAddress(_) => "bindaddress",
            Self::BindDevice(_) => "binddevice",
            Self::Broadcast(_) => "broadcast",
            Self::ClientLogLimit(_) => "clientloglimit",
            Self::NoClientLog => "noclientlog",
            Self::Local(_) => "local",
            Self::NtpSignDSocket(_) => "ntpsigndsocket",
            Self::NtsPort(_) => "ntsport",
            Self::NtsServerCert(_) => "ntsservercert",
            Self::NtsServerKey(_) => "ntsserverkey",
            Self::NtsProcesses(_) => "ntsprocesses",
            Self::MaxNtsConnections(_) => "maxntsconnections",
            Self::NtsNtpServer(_) => "ntsntpserver",
            Self::NtsRotate(_) => "ntsrotate",
            Self::Port(_) => "port",
            Self::RateLimit(_) => "ratelimit",
            Self::NtsRateLimit(_) => "ntsratelimit",
            Self::SmoothTime(_) => "smoothtime",
            Self::BindCmdAddress(_) => "bindcmdaddress",
            Self::BindCmdDevice(_) => "bindcmddevice",
            Self::CmdAllow(_) => "cmdallow",
            Self::CmdDeny(_) => "cmddeny",
            Self::CmdPort(_) => "cmdport",
            Self::CmdRateLimit(_) => "cmdratelimit",
            Self::OpenCommands(_) => "opencommands",
            Self::HwClockFile(_) => "hwclockfile",
            Self::RtcAutoTrim(_) => "rtcautotrim",
            Self::RtcDevice(_) => "rtcdevice",
            Self::RtcFile(_) => "rtcfile",
            Self::RtcOnUtc => "rtconutc",
            Self::RtcSync => "rtcsync",
            Self::Log(_) => "log",
            Self::LogBanner(_) => "logbanner",
            Self::LogChange(_) => "logchange",
            Self::LogDir(_) => "logdir",
            Self::HwTimestamp(_) => "hwtimestamp",
            Self::HwTsTimeout(_) => "hwtstimeout",
            Self::MaxTxBuffers(_) => "maxtxbuffers",
            Self::PtpPort(_) => "ptpport",
            Self::PtpDomain(_) => "ptpdomain",
            Self::NtsAeads(_) => "ntsaeads",
            Self::ConfDir(_) => "confdir",
            Self::Include(_) => "include",
            Self::SourceDir(_) => "sourcedir",
            Self::LockAll => "lock_all",
            Self::MailOnChange(_) => "mailonchange",
            Self::PidFile(_) => "pidfile",
            Self::SchedPriority(_) => "sched_priority",
            Self::User(_) => "user",
            Self::KeyFile(_) => "keyfile",
            Self::DumpOnExit => "dumponexit",
        }
    }

    /// Returns the category this directive belongs to.
    ///
    /// Categories group directives by their functional area: source configuration,
    /// selection tuning, system clock, NTP server, command access, RTC, logging,
    /// hardware timestamping, NTS, and miscellaneous.
    pub fn category(&self) -> DirectiveCategory {
        match self {
            Self::Server(_) | Self::Pool(_) | Self::Peer(_)
                | Self::InitStepSlew(_) | Self::RefClock(_) | Self::Manual
                | Self::AcquisitionPort(_) | Self::BindAcqAddress(_)
                | Self::BindAcqDevice(_) | Self::Dscp(_) | Self::DumpDir(_)
                | Self::MaxSamples(_) | Self::MinSamples(_) | Self::NtsDumpDir(_)
                | Self::NtsRefresh(_) | Self::NtsTrustedCerts(_)
                | Self::NoSystemCert | Self::NoCertTimeCheck(_)
                | Self::Refresh(_) => DirectiveCategory::Source,
            Self::AuthSelectMode(_) | Self::CombineLimit(_)
                | Self::MaxDistance(_) | Self::MaxJitter(_)
                | Self::MinSources(_) | Self::ReselectDist(_)
                | Self::StratumWeight(_) => DirectiveCategory::Selection,
            Self::ClockPrecision(_) | Self::CorrTimeRatio(_)
                | Self::DriftFile(_) | Self::FallbackDrift(_)
                | Self::LeapSecMode(_) | Self::LeapSecTz(_)
                | Self::LeapSecList(_) | Self::MakeStep(_)
                | Self::MaxChange(_) | Self::MaxClockError(_)
                | Self::MaxDrift(_) | Self::MaxUpdateSkew(_)
                | Self::MaxSlewRate(_) | Self::TempComp(_) => DirectiveCategory::SystemClock,
            Self::Allow(_) | Self::Deny(_) | Self::BindAddress(_)
                | Self::BindDevice(_) | Self::Broadcast(_)
                | Self::ClientLogLimit(_) | Self::NoClientLog
                | Self::Local(_) | Self::NtpSignDSocket(_)
                | Self::NtsPort(_) | Self::NtsServerCert(_)
                | Self::NtsServerKey(_) | Self::NtsProcesses(_)
                | Self::MaxNtsConnections(_) | Self::NtsNtpServer(_)
                | Self::NtsRotate(_) | Self::Port(_) | Self::RateLimit(_)
                | Self::NtsRateLimit(_) | Self::SmoothTime(_) => DirectiveCategory::NtpServer,
            Self::BindCmdAddress(_) | Self::BindCmdDevice(_)
                | Self::CmdAllow(_) | Self::CmdDeny(_)
                | Self::CmdPort(_) | Self::CmdRateLimit(_)
                | Self::OpenCommands(_) => DirectiveCategory::CommandAccess,
            Self::HwClockFile(_) | Self::RtcAutoTrim(_)
                | Self::RtcDevice(_) | Self::RtcFile(_)
                | Self::RtcOnUtc | Self::RtcSync => DirectiveCategory::Rtc,
            Self::Log(_) | Self::LogBanner(_) | Self::LogChange(_)
                | Self::LogDir(_) => DirectiveCategory::Log,
            Self::HwTimestamp(_) | Self::HwTsTimeout(_)
                | Self::MaxTxBuffers(_) | Self::PtpPort(_)
                | Self::PtpDomain(_) => DirectiveCategory::HardwareTimestamping,
            Self::NtsAeads(_) => DirectiveCategory::Nts,
            Self::ConfDir(_) | Self::Include(_) | Self::SourceDir(_)
                | Self::LockAll | Self::MailOnChange(_) | Self::PidFile(_)
                | Self::SchedPriority(_) | Self::User(_) | Self::KeyFile(_)
                | Self::DumpOnExit => DirectiveCategory::Miscellaneous,
        }
    }

    /// Returns `true` if this directive is deprecated and silently accepted for backward
    /// compatibility.
    pub fn is_deprecated(&self) -> bool {
        matches!(self, Self::DumpOnExit)
    }
}