Skip to main content

next_rust_server/
seo.rs

1//! Generated `sitemap.xml` and `robots.txt` (`app/sitemap.rs`, `app/robots.rs`).
2
3use crate::response::{IntoResponse, Response};
4
5/// `pub async fn sitemap() -> Sitemap`
6#[derive(Debug, Clone, Default)]
7pub struct Sitemap {
8    pub entries: Vec<SitemapEntry>,
9}
10
11#[derive(Debug, Clone, Default)]
12pub struct SitemapEntry {
13    pub url: String,
14    /// W3C datetime, e.g. `2026-09-17`.
15    pub last_modified: Option<String>,
16    pub change_frequency: Option<String>,
17    pub priority: Option<f32>,
18}
19
20impl Sitemap {
21    pub fn new() -> Self {
22        Self::default()
23    }
24
25    pub fn url(mut self, url: impl Into<String>) -> Self {
26        self.entries.push(SitemapEntry { url: url.into(), ..Default::default() });
27        self
28    }
29
30    pub fn entry(mut self, entry: SitemapEntry) -> Self {
31        self.entries.push(entry);
32        self
33    }
34
35    pub fn to_xml(&self) -> String {
36        let esc = |s: &str| next_rust_view::escape_attr(s).into_owned();
37        let mut x = String::from(
38            "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n",
39        );
40        for e in &self.entries {
41            x.push_str("  <url>\n    <loc>");
42            x.push_str(&esc(&e.url));
43            x.push_str("</loc>\n");
44            if let Some(v) = &e.last_modified {
45                x.push_str(&format!("    <lastmod>{}</lastmod>\n", esc(v)));
46            }
47            if let Some(v) = &e.change_frequency {
48                x.push_str(&format!("    <changefreq>{}</changefreq>\n", esc(v)));
49            }
50            if let Some(v) = e.priority {
51                x.push_str(&format!("    <priority>{:.1}</priority>\n", v.clamp(0.0, 1.0)));
52            }
53            x.push_str("  </url>\n");
54        }
55        x.push_str("</urlset>\n");
56        x
57    }
58}
59
60impl IntoResponse for Sitemap {
61    fn into_response(self) -> Response {
62        Response::new(http::StatusCode::OK, crate::response::Body::Bytes(self.to_xml().into()))
63            .with_content_type("application/xml")
64            .with_cache_control("public, max-age=3600")
65    }
66}
67
68/// `pub async fn robots() -> Robots`
69#[derive(Debug, Clone, Default)]
70pub struct Robots {
71    pub rules: Vec<RobotsRule>,
72    pub sitemap: Option<String>,
73    pub host: Option<String>,
74}
75
76#[derive(Debug, Clone, Default)]
77pub struct RobotsRule {
78    pub user_agent: String,
79    pub allow: Vec<String>,
80    pub disallow: Vec<String>,
81    pub crawl_delay: Option<u32>,
82}
83
84impl Robots {
85    /// Allow everything for all user agents.
86    pub fn allow_all() -> Self {
87        Robots {
88            rules: vec![RobotsRule { user_agent: "*".into(), allow: vec!["/".into()], ..Default::default() }],
89            ..Default::default()
90        }
91    }
92
93    pub fn rule(mut self, rule: RobotsRule) -> Self {
94        self.rules.push(rule);
95        self
96    }
97
98    pub fn sitemap(mut self, url: impl Into<String>) -> Self {
99        self.sitemap = Some(url.into());
100        self
101    }
102
103    pub fn to_text(&self) -> String {
104        let clean = |s: &str| s.replace(['\r', '\n'], "");
105        let mut t = String::new();
106        for r in &self.rules {
107            t.push_str(&format!("User-Agent: {}\n", clean(&r.user_agent)));
108            for a in &r.allow {
109                t.push_str(&format!("Allow: {}\n", clean(a)));
110            }
111            for d in &r.disallow {
112                t.push_str(&format!("Disallow: {}\n", clean(d)));
113            }
114            if let Some(c) = r.crawl_delay {
115                t.push_str(&format!("Crawl-delay: {c}\n"));
116            }
117            t.push('\n');
118        }
119        if let Some(h) = &self.host {
120            t.push_str(&format!("Host: {}\n", clean(h)));
121        }
122        if let Some(s) = &self.sitemap {
123            t.push_str(&format!("Sitemap: {}\n", clean(s)));
124        }
125        t
126    }
127}
128
129impl IntoResponse for Robots {
130    fn into_response(self) -> Response {
131        Response::text(self.to_text()).with_cache_control("public, max-age=3600")
132    }
133}
134
135/// A syndication feed, rendered as RSS 2.0, Atom 1.0 or JSON Feed 1.1.
136///
137/// Serve it from an API route, one URL per format:
138///
139/// ```ignore
140/// // app/feed.xml/route.rs
141/// pub async fn GET() -> Response {
142///     Response::xml(feed().to_rss())
143/// }
144/// ```
145///
146/// Dates are `YYYY-MM-DD` or full RFC 3339 (`2026-09-18T09:30:00Z`); each
147/// format receives the shape it requires.
148#[derive(Debug, Clone, Default)]
149pub struct Feed {
150    pub title: String,
151    /// The site the feed belongs to, e.g. `https://example.com`.
152    pub site_url: String,
153    /// This feed's own URL, e.g. `https://example.com/feed.xml`.
154    pub feed_url: String,
155    pub description: Option<String>,
156    pub language: Option<String>,
157    /// When the feed last changed. Defaults to the newest entry's date.
158    pub updated: Option<String>,
159    pub icon: Option<String>,
160    pub author: Option<String>,
161    pub entries: Vec<FeedEntry>,
162}
163
164/// One item in a [`Feed`].
165#[derive(Debug, Clone, Default)]
166pub struct FeedEntry {
167    pub url: String,
168    pub title: String,
169    /// A short plain-text summary.
170    pub summary: Option<String>,
171    /// The full entry as HTML.
172    pub content_html: Option<String>,
173    pub published: Option<String>,
174    pub updated: Option<String>,
175    pub author: Option<String>,
176    pub tags: Vec<String>,
177    /// Stable identifier. Defaults to `url`.
178    pub id: Option<String>,
179    /// A representative image.
180    pub image: Option<String>,
181}
182
183impl FeedEntry {
184    pub fn new(url: impl Into<String>, title: impl Into<String>) -> Self {
185        Self { url: url.into(), title: title.into(), ..Default::default() }
186    }
187
188    pub fn summary(mut self, text: impl Into<String>) -> Self {
189        self.summary = Some(text.into());
190        self
191    }
192
193    pub fn content_html(mut self, html: impl Into<String>) -> Self {
194        self.content_html = Some(html.into());
195        self
196    }
197
198    pub fn published(mut self, date: impl Into<String>) -> Self {
199        self.published = Some(date.into());
200        self
201    }
202
203    pub fn updated(mut self, date: impl Into<String>) -> Self {
204        self.updated = Some(date.into());
205        self
206    }
207
208    pub fn author(mut self, name: impl Into<String>) -> Self {
209        self.author = Some(name.into());
210        self
211    }
212
213    pub fn tag(mut self, tag: impl Into<String>) -> Self {
214        self.tags.push(tag.into());
215        self
216    }
217
218    pub fn image(mut self, url: impl Into<String>) -> Self {
219        self.image = Some(url.into());
220        self
221    }
222
223    pub fn id(mut self, id: impl Into<String>) -> Self {
224        self.id = Some(id.into());
225        self
226    }
227
228    fn identifier(&self) -> &str {
229        self.id.as_deref().unwrap_or(&self.url)
230    }
231}
232
233impl Feed {
234    pub fn new(title: impl Into<String>, site_url: impl Into<String>, feed_url: impl Into<String>) -> Self {
235        Self { title: title.into(), site_url: site_url.into(), feed_url: feed_url.into(), ..Default::default() }
236    }
237
238    pub fn description(mut self, text: impl Into<String>) -> Self {
239        self.description = Some(text.into());
240        self
241    }
242
243    pub fn language(mut self, lang: impl Into<String>) -> Self {
244        self.language = Some(lang.into());
245        self
246    }
247
248    pub fn updated(mut self, date: impl Into<String>) -> Self {
249        self.updated = Some(date.into());
250        self
251    }
252
253    pub fn icon(mut self, url: impl Into<String>) -> Self {
254        self.icon = Some(url.into());
255        self
256    }
257
258    pub fn author(mut self, name: impl Into<String>) -> Self {
259        self.author = Some(name.into());
260        self
261    }
262
263    pub fn entry(mut self, entry: FeedEntry) -> Self {
264        self.entries.push(entry);
265        self
266    }
267
268    pub fn entries(mut self, entries: impl IntoIterator<Item = FeedEntry>) -> Self {
269        self.entries.extend(entries);
270        self
271    }
272
273    /// The feed's timestamp: the explicit one, else the newest entry's.
274    fn last_updated(&self) -> Option<String> {
275        self.updated
276            .clone()
277            .or_else(|| self.entries.iter().filter_map(|e| e.updated.clone().or_else(|| e.published.clone())).max())
278    }
279
280    /// RSS 2.0.
281    pub fn to_rss(&self) -> String {
282        let esc = |s: &str| next_rust_view::escape_text(s).into_owned();
283        let mut x = String::from("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n");
284        x.push_str("<rss version=\"2.0\" xmlns:atom=\"http://www.w3.org/2005/Atom\">\n<channel>\n");
285        x.push_str(&format!("  <title>{}</title>\n", esc(&self.title)));
286        x.push_str(&format!("  <link>{}</link>\n", esc(&self.site_url)));
287        x.push_str(&format!(
288            "  <atom:link href=\"{}\" rel=\"self\" type=\"application/rss+xml\"/>\n",
289            next_rust_view::escape_attr(&self.feed_url)
290        ));
291        x.push_str(&format!("  <description>{}</description>\n", esc(self.description.as_deref().unwrap_or(""))));
292        if let Some(l) = &self.language {
293            x.push_str(&format!("  <language>{}</language>\n", esc(l)));
294        }
295        if let Some(d) = self.last_updated().as_deref().and_then(rfc2822) {
296            x.push_str(&format!("  <lastBuildDate>{d}</lastBuildDate>\n"));
297        }
298        for e in &self.entries {
299            x.push_str("  <item>\n");
300            x.push_str(&format!("    <title>{}</title>\n", esc(&e.title)));
301            x.push_str(&format!("    <link>{}</link>\n", esc(&e.url)));
302            x.push_str(&format!("    <guid isPermaLink=\"false\">{}</guid>\n", esc(e.identifier())));
303            if let Some(d) = e.published.as_deref().and_then(rfc2822) {
304                x.push_str(&format!("    <pubDate>{d}</pubDate>\n"));
305            }
306            if let Some(a) = e.author.as_deref().or(self.author.as_deref()) {
307                x.push_str(&format!(
308                    "    <dc:creator xmlns:dc=\"http://purl.org/dc/elements/1.1/\">{}</dc:creator>\n",
309                    esc(a)
310                ));
311            }
312            if let Some(s) = &e.summary {
313                x.push_str(&format!("    <description>{}</description>\n", esc(s)));
314            }
315            if let Some(c) = &e.content_html {
316                x.push_str(&format!(
317                    "    <content:encoded xmlns:content=\"http://purl.org/rss/1.0/modules/content/\"><![CDATA[{}]]></content:encoded>\n",
318                    c.replace("]]>", "]]]]><![CDATA[>")
319                ));
320            }
321            for t in &e.tags {
322                x.push_str(&format!("    <category>{}</category>\n", esc(t)));
323            }
324            x.push_str("  </item>\n");
325        }
326        x.push_str("</channel>\n</rss>\n");
327        x
328    }
329
330    /// Atom 1.0.
331    pub fn to_atom(&self) -> String {
332        let esc = |s: &str| next_rust_view::escape_text(s).into_owned();
333        let attr = |s: &str| next_rust_view::escape_attr(s).into_owned();
334        let mut x = String::from("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n");
335        x.push_str("<feed xmlns=\"http://www.w3.org/2005/Atom\">\n");
336        x.push_str(&format!("  <title>{}</title>\n", esc(&self.title)));
337        x.push_str(&format!("  <id>{}</id>\n", esc(&self.site_url)));
338        x.push_str(&format!("  <link href=\"{}\"/>\n", attr(&self.site_url)));
339        x.push_str(&format!(
340            "  <link href=\"{}\" rel=\"self\" type=\"application/atom+xml\"/>\n",
341            attr(&self.feed_url)
342        ));
343        if let Some(d) = &self.description {
344            x.push_str(&format!("  <subtitle>{}</subtitle>\n", esc(d)));
345        }
346        if let Some(i) = &self.icon {
347            x.push_str(&format!("  <icon>{}</icon>\n", esc(i)));
348        }
349        if let Some(a) = &self.author {
350            x.push_str(&format!("  <author><name>{}</name></author>\n", esc(a)));
351        }
352        x.push_str(&format!("  <updated>{}</updated>\n", rfc3339(self.last_updated().as_deref().unwrap_or(""))));
353        for e in &self.entries {
354            x.push_str("  <entry>\n");
355            x.push_str(&format!("    <title>{}</title>\n", esc(&e.title)));
356            x.push_str(&format!("    <id>{}</id>\n", esc(e.identifier())));
357            x.push_str(&format!("    <link href=\"{}\"/>\n", attr(&e.url)));
358            let updated = e.updated.as_deref().or(e.published.as_deref()).unwrap_or("");
359            x.push_str(&format!("    <updated>{}</updated>\n", rfc3339(updated)));
360            if let Some(p) = &e.published {
361                x.push_str(&format!("    <published>{}</published>\n", rfc3339(p)));
362            }
363            if let Some(a) = e.author.as_deref().or(self.author.as_deref()) {
364                x.push_str(&format!("    <author><name>{}</name></author>\n", esc(a)));
365            }
366            if let Some(s) = &e.summary {
367                x.push_str(&format!("    <summary>{}</summary>\n", esc(s)));
368            }
369            if let Some(c) = &e.content_html {
370                x.push_str(&format!("    <content type=\"html\">{}</content>\n", esc(c)));
371            }
372            for t in &e.tags {
373                x.push_str(&format!("    <category term=\"{}\"/>\n", attr(t)));
374            }
375            x.push_str("  </entry>\n");
376        }
377        x.push_str("</feed>\n");
378        x
379    }
380
381    /// JSON Feed 1.1.
382    pub fn to_json(&self) -> String {
383        let mut items = Vec::with_capacity(self.entries.len());
384        for e in &self.entries {
385            let mut item = serde_json::Map::new();
386            item.insert("id".into(), e.identifier().into());
387            item.insert("url".into(), e.url.clone().into());
388            item.insert("title".into(), e.title.clone().into());
389            if let Some(s) = &e.summary {
390                item.insert("summary".into(), s.clone().into());
391            }
392            match &e.content_html {
393                Some(c) => item.insert("content_html".into(), c.clone().into()),
394                None => item.insert("content_text".into(), e.summary.clone().unwrap_or_default().into()),
395            };
396            if let Some(p) = &e.published {
397                item.insert("date_published".into(), rfc3339(p).into());
398            }
399            if let Some(u) = &e.updated {
400                item.insert("date_modified".into(), rfc3339(u).into());
401            }
402            if let Some(i) = &e.image {
403                item.insert("image".into(), i.clone().into());
404            }
405            if !e.tags.is_empty() {
406                item.insert("tags".into(), e.tags.clone().into());
407            }
408            if let Some(a) = e.author.as_deref().or(self.author.as_deref()) {
409                item.insert("authors".into(), serde_json::json!([{ "name": a }]));
410            }
411            items.push(serde_json::Value::Object(item));
412        }
413        let mut feed = serde_json::Map::new();
414        feed.insert("version".into(), "https://jsonfeed.org/version/1.1".into());
415        feed.insert("title".into(), self.title.clone().into());
416        feed.insert("home_page_url".into(), self.site_url.clone().into());
417        feed.insert("feed_url".into(), self.feed_url.clone().into());
418        if let Some(d) = &self.description {
419            feed.insert("description".into(), d.clone().into());
420        }
421        if let Some(l) = &self.language {
422            feed.insert("language".into(), l.clone().into());
423        }
424        if let Some(i) = &self.icon {
425            feed.insert("icon".into(), i.clone().into());
426        }
427        if let Some(a) = &self.author {
428            feed.insert("authors".into(), serde_json::json!([{ "name": a }]));
429        }
430        feed.insert("items".into(), serde_json::Value::Array(items));
431        serde_json::to_string_pretty(&serde_json::Value::Object(feed)).unwrap_or_else(|_| "{}".into())
432    }
433}
434
435/// `2026-09-18` or `2026-09-18T09:30:00Z` → RFC 3339. Anything else is
436/// passed through, so an already-formatted timestamp survives.
437fn rfc3339(date: &str) -> String {
438    match parse_date(date) {
439        Some((y, m, d)) if date.len() == 10 => format!("{y:04}-{m:02}-{d:02}T00:00:00Z"),
440        _ => date.to_owned(),
441    }
442}
443
444/// `2026-09-18` → `Fri, 18 Sep 2026 00:00:00 +0000` (RSS wants RFC 822).
445fn rfc2822(date: &str) -> Option<String> {
446    let (y, m, d) = parse_date(date)?;
447    let time = if date.len() > 10 { date.get(11..19).unwrap_or("00:00:00").to_owned() } else { "00:00:00".into() };
448    const DAYS: [&str; 7] = ["Thu", "Fri", "Sat", "Sun", "Mon", "Tue", "Wed"];
449    const MONTHS: [&str; 12] = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
450    // Days since 1970-01-01, which was a Thursday.
451    let days = days_from_civil(y as i64, m as i64, d as i64);
452    let weekday = DAYS[days.rem_euclid(7) as usize];
453    Some(format!("{weekday}, {d:02} {} {y:04} {time} +0000", MONTHS[(m - 1) as usize]))
454}
455
456fn parse_date(date: &str) -> Option<(u32, u32, u32)> {
457    let bytes = date.as_bytes();
458    if bytes.len() < 10 || bytes[4] != b'-' || bytes[7] != b'-' {
459        return None;
460    }
461    let y = date.get(0..4)?.parse().ok()?;
462    let m: u32 = date.get(5..7)?.parse().ok()?;
463    let d: u32 = date.get(8..10)?.parse().ok()?;
464    (1..=12).contains(&m).then_some(())?;
465    (1..=31).contains(&d).then_some(())?;
466    Some((y, m, d))
467}
468
469/// Days from 1970-01-01 (Howard Hinnant's algorithm, as in `http_date`).
470fn days_from_civil(y: i64, m: i64, d: i64) -> i64 {
471    let y = if m <= 2 { y - 1 } else { y };
472    let era = if y >= 0 { y } else { y - 399 } / 400;
473    let yoe = y - era * 400;
474    let mp = (m + 9) % 12;
475    let doy = (153 * mp + 2) / 5 + d - 1;
476    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
477    era * 146_097 + doe - 719_468
478}
479
480#[cfg(test)]
481mod tests {
482    use super::*;
483
484    fn feed() -> Feed {
485        Feed::new("Next Rust", "https://next-rust.dev", "https://next-rust.dev/feed.xml")
486            .description("Notes from the framework")
487            .language("en")
488            .author("The Next Rust team")
489            .entry(
490                FeedEntry::new("https://next-rust.dev/blog/one", "One & two")
491                    .summary("A <summary>")
492                    .content_html("<p>Body</p>")
493                    .published("2026-09-18")
494                    .tag("rust"),
495            )
496            .entry(FeedEntry::new("https://next-rust.dev/blog/older", "Older").published("2026-01-02T08:30:00Z"))
497    }
498
499    #[test]
500    fn rss_escapes_and_dates_are_rfc2822() {
501        let rss = feed().to_rss();
502        assert!(rss.contains("<title>One &amp; two</title>"), "{rss}");
503        assert!(rss.contains("<description>A &lt;summary&gt;</description>"), "{rss}");
504        assert!(rss.contains("<![CDATA[<p>Body</p>]]>"), "{rss}");
505        // 2026-09-18 is a Friday.
506        assert!(rss.contains("<pubDate>Fri, 18 Sep 2026 00:00:00 +0000</pubDate>"), "{rss}");
507        assert!(rss.contains("<lastBuildDate>Fri, 18 Sep 2026 00:00:00 +0000</lastBuildDate>"), "{rss}");
508        assert!(rss.contains("rel=\"self\""), "{rss}");
509        assert!(rss.contains("<category>rust</category>"), "{rss}");
510    }
511
512    #[test]
513    fn atom_uses_rfc3339_and_keeps_full_timestamps() {
514        let atom = feed().to_atom();
515        assert!(atom.contains("<published>2026-09-18T00:00:00Z</published>"), "{atom}");
516        assert!(atom.contains("<published>2026-01-02T08:30:00Z</published>"), "{atom}");
517        assert!(atom.contains("<updated>2026-09-18T00:00:00Z</updated>"), "{atom}");
518        assert!(atom.contains("<content type=\"html\">&lt;p&gt;Body&lt;/p&gt;</content>"), "{atom}");
519        assert!(atom.contains("<author><name>The Next Rust team</name></author>"), "{atom}");
520    }
521
522    #[test]
523    fn json_feed_has_the_required_fields() {
524        let json: serde_json::Value = serde_json::from_str(&feed().to_json()).expect("valid JSON");
525        assert_eq!(json["version"], "https://jsonfeed.org/version/1.1");
526        assert_eq!(json["feed_url"], "https://next-rust.dev/feed.xml");
527        assert_eq!(json["items"][0]["title"], "One & two");
528        assert_eq!(json["items"][0]["content_html"], "<p>Body</p>");
529        assert_eq!(json["items"][0]["date_published"], "2026-09-18T00:00:00Z");
530        assert_eq!(json["items"][0]["authors"][0]["name"], "The Next Rust team");
531        assert_eq!(json["items"][0]["tags"][0], "rust");
532    }
533
534    #[test]
535    fn weekdays_are_right_across_centuries() {
536        assert!(rfc2822("2000-02-29").unwrap().starts_with("Tue, 29 Feb 2000"));
537        assert!(rfc2822("1970-01-01").unwrap().starts_with("Thu, 01 Jan 1970"));
538        assert!(rfc2822("2026-12-25").unwrap().starts_with("Fri, 25 Dec 2026"));
539        assert_eq!(rfc2822("not-a-date"), None);
540        assert_eq!(rfc3339("whenever"), "whenever");
541    }
542}