Skip to main content

rustango_cms/
snippet_render.rs

1//! `snippet_html(type=…, id=N)` Tera helper — per-snippet template
2//! rendering.
3//!
4//! Pairs with [`crate::library::LibraryTypeHandler::render_template`]:
5//! a page template asks for a row of such a type by `(type, id)` and
6//! gets it rendered through that template.
7//!
8//! A type may instead let each element name its own template, by
9//! returning `true` from
10//! [`allows_element_template`](crate::library::LibraryTypeHandler::allows_element_template);
11//! the name then comes from that row's `data.template` and falls back
12//! to the type's own. That is what makes an element the whole unit —
13//! its content and its markup travel together — and it needs no
14//! migration, because `cms_snippet.data` is already free-form JSON.
15//!
16//! The name resolves against the Tera instance handed to [`fill`],
17//! which the public router has already overlaid with the tenant's
18//! templates (`router.rs` `tera_for`). So a template written into
19//! `templates_tenants/<org>/…` — by the admin editor or the
20//! `write_template` MCP tool — is renderable by name here, with no
21//! per-render `add_raw_template`.
22//!
23//! Rendering is lazy and scoped (#731). While the page renders, each
24//! `snippet_html(...)` call is recorded and leaves a marker; afterwards
25//! [`fill`] fetches only the recorded rows — one query per type — renders
26//! them and puts the HTML in place of the markers. A page pays for the
27//! snippets it shows, not for every row of every templated type.
28//!
29//! ## Usage in templates
30//!
31//! ```text
32//! {{ snippet_html(type="Category", id=4) | safe }}
33//! ```
34//!
35//! Unknown type, unknown id, or a type without a template → empty. Use
36//! the call's output as it is: the marker is replaced in the finished
37//! page, so a filter applied to it (`| escape`, `| truncate`) mangles the
38//! marker instead of the snippet.
39
40use std::cell::RefCell;
41use std::collections::{BTreeMap, BTreeSet, HashMap};
42
43use tera::{Function, Tera, Value};
44
45/// Composite key for one snippet: `(type name, id)`.
46type Key = (String, i64);
47
48/// How deep a snippet's template may itself call `snippet_html`.
49const MAX_NESTING: usize = 4;
50
51/// Ceiling on the HTML snippets may add to one page. Fan-out nesting
52/// (a snippet that names 50 snippets that each name 50 more) grows
53/// geometrically; past this the remaining markers render empty.
54const MAX_FILLED_BYTES: usize = 4 * 1024 * 1024;
55
56thread_local! {
57    static RECORDING: RefCell<Option<BTreeSet<Key>>> = const { RefCell::new(None) };
58}
59
60/// RAII guard: while in scope, `snippet_html(...)` records its key and
61/// returns a marker. [`SnippetRecorder::take`] ends the recording.
62#[must_use = "the guard stops recording on drop; bind it to a local"]
63pub struct SnippetRecorder {
64    _priv: (),
65}
66
67impl SnippetRecorder {
68    /// The keys recorded so far, ending the recording.
69    pub fn take(self) -> BTreeSet<Key> {
70        RECORDING.with(|cell| cell.borrow_mut().take()).unwrap_or_default()
71    }
72}
73
74impl Drop for SnippetRecorder {
75    fn drop(&mut self) {
76        RECORDING.with(|cell| *cell.borrow_mut() = None);
77    }
78}
79
80/// Start recording `snippet_html(...)` calls on this thread. Bind it
81/// right before `tera.render`, with no `.await` in between.
82pub fn record() -> SnippetRecorder {
83    RECORDING.with(|cell| *cell.borrow_mut() = Some(BTreeSet::new()));
84    SnippetRecorder { _priv: () }
85}
86
87/// Register the `snippet_html` Tera function. Wired from
88/// [`crate::urls::register_tera_helpers`].
89pub fn register_tera_function(tera: &mut Tera) {
90    tera.register_function("snippet_html", SnippetHtmlFn);
91}
92
93/// The placeholder `snippet_html` leaves for [`fill`].
94fn marker(type_name: &str, id: i64) -> String {
95    format!("<!--rcms-snippet:{type_name}:{id}-->")
96}
97
98/// A type name the marker can carry: anything that cannot close the
99/// HTML comment or break the `:<id>` suffix parse.
100fn valid_type_name(ty: &str) -> bool {
101    !ty.is_empty() && !ty.contains("--") && !ty.contains('>') && !ty.contains('\n')
102}
103
104fn marker_re() -> &'static regex::Regex {
105    static RE: std::sync::OnceLock<regex::Regex> = std::sync::OnceLock::new();
106    RE.get_or_init(|| regex::Regex::new(r"<!--rcms-snippet:([^\n>]+?):([0-9]+)-->").expect("marker regex"))
107}
108
109/// `is_safe = true`: the output is a marker that [`fill`] replaces with
110/// the snippet template's own HTML; autoescaping would mangle both.
111struct SnippetHtmlFn;
112
113impl Function for SnippetHtmlFn {
114    fn call(&self, args: &HashMap<String, Value>) -> tera::Result<Value> {
115        let ty = args.get("type").and_then(Value::as_str).unwrap_or("");
116        let id = args.get("id").and_then(Value::as_i64).unwrap_or(0);
117        if !valid_type_name(ty) || id <= 0 {
118            return Ok(Value::String(String::new()));
119        }
120        let recorded = RECORDING.with(|cell| {
121            cell.borrow_mut()
122                .as_mut()
123                .map(|keys| keys.insert((ty.to_owned(), id)))
124                .is_some()
125        });
126        Ok(Value::String(if recorded { marker(ty, id) } else { String::new() }))
127    }
128    fn is_safe(&self) -> bool {
129        true
130    }
131}
132
133/// Render the `keys` a page recorded and put each snippet's HTML in
134/// place of its marker in `html`. Snippets whose own templates call
135/// `snippet_html` are filled the same way, up to [`MAX_NESTING`] levels.
136///
137/// Best effort: a failed fetch or template render leaves that snippet
138/// empty and logs it; the rest of the page still ships.
139pub async fn fill(
140    pool: &rustango::sql::Pool,
141    tera: &Tera,
142    locale_id: Option<i64>,
143    html: String,
144    mut keys: BTreeSet<Key>,
145) -> String {
146    let mut rendered: HashMap<Key, String> = HashMap::new();
147    for _ in 0..MAX_NESTING {
148        keys.retain(|k| !rendered.contains_key(k));
149        if keys.is_empty() {
150            break;
151        }
152        let rows = fetch_rows(pool, locale_id, &keys).await;
153        // Render with a recorder on: a snippet template may call
154        // `snippet_html` itself. No await until `take`.
155        let recorder = record();
156        for key in std::mem::take(&mut keys) {
157            let out = rows
158                .get(&key)
159                .and_then(|(template, value)| render_one(tera, &key, template, value))
160                .unwrap_or_default();
161            rendered.insert(key, out);
162        }
163        keys = recorder.take();
164    }
165    let mut expanded: HashMap<Key, String> = HashMap::new();
166    let mut budget = MAX_FILLED_BYTES;
167    let mut stack = Vec::new();
168    expand_markers(&html, &rendered, &mut expanded, &mut stack, &mut budget)
169}
170
171/// Replace every marker in `html` with its snippet's HTML, itself
172/// expanded. A snippet that (indirectly) names itself gets an empty
173/// slot for the repeat; markers with no rendered snippet (unknown, or
174/// nested past [`MAX_NESTING`]) are removed; past `budget` bytes the
175/// rest render empty.
176fn expand_markers(
177    html: &str,
178    rendered: &HashMap<Key, String>,
179    expanded: &mut HashMap<Key, String>,
180    stack: &mut Vec<Key>,
181    budget: &mut usize,
182) -> String {
183    let re = marker_re();
184    if !html.contains("<!--rcms-snippet:") {
185        return html.to_owned();
186    }
187    let mut out = String::with_capacity(html.len());
188    let mut last = 0;
189    for caps in re.captures_iter(html) {
190        let whole = caps.get(0).expect("match");
191        out.push_str(&html[last..whole.start()]);
192        last = whole.end();
193        let Ok(id) = caps[2].parse::<i64>() else { continue };
194        let key = (caps[1].to_owned(), id);
195        if stack.contains(&key) {
196            continue;
197        }
198        let piece = if let Some(done) = expanded.get(&key) {
199            done.clone()
200        } else if let Some(raw) = rendered.get(&key) {
201            stack.push(key.clone());
202            let done = expand_markers(raw, rendered, expanded, stack, budget);
203            stack.pop();
204            expanded.insert(key, done.clone());
205            done
206        } else {
207            String::new()
208        };
209        if piece.len() > *budget {
210            *budget = 0;
211            continue;
212        }
213        *budget -= piece.len();
214        out.push_str(&piece);
215    }
216    out.push_str(&html[last..]);
217    out
218}
219
220/// Fetch and prepare the recorded rows: `(template name, snippet JSON)`
221/// per key, translations applied. Keys of a type with no template, or of
222/// a missing row, are absent.
223async fn fetch_rows(
224    pool: &rustango::sql::Pool,
225    locale_id: Option<i64>,
226    keys: &BTreeSet<Key>,
227) -> HashMap<Key, (String, Value)> {
228    use rustango::core::Column as _;
229    use rustango::sql::FetcherPool as _;
230    let mut by_type: BTreeMap<&str, Vec<i64>> = BTreeMap::new();
231    for (ty, id) in keys {
232        by_type.entry(ty.as_str()).or_default().push(*id);
233    }
234    let mut out = HashMap::new();
235    for (type_name, ids) in by_type {
236        let Some(handler) = crate::library::find_handler(type_name) else {
237            continue;
238        };
239        let type_default = handler.render_template();
240        let per_element = handler.allows_element_template();
241        if type_default.is_none() && !per_element {
242            continue;
243        }
244        let rows = match crate::snippet::Snippet::objects()
245            .where_(crate::snippet::Snippet::type_name.eq(type_name.to_owned()))
246            .where_(crate::snippet::Snippet::id.is_in(ids.clone()))
247            .fetch(pool)
248            .await
249        {
250            Ok(r) => r,
251            Err(e) => {
252                tracing::warn!(
253                    target: "rustango_cms::snippet_render",
254                    error = %e,
255                    type_name = %type_name,
256                    "snippet fetch failed for type; leaving its slots empty",
257                );
258                continue;
259            }
260        };
261        // #409 — per-locale field overrides, one batched fetch.
262        let translations = match locale_id {
263            Some(lid) => crate::snippet_translation::fetch_for_snippets(pool, &ids, lid)
264                .await
265                .unwrap_or_default(),
266            None => HashMap::new(),
267        };
268        for row in rows {
269            let Some(id) = row.id.get().copied() else {
270                continue;
271            };
272            let mut value = serde_json::to_value(&row).unwrap_or(Value::Null);
273            if let Some(overrides) = translations.get(&id) {
274                apply_overrides(&mut value, overrides);
275            }
276            // After the translation overlay: a locale may override
277            // `data.template` to swap markup per language.
278            let template = per_element
279                .then(|| element_template(&value))
280                .flatten()
281                .or_else(|| type_default.map(str::to_owned));
282            // A per-element type whose row names nothing: not an error.
283            if let Some(template) = template {
284                out.insert((type_name.to_owned(), id), (template, value));
285            }
286        }
287    }
288    out
289}
290
291fn render_one(tera: &Tera, key: &Key, template: &str, value: &Value) -> Option<String> {
292    let mut ctx = tera::Context::new();
293    ctx.insert("snippet", value);
294    match tera.render(template, &ctx) {
295        Ok(html) => Some(html),
296        Err(e) => {
297            tracing::warn!(
298                target: "rustango_cms::snippet_render",
299                error = %e,
300                type_name = %key.0,
301                id = key.1,
302                template = %template,
303                "snippet template render failed; leaving slot empty",
304            );
305            None
306        }
307    }
308}
309
310/// The template an individual element names in its `data.template`,
311/// for types that opted in via
312/// [`crate::library::LibraryTypeHandler::allows_element_template`].
313///
314/// The name must pass [`crate::tenant_templates::safe_name`], the rule for
315/// every editor-supplied template name: relative, `.html`, no
316/// traversal. Tera resolves names against its registered set, so a bad
317/// name could not load a file anyway; refusing it keeps a broken value
318/// from looking like a working one.
319fn element_template(snippet_value: &Value) -> Option<String> {
320    let name = snippet_value.get("data")?.get("template")?.as_str()?;
321    crate::tenant_templates::safe_name(name).ok()
322}
323
324/// Apply per-locale translation `overrides` onto a snippet's JSON value.
325/// Top-level fields (`title`, `body_markdown`, …) are replaced
326/// in place; a `data.<key>` path writes into the snippet's `data`
327/// object. Non-object values + missing `data` are created as needed.
328fn apply_overrides(value: &mut Value, overrides: &HashMap<String, String>) {
329    let Some(obj) = value.as_object_mut() else {
330        return;
331    };
332    for (path, v) in overrides {
333        if let Some(key) = path.strip_prefix("data.") {
334            let data = obj
335                .entry("data")
336                .or_insert_with(|| Value::Object(serde_json::Map::new()));
337            if let Some(map) = data.as_object_mut() {
338                map.insert(key.to_owned(), Value::String(v.clone()));
339            }
340        } else {
341            obj.insert(path.clone(), Value::String(v.clone()));
342        }
343    }
344}
345
346#[cfg(test)]
347mod tests {
348    use super::*;
349    use tera::{Context, Tera};
350
351    fn fresh_tera() -> Tera {
352        let mut tera = Tera::default();
353        register_tera_function(&mut tera);
354        tera
355    }
356
357    fn render(tera: &Tera, src: &str) -> String {
358        let mut t = tera.clone();
359        t.add_raw_template("t.html", src).unwrap();
360        t.render("t.html", &Context::new()).unwrap()
361    }
362
363    fn with_template(name: &str) -> Value {
364        serde_json::json!({ "data": { "template": name } })
365    }
366
367    #[test]
368    fn element_template_reads_a_plain_relative_name() {
369        assert_eq!(
370            element_template(&with_template("widgets/donations.html")),
371            Some("widgets/donations.html".to_owned())
372        );
373    }
374
375    #[test]
376    fn element_template_trims_surrounding_whitespace() {
377        assert_eq!(
378            element_template(&with_template("  widgets/a.html \n")),
379            Some("widgets/a.html".to_owned())
380        );
381    }
382
383    #[test]
384    fn element_template_absent_when_unset_or_wrong_shape() {
385        assert_eq!(element_template(&serde_json::json!({})), None);
386        assert_eq!(element_template(&serde_json::json!({"data": {}})), None);
387        // A non-string `template` is a malformed row, not a name.
388        assert_eq!(
389            element_template(&serde_json::json!({"data": {"template": 7}})),
390            None
391        );
392    }
393
394    #[test]
395    fn element_template_refuses_traversal_and_absolute_names() {
396        for bad in [
397            "",
398            "   ",
399            "/etc/passwd",
400            "../../secrets.html",
401            "widgets/../../../x.html",
402            "widgets\\win.html",
403            // #661 — what the weaker copy let through.
404            ".env",
405            "a//b.html",
406            "a/./b.html",
407            "widgets/donations",
408        ] {
409            assert_eq!(
410                element_template(&with_template(bad)),
411                None,
412                "should have refused {bad:?}"
413            );
414        }
415    }
416
417    #[test]
418    fn element_template_allows_dots_inside_a_segment() {
419        // `..` is only a traversal as a whole segment — a file called
420        // `a..b.html` is an ordinary name and must not be refused.
421        assert_eq!(
422            element_template(&with_template("widgets/a..b.html")),
423            Some("widgets/a..b.html".to_owned())
424        );
425    }
426
427    #[test]
428    fn apply_overrides_replaces_top_level_and_data_paths() {
429        // #409 — title/body_markdown replace in place; `data.<key>`
430        // writes into the data object.
431        let mut v = serde_json::json!({
432            "title": "Hi", "body_markdown": "en body", "data": {"cta": "Click"}
433        });
434        let mut o = HashMap::new();
435        o.insert("title".to_owned(), "Bonjour".to_owned());
436        o.insert("body_markdown".to_owned(), "corps fr".to_owned());
437        o.insert("data.cta".to_owned(), "Cliquez".to_owned());
438        super::apply_overrides(&mut v, &o);
439        assert_eq!(v["title"], serde_json::json!("Bonjour"));
440        assert_eq!(v["body_markdown"], serde_json::json!("corps fr"));
441        assert_eq!(v["data"]["cta"], serde_json::json!("Cliquez"));
442    }
443
444    #[test]
445    fn apply_overrides_creates_missing_data_object() {
446        let mut v = serde_json::json!({ "title": "Hi" });
447        let mut o = HashMap::new();
448        o.insert("data.x".to_owned(), "y".to_owned());
449        super::apply_overrides(&mut v, &o);
450        assert_eq!(v["data"]["x"], serde_json::json!("y"));
451    }
452
453    #[test]
454    fn without_a_recorder_the_call_is_empty() {
455        let tera = fresh_tera();
456        let out = render(&tera, r#"x{{ snippet_html(type="Category", id=1) }}y"#);
457        assert_eq!(out, "xy");
458    }
459
460    #[test]
461    fn a_recorded_call_leaves_a_marker_and_its_key() {
462        let rec = record();
463        let tera = fresh_tera();
464        let out = render(&tera, r#"a{{ snippet_html(type="Category", id=4) }}b{{ snippet_html(type="Category", id=4) }}"#);
465        assert_eq!(out, format!("a{m}b{m}", m = marker("Category", 4)));
466        assert_eq!(rec.take(), BTreeSet::from([("Category".to_owned(), 4)]));
467    }
468
469    #[test]
470    fn bad_arguments_record_nothing() {
471        let rec = record();
472        let tera = fresh_tera();
473        for call in [
474            r#"{{ snippet_html(type="Category") }}"#,
475            r#"{{ snippet_html(id=4) }}"#,
476            r#"{{ snippet_html(type="Category", id=0) }}"#,
477            r#"{{ snippet_html(type="x-->y", id=1) }}"#,
478            r#"{{ snippet_html(type="a>b", id=1) }}"#,
479        ] {
480            assert_eq!(render(&tera, call), "", "{call}");
481        }
482        assert!(rec.take().is_empty());
483    }
484
485    #[test]
486    fn the_marker_is_not_escaped() {
487        let _rec = record();
488        let tera = fresh_tera();
489        let out = render(&tera, r#"{{ snippet_html(type="X", id=1) }}"#);
490        assert!(out.starts_with("<!--"), "got `{out}`");
491    }
492
493    #[test]
494    fn dropping_the_recorder_stops_recording() {
495        {
496            let _rec = record();
497        }
498        let tera = fresh_tera();
499        assert_eq!(render(&tera, r#"x{{ snippet_html(type="X", id=1) }}y"#), "xy");
500    }
501}