Skip to main content

rustango_cms/api/
snippets.rs

1//! `GET /api/v2/snippets/` + `GET /api/v2/snippets/{id}/`.
2//!
3//! Read-only snippet access for headless consumers, mirroring the
4//! pages / images / documents endpoints. Snippets are the reusable
5//! content rows authors manage under the admin "Library"
6//! ([`crate::snippet::Snippet`]); the API exposes their `title`,
7//! `slug`, `body_markdown`, and typed `data`. Filter to one type with
8//! `?type=<type_name>`.
9
10// Our extractors, not axum's: they refuse a malformed value in the same
11// JSON envelope as everything else. See `query::Query`.
12use crate::api::query::{Path, Query};
13use axum::response::{IntoResponse, Response};
14use axum::Json;
15use rustango::core::Column as _;
16use rustango::extractors::Tenant;
17use rustango::sql::FetcherPool as _;
18use serde::Deserialize;
19
20use super::query as q;
21use crate::snippet::Snippet;
22
23#[derive(Debug, Default, Deserialize)]
24pub struct SnippetListQuery {
25    #[serde(flatten)]
26    pub list: q::ListQuery,
27    /// Optional `type_name` scope — filters snippets by type.
28    #[serde(default, rename = "type")]
29    pub type_name: Option<String>,
30}
31
32/// `GET /api/v2/snippets/`
33pub async fn list(tenant: Tenant, Query(qs): Query<SnippetListQuery>) -> Response {
34    match list_inner(&tenant, &qs).await {
35        Ok(resp) => resp,
36        Err(e) => {
37            tracing::error!(target: "rustango_cms::api", error = %e, "snippets list failed");
38            crate::api::error::ApiError::internal().into_response()
39        }
40    }
41}
42
43async fn list_inner(
44    tenant: &Tenant,
45    qs: &SnippetListQuery,
46) -> Result<Response, rustango::sql::ExecError> {
47    let pool = tenant.pool();
48    let (limit, offset) = q::paginate(&qs.list);
49    let fields = q::field_set(&qs.list);
50    let orderings = match q::parse_order_in(&qs.list, &SNIPPET_ORDER_FIELDS) {
51        Ok(v) => v,
52        Err(msg) => return Ok(crate::api::error::ApiError::bad_request(msg).into_response()),
53    };
54
55    // #changes — `?updated_since=` so a polling client can ask for only
56    // what moved, instead of re-fetching the collection and diffing it.
57    let updated_since = match crate::api::query::parse_updated_since(&qs.list) {
58        Ok(v) => v,
59        Err(msg) => return Ok(crate::api::error::ApiError::bad_request(msg).into_response()),
60    };
61    // Exact filters run in SQL (#655); so do count and paging unless a
62    // text search (accent-folded, in Rust) or a text/random order needs
63    // the narrowed set in memory.
64    let narrowed = || {
65        let mut qs_db = Snippet::objects();
66        if let Some(t) = qs.type_name.as_deref().filter(|s| !s.is_empty()) {
67            qs_db = qs_db.where_(Snippet::type_name.eq(t.to_owned()));
68        }
69        if let Some(since) = updated_since {
70            qs_db = qs_db.where_(Snippet::updated_at.gte(since));
71        }
72        qs_db
73    };
74    let search = qs.list.search.as_deref().filter(|s| !s.trim().is_empty());
75    let sql_order: Option<Vec<(&'static str, bool)>> = if search.is_some() {
76        None
77    } else if orderings.is_empty() {
78        Some(vec![("updated_at", true)])
79    } else {
80        orderings
81            .iter()
82            .map(|o| match o.field.as_str() {
83                _ if o.random => None,
84                "updated_at" => Some(("updated_at", o.descending)),
85                "created_at" => Some(("created_at", o.descending)),
86                // Text orders stay in Rust: collations differ per backend.
87                _ => None,
88            })
89            .collect()
90    };
91    let (window, total_count): (Vec<Snippet>, usize) = if let Some(mut order) = sql_order {
92        use rustango::sql::CounterPool as _;
93        order.push(("id", true));
94        let total = usize::try_from(narrowed().count(pool).await?).unwrap_or_default();
95        let rows = narrowed()
96            .order_by(&order)
97            .limit(limit as i64)
98            // A huge `?offset=` must not wrap negative (backends differ).
99            .offset(i64::try_from(offset).unwrap_or(i64::MAX))
100            .fetch(pool)
101            .await?;
102        (rows, total)
103    } else {
104        let mut rows: Vec<Snippet> = narrowed().order_by(&[("id", true)]).fetch(pool).await?;
105        if let Some(needle) = search {
106            let n = crate::api::search::fold(needle);
107            rows.retain(|s| {
108                crate::api::search::contains_folded(&s.title, &n)
109                    || crate::api::search::contains_folded(&s.slug, &n)
110                    || crate::api::search::contains_folded(&s.type_name, &n)
111                    || crate::api::search::contains_folded(&s.body_markdown, &n)
112            });
113        }
114        if orderings.iter().any(|o| o.random) {
115            use rand::seq::SliceRandom as _;
116            rows.shuffle(&mut rand::rng());
117        } else if !orderings.is_empty() {
118            rows.sort_by(|a, b| compare_snippet(a, b, &orderings));
119        } else {
120            rows.sort_by(|a, b| b.updated_at.get().cmp(&a.updated_at.get()));
121        }
122        let total = rows.len();
123        (rows.into_iter().skip(offset).take(limit).collect(), total)
124    };
125
126    let mut items = Vec::with_capacity(window.len());
127    for s in &window {
128        let mut obj = serialize_snippet(s);
129        // Validated against the first serialized row rather than a
130        // hand-written list, so it cannot drift from what we return.
131        if let Err(msg) = q::validate_fields(fields.as_ref(), &obj) {
132            return Ok(crate::api::error::ApiError::bad_request(msg).into_response());
133        }
134        q::apply_fields(&mut obj, fields.as_ref());
135        items.push(serde_json::Value::Object(obj));
136    }
137
138    Ok(Json(q::ListEnvelope {
139        meta: q::ListMeta::paged(total_count, limit, offset),
140        items,
141    })
142    .into_response())
143}
144
145/// `GET /api/v2/snippets/{id}/`
146pub async fn detail(
147    tenant: Tenant,
148    Path(id): Path<i64>,
149    Query(q): Query<crate::api::query::DetailFields>,
150) -> Response {
151    match detail_inner(&tenant, id, &q).await {
152        Ok(resp) => resp,
153        Err(e) => {
154            tracing::error!(target: "rustango_cms::api", error = %e, "snippet detail failed");
155            crate::api::error::ApiError::internal().into_response()
156        }
157    }
158}
159
160async fn detail_inner(
161    tenant: &Tenant,
162    id: i64,
163    q: &crate::api::query::DetailFields,
164) -> Result<Response, rustango::sql::ExecError> {
165    let row: Option<Snippet> = Snippet::objects()
166        .where_(Snippet::id.eq(id))
167        .first(tenant.pool())
168        .await?;
169    match row {
170        Some(row) => {
171            let mut obj = serialize_snippet(&row);
172            crate::api::query::apply_fields(&mut obj, q.keep().as_ref());
173            Ok(Json(serde_json::Value::Object(obj)).into_response())
174        }
175        None => Ok(crate::api::error::ApiError::not_found("snippet").into_response()),
176    }
177}
178
179fn serialize_snippet(s: &Snippet) -> serde_json::Map<String, serde_json::Value> {
180    let id = s.id.get().copied().unwrap_or_default();
181    let mut obj = serde_json::Map::new();
182    obj.insert("id".to_owned(), serde_json::json!(id));
183    obj.insert(
184        "meta".to_owned(),
185        serde_json::json!({
186            "type": "cms.Snippet",
187            "type_name": s.type_name,
188            "detail_url": format!("/api/v2/snippets/{id}/"),
189            "updated_at": s.updated_at.get().copied(),
190        }),
191    );
192    obj.insert("type_name".to_owned(), serde_json::json!(s.type_name));
193    obj.insert("slug".to_owned(), serde_json::json!(s.slug));
194    obj.insert("title".to_owned(), serde_json::json!(s.title));
195    obj.insert("folder_path".to_owned(), serde_json::json!(s.folder_path));
196    obj.insert(
197        "body_markdown".to_owned(),
198        serde_json::json!(s.body_markdown),
199    );
200    obj.insert("data".to_owned(), s.data.clone());
201    obj
202}
203
204/// Fields `?order=` accepts here. Must match the arms of
205/// `compare_snippet` below.
206const SNIPPET_ORDER_FIELDS: [&str; 6] =
207    ["title", "slug", "type_name", "type", "updated_at", "created_at"];
208
209fn compare_snippet(a: &Snippet, b: &Snippet, specs: &[q::OrderSpec]) -> std::cmp::Ordering {
210    for spec in specs {
211        let ord = match spec.field.as_str() {
212            "title" => a.title.cmp(&b.title),
213            "slug" => a.slug.cmp(&b.slug),
214            "type_name" | "type" => a.type_name.cmp(&b.type_name),
215            "updated_at" => a.updated_at.get().cmp(&b.updated_at.get()),
216            "created_at" => a.created_at.get().cmp(&b.created_at.get()),
217            _ => continue,
218        };
219        if ord != std::cmp::Ordering::Equal {
220            return if spec.descending { ord.reverse() } else { ord };
221        }
222    }
223    std::cmp::Ordering::Equal
224}