Skip to main content

rustango_cms/
media_usage.rs

1//! Which media-library pictures and files are in use, and where.
2//!
3//! A picture can be referenced from a page's code extension row, from its
4//! page-builder data (fields, blocks, and the items of list blocks such as
5//! Cards, Slider and Gallery), from a library element, or from a site
6//! setting (Branding's logo and icon, a theme's footer badge). Each holds
7//! the media id under a field whose name the schema decides (`cover`,
8//! `image`, `logo`, …), so this first learns those names from every
9//! schema that can hold a picture ([`media_fields`]) and then scans the
10//! stored values for them.
11//!
12//! The **Unused media** report and a picture's **Used on** panel both read
13//! from here, so they always agree.
14
15use std::collections::{BTreeSet, HashSet};
16
17use rustango::sql::{ExecError, FetcherPool as _, Pool};
18use serde_json::Value;
19
20use crate::block::BlockField;
21use crate::page::Page;
22use crate::page_builder::model::{PageBuilderData, PageTypeSchema};
23use crate::page_type_model::PageType;
24use crate::widget::WidgetKind;
25
26/// Where a picture is used.
27#[derive(Debug, Clone, PartialEq, Eq)]
28pub enum Use {
29    /// A page: id, title, URL path, status.
30    Page { id: i64, title: String, url_path: String, status: String },
31    /// A library element: id, title.
32    Library { id: i64, title: String },
33    /// A site setting, by scope.
34    Setting { scope: String },
35}
36
37/// Names of the fields that hold a media id, across every schema that can
38/// hold one: built-in and registered blocks, page-builder page types and
39/// components, and site-setting forms. Code page types keep the older
40/// `media_id` / `*_media_id` convention, matched in [`is_media_field`].
41pub async fn media_fields(pool: &Pool) -> Result<HashSet<String>, ExecError> {
42    let mut names: HashSet<String> = HashSet::new();
43    for block in crate::block::registered_blocks() {
44        for field in block.fields() {
45            if let BlockField::Widget { name, widget: WidgetKind::MediaPicker, .. } = field {
46                names.insert(name);
47            }
48        }
49    }
50    for schema in PageTypeSchema::objects().fetch(pool).await? {
51        schema_fields(&schema.document, &mut names);
52    }
53    for component in crate::page_builder::model::component_map(pool).await?.into_values() {
54        if let Ok(children) = serde_json::to_value(&component.doc.children) {
55            schema_fields(&serde_json::json!({ "nodes": children }), &mut names);
56        }
57    }
58    for schema in crate::site_setting::registered_schemas() {
59        for widget in (schema.fields)() {
60            if widget.kind == WidgetKind::MediaPicker {
61                names.insert(widget.name.clone());
62            }
63        }
64    }
65    for picture in [crate::branding::Picture::Logo, crate::branding::Picture::Favicon] {
66        names.insert(picture.key().to_owned());
67    }
68    Ok(names)
69}
70
71/// Every `"widget": "mediapicker"` field key in a page-builder document,
72/// at any depth (rows, groups, repeater items, flexible-zone groups).
73fn schema_fields(value: &Value, names: &mut HashSet<String>) {
74    match value {
75        Value::Object(map) => {
76            if map.get("widget").and_then(Value::as_str) == Some("mediapicker") {
77                if let Some(key) = map.get("key").and_then(Value::as_str) {
78                    names.insert(key.to_owned());
79                }
80            }
81            map.values().for_each(|v| schema_fields(v, names));
82        }
83        Value::Array(items) => items.iter().for_each(|v| schema_fields(v, names)),
84        _ => {}
85    }
86}
87
88fn is_media_field(key: &str, names: &HashSet<String>) -> bool {
89    names.contains(key) || key == "media_id" || key.ends_with("_media_id")
90}
91
92/// The media ids `value` references through `names` fields. A string that
93/// holds JSON (stream bodies stored as text) is read too.
94pub fn collect(value: &Value, names: &HashSet<String>, out: &mut BTreeSet<i64>) {
95    match value {
96        Value::Object(map) => {
97            for (key, child) in map {
98                let id = match child {
99                    Value::Number(n) if is_media_field(key, names) => n.as_i64(),
100                    Value::String(s) if is_media_field(key, names) => s.trim().parse::<i64>().ok(),
101                    _ => None,
102                };
103                match id {
104                    Some(id) if id > 0 => {
105                        out.insert(id);
106                    }
107                    _ => collect(child, names, out),
108                }
109            }
110        }
111        Value::Array(items) => items.iter().for_each(|v| collect(v, names, out)),
112        Value::String(s) => {
113            let t = s.trim_start();
114            if t.starts_with('[') || t.starts_with('{') {
115                if let Ok(parsed) = serde_json::from_str::<Value>(s) {
116                    collect(&parsed, names, out);
117                }
118            }
119        }
120        _ => {}
121    }
122}
123
124/// Everything that references pictures, each with what it is.
125async fn sources(pool: &Pool, names: &HashSet<String>) -> Result<Vec<(Use, BTreeSet<i64>)>, ExecError> {
126    let mut out = Vec::new();
127    let types: Vec<PageType> = PageType::objects().fetch(pool).await?;
128    let builder: Vec<PageBuilderData> = PageBuilderData::objects().fetch(pool).await?;
129    for page in Page::objects().fetch(pool).await? {
130        let Some(id) = page.id.get().copied() else { continue };
131        let mut ids = BTreeSet::new();
132        if let Ok(v) = serde_json::to_value(&page) {
133            collect(&v, names, &mut ids);
134        }
135        let handler = types
136            .iter()
137            .find(|t| t.id.get().copied() == Some(page.page_type_id))
138            .and_then(|t| crate::page_type::find_handler(&t.type_name));
139        if let Some(handler) = handler {
140            if let Ok(ext) = handler.load_extension(pool, id).await {
141                collect(&ext, names, &mut ids);
142            }
143        }
144        for row in builder.iter().filter(|b| b.page_id == id) {
145            collect(&row.data, names, &mut ids);
146        }
147        if !ids.is_empty() {
148            out.push((Use::Page { id, title: page.title, url_path: page.url_path, status: page.status }, ids));
149        }
150    }
151    for snippet in crate::snippet::Snippet::objects().fetch(pool).await? {
152        let mut ids = BTreeSet::new();
153        collect(&snippet.data, names, &mut ids);
154        if let (Some(id), false) = (snippet.id.get().copied(), ids.is_empty()) {
155            out.push((Use::Library { id, title: snippet.title }, ids));
156        }
157    }
158    for setting in crate::site_setting::list_all(pool).await? {
159        let mut ids = BTreeSet::new();
160        collect(&setting.value_json, names, &mut ids);
161        if !ids.is_empty() {
162            out.push((Use::Setting { scope: setting.scope }, ids));
163        }
164    }
165    Ok(out)
166}
167
168/// Ids of every picture or file in use anywhere.
169///
170/// # Errors
171/// Database errors.
172pub async fn used(pool: &Pool) -> Result<BTreeSet<i64>, ExecError> {
173    let names = media_fields(pool).await?;
174    Ok(sources(pool, &names).await?.into_iter().flat_map(|(_, ids)| ids).collect())
175}
176
177/// Where one picture or file is used.
178///
179/// # Errors
180/// Database errors.
181pub async fn uses_of(pool: &Pool, media_id: i64) -> Result<Vec<Use>, ExecError> {
182    let names = media_fields(pool).await?;
183    Ok(sources(pool, &names)
184        .await?
185        .into_iter()
186        .filter(|(_, ids)| ids.contains(&media_id))
187        .map(|(u, _)| u)
188        .collect())
189}
190
191#[cfg(test)]
192mod tests {
193    use super::*;
194    use serde_json::json;
195
196    #[test]
197    fn ids_are_found_under_schema_named_fields_at_any_depth() {
198        let names: HashSet<String> = ["cover", "image"].iter().map(|s| (*s).to_owned()).collect();
199        let data = json!({
200            "cover": "3",
201            "title": "7",
202            "body": [
203                { "type": "hero", "value": { "image": "4", "heading": "x" } },
204                { "type": "gallery", "value": { "images": [
205                    { "type": "gallery_image", "value": { "image": 5 } }
206                ] } }
207            ],
208            "legacy": "{\"hero_media_id\": 6}"
209        });
210        let mut out = BTreeSet::new();
211        collect(&data, &names, &mut out);
212        assert_eq!(out.into_iter().collect::<Vec<_>>(), vec![3, 4, 5, 6]);
213    }
214
215    #[test]
216    fn page_builder_schemas_name_their_picture_fields() {
217        let doc = json!({ "nodes": [
218            { "kind": "field", "key": "cover", "widget": "mediapicker" },
219            { "kind": "field", "key": "intro", "widget": "textarea" },
220            { "kind": "flex", "key": "body", "groups": [
221                { "key": "hero", "children": [
222                    { "kind": "row", "children": [ { "kind": "field", "key": "image", "widget": "mediapicker" } ] }
223                ] }
224            ] }
225        ] });
226        let mut names = HashSet::new();
227        schema_fields(&doc, &mut names);
228        assert_eq!(names, ["cover", "image"].iter().map(|s| (*s).to_owned()).collect());
229    }
230}