Skip to main content

rustango_cms/
reference_index.rs

1//! Generic reference index — \"what links here\".
2//!
3//! Tracks every inbound reference: page→page links, snippet→page
4//! embeds, page→media renditions. Feeds two surfaces:
5//!
6//! 1. A \"References\" panel on the page + snippet editor showing
7//!    every object that points at the current row.
8//! 2. Cascade-delete warnings (\"deleting this snippet will break
9//!    12 pages\") on the delete confirmation.
10//!
11//! Index updater runs from page + snippet save handlers. Reference
12//! extraction is a simple scanner over the rendered HTML / persisted
13//! JSON shape — looks for known patterns:
14//!   - \`href=\"/some/path\"\` → page reference (resolved via url_path
15//!     lookup).
16//!   - \`{{ cms_snippet(slug=\"X\") }}\` → snippet reference.
17//!   - `/__media__/<spec>/<id>` → media reference.
18//!   - StreamField block values with \`media_id\` / \`page_id\` keys.
19
20use chrono::{DateTime, Utc};
21use rustango::sql::Auto;
22use rustango::Model;
23use serde::{Deserialize, Serialize};
24
25/// Resource kind identifiers used in `from_kind` / `to_kind`. Strings
26/// not enums so plugin types can join the index without code changes.
27pub const KIND_PAGE: &str = "cms_page";
28pub const KIND_SNIPPET: &str = "cms_snippet";
29pub const KIND_MEDIA: &str = "cms_media";
30
31#[derive(Model, Debug, Clone, Serialize, Deserialize)]
32#[rustango(
33    table = "cms_reference_index",
34    app = "cms",
35    display = "id",
36    admin(
37        list_display = "from_kind, from_id, to_kind, to_id, field_path",
38        ordering = "to_kind, to_id",
39    )
40)]
41pub struct ReferenceIndex {
42    #[rustango(primary_key)]
43    pub id: Auto<i64>,
44
45    #[rustango(max_length = 32, index)]
46    pub from_kind: String,
47
48    pub from_id: i64,
49
50    #[rustango(max_length = 32, index)]
51    pub to_kind: String,
52
53    pub to_id: i64,
54
55    /// Optional locator inside the source — typically the field name
56    /// (\`body_markdown\`, \`body_stream\`, etc.). Empty when the
57    /// reference is at the row level.
58    #[rustango(max_length = 128)]
59    pub field_path: String,
60
61    #[rustango(auto_now_add)]
62    pub created_at: Auto<DateTime<Utc>>,
63}
64
65/// One scanned reference (target identity only; the source identity
66/// is supplied by the caller).
67#[derive(Debug, Clone)]
68pub struct Reference {
69    pub to_kind: &'static str,
70    pub to_id: i64,
71    pub field_path: String,
72}
73
74/// Walk `haystack` looking for media / page / snippet references.
75/// Pure: no DB access. Caller resolves \`href=\"/path\"\` URLs via a
76/// follow-up Page lookup if needed.
77///
78/// Patterns recognized:
79///   - `/__media__/<spec>/<id>` → media reference.
80///   - \`{{ cms_snippet(slug=\"X\") }}\` or \`cms_snippet(slug=X)\` → no
81///     direct id, caller must resolve via slug.
82#[must_use]
83pub fn scan(haystack: &str, field_path: &str) -> Vec<Reference> {
84    let mut out = Vec::new();
85    // Media references — /__media__/<spec>/<id>
86    let mut start = 0;
87    while let Some(rel) = haystack[start..].find("/__media__/") {
88        let abs = start + rel;
89        let tail = &haystack[abs + "/__media__/".len()..];
90        // Skip the filter spec.
91        let after_spec = match tail.find('/') {
92            Some(i) => &tail[i + 1..],
93            None => {
94                start = abs + 1;
95                continue;
96            }
97        };
98        // Parse the id up to the next non-digit.
99        let id_end = after_spec
100            .find(|c: char| !c.is_ascii_digit())
101            .unwrap_or(after_spec.len());
102        if id_end > 0 {
103            if let Ok(id) = after_spec[..id_end].parse::<i64>() {
104                out.push(Reference {
105                    to_kind: KIND_MEDIA,
106                    to_id: id,
107                    field_path: field_path.to_owned(),
108                });
109            }
110        }
111        start = abs + 1;
112    }
113    out
114}
115
116/// Replace every (from_kind, from_id) row in the index with `refs`.
117/// Atomic per-source — readers see either the old set or the new
118/// set, never an intermediate state.
119///
120/// # Errors
121/// Driver / query failures.
122pub async fn reindex_source(
123    pool: &rustango::sql::Pool,
124    from_kind: &'static str,
125    from_id: i64,
126    refs: Vec<Reference>,
127) -> Result<(), rustango::sql::ExecError> {
128    use rustango::core::Column as _;
129    use rustango::sql::FetcherPool as _;
130    let existing: Vec<ReferenceIndex> = ReferenceIndex::objects()
131        .where_(ReferenceIndex::from_kind.eq(from_kind.to_owned()))
132        .where_(ReferenceIndex::from_id.eq(from_id))
133        .fetch(pool)
134        .await?;
135    for row in existing {
136        row.delete_pool(pool).await?;
137    }
138    for r in refs {
139        let mut row = ReferenceIndex {
140            id: Auto::Unset,
141            from_kind: from_kind.to_owned(),
142            from_id,
143            to_kind: r.to_kind.to_owned(),
144            to_id: r.to_id,
145            field_path: r.field_path,
146            created_at: Auto::Unset,
147        };
148        row.insert_pool(pool).await?;
149    }
150    Ok(())
151}
152
153/// Every inbound reference to (kind, id). Used by the page + snippet
154/// editor's References panel.
155///
156/// # Errors
157/// Driver / query failures.
158pub async fn inbound(
159    pool: &rustango::sql::Pool,
160    to_kind: &str,
161    to_id: i64,
162) -> Result<Vec<ReferenceIndex>, rustango::sql::ExecError> {
163    use rustango::core::Column as _;
164    use rustango::sql::FetcherPool as _;
165    ReferenceIndex::objects()
166        .where_(ReferenceIndex::to_kind.eq(to_kind.to_owned()))
167        .where_(ReferenceIndex::to_id.eq(to_id))
168        .fetch(pool)
169        .await
170}
171
172// ---- #419 — usage view (aggregate + jump-to-referrer) ------------
173
174/// One inbound referrer to a target, aggregated across every field in
175/// which it references the target. The `title` resolves to the
176/// referrer's display name (page / snippet title) for a clickable
177/// "used in N places" view; falls back to `kind#id`.
178#[derive(Debug, Clone, serde::Serialize)]
179pub struct Referrer {
180    pub from_kind: String,
181    pub from_id: i64,
182    pub title: String,
183    /// Distinct field paths through which this referrer points at the
184    /// target (e.g. `body_markdown`, `hero_media_id`).
185    pub fields: Vec<String>,
186}
187
188/// Group raw inbound rows by `(from_kind, from_id)`, collecting the
189/// distinct field paths in first-seen order. Pure — titles are filled
190/// in by [`usage_summary`]. The returned length is the aggregate
191/// "used in N places" count.
192#[must_use]
193pub fn aggregate_referrers(refs: Vec<ReferenceIndex>) -> Vec<Referrer> {
194    use std::collections::HashMap;
195    let mut order: Vec<(String, i64)> = Vec::new();
196    let mut fields: HashMap<(String, i64), Vec<String>> = HashMap::new();
197    for r in refs {
198        let key = (r.from_kind.clone(), r.from_id);
199        if !fields.contains_key(&key) {
200            order.push(key.clone());
201        }
202        let entry = fields.entry(key).or_default();
203        if !r.field_path.is_empty() && !entry.contains(&r.field_path) {
204            entry.push(r.field_path);
205        }
206    }
207    order
208        .into_iter()
209        .map(|(from_kind, from_id)| {
210            let fields = fields
211                .remove(&(from_kind.clone(), from_id))
212                .unwrap_or_default();
213            let title = format!("{from_kind}#{from_id}");
214            Referrer {
215                from_kind,
216                from_id,
217                title,
218                fields,
219            }
220        })
221        .collect()
222}
223
224/// Aggregated, title-resolved inbound usage for any target
225/// `(to_kind, to_id)` — reused across pages / snippets / media /
226/// documents. Page + snippet referrers get their real title
227/// resolved in one batched query each; other kinds keep the `kind#id`
228/// fallback.
229pub async fn usage_summary(pool: &rustango::sql::Pool, to_kind: &str, to_id: i64) -> Vec<Referrer> {
230    use rustango::core::Column as _;
231    use rustango::sql::FetcherPool as _;
232
233    let refs = inbound(pool, to_kind, to_id).await.unwrap_or_default();
234    let mut referrers = aggregate_referrers(refs);
235
236    let page_ids: Vec<i64> = referrers
237        .iter()
238        .filter(|r| r.from_kind == KIND_PAGE)
239        .map(|r| r.from_id)
240        .collect();
241    let snippet_ids: Vec<i64> = referrers
242        .iter()
243        .filter(|r| r.from_kind == KIND_SNIPPET)
244        .map(|r| r.from_id)
245        .collect();
246
247    let mut page_titles: std::collections::HashMap<i64, String> = std::collections::HashMap::new();
248    if !page_ids.is_empty() {
249        let rows: Vec<crate::page::Page> = crate::page::Page::objects()
250            .where_(crate::page::Page::id.is_in(page_ids))
251            .fetch(pool)
252            .await
253            .unwrap_or_default();
254        for p in rows {
255            if let Some(id) = p.id.get().copied() {
256                page_titles.insert(id, p.title);
257            }
258        }
259    }
260    let mut snippet_titles: std::collections::HashMap<i64, String> =
261        std::collections::HashMap::new();
262    if !snippet_ids.is_empty() {
263        let rows: Vec<crate::snippet::Snippet> = crate::snippet::Snippet::objects()
264            .where_(crate::snippet::Snippet::id.is_in(snippet_ids))
265            .fetch(pool)
266            .await
267            .unwrap_or_default();
268        for s in rows {
269            if let Some(id) = s.id.get().copied() {
270                snippet_titles.insert(id, s.title);
271            }
272        }
273    }
274
275    for r in &mut referrers {
276        let resolved = match r.from_kind.as_str() {
277            KIND_PAGE => page_titles.get(&r.from_id),
278            KIND_SNIPPET => snippet_titles.get(&r.from_id),
279            _ => None,
280        };
281        if let Some(t) = resolved.filter(|t| !t.is_empty()) {
282            r.title = t.clone();
283        }
284    }
285    referrers
286}
287
288#[cfg(test)]
289mod usage_tests {
290    use super::*;
291
292    fn row(from_kind: &str, from_id: i64, field: &str) -> ReferenceIndex {
293        ReferenceIndex {
294            id: rustango::sql::Auto::Unset,
295            from_kind: from_kind.to_owned(),
296            from_id,
297            to_kind: KIND_MEDIA.to_owned(),
298            to_id: 1,
299            field_path: field.to_owned(),
300            created_at: rustango::sql::Auto::Unset,
301        }
302    }
303
304    #[test]
305    fn groups_referrer_and_dedups_fields() {
306        let out = aggregate_referrers(vec![
307            row(KIND_PAGE, 5, "body_markdown"),
308            row(KIND_PAGE, 5, "hero_media_id"),
309            row(KIND_PAGE, 5, "body_markdown"), // dup field
310        ]);
311        assert_eq!(out.len(), 1, "one distinct referrer");
312        assert_eq!(out[0].from_id, 5);
313        assert_eq!(out[0].fields, vec!["body_markdown", "hero_media_id"]);
314        assert_eq!(out[0].title, "cms_page#5"); // fallback until resolved
315    }
316
317    #[test]
318    fn distinct_referrers_in_first_seen_order_is_the_count() {
319        let out = aggregate_referrers(vec![
320            row(KIND_PAGE, 5, "body"),
321            row(KIND_SNIPPET, 9, "intro"),
322            row(KIND_PAGE, 5, "body2"),
323        ]);
324        // "used in N places" = 2, ordered by first appearance.
325        assert_eq!(out.len(), 2);
326        assert_eq!((out[0].from_kind.as_str(), out[0].from_id), (KIND_PAGE, 5));
327        assert_eq!(
328            (out[1].from_kind.as_str(), out[1].from_id),
329            (KIND_SNIPPET, 9)
330        );
331        assert_eq!(out[0].fields, vec!["body", "body2"]);
332    }
333
334    #[test]
335    fn empty_field_path_yields_no_field_entry() {
336        let out = aggregate_referrers(vec![row(KIND_PAGE, 7, "")]);
337        assert_eq!(out.len(), 1);
338        assert!(out[0].fields.is_empty());
339    }
340}
341
342#[cfg(test)]
343mod tests {
344    use super::*;
345
346    #[test]
347    fn scan_finds_single_media_ref() {
348        let html = r#"<img src="/__media__/fill-300x200/42">"#;
349        let refs = scan(html, "body");
350        assert_eq!(refs.len(), 1);
351        assert_eq!(refs[0].to_kind, KIND_MEDIA);
352        assert_eq!(refs[0].to_id, 42);
353        assert_eq!(refs[0].field_path, "body");
354    }
355
356    #[test]
357    fn scan_handles_multiple_media_refs() {
358        let html = r#"<p>see /__media__/width-800/7 and /__media__/max-200x200/3</p>"#;
359        let refs = scan(html, "body");
360        assert_eq!(refs.len(), 2);
361        assert_eq!(refs[0].to_id, 7);
362        assert_eq!(refs[1].to_id, 3);
363    }
364
365    #[test]
366    fn scan_skips_garbage() {
367        let html = "no media refs in this text at all";
368        assert!(scan(html, "body").is_empty());
369    }
370
371    #[test]
372    fn scan_ignores_id_with_query_string() {
373        let html = r#"<img src="/__media__/fill-300x200/42?v=abc123">"#;
374        let refs = scan(html, "body");
375        assert_eq!(refs.len(), 1);
376        assert_eq!(refs[0].to_id, 42);
377    }
378}