molt-framework 2.0.0

//! XML sitemap generation.
//!

use std::fmt::Write as _;

use crate::core::escape::escape_xml;
use crate::core::url_policy::is_http_url;

/// How often a page is expected to change, as the sitemap protocol spells it.
///
/// An enum rather than a string so `"weakly"` is a compile error instead of a sitemap that
/// search engines quietly ignore. Use [`str::parse`] when the value arrives as text.
///
/// # Examples
/// ```
/// use molt::sitemap::ChangeFreq;
/// assert_eq!(ChangeFreq::Weekly.as_str(), "weekly");
/// assert_eq!("monthly".parse::<ChangeFreq>(), Ok(ChangeFreq::Monthly));
/// assert!("weakly".parse::<ChangeFreq>().is_err());
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum ChangeFreq {
    /// `always` — changes on every access.
    Always,
    /// `hourly`.
    Hourly,
    /// `daily`.
    Daily,
    /// `weekly`.
    Weekly,
    /// `monthly`.
    Monthly,
    /// `yearly`.
    Yearly,
    /// `never` — archived content.
    Never,
}

impl ChangeFreq {
    /// The value written between `<changefreq>` tags.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Always => "always",
            Self::Hourly => "hourly",
            Self::Daily => "daily",
            Self::Weekly => "weekly",
            Self::Monthly => "monthly",
            Self::Yearly => "yearly",
            Self::Never => "never",
        }
    }
}

impl std::fmt::Display for ChangeFreq {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

/// The text was not one of the seven values the protocol defines.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParseChangeFreqError(String);

impl std::fmt::Display for ParseChangeFreqError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "{:?} is not a change frequency (always, hourly, daily, weekly, monthly, yearly, never)",
            self.0
        )
    }
}

impl std::error::Error for ParseChangeFreqError {}

impl std::str::FromStr for ChangeFreq {
    type Err = ParseChangeFreqError;

    fn from_str(text: &str) -> Result<Self, Self::Err> {
        Ok(match text {
            "always" => Self::Always,
            "hourly" => Self::Hourly,
            "daily" => Self::Daily,
            "weekly" => Self::Weekly,
            "monthly" => Self::Monthly,
            "yearly" => Self::Yearly,
            "never" => Self::Never,
            other => return Err(ParseChangeFreqError(other.to_owned())),
        })
    }
}

/// The most `<url>` entries the sitemap protocol allows in one file.
pub const MAX_URLS: usize = 50_000;

/// The largest an uncompressed sitemap file may be under the protocol: 50 MiB.
pub const MAX_BYTES: usize = 50 * 1024 * 1024;

/// One entry in a sitemap.
///
/// # Examples
/// ```
/// use molt::sitemap::{ChangeFreq, SitemapGenerator, SitemapUrl};
///
/// let xml = SitemapGenerator::generate(&[
///     SitemapUrl::new("https://example.com/").changefreq(ChangeFreq::Weekly).priority(1.0),
/// ]);
/// assert!(xml.contains("<priority>1.0</priority>"));
/// ```
#[derive(Debug, Clone, PartialEq, Default)]
#[non_exhaustive]
pub struct SitemapUrl {
    /// The absolute URL of the page.
    pub loc: String,
    /// The last modification date, typically `YYYY-MM-DD`.
    pub lastmod: Option<String>,
    /// How often the page changes.
    pub changefreq: Option<ChangeFreq>,
    /// Relative priority within the site, from `0.0` to `1.0`.
    ///
    /// Set through [`SitemapUrl::priority`], which clamps. A value written to this field
    /// directly is checked again when the sitemap is rendered: out of range is clamped and
    /// a non-finite one is left out, because `NaN` is not a number a sitemap can hold.
    pub priority: Option<f64>,
    /// Other-language versions of this page, as `(hreflang, href)` pairs.
    ///
    /// Set through [`SitemapUrl::alternate`]. Written as `<xhtml:link rel="alternate">`
    /// elements; a pair whose `href` is not an absolute `http(s)` URL or whose `hreflang` is
    /// not a language tag (or `x-default`) is left out when the sitemap is rendered.
    pub alternates: Vec<(String, String)>,
}

