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/// writing only the difference: rows no longer referenced are deleted,
118/// new references inserted, and an unchanged set writes nothing.
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    // A multiset: one field can reference the same target twice.
136    let mut wanted: std::collections::HashMap<(String, i64, String), usize> =
137        std::collections::HashMap::new();
138    for r in &refs {
139        *wanted
140            .entry((r.to_kind.to_owned(), r.to_id, r.field_path.clone()))
141            .or_default() += 1;
142    }
143    for row in existing {
144        let key = (row.to_kind.clone(), row.to_id, row.field_path.clone());
145        match wanted.get_mut(&key) {
146            Some(n) if *n > 0 => *n -= 1,
147            _ => {
148                row.delete(pool).await?;
149            }
150        }
151    }
152    for r in refs {
153        let key = (r.to_kind.to_owned(), r.to_id, r.field_path.clone());
154        match wanted.get_mut(&key) {
155            Some(n) if *n > 0 => *n -= 1,
156            _ => continue,
157        }
158        let mut row = ReferenceIndex {
159            id: Auto::Unset,
160            from_kind: from_kind.to_owned(),
161            from_id,
162            to_kind: r.to_kind.to_owned(),
163            to_id: r.to_id,
164            field_path: r.field_path,
165            created_at: Auto::Unset,
166        };
167        row.insert(pool).await?;
168    }
169    Ok(())
170}
171
172/// Every inbound reference to (kind, id). Used by the page + snippet
173/// editor's References panel.
174///
175/// # Errors
176/// Driver / query failures.
177pub async fn inbound(
178    pool: &rustango::sql::Pool,
179    to_kind: &str,
180    to_id: i64,
181) -> Result<Vec<ReferenceIndex>, rustango::sql::ExecError> {
182    use rustango::core::Column as _;
183    use rustango::sql::FetcherPool as _;
184    ReferenceIndex::objects()
185        .where_(ReferenceIndex::to_kind.eq(to_kind.to_owned()))
186        .where_(ReferenceIndex::to_id.eq(to_id))
187        .fetch(pool)
188        .await
189}
190
191// ---- #419 — usage view (aggregate + jump-to-referrer) ------------
192
193/// One inbound referrer to a target, aggregated across every field in
194/// which it references the target. The `title` resolves to the
195/// referrer's display name (page / snippet title) for a clickable
196/// "used in N places" view; falls back to `kind#id`.
197#[derive(Debug, Clone, serde::Serialize)]
198pub struct Referrer {
199    pub from_kind: String,
200    pub from_id: i64,
201    pub title: String,
202    /// Distinct field paths through which this referrer points at the
203    /// target (e.g. `body_markdown`, `hero_media_id`).
204    pub fields: Vec<String>,
205}
206
207/// Group raw inbound rows by `(from_kind, from_id)`, collecting the
208/// distinct field paths in first-seen order. Pure — titles are filled
209/// in by [`usage_summary`]. The returned length is the aggregate
210/// "used in N places" count.
211#[must_use]
212pub fn aggregate_referrers(refs: Vec<ReferenceIndex>) -> Vec<Referrer> {
213    use std::collections::HashMap;
214    let mut order: Vec<(String, i64)> = Vec::new();
215    let mut fields: HashMap<(String, i64), Vec<String>> = HashMap::new();
216    for r in refs {
217        let key = (r.from_kind.clone(), r.from_id);
218        if !fields.contains_key(&key) {
219            order.push(key.clone());
220        }
221        let entry = fields.entry(key).or_default();
222        if !r.field_path.is_empty() && !entry.contains(&r.field_path) {
223            entry.push(r.field_path);
224        }
225    }
226    order
227        .into_iter()
228        .map(|(from_kind, from_id)| {
229            let fields = fields
230                .remove(&(from_kind.clone(), from_id))
231                .unwrap_or_default();
232            let title = format!("{from_kind}#{from_id}");
233            Referrer {
234                from_kind,
235                from_id,
236                title,
237                fields,
238            }
239        })
240        .collect()
241}
242
243/// Aggregated, title-resolved inbound usage for any target
244/// `(to_kind, to_id)` — reused across pages / snippets / media /
245/// documents. Page + snippet referrers get their real title
246/// resolved in one batched query each; other kinds keep the `kind#id`
247/// fallback.
248pub async fn usage_summary(pool: &rustango::sql::Pool, to_kind: &str, to_id: i64) -> Vec<Referrer> {
249    use rustango::core::Column as _;
250    use rustango::sql::FetcherPool as _;
251
252    let refs = inbound(pool, to_kind, to_id).await.unwrap_or_default();
253    let mut referrers = aggregate_referrers(refs);
254
255    let page_ids: Vec<i64> = referrers
256        .iter()
257        .filter(|r| r.from_kind == KIND_PAGE)
258        .map(|r| r.from_id)
259        .collect();
260    let snippet_ids: Vec<i64> = referrers
261        .iter()
262        .filter(|r| r.from_kind == KIND_SNIPPET)
263        .map(|r| r.from_id)
264        .collect();
265
266    let mut page_titles: std::collections::HashMap<i64, String> = std::collections::HashMap::new();
267    if !page_ids.is_empty() {
268        let rows: Vec<crate::page::Page> = crate::page::Page::objects()
269            .where_(crate::page::Page::id.is_in(page_ids))
270            .fetch(pool)
271            .await
272            .unwrap_or_default();
273        for p in rows {
274            if let Some(id) = p.id.get().copied() {
275                page_titles.insert(id, p.title);
276            }
277        }
278    }
279    let mut snippet_titles: std::collections::HashMap<i64, String> =
280        std::collections::HashMap::new();
281    if !snippet_ids.is_empty() {
282        let rows: Vec<crate::snippet::Snippet> = crate::snippet::Snippet::objects()
283            .where_(crate::snippet::Snippet::id.is_in(snippet_ids))
284            .fetch(pool)
285            .await
286            .unwrap_or_default();
287        for s in rows {
288            if let Some(id) = s.id.get().copied() {
289                snippet_titles.insert(id, s.title);
290            }
291        }
292    }
293
294    for r in &mut referrers {
295        let resolved = match r.from_kind.as_str() {
296            KIND_PAGE => page_titles.get(&r.from_id),
297            KIND_SNIPPET => snippet_titles.get(&r.from_id),
298            _ => None,
299        };
300        if let Some(t) = resolved.filter(|t| !t.is_empty()) {
301            r.title = t.clone();
302        }
303    }
304    referrers
305}
306
307#[cfg(test)]
308mod usage_tests {
309    use super::*;
310
311    fn row(from_kind: &str, from_id: i64, field: &str) -> ReferenceIndex {
312        ReferenceIndex {
313            id: rustango::sql::Auto::Unset,
314            from_kind: from_kind.to_owned(),
315            from_id,
316            to_kind: KIND_MEDIA.to_owned(),
317            to_id: 1,
318            field_path: field.to_owned(),
319            created_at: rustango::sql::Auto::Unset,
320        }
321    }
322
323    #[test]
324    fn groups_referrer_and_dedups_fields() {
325        let out = aggregate_referrers(vec![
326            row(KIND_PAGE, 5, "body_markdown"),
327            row(KIND_PAGE, 5, "hero_media_id"),
328            row(KIND_PAGE, 5, "body_markdown"), // dup field
329        ]);
330        assert_eq!(out.len(), 1, "one distinct referrer");
331        assert_eq!(out[0].from_id, 5);
332        assert_eq!(out[0].fields, vec!["body_markdown", "hero_media_id"]);
333        assert_eq!(out[0].title, "cms_page#5"); // fallback until resolved
334    }
335
336    #[test]
337    fn distinct_referrers_in_first_seen_order_is_the_count() {
338        let out = aggregate_referrers(vec![
339            row(KIND_PAGE, 5, "body"),
340            row(KIND_SNIPPET, 9, "intro"),
341            row(KIND_PAGE, 5, "body2"),
342        ]);
343        // "used in N places" = 2, ordered by first appearance.
344        assert_eq!(out.len(), 2);
345        assert_eq!((out[0].from_kind.as_str(), out[0].from_id), (KIND_PAGE, 5));
346        assert_eq!(
347            (out[1].from_kind.as_str(), out[1].from_id),
348            (KIND_SNIPPET, 9)
349        );
350        assert_eq!(out[0].fields, vec!["body", "body2"]);
351    }
352
353    #[test]
354    fn empty_field_path_yields_no_field_entry() {
355        let out = aggregate_referrers(vec![row(KIND_PAGE, 7, "")]);
356        assert_eq!(out.len(), 1);
357        assert!(out[0].fields.is_empty());
358    }
359}
360
361#[cfg(test)]
362mod tests {
363    use super::*;
364
365    #[test]
366    fn scan_finds_single_media_ref() {
367        let html = r#"<img src="/__media__/fill-300x200/42">"#;
368        let refs = scan(html, "body");
369        assert_eq!(refs.len(), 1);
370        assert_eq!(refs[0].to_kind, KIND_MEDIA);
371        assert_eq!(refs[0].to_id, 42);
372        assert_eq!(refs[0].field_path, "body");
373    }
374
375    #[test]
376    fn scan_handles_multiple_media_refs() {
377        let html = r#"<p>see /__media__/width-800/7 and /__media__/max-200x200/3</p>"#;
378        let refs = scan(html, "body");
379        assert_eq!(refs.len(), 2);
380        assert_eq!(refs[0].to_id, 7);
381        assert_eq!(refs[1].to_id, 3);
382    }
383
384    #[test]
385    fn scan_skips_garbage() {
386        let html = "no media refs in this text at all";
387        assert!(scan(html, "body").is_empty());
388    }
389
390    #[test]
391    fn scan_ignores_id_with_query_string() {
392        let html = r#"<img src="/__media__/fill-300x200/42?v=abc123">"#;
393        let refs = scan(html, "body");
394        assert_eq!(refs.len(), 1);
395        assert_eq!(refs[0].to_id, 42);
396    }
397}