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    let mut rows: Vec<Snippet> = Snippet::objects().fetch(pool).await?;
56
57    if let Some(t) = qs.type_name.as_deref().filter(|s| !s.is_empty()) {
58        rows.retain(|s| s.type_name == t);
59    }
60    if let Some(needle) = qs.list.search.as_deref().filter(|s| !s.trim().is_empty()) {
61        let n = crate::api::search::fold(needle);
62        rows.retain(|s| {
63            crate::api::search::contains_folded(&s.title, &n)
64                || crate::api::search::contains_folded(&s.slug, &n)
65                || crate::api::search::contains_folded(&s.type_name, &n)
66                || crate::api::search::contains_folded(&s.body_markdown, &n)
67        });
68    }
69
70    if orderings.iter().any(|o| o.random) {
71        use rand::seq::SliceRandom as _;
72        rows.shuffle(&mut rand::rng());
73    } else if !orderings.is_empty() {
74        rows.sort_by(|a, b| compare_snippet(a, b, &orderings));
75    } else {
76        rows.sort_by(|a, b| b.updated_at.get().cmp(&a.updated_at.get()));
77    }
78
79    // #changes — `?updated_since=` so a polling client can ask for only
80    // what moved, instead of re-fetching the collection and diffing it.
81    let updated_since = match crate::api::query::parse_updated_since(&qs.list) {
82        Ok(v) => v,
83        Err(msg) => return Ok(crate::api::error::ApiError::bad_request(msg).into_response()),
84    };
85    if let Some(since) = updated_since {
86        rows.retain(|r| r.updated_at.get().copied().is_some_and(|t| t >= since));
87    }
88
89    let total_count = rows.len();
90    let window: Vec<&Snippet> = rows.iter().skip(offset).take(limit).collect();
91
92    let mut items = Vec::with_capacity(window.len());
93    for s in window {
94        let mut obj = serialize_snippet(s);
95        // Validated against the first serialized row rather than a
96        // hand-written list, so it cannot drift from what we return.
97        if let Err(msg) = q::validate_fields(fields.as_ref(), &obj) {
98            return Ok(crate::api::error::ApiError::bad_request(msg).into_response());
99        }
100        q::apply_fields(&mut obj, fields.as_ref());
101        items.push(serde_json::Value::Object(obj));
102    }
103
104    Ok(Json(q::ListEnvelope {
105        meta: q::ListMeta::paged(total_count, limit, offset),
106        items,
107    })
108    .into_response())
109}
110
111/// `GET /api/v2/snippets/{id}/`
112pub async fn detail(
113    tenant: Tenant,
114    Path(id): Path<i64>,
115    Query(q): Query<crate::api::query::DetailFields>,
116) -> Response {
117    match detail_inner(&tenant, id, &q).await {
118        Ok(resp) => resp,
119        Err(e) => {
120            tracing::error!(target: "rustango_cms::api", error = %e, "snippet detail failed");
121            crate::api::error::ApiError::internal().into_response()
122        }
123    }
124}
125
126async fn detail_inner(
127    tenant: &Tenant,
128    id: i64,
129    q: &crate::api::query::DetailFields,
130) -> Result<Response, rustango::sql::ExecError> {
131    let row: Option<Snippet> = Snippet::objects()
132        .where_(Snippet::id.eq(id))
133        .first(tenant.pool())
134        .await?;
135    match row {
136        Some(row) => {
137            let mut obj = serialize_snippet(&row);
138            crate::api::query::apply_fields(&mut obj, q.keep().as_ref());
139            Ok(Json(serde_json::Value::Object(obj)).into_response())
140        }
141        None => Ok(crate::api::error::ApiError::not_found("snippet").into_response()),
142    }
143}
144
145fn serialize_snippet(s: &Snippet) -> serde_json::Map<String, serde_json::Value> {
146    let id = s.id.get().copied().unwrap_or_default();
147    let mut obj = serde_json::Map::new();
148    obj.insert("id".to_owned(), serde_json::json!(id));
149    obj.insert(
150        "meta".to_owned(),
151        serde_json::json!({
152            "type": "cms.Snippet",
153            "type_name": s.type_name,
154            "detail_url": format!("/api/v2/snippets/{id}/"),
155            "updated_at": s.updated_at.get().copied(),
156        }),
157    );
158    obj.insert("type_name".to_owned(), serde_json::json!(s.type_name));
159    obj.insert("slug".to_owned(), serde_json::json!(s.slug));
160    obj.insert("title".to_owned(), serde_json::json!(s.title));
161    obj.insert("folder_path".to_owned(), serde_json::json!(s.folder_path));
162    obj.insert(
163        "body_markdown".to_owned(),
164        serde_json::json!(s.body_markdown),
165    );
166    obj.insert("data".to_owned(), s.data.clone());
167    obj
168}
169
170/// Fields `?order=` accepts here. Must match the arms of
171/// `compare_snippet` below.
172const SNIPPET_ORDER_FIELDS: [&str; 6] =
173    ["title", "slug", "type_name", "type", "updated_at", "created_at"];
174
175fn compare_snippet(a: &Snippet, b: &Snippet, specs: &[q::OrderSpec]) -> std::cmp::Ordering {
176    for spec in specs {
177        let ord = match spec.field.as_str() {
178            "title" => a.title.cmp(&b.title),
179            "slug" => a.slug.cmp(&b.slug),
180            "type_name" | "type" => a.type_name.cmp(&b.type_name),
181            "updated_at" => a.updated_at.get().cmp(&b.updated_at.get()),
182            "created_at" => a.created_at.get().cmp(&b.created_at.get()),
183            _ => continue,
184        };
185        if ord != std::cmp::Ordering::Equal {
186            return if spec.descending { ord.reverse() } else { ord };
187        }
188    }
189    std::cmp::Ordering::Equal
190}