impl SitemapUrl {
    /// Creates an entry for the given URL.
    pub fn new(loc: impl Into<String>) -> Self {
        Self {
            loc: loc.into(),
            ..Self::default()
        }
    }

    /// Sets the last modification date.
    #[must_use]
    pub fn lastmod(mut self, lastmod: impl Into<String>) -> Self {
        self.lastmod = Some(lastmod.into());
        self
    }

    /// Sets the change frequency.
    #[must_use]
    pub fn changefreq(mut self, changefreq: ChangeFreq) -> Self {
        self.changefreq = Some(changefreq);
        self
    }

    /// Adds an other-language version of this page: `hreflang` is a language tag such as
    /// `pt-BR`, or `x-default`; `href` is its absolute URL.
    ///
    /// List every version on each entry, **including the page itself**, as search engines
    /// expect. Entries are written in call order. The `xmlns:xhtml` namespace is declared only
    /// when at least one alternate is written, so a sitemap without them is unchanged.
    ///
    /// # Examples
    /// ```
    /// use molt::sitemap::{SitemapGenerator, SitemapUrl};
    ///
    /// let xml = SitemapGenerator::generate(&[SitemapUrl::new("https://example.com/en/")
    ///     .alternate("en", "https://example.com/en/")
    ///     .alternate("pt-BR", "https://example.com/pt/")]);
    /// assert!(xml.contains(r#"xmlns:xhtml="http://www.w3.org/1999/xhtml""#));
    /// assert!(xml.contains(
    ///     r#"<xhtml:link rel="alternate" hreflang="pt-BR" href="https://example.com/pt/"/>"#
    /// ));
    /// ```
    #[must_use]
    pub fn alternate(mut self, hreflang: impl Into<String>, href: impl Into<String>) -> Self {
        self.alternates.push((hreflang.into(), href.into()));
        self
    }

    /// Sets the priority, clamped to `0.0..=1.0`. A non-finite value clears it.
    ///
    /// Clamping rather than failing keeps the builder chainable; the protocol allows no
    /// value outside the range, so there is nothing to preserve.
    #[must_use]
    pub fn priority(mut self, priority: f64) -> Self {
        self.priority = valid_priority(priority);
        self
    }
}

/// Renders sitemaps and sitemap indexes.
#[derive(Debug, Clone, Copy)]
pub struct SitemapGenerator;

impl SitemapGenerator {
    /// Renders a `<urlset>` sitemap.
    ///
    /// An empty list still produces a well-formed, empty `<urlset>`. An entry whose `loc`
    /// is not an absolute `http://` or `https://` URL is **left out**: the protocol requires
    /// a full URL, and a crawler or tool that lists the entries would otherwise be handed
    /// `javascript:…`.
    ///
    /// This does not enforce the protocol's limit of [`MAX_URLS`] URLs and [`MAX_BYTES`]
    /// bytes per file; split a larger site with [`SitemapGenerator::chunks`] and list the
    /// parts in a [`generate_index`](Self::generate_index).
    #[must_use]
    pub fn generate(urls: &[SitemapUrl]) -> String {
        let mut xml = String::with_capacity(256 + urls.len() * 160);
        xml.push_str("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n");
        xml.push_str("<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\"");
        // Declared only when something uses it, so the header of a sitemap without alternates
        // stays what the golden fixture pins.
        if urls
            .iter()
            .filter(|url| is_http_url(&url.loc))
            .any(|url| url.alternates.iter().any(is_valid_alternate))
        {
            xml.push_str(" xmlns:xhtml=\"http://www.w3.org/1999/xhtml\"");
        }
        xml.push_str(">\n");

        for url in urls.iter().filter(|url| is_http_url(&url.loc)) {
            xml.push_str("  <url>\n");
            let _ = writeln!(xml, "    <loc>{}</loc>", escape_xml(&url.loc));
            for (hreflang, href) in url
                .alternates
                .iter()
                .filter(|pair| is_valid_alternate(pair))
            {
                let _ = writeln!(
                    xml,
                    "    <xhtml:link rel=\"alternate\" hreflang=\"{}\" href=\"{}\"/>",
                    escape_xml(hreflang),
                    escape_xml(href)
                );
            }
            if let Some(lastmod) = &url.lastmod {
                let _ = writeln!(xml, "    <lastmod>{}</lastmod>", escape_xml(lastmod));
            }
            if let Some(changefreq) = url.changefreq {
                let _ = writeln!(xml, "    <changefreq>{changefreq}</changefreq>");
            }
            if let Some(priority) = url.priority.and_then(valid_priority) {
                let _ = writeln!(
                    xml,
                    "    <priority>{}</priority>",
                    format_priority(priority)
                );
            }
            xml.push_str("  </url>\n");
        }

        xml.push_str("</urlset>");
        xml
    }

