Skip to main content

rustango_cms/api/
tree.rs

1//! `GET /api/v2/pages/tree/` — the site's page structure, nested.
2//!
3//! The flat list endpoint can express a subtree (`?descendant_of=`) but
4//! never its *shape*: a client building navigation has to fetch every
5//! page and reassemble the hierarchy itself. This returns it already
6//! nested, localized, and filtered to what the caller may actually see.
7//!
8//! ## Why it is one query
9//!
10//! `cms_page.parent_id` carries no index — only `path`, `status`,
11//! `url_path` and `page_type_id` do. Asking for each node's children
12//! would therefore be both an N+1 *and* a sequential scan per node. So
13//! this does what `auto_menu` does: one `ORDER BY path` fetch (already
14//! tree pre-order, index-backed), bucket by parent in memory, then
15//! recurse with [`crate::tree_build`]. Node count does not change the
16//! query count.
17//!
18//! ## Why it is bounded
19//!
20//! `MAX_LIMIT = 100` on the list endpoints is a *row* cap and means
21//! nothing to a tree. Without its own ceiling this endpoint is an
22//! unbounded response generator, so `depth` defaults to
23//! [`DEFAULT_DEPTH`] and the emitted node count is capped at
24//! [`MAX_NODES`].
25
26// Our extractor, not axum's — see `query::Query`.
27use crate::api::query::Query;
28use axum::response::{IntoResponse, Response};
29use axum::Json;
30use rustango::core::Column as _;
31use rustango::extractors::{SessionUser, Tenant};
32use rustango::sql::FetcherPool as _;
33use serde::Deserialize;
34
35use crate::page::Page;
36
37/// Levels returned when `?depth=` is omitted. Deep enough for a primary
38/// nav with dropdowns, shallow enough that the default response stays
39/// small on a big site.
40pub const DEFAULT_DEPTH: i64 = 3;
41/// Ceiling for `?depth=`.
42pub const MAX_DEPTH: i64 = 10;
43/// Hard cap on emitted nodes, whatever the depth asks for. The response
44/// is truncated rather than refused, and `meta.truncated` says so.
45pub const MAX_NODES: usize = 5_000;
46
47#[derive(Debug, Default, Deserialize)]
48pub struct TreeQuery {
49    /// `?root=N` — return the subtree under page N instead of the whole
50    /// site. N itself is not included; its children are the top level.
51    #[serde(default, deserialize_with = "crate::api::query::empty_as_none")]
52    pub root: Option<i64>,
53    /// `?depth=N` — levels to walk, clamped to [`MAX_DEPTH`].
54    #[serde(default, deserialize_with = "crate::api::query::empty_as_none")]
55    pub depth: Option<i64>,
56    /// `?locale=fr` — localize titles via `cms_translation`. Untranslated
57    /// pages keep their canonical title.
58    #[serde(default, deserialize_with = "crate::api::query::empty_string_as_none")]
59    pub locale: Option<String>,
60}
61
62/// `GET /api/v2/pages/tree/`
63pub async fn tree(
64    tenant: Tenant,
65    SessionUser(session_user): SessionUser,
66    rustango::tenancy::member_auth::CurrentMember(member): rustango::tenancy::member_auth::CurrentMember,
67    crate::api::auth::BearerMember(bearer): crate::api::auth::BearerMember,
68    Query(q): Query<TreeQuery>,
69) -> Response {
70    // #members — a public member outranks an admin session, matching
71    // `menus::detail` and the public renderer.
72    let viewer = member.as_ref().or(bearer.as_ref()).or(session_user.as_ref());
73    match tree_inner(tenant.pool(), viewer, &q).await {
74        Ok(resp) => resp,
75        Err(e) => {
76            tracing::error!(target: "rustango_cms::api", error = %e, "page tree failed");
77            crate::api::error::ApiError::internal().into_response()
78        }
79    }
80}
81
82/// Takes a `&Pool` rather than the `Tenant` so the whole endpoint is
83/// exercisable against an in-memory database — `Tenant::for_test` needs
84/// a real PostgreSQL connection, which would put the restriction-leak
85/// test out of reach of the normal suite.
86pub async fn tree_inner(
87    pool: &rustango::sql::Pool,
88    viewer: Option<&rustango::tenancy::auth::User>,
89    q: &TreeQuery,
90) -> Result<Response, rustango::sql::ExecError> {
91    let depth = q.depth.unwrap_or(DEFAULT_DEPTH).clamp(1, MAX_DEPTH);
92
93    // Serve what the public site serves. The list endpoint filters to
94    // `published` alone, but the renderer and sitemap both treat
95    // `archived` as public (`PageStatus::is_public`), and a tree that
96    // omitted archived pages would disagree with the URLs that resolve.
97    let statuses = [
98        crate::page::PageStatus::Published.as_str().to_owned(),
99        crate::page::PageStatus::Archived.as_str().to_owned(),
100    ];
101    let mut rows: Vec<Page> = Page::objects()
102        .where_(Page::status.is_in(statuses))
103        // Fetched by `path` because that column is indexed; re-sorted
104        // below into the order the site actually renders.
105        .order_by(&[("path", false)])
106        .fetch(pool)
107        .await?;
108
109    // Siblings come back in `sort_order` order, matching `auto_menu` and
110    // `default_children` — i.e. what every template's `children` loop
111    // shows. Ordering by `path` alone meant ordering by id, so any page
112    // moved after creation appeared in a different position here than on
113    // the rendered site, and a SPA's nav silently disagreed with the
114    // server-rendered one. `index_by_parent` preserves input order, so
115    // sorting the flat list once orders every sibling bucket.
116    rows.sort_by_key(|p| (p.sort_order, p.id.get().copied().unwrap_or_default()));
117
118    // Error pages are routing furniture, not site structure — excluded
119    // here exactly as `auto_menu` and `sitemap` exclude them.
120    let error_tid = crate::error_pages::error_page_type_id(pool).await;
121    rows.retain(|p| error_tid.is_none_or(|tid| p.page_type_id != tid));
122
123    // Legacy locale variants were standalone per-locale trees, so leaving
124    // them in would return the whole site once per locale. The column is
125    // deprecated (#275); this matches `feed.rs`.
126    rows.retain(|p| p.locale_variant_of.is_none());
127
128    // #members — drop pages the viewer may not see. Batched and
129    // subtree-aware via `path`, so a gated ancestor takes its descendants
130    // with it. Without this the tree would leak the titles and URLs of
131    // member-only sections to anonymous callers.
132    let triples: Vec<(i64, String, i64)> = rows
133        .iter()
134        .map(|p| {
135            (
136                p.id.get().copied().unwrap_or_default(),
137                p.path.clone(),
138                p.page_type_id,
139            )
140        })
141        .collect();
142    let denied = crate::view_restriction::denied_page_ids(pool, viewer, &triples).await;
143    if !denied.is_empty() {
144        rows.retain(|p| !denied.contains(&p.id.get().copied().unwrap_or_default()));
145    }
146
147    // `?root=` — restrict to a subtree using the same `path` prefix test
148    // `Page::descendants` uses, without a second query.
149    let root_parent = match q.root {
150        Some(root_id) => {
151            let Some(root) = rows
152                .iter()
153                .find(|p| p.id.get().copied() == Some(root_id))
154                .cloned()
155            else {
156                // Unknown, non-public, or denied — all indistinguishable
157                // from the outside on purpose.
158                return Ok(
159                    crate::api::error::ApiError::not_found("page").into_response()
160                );
161            };
162            let prefix = root.path.clone();
163            rows.retain(|p| p.path.starts_with(&prefix) && p.path != prefix);
164            Some(root_id)
165        }
166        None => None,
167    };
168
169    // An alias row carries a stale copy of the source's title, taken at
170    // creation; the renderer shadows it with the source's. Resolve them
171    // in one batched lookup so the tree shows what the page actually
172    // renders, rather than N queries or a wrong label.
173    let alias_sources: Vec<i64> = rows.iter().filter_map(|p| p.alias_of).collect();
174    let alias_titles: std::collections::HashMap<i64, String> = if alias_sources.is_empty() {
175        std::collections::HashMap::new()
176    } else {
177        let sources: Vec<Page> = Page::objects()
178            .where_(Page::id.is_in(alias_sources))
179            .fetch(pool)
180            .await?;
181        // The source is fetched with no status or restriction filter, so
182        // an alias pointing at a draft or member-only page would publish
183        // that page's title on a node everyone can see. Vet the sources
184        // the same way the tree vets everything else; an alias whose
185        // source fails keeps its own (stale) title rather than borrowing
186        // one the caller may not see.
187        let src_triples: Vec<(i64, String, i64)> = sources
188            .iter()
189            .map(|p| {
190                (
191                    p.id.get().copied().unwrap_or_default(),
192                    p.path.clone(),
193                    p.page_type_id,
194                )
195            })
196            .collect();
197        let src_denied =
198            crate::view_restriction::denied_page_ids(pool, viewer, &src_triples).await;
199        sources
200            .into_iter()
201            .filter(|p| {
202                p.status == crate::page::PageStatus::Published.as_str()
203                    || p.status == crate::page::PageStatus::Archived.as_str()
204            })
205            .filter_map(|p| p.id.get().copied().map(|id| (id, p.title)))
206            .filter(|(id, _)| !src_denied.contains(id))
207            .collect()
208    };
209
210    // Page-type names, so a tree node reports `type` like a list item
211    // does. One query for the registry (it is small and fully cached by
212    // the query itself), never per node.
213    let type_names = crate::api::pages::page_type_names(pool).await?;
214
215    // Localized titles — one query for the whole id set, never per node.
216    let locale = crate::translation::resolve_locale(pool, q.locale.as_deref()).await?;
217    let translations = match locale.as_ref().filter(|l| !l.is_default) {
218        Some(l) => {
219            let lid = l.id.get().copied().unwrap_or_default();
220            let ids: Vec<i64> = rows
221                .iter()
222                .filter_map(|p| p.id.get().copied())
223                .chain(alias_titles.keys().copied())
224                .collect();
225            crate::translation::fetch_for_pages(pool, &ids, lid)
226                .await
227                .unwrap_or_default()
228        }
229        _ => std::collections::HashMap::new(),
230    };
231
232    // Which nodes have children the caller can't see at this depth —
233    // computed over the filtered set, so `has_children` never promises a
234    // subtree that a restriction already removed.
235    let mut child_count: std::collections::HashMap<i64, usize> = std::collections::HashMap::new();
236    for p in &rows {
237        if let Some(pid) = p.parent_id {
238            *child_count.entry(pid).or_default() += 1;
239        }
240    }
241
242    let by_parent = crate::tree_build::index_by_parent(&rows, |p| {
243        // Under `?root=`, the root's own children are the top level.
244        if p.parent_id == root_parent {
245            None
246        } else {
247            p.parent_id
248        }
249    });
250
251    // `Cell` because the builder's `make` is `Fn`, not `FnMut` — the
252    // recursion hands the same closure to every level.
253    let emitted = std::cell::Cell::new(0usize);
254    let nodes = crate::tree_build::build(
255        &by_parent,
256        None,
257        depth,
258        &|p: &Page| p.id.get().copied().unwrap_or_default(),
259        &|p: &Page, children: Vec<serde_json::Value>| {
260            emitted.set(emitted.get() + 1);
261            node_json(
262                p,
263                children,
264                &alias_titles,
265                &translations,
266                &child_count,
267                &type_names,
268            )
269        },
270    );
271    let emitted = emitted.get();
272    let truncated = emitted > MAX_NODES;
273    let mut nodes = nodes;
274    if truncated {
275        // Keep the shape valid rather than erroring: a client gets a
276        // usable prefix plus an explicit flag. Pruning is pre-order over
277        // the *whole* tree — capping the top level instead would keep
278        // one root's entire ten-thousand-node subtree.
279        let mut budget = MAX_NODES;
280        prune(&mut nodes, &mut budget);
281    }
282
283    Ok(Json(serde_json::json!({
284        "meta": {
285            "depth": depth,
286            "root": q.root,
287            "locale": locale.as_ref().map(|l| l.code.clone()),
288            "total_count": emitted.min(MAX_NODES),
289            "truncated": truncated,
290            // How many nodes the cap removed. `total_count` equals the
291            // items length once truncated, so without this a client
292            // cannot tell whether it lost one node or ten thousand, nor
293            // decide whether a smaller `depth` would fit.
294            "dropped_count": emitted.saturating_sub(MAX_NODES),
295        },
296        "items": nodes,
297    }))
298    .into_response())
299}
300
301/// Keep at most `budget` nodes, pre-order, in place. A node that fits
302/// keeps only as many descendants as the remaining budget allows, so
303/// the result is a prefix of a depth-first walk and always well-formed.
304fn prune(nodes: &mut Vec<serde_json::Value>, budget: &mut usize) {
305    let keep = nodes.len().min(*budget);
306    nodes.truncate(keep);
307    *budget -= keep;
308    for n in nodes.iter_mut() {
309        let Some(children) = n.get_mut("children").and_then(|c| c.as_array_mut()) else {
310            continue;
311        };
312        prune(children, budget);
313    }
314}
315
316/// One tree node. Deliberately slim — id, label, where it points, and
317/// whether there is more below. A client that wants the full record
318/// follows `detail_url`.
319fn node_json(
320    p: &Page,
321    children: Vec<serde_json::Value>,
322    alias_titles: &std::collections::HashMap<i64, String>,
323    translations: &std::collections::HashMap<i64, std::collections::HashMap<String, String>>,
324    child_count: &std::collections::HashMap<i64, usize>,
325    type_names: &std::collections::HashMap<i64, String>,
326) -> serde_json::Value {
327    let id = p.id.get().copied().unwrap_or_default();
328    // An alias shows the source's title, then that title's translation —
329    // the same order the renderer resolves them in.
330    let source_id = p.alias_of.unwrap_or(id);
331    let base_title = p
332        .alias_of
333        .and_then(|src| alias_titles.get(&src).cloned())
334        .unwrap_or_else(|| p.title.clone());
335    let title = translations
336        .get(&source_id)
337        .and_then(|m| m.get("title"))
338        .filter(|s| !s.is_empty())
339        .cloned()
340        .unwrap_or(base_title);
341
342    let mut obj = serde_json::json!({
343        "id": id,
344        "title": title,
345        "type": type_names.get(&p.page_type_id).cloned().unwrap_or_default(),
346        "slug": p.slug,
347        "url": if p.url_path.is_empty() { "/" } else { p.url_path.as_str() },
348        "depth": p.depth,
349        "has_children": child_count.get(&id).copied().unwrap_or(0) > 0,
350        "detail_url": format!("/api/v2/pages/{id}/"),
351        "children": children,
352    });
353    if let Some(src) = p.alias_of {
354        // An alias is a real, distinct URL — surfaced, not deduped — but
355        // clients need to know it mirrors another page's content.
356        obj["alias_of"] = serde_json::json!(src);
357    }
358    obj
359}
360
361#[cfg(test)]
362mod tests {
363    use super::*;
364    use serde_json::json;
365
366    /// `[a[a1,a2],b]` — 2 roots, 4 nodes.
367    fn sample() -> Vec<serde_json::Value> {
368        vec![
369            json!({"id": 1, "children": [
370                {"id": 2, "children": []},
371                {"id": 3, "children": []},
372            ]}),
373            json!({"id": 4, "children": []}),
374        ]
375    }
376
377    fn ids(nodes: &[serde_json::Value]) -> Vec<i64> {
378        let mut out = Vec::new();
379        for n in nodes {
380            out.push(n["id"].as_i64().unwrap());
381            out.extend(ids(n["children"].as_array().unwrap()));
382        }
383        out
384    }
385
386    #[test]
387    fn prune_counts_descendants_not_just_roots() {
388        // The bug this guards: truncating the top-level vec keeps one
389        // root's entire subtree, so the cap bounds nothing.
390        let mut nodes = sample();
391        let mut budget = 3;
392        prune(&mut nodes, &mut budget);
393        assert_eq!(ids(&nodes).len(), 3);
394    }
395
396    #[test]
397    fn prune_keeps_a_breadth_then_depth_prefix() {
398        let mut nodes = sample();
399        let mut budget = 3;
400        prune(&mut nodes, &mut budget);
401        // Both roots survive first, then the budget spends downward.
402        assert_eq!(ids(&nodes), vec![1, 2, 4]);
403    }
404
405    #[test]
406    fn prune_under_budget_changes_nothing() {
407        let mut nodes = sample();
408        let mut budget = MAX_NODES;
409        prune(&mut nodes, &mut budget);
410        assert_eq!(ids(&nodes), vec![1, 2, 3, 4]);
411    }
412
413    #[test]
414    fn a_zero_budget_empties_the_tree() {
415        let mut nodes = sample();
416        let mut budget = 0;
417        prune(&mut nodes, &mut budget);
418        assert!(nodes.is_empty());
419    }
420
421    #[test]
422    fn depth_is_clamped_to_the_ceiling() {
423        // A client asking for depth=999 must not get an unbounded walk.
424        for (asked, want) in [(None, DEFAULT_DEPTH), (Some(999), MAX_DEPTH), (Some(0), 1)] {
425            let got = asked.unwrap_or(DEFAULT_DEPTH).clamp(1, MAX_DEPTH);
426            assert_eq!(got, want, "depth={asked:?}");
427        }
428    }
429}