Skip to main content

rustango_cms/
richtext.rs

1//! `| richtext` Tera filter — `{{ page.body | richtext }}`.
2//!
3//! The filter rewrites the storage shape the editor
4//! emits — `<a linktype="page" id="42">…</a>` — into the renderable
5//! shape — `<a href="/about/team">…</a>` — at template-render time.
6//! Storing page-id references in rich-text bodies means anchors keep
7//! working when pages move.
8//!
9//! Concretely, the filter:
10//!   - rewrites `<a linktype="page" id="N">` → `<a href="<page url>">`
11//!   - rewrites `<a linktype="media" id="N">` → `<a href="<media url>">`
12//!   - marks the output safe (`is_safe = true`) so Tera doesn't
13//!     double-escape on top of the editor's already-HTML-escaped
14//!     content
15//!   - missing / unresolvable ids fall back to `href="#"` — the
16//!     anchor still renders, just inert (a "broken link"
17//!     placeholder)
18//!
19//! Resolution maps:
20//!   - **Page urls** — reuses [`crate::page_url`]'s thread-local
21//!     (populated by the public-render handler via
22//!     [`crate::page_url::install`] in [`crate::render`](mod@crate::render)). Any
23//!     extension-level `*_id` field that pointed at a page is
24//!     resolvable through here too.
25//!   - **Everything else** — anchors the filter cannot resolve are left
26//!     intact, and [`resolve_internal_links`] rewrites them over the
27//!     page's final HTML, where stream blocks' links are visible too:
28//!     one query for the pages, one for the media.
29//!
30//! ## Usage
31//!
32//! ```text
33//! {{ extension.hero_body | richtext }}
34//! ```
35//!
36//! ## Implementation note
37//!
38//! Avoids pulling `html5ever` / `ammonia` in for what's effectively a
39//! constrained-shape rewrite. The editor's output for internal links
40//! is well-formed (always `<a` followed by whitespace + a single
41//! `>`-terminated open tag), so a small string scanner that walks
42//! `<a ...>` openings and edits the attribute set in place is
43//! sufficient. Anything that doesn't match `linktype="page|media"` +
44//! `id="…"` is left verbatim — including arbitrary editor-emitted
45//! markup like `<img>` / `<ul>` / `<strong>`.
46
47use std::collections::HashMap;
48
49use tera::{Filter, Tera, Value};
50
51/// Register the `richtext` Tera filter. Called once at Tera setup —
52/// wired from [`crate::urls::register_tera_helpers`].
53pub fn register_tera_filter(tera: &mut Tera) {
54    tera.register_filter("richtext", RichtextFilter);
55}
56
57struct RichtextFilter;
58
59impl Filter for RichtextFilter {
60    fn filter(&self, value: &Value, _args: &HashMap<String, Value>) -> tera::Result<Value> {
61        let html = value.as_str().unwrap_or("");
62        // Resolve what the render already knows (pages an extension
63        // `*_id` field points at); leave every other anchor intact for
64        // `resolve_internal_links`, which sees the whole page.
65        Ok(Value::String(expand_db_html(html, &|kind, id| match kind {
66            LinkKind::Page => crate::page_url::lookup(id),
67            LinkKind::Media => None,
68        }, false)))
69    }
70    fn is_safe(&self) -> bool {
71        true
72    }
73}
74
75/// Walk `html` and rewrite every `<a linktype="page|media" id="N">`
76/// opening tag in place. Other markup (text, non-`<a>` tags,
77/// already-resolved `<a href=…>` without `linktype`) passes through
78/// unchanged.
79/// Whether an anchor links a page or a media item (a document).
80#[derive(Clone, Copy, PartialEq, Eq)]
81enum LinkKind {
82    Page,
83    Media,
84}
85
86/// `resolve` maps an anchor to its URL. `fallback` decides what happens
87/// to an anchor it cannot resolve: `true` rewrites it to `href="#"`,
88/// `false` leaves it verbatim for a later pass.
89fn expand_db_html(html: &str, resolve: &dyn Fn(LinkKind, i64) -> Option<String>, fallback: bool) -> String {
90    let mut out = String::with_capacity(html.len());
91    let mut cursor = 0;
92    while cursor < html.len() {
93        // Find the next `<a` and confirm the char after it is
94        // whitespace (filters out `<address>`, `<area>`, `<aside>`).
95        let Some(rel) = html[cursor..].find("<a") else {
96            out.push_str(&html[cursor..]);
97            break;
98        };
99        let open = cursor + rel;
100        out.push_str(&html[cursor..open]);
101        let after_a = open + 2;
102        let next_ch = html[after_a..].chars().next();
103        if !matches!(next_ch, Some(c) if c.is_ascii_whitespace()) {
104            // `<an…>` or `<area>` etc. — keep `<a` verbatim and resume.
105            out.push_str("<a");
106            cursor = after_a;
107            continue;
108        }
109        // Find the `>` that closes this opening tag. The editor never
110        // emits `>` inside an attribute value, so a simple search is
111        // safe for the rewrite-target shape.
112        let Some(close_rel) = html[after_a..].find('>') else {
113            // Malformed tail — copy verbatim and stop.
114            out.push_str(&html[open..]);
115            break;
116        };
117        let close = after_a + close_rel;
118        let attrs = &html[after_a..close];
119        match rewrite_anchor(attrs, resolve, fallback) {
120            Some(new_open) => out.push_str(&new_open),
121            None => out.push_str(&html[open..=close]),
122        }
123        cursor = close + 1;
124    }
125    out
126}
127
128/// The `(kind, id)` an internal-link anchor points at, from the attribute
129/// slice of its opening tag. `None` for any other anchor.
130fn link_target(attrs: &str) -> Option<(LinkKind, i64)> {
131    let kind = match attr_value(attrs, "linktype")? {
132        "page" => LinkKind::Page,
133        "media" => LinkKind::Media,
134        _ => return None,
135    };
136    let id: i64 = attr_value(attrs, "id")?.parse().ok()?;
137    (id > 0).then_some((kind, id))
138}
139
140/// The attribute slices of every `<a …>` opening tag in `html`.
141fn anchor_attrs(html: &str) -> impl Iterator<Item = &str> {
142    let mut cursor = 0;
143    std::iter::from_fn(move || {
144        while let Some(rel) = html.get(cursor..)?.find("<a") {
145            let after_a = cursor + rel + 2;
146            let is_anchor = html[after_a..].chars().next().is_some_and(|c| c.is_ascii_whitespace());
147            let close = html[after_a..].find('>').map(|c| after_a + c);
148            cursor = close.map_or(html.len(), |c| c + 1);
149            if is_anchor {
150                if let Some(close) = close {
151                    return Some(&html[after_a..close]);
152                }
153            }
154        }
155        None
156    })
157}
158
159/// Rewrite every internal-link anchor in a rendered page.
160///
161/// Rich text stores links as `<a linktype="page|media" id="N">` so they
162/// survive moves. The `| richtext` filter only knows the pages an
163/// extension field points at, and stream blocks are rendered before any
164/// lookup is available, so the page's final HTML is where every anchor is
165/// visible at once. One query per kind resolves them; an id that no
166/// longer exists becomes an inert `href="#"`.
167pub async fn resolve_internal_links(pool: &rustango::sql::Pool, html: String) -> String {
168    use rustango::core::Column as _;
169    use rustango::sql::FetcherPool as _;
170    if !html.contains("linktype=") {
171        return html;
172    }
173    let (mut page_ids, mut media_ids) = (Vec::new(), Vec::new());
174    for (kind, id) in anchor_attrs(&html).filter_map(link_target) {
175        match kind {
176            LinkKind::Page => page_ids.push(id),
177            LinkKind::Media => media_ids.push(id),
178        }
179    }
180    for ids in [&mut page_ids, &mut media_ids] {
181        ids.sort_unstable();
182        ids.dedup();
183    }
184    let mut pages = HashMap::new();
185    if !page_ids.is_empty() {
186        match crate::page::Page::objects()
187            .where_(crate::page::Page::id.is_in(page_ids))
188            .fetch(pool)
189            .await
190        {
191            Ok(rows) => pages.extend(rows.into_iter().filter_map(|p| p.id.get().copied().map(|id| (id, p.url_path)))),
192            Err(e) => tracing::warn!(target: "rustango_cms::richtext", error = %e, "page link lookup failed"),
193        }
194    }
195    let mut media = HashMap::new();
196    if !media_ids.is_empty() {
197        match crate::media::Media::objects()
198            .where_(crate::media::Media::id.is_in(media_ids))
199            .fetch(pool)
200            .await
201        {
202            Ok(rows) => media.extend(rows.into_iter().filter_map(|m| m.id.get().copied().map(|id| (id, m.public_url())))),
203            Err(e) => tracing::warn!(target: "rustango_cms::richtext", error = %e, "media link lookup failed"),
204        }
205    }
206    expand_db_html(
207        &html,
208        &|kind, id| match kind {
209            LinkKind::Page => pages.get(&id).cloned(),
210            LinkKind::Media => media.get(&id).cloned(),
211        },
212        true,
213    )
214}
215
216/// Inspect the attribute slice of a `<a … >` opening tag. If it
217/// carries `linktype="page"` + `id="N"` (or `linktype="media"`),
218/// return the rewritten opening tag with `href` resolved. Otherwise
219/// return `None` so the caller keeps the original.
220///
221/// Other attributes on the anchor (`class`, `target`, `rel`, etc.)
222/// are preserved verbatim; `linktype` and `id` are stripped from the
223/// output since they're internal markers, not browser-renderable.
224fn rewrite_anchor(
225    attrs: &str,
226    resolve: &dyn Fn(LinkKind, i64) -> Option<String>,
227    fallback: bool,
228) -> Option<String> {
229    let (kind, id) = link_target(attrs)?;
230    let href = match resolve(kind, id) {
231        Some(url) => url,
232        None if fallback => "#".to_owned(),
233        None => return None,
234    };
235    let extra = remaining_attrs(attrs, &["linktype", "id"]);
236    let extra_trim = extra.trim();
237    if extra_trim.is_empty() {
238        Some(format!(r#"<a href="{}">"#, html_attr_escape(&href)))
239    } else {
240        Some(format!(
241            r#"<a href="{}" {}>"#,
242            html_attr_escape(&href),
243            extra_trim
244        ))
245    }
246}
247
248/// Read the value of `name="value"` from `attrs`. Accepts double-
249/// or single-quoted strings. Returns `None` when the attribute is
250/// absent. False-positive risk (`name` appearing inside an unrelated
251/// attribute value) is negligible for editor-emitted richtext.
252fn attr_value<'a>(attrs: &'a str, name: &str) -> Option<&'a str> {
253    for (open, close) in [("\"", '"'), ("'", '\'')] {
254        let pattern = format!("{name}={open}");
255        let mut search = attrs;
256        let mut absolute_offset = 0usize;
257        while let Some(start) = search.find(&pattern) {
258            // Confirm `name` is at an attribute boundary — preceded by
259            // whitespace or the start of the slice. Without this guard
260            // `id="…"` matches inside `data-id="…"`.
261            let abs_start = absolute_offset + start;
262            if abs_start > 0 {
263                let prev = attrs[..abs_start].chars().next_back();
264                if !matches!(prev, Some(c) if c.is_ascii_whitespace()) {
265                    let step = start + pattern.len();
266                    absolute_offset += step;
267                    search = &attrs[absolute_offset..];
268                    continue;
269                }
270            }
271            let value_start = abs_start + pattern.len();
272            let end_rel = attrs[value_start..].find(close)?;
273            return Some(&attrs[value_start..value_start + end_rel]);
274        }
275    }
276    None
277}
278
279/// Re-emit `attrs` with every attribute in `strip` removed. Used to
280/// drop `linktype` and `id` from the rewritten anchor while
281/// preserving everything else (`class`, `target`, `rel`, …).
282fn remaining_attrs(attrs: &str, strip: &[&str]) -> String {
283    let mut out = String::with_capacity(attrs.len());
284    let mut chars = attrs.char_indices().peekable();
285    'outer: while let Some(&(i, c)) = chars.peek() {
286        // Skip leading whitespace
287        if c.is_ascii_whitespace() {
288            out.push(c);
289            chars.next();
290            continue;
291        }
292        // Parse one attribute: name [= "value" | = 'value' | (no value)]
293        let name_start = i;
294        let mut name_end = name_start;
295        while let Some(&(j, ch)) = chars.peek() {
296            if ch == '=' || ch.is_ascii_whitespace() {
297                break;
298            }
299            name_end = j + ch.len_utf8();
300            chars.next();
301        }
302        let name = &attrs[name_start..name_end];
303        // Skip any spaces between name and `=`
304        while let Some(&(_, ch)) = chars.peek() {
305            if ch.is_ascii_whitespace() {
306                chars.next();
307            } else {
308                break;
309            }
310        }
311        // Optional `="value"` clause
312        let mut value_end = name_end;
313        if let Some(&(_, '=')) = chars.peek() {
314            chars.next();
315            while let Some(&(_, ch)) = chars.peek() {
316                if ch.is_ascii_whitespace() {
317                    chars.next();
318                } else {
319                    break;
320                }
321            }
322            let quote = match chars.peek() {
323                Some(&(_, '"')) => Some('"'),
324                Some(&(_, '\'')) => Some('\''),
325                _ => None,
326            };
327            if let Some(q) = quote {
328                chars.next(); // consume opening quote
329                while let Some(&(j, ch)) = chars.peek() {
330                    chars.next();
331                    if ch == q {
332                        value_end = j + ch.len_utf8();
333                        break;
334                    }
335                    value_end = j + ch.len_utf8();
336                }
337            } else {
338                // Unquoted value — until whitespace or end
339                while let Some(&(j, ch)) = chars.peek() {
340                    if ch.is_ascii_whitespace() {
341                        break;
342                    }
343                    value_end = j + ch.len_utf8();
344                    chars.next();
345                }
346            }
347        }
348        let chunk = &attrs[name_start..value_end];
349        if strip.iter().any(|s| name.eq_ignore_ascii_case(s)) {
350            // Drop this attribute entirely. Don't emit anything; the
351            // surrounding whitespace handling above already pads.
352            continue 'outer;
353        }
354        // Re-emit with a single leading space if `out` isn't empty
355        // and doesn't already end in whitespace.
356        if !out.is_empty() && !out.ends_with(|c: char| c.is_ascii_whitespace()) {
357            out.push(' ');
358        }
359        out.push_str(chunk);
360    }
361    out
362}
363
364/// Escape `&`, `"`, `<`, `>` for safe insertion into a `href="…"`
365/// attribute. Anchor targets come from `cms_page.url_path` (CMS-
366/// controlled) or media filenames, but the escape keeps a defense in
367/// depth in case either source ever lands with user-supplied chars.
368fn html_attr_escape(s: &str) -> String {
369    let mut out = String::with_capacity(s.len());
370    for c in s.chars() {
371        match c {
372            '&' => out.push_str("&amp;"),
373            '"' => out.push_str("&quot;"),
374            '<' => out.push_str("&lt;"),
375            '>' => out.push_str("&gt;"),
376            other => out.push(other),
377        }
378    }
379    out
380}
381
382#[cfg(test)]
383mod tests {
384    use super::*;
385    use tera::{Context, Tera};
386
387    fn fresh_tera() -> Tera {
388        let mut tera = Tera::default();
389        register_tera_filter(&mut tera);
390        tera
391    }
392
393    fn render(tera: &Tera, src: &str, body: &str) -> String {
394        let mut t = tera.clone();
395        t.add_raw_template("t.html", src).unwrap();
396        let mut ctx = Context::new();
397        ctx.insert("body", body);
398        t.render("t.html", &ctx).unwrap()
399    }
400
401    fn install_pages(pairs: &[(i64, &str)]) -> crate::page_url::PageUrlGuard {
402        let mut m = HashMap::new();
403        for (id, url) in pairs {
404            m.insert(*id, (*url).to_owned());
405        }
406        crate::page_url::install(m)
407    }
408
409    #[test]
410    fn rewrites_page_link() {
411        let _g = install_pages(&[(42, "/about/team")]);
412        let tera = fresh_tera();
413        let out = render(
414            &tera,
415            "{{ body | richtext }}",
416            r#"<p>See <a linktype="page" id="42">the team</a>.</p>"#,
417        );
418        assert_eq!(out, r#"<p>See <a href="/about/team">the team</a>.</p>"#,);
419    }
420
421    #[test]
422    fn an_unknown_page_is_left_for_the_page_pass() {
423        let _g = install_pages(&[(1, "/known")]);
424        let tera = fresh_tera();
425        let out = render(
426            &tera,
427            "{{ body | richtext }}",
428            r#"<a linktype="page" id="999">missing</a>"#,
429        );
430        assert_eq!(out, r#"<a linktype="page" id="999">missing</a>"#);
431    }
432
433    #[test]
434    fn the_page_pass_rewrites_page_and_media_links_and_inerts_the_rest() {
435        let html = r#"<a linktype="page" id="3" class="x">p</a> <a linktype="media" id="7">pdf</a> <a linktype="media" id="8">gone</a>"#;
436        let out = super::expand_db_html(
437            html,
438            &|kind, id| match (kind, id) {
439                (super::LinkKind::Page, 3) => Some("/about".to_owned()),
440                (super::LinkKind::Media, 7) => Some("/__media__/raw/7".to_owned()),
441                _ => None,
442            },
443            true,
444        );
445        assert_eq!(
446            out,
447            r##"<a href="/about" class="x">p</a> <a href="/__media__/raw/7">pdf</a> <a href="#">gone</a>"##
448        );
449    }
450
451    #[test]
452    fn internal_link_targets_are_collected_from_every_anchor() {
453        let html = r#"<p><a href="/plain">x</a><a linktype="page" id="4">a</a><abbr>n</abbr><a linktype="media" id="9">b</a><a linktype="other" id="1">c</a></p>"#;
454        let found: Vec<_> = super::anchor_attrs(html).filter_map(super::link_target).collect();
455        assert!(found == vec![(super::LinkKind::Page, 4), (super::LinkKind::Media, 9)]);
456    }
457
458    #[test]
459    fn with_no_map_the_filter_leaves_internal_links_intact() {
460        let tera = fresh_tera();
461        let out = render(
462            &tera,
463            "{{ body | richtext }}",
464            r#"<a linktype="page" id="5">x</a><a linktype="media" id="6">y</a>"#,
465        );
466        assert_eq!(out, r#"<a linktype="page" id="5">x</a><a linktype="media" id="6">y</a>"#);
467    }
468
469    #[test]
470    fn preserves_unrelated_anchors() {
471        let _g = install_pages(&[]);
472        let tera = fresh_tera();
473        let html = r#"<a href="https://example.com" class="ext">link</a>"#;
474        let out = render(&tera, "{{ body | richtext }}", html);
475        // `linktype` absent → tag passes through verbatim.
476        assert_eq!(out, html);
477    }
478
479    #[test]
480    fn preserves_extra_attributes_on_rewritten_anchor() {
481        let _g = install_pages(&[(8, "/services")]);
482        let tera = fresh_tera();
483        let out = render(
484            &tera,
485            "{{ body | richtext }}",
486            r#"<a linktype="page" id="8" class="cta" target="_blank">go</a>"#,
487        );
488        assert_eq!(
489            out,
490            r#"<a href="/services" class="cta" target="_blank">go</a>"#,
491        );
492    }
493
494    #[test]
495    fn handles_attribute_order_id_first() {
496        let _g = install_pages(&[(3, "/blog")]);
497        let tera = fresh_tera();
498        let out = render(
499            &tera,
500            "{{ body | richtext }}",
501            r#"<a id="3" linktype="page">blog</a>"#,
502        );
503        assert_eq!(out, r#"<a href="/blog">blog</a>"#);
504    }
505
506    #[test]
507    fn handles_multiple_links_in_one_body() {
508        let _g = install_pages(&[(1, "/one"), (2, "/two")]);
509        let tera = fresh_tera();
510        let out = render(
511            &tera,
512            "{{ body | richtext }}",
513            r#"<p>A: <a linktype="page" id="1">one</a> B: <a linktype="page" id="2">two</a></p>"#,
514        );
515        assert_eq!(
516            out,
517            r#"<p>A: <a href="/one">one</a> B: <a href="/two">two</a></p>"#,
518        );
519    }
520
521    #[test]
522    fn output_is_marked_safe() {
523        // If `is_safe` weren't true, Tera autoescape on `.html`
524        // templates would convert `<` → `&lt;`. The fact that the
525        // rendered output contains a literal `<a` proves the filter's
526        // output is treated as raw HTML.
527        let _g = install_pages(&[(1, "/x")]);
528        let tera = fresh_tera();
529        let out = render(
530            &tera,
531            "{{ body | richtext }}",
532            r#"<a linktype="page" id="1">x</a>"#,
533        );
534        assert!(out.starts_with("<a "), "expected literal `<a`, got `{out}`");
535    }
536
537    #[test]
538    fn does_not_misfire_on_address_or_area_tags() {
539        let _g = install_pages(&[]);
540        let tera = fresh_tera();
541        let html = r#"<address>123 Main St</address><area shape="rect">"#;
542        let out = render(&tera, "{{ body | richtext }}", html);
543        assert_eq!(out, html);
544    }
545
546    #[test]
547    fn skips_anchor_without_linktype() {
548        let _g = install_pages(&[(1, "/should-not-resolve")]);
549        let tera = fresh_tera();
550        let html = r#"<a id="1" class="x">no linktype</a>"#;
551        let out = render(&tera, "{{ body | richtext }}", html);
552        assert_eq!(out, html);
553    }
554
555    #[test]
556    fn ignores_id_inside_unrelated_attribute_name() {
557        // `data-id="9"` must not be picked up as the anchor's id.
558        let _g = install_pages(&[(9, "/wrong"), (5, "/right")]);
559        let tera = fresh_tera();
560        let out = render(
561            &tera,
562            "{{ body | richtext }}",
563            r#"<a linktype="page" data-id="9" id="5">x</a>"#,
564        );
565        assert_eq!(out, r#"<a href="/right" data-id="9">x</a>"#,);
566    }
567
568    #[test]
569    fn empty_body_returns_empty() {
570        let tera = fresh_tera();
571        let out = render(&tera, "{{ body | richtext }}", "");
572        assert_eq!(out, "");
573    }
574
575    #[test]
576    fn html_attr_escape_handles_quotes() {
577        let _g = install_pages(&[(1, r#"/with"quote"#)]);
578        let tera = fresh_tera();
579        let out = render(
580            &tera,
581            "{{ body | richtext }}",
582            r#"<a linktype="page" id="1">x</a>"#,
583        );
584        // The href value was escaped — the `"` in the URL becomes
585        // `&quot;` so the attribute syntax remains valid.
586        assert!(out.contains(r#"href="/with&quot;quote""#), "got `{out}`");
587    }
588}