    /// Splits `urls` into slices that each fit in one sitemap file (at most [`MAX_URLS`]).
    ///
    /// The byte limit depends on how long the URLs are, so check
    /// `generate(chunk).len() <= MAX_BYTES` and split further if a chunk is over.
    ///
    /// # Examples
    /// ```
    /// use molt::sitemap::{SitemapGenerator, SitemapUrl, MAX_URLS};
    /// let urls: Vec<SitemapUrl> = (0..=MAX_URLS)
    ///     .map(|i| SitemapUrl::new(format!("https://example.com/{i}")))
    ///     .collect();
    /// assert_eq!(SitemapGenerator::chunks(&urls).count(), 2);
    /// ```
    pub fn chunks(urls: &[SitemapUrl]) -> impl Iterator<Item = &[SitemapUrl]> {
        urls.chunks(MAX_URLS)
    }

    /// Renders a `<sitemapindex>` pointing at several sitemaps. An entry whose location is
    /// not an absolute `http://` or `https://` URL is left out, as in [`generate`](Self::generate).
    #[must_use]
    pub fn generate_index(sitemaps: &[(String, Option<String>)]) -> String {
        let mut xml = String::with_capacity(256 + sitemaps.len() * 96);
        xml.push_str("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n");
        xml.push_str("<sitemapindex xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n");

        for (loc, lastmod) in sitemaps.iter().filter(|(loc, _)| is_http_url(loc)) {
            xml.push_str("  <sitemap>\n");
            let _ = writeln!(xml, "    <loc>{}</loc>", escape_xml(loc));
            if let Some(lastmod) = lastmod {
                let _ = writeln!(xml, "    <lastmod>{}</lastmod>", escape_xml(lastmod));
            }
            xml.push_str("  </sitemap>\n");
        }

        xml.push_str("</sitemapindex>");
        xml
    }
}

/// Whether an `(hreflang, href)` pair can be written: an absolute `http(s)` URL, and a language
/// tag. A tag is not parsed against BCP 47 here; it must be `x-default` or start with a letter
/// and hold only ASCII letters, digits and `-`, at most 35 characters, which is every
/// registered tag and nothing that could carry markup.
fn is_valid_alternate((hreflang, href): &(String, String)) -> bool {
    is_http_url(href)
        && hreflang.len() <= 35
        && hreflang.starts_with(|c: char| c.is_ascii_alphabetic())
        && hreflang
            .chars()
            .all(|c| c.is_ascii_alphanumeric() || c == '-')
}

/// A priority the protocol can hold: clamped into `0.0..=1.0`, and `None` for `NaN`/infinity.
fn valid_priority(priority: f64) -> Option<f64> {
    priority.is_finite().then(|| priority.clamp(0.0, 1.0))
}

/// Formats a priority with at least one decimal place.
///
/// Rust's `{}` renders `1.0` as `"1"`, but the golden fixture has `"1.0"`, so a whole number
/// keeps one decimal place here. Fractional values use the shortest round-tripping form.
fn format_priority(priority: f64) -> String {
    if priority.fract() == 0.0 && priority.is_finite() {
        format!("{priority:.1}")
    } else {
        format!("{priority}")
    }
}

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

    #[test]
    fn alternates_declare_the_xhtml_namespace_and_list_every_version() {
        let xml = SitemapGenerator::generate(&[SitemapUrl::new("https://e.com/en/")
            .alternate("en", "https://e.com/en/")
            .alternate("pt-BR", "https://e.com/pt/?a=1&b=2")
            .alternate("x-default", "https://e.com/")]);
        assert!(xml.contains(
            "<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\" \
             xmlns:xhtml=\"http://www.w3.org/1999/xhtml\">\n"
        ));
        assert!(xml.contains(
            "    <loc>https://e.com/en/</loc>\n\
             \x20   <xhtml:link rel=\"alternate\" hreflang=\"en\" href=\"https://e.com/en/\"/>\n\
             \x20   <xhtml:link rel=\"alternate\" hreflang=\"pt-BR\" href=\"https://e.com/pt/?a=1&amp;b=2\"/>\n\
             \x20   <xhtml:link rel=\"alternate\" hreflang=\"x-default\" href=\"https://e.com/\"/>\n"
        ));
    }

    #[test]
    fn without_alternates_the_header_has_no_xhtml_namespace() {
        let xml = SitemapGenerator::generate(&[SitemapUrl::new("https://e.com/")]);
        assert!(!xml.contains("xhtml"), "{xml}");
    }

    #[test]
    fn a_hostile_alternate_is_left_out_and_does_not_declare_the_namespace() {
        let xml = SitemapGenerator::generate(&[SitemapUrl::new("https://e.com/")
            .alternate("en", "javascript:alert(1)")
            .alternate("en\"/><x", "https://e.com/en/")
            .alternate("", "https://e.com/")
            .alternate("1en", "https://e.com/")
            .alternate("e".repeat(36), "https://e.com/")]);
        assert!(!xml.contains("xhtml"), "{xml}");
    }

    #[test]
    fn an_alternate_on_an_entry_that_is_left_out_declares_nothing() {
        let xml = SitemapGenerator::generate(&[
            SitemapUrl::new("javascript:alert(1)").alternate("en", "https://e.com/en/")
        ]);
        assert!(!xml.contains("xhtml"), "{xml}");
    }

    #[test]
    fn a_sitemap_has_an_xml_declaration_and_a_urlset() {
        let xml = SitemapGenerator::generate(&[SitemapUrl::new("https://example.com/")]);
        assert!(xml.starts_with("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<urlset "));
        assert!(xml.ends_with("</urlset>"));
    }

    #[test]
    fn a_loc_containing_an_ampersand_is_escaped() {
        let xml = SitemapGenerator::generate(&[SitemapUrl::new("https://e.com/a?x=1&y=2")]);
        assert!(xml.contains("<loc>https://e.com/a?x=1&amp;y=2</loc>"));
    }

    /// This is the subtle one: `1.0` must print as `1.0`, and Rust's default `{}` prints `1`.
    #[test]
    fn whole_priorities_keep_one_decimal_place() {
        assert_eq!(format_priority(1.0), "1.0");
        assert_eq!(format_priority(0.0), "0.0");
        assert_eq!(format_priority(0.7), "0.7");
        assert_eq!(format_priority(0.25), "0.25");
    }

    #[test]
    fn a_change_frequency_round_trips_through_text() {
        for freq in [
            ChangeFreq::Always,
            ChangeFreq::Hourly,
            ChangeFreq::Daily,
            ChangeFreq::Weekly,
            ChangeFreq::Monthly,
            ChangeFreq::Yearly,
            ChangeFreq::Never,
        ] {
            assert_eq!(freq.as_str().parse(), Ok(freq));
            assert_eq!(freq.to_string(), freq.as_str());
        }
        let error = "Weekly".parse::<ChangeFreq>().expect_err("case-sensitive");
        assert!(error.to_string().contains("\"Weekly\""));
    }

    #[test]
    fn a_priority_outside_the_range_is_clamped_and_a_non_number_is_left_out() {
        let render = |priority: f64| {
            SitemapGenerator::generate(&[SitemapUrl::new("https://e.com/").priority(priority)])
        };
        assert!(render(7.0).contains("<priority>1.0</priority>"));
        assert!(render(-3.0).contains("<priority>0.0</priority>"));
        for bad in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
            assert!(!render(bad).contains("<priority>"), "{bad}");
        }

        // The field is public, so the renderer checks again.
        let mut url = SitemapUrl::new("https://e.com/");
        url.priority = Some(f64::NAN);
        assert!(!SitemapGenerator::generate(&[url]).contains("NaN"));
    }

    #[test]
    fn an_entry_whose_loc_is_not_http_is_left_out() {
        let xml = SitemapGenerator::generate(&[
            SitemapUrl::new("https://e.com/ok"),
            SitemapUrl::new("javascript:alert(1)"),
            SitemapUrl::new("/relative"),
            SitemapUrl::new("HTTP://e.com/upper"),
        ]);
        assert_eq!(xml.matches("<url>").count(), 2, "{xml}");
        assert!(!xml.contains("javascript"));
        let index = SitemapGenerator::generate_index(&[
            ("https://e.com/s.xml".into(), None),
            ("javascript:x".into(), None),
        ]);
        assert_eq!(index.matches("<sitemap>").count(), 1);
    }

    #[test]
    fn a_large_site_is_split_into_files_that_fit_the_protocol() {
        let urls: Vec<SitemapUrl> = (0..=MAX_URLS * 2)
            .map(|i| SitemapUrl::new(format!("https://e.com/{i}")))
            .collect();
        let chunks: Vec<&[SitemapUrl]> = SitemapGenerator::chunks(&urls).collect();
        assert_eq!(chunks.len(), 3);
        assert!(chunks.iter().all(|chunk| chunk.len() <= MAX_URLS));
        assert_eq!(
            chunks.iter().map(|chunk| chunk.len()).sum::<usize>(),
            urls.len()
        );
        assert_eq!(MAX_BYTES, 52_428_800);
    }

    #[test]
    fn optional_fields_are_omitted_entirely() {
        let xml = SitemapGenerator::generate(&[SitemapUrl::new("https://e.com/")]);
        assert!(!xml.contains("<lastmod>"));
        assert!(!xml.contains("<changefreq>"));
        assert!(!xml.contains("<priority>"));
    }

    #[test]
    fn an_empty_sitemap_is_still_well_formed() {
        let xml = SitemapGenerator::generate(&[]);
        assert!(xml.contains("<urlset"));
        assert!(xml.ends_with("</urlset>"));
    }

    #[test]
    fn an_index_lists_each_sitemap() {
        let xml = SitemapGenerator::generate_index(&[
            (
                "https://e.com/sitemap-posts.xml".into(),
                Some("2026-01-15".into()),
            ),
            ("https://e.com/sitemap-pages.xml".into(), None),
        ]);
        assert!(xml.contains("<sitemapindex"));
        assert!(xml.contains("<loc>https://e.com/sitemap-posts.xml</loc>"));
        assert!(xml.contains("<lastmod>2026-01-15</lastmod>"));
        assert_eq!(xml.matches("<sitemap>").count(), 2);
        assert_eq!(xml.matches("<lastmod>").count(), 1);

        // A query string in an index entry is escaped too, not just in `<urlset>`.
        let escaped = SitemapGenerator::generate_index(&[(
            "https://e.com/sitemap-pages.xml?v=2&full=1".into(),
            None,
        )]);
        assert!(escaped.contains("v=2&amp;full=1"));
    }

    #[test]
    fn an_index_entry_without_a_lastmod_emits_no_element() {
        let xml = SitemapGenerator::generate_index(&[("https://e.com/sitemap.xml".into(), None)]);

        assert!(!xml.contains("<lastmod>"));
    }
}