Skip to main content

rustango_cms/api/
query.rs

1//! Shared query helpers for the v2 API.
2//!
3//! Pagination caps, sparse-field selection, and the meta envelope.
4
5use serde::{Deserialize, Deserializer, Serialize};
6
7/// Hard cap on `?limit=`.
8/// Beyond this, slow clients can DoS the cms with one request.
9pub const MAX_LIMIT: usize = 100;
10/// Default page size when `?limit=` is omitted.
11pub const DEFAULT_LIMIT: usize = 20;
12
13/// Deserialize an optional query parameter, treating an **empty value as
14/// absent**.
15///
16/// `?root=` is what a client sends when it builds a URL from a template
17/// and the value happens to be unset — `?root=&depth=&locale=` is an
18/// entirely ordinary request. Plain `Option<i64>` rejects it with
19/// `400 cannot parse integer from empty string`, which is both wrong and
20/// hostile: the parameter is optional, and omitting its value is the
21/// clearest way to say so.
22///
23/// A non-empty value that still doesn't parse remains a 400 — that is a
24/// genuine client error, and silently coercing `?depth=abc` to the
25/// default would hide it.
26///
27/// # Errors
28/// Propagates the underlying parse failure for non-empty values.
29pub fn empty_as_none<'de, D, T>(de: D) -> Result<Option<T>, D::Error>
30where
31    D: Deserializer<'de>,
32    T: std::str::FromStr,
33    T::Err: std::fmt::Display,
34{
35    let raw = Option::<String>::deserialize(de)?;
36    match raw.as_deref().map(str::trim) {
37        None | Some("") => Ok(None),
38        Some(s) => s.parse().map(Some).map_err(serde::de::Error::custom),
39    }
40}
41
42/// Like [`empty_as_none`] for string parameters: `?locale=` means "not
43/// specified", never the locale whose code is the empty string.
44///
45/// # Errors
46/// Only the underlying deserializer's own failures.
47pub fn empty_string_as_none<'de, D>(de: D) -> Result<Option<String>, D::Error>
48where
49    D: Deserializer<'de>,
50{
51    let raw = Option::<String>::deserialize(de)?;
52    Ok(raw.filter(|s| !s.trim().is_empty()))
53}
54
55/// Common query parameters that work across every list endpoint.
56#[derive(Debug, Default, Deserialize)]
57pub struct ListQuery {
58    #[serde(default, deserialize_with = "empty_as_none")]
59    pub limit: Option<usize>,
60    #[serde(default, deserialize_with = "empty_as_none")]
61    pub offset: Option<usize>,
62    /// Comma-separated field allowlist. When set, only these fields
63    /// appear in each row's content (meta is always preserved).
64    #[serde(default, deserialize_with = "empty_string_as_none")]
65    pub fields: Option<String>,
66    /// Comma-separated ordering. Prefix `-` for descending. `random`
67    /// shuffles client-side (cheap on bounded list sizes).
68    #[serde(default, deserialize_with = "empty_string_as_none")]
69    pub order: Option<String>,
70    #[serde(default, deserialize_with = "empty_string_as_none")]
71    pub search: Option<String>,
72    /// `?updated_since=2026-01-02T15:04:05Z` — only rows touched at or
73    /// after this instant.
74    ///
75    /// Without it a client polling for changes has to re-fetch and diff
76    /// the whole collection, which is the only option the API offered.
77    /// RFC 3339; anything else is a 400 rather than a silent full result,
78    /// because quietly ignoring it would make a client believe nothing
79    /// had changed.
80    #[serde(default, deserialize_with = "empty_string_as_none")]
81    pub updated_since: Option<String>,
82}
83
84/// Parse `?updated_since=` as RFC 3339.
85///
86/// # Errors
87/// A human-readable message when the value is not a valid timestamp.
88pub fn parse_updated_since(
89    q: &ListQuery,
90) -> Result<Option<chrono::DateTime<chrono::Utc>>, String> {
91    let Some(raw) = q.updated_since.as_deref() else {
92        return Ok(None);
93    };
94    chrono::DateTime::parse_from_rfc3339(raw)
95        .map(|dt| Some(dt.with_timezone(&chrono::Utc)))
96        .map_err(|e| format!("`updated_since` must be an RFC 3339 timestamp: {e}"))
97}
98
99/// The query a *detail* endpoint accepts.
100///
101/// Sparse selection used to be list-only, so a client fetching one row
102/// had no way to trim the payload — and on a page that meant pulling
103/// `extension`, `builder` and the whole `children` array to read a title.
104#[derive(Debug, Default, Deserialize)]
105pub struct DetailFields {
106    #[serde(default, deserialize_with = "empty_string_as_none")]
107    pub fields: Option<String>,
108}
109
110impl DetailFields {
111    /// The parsed allowlist, or `None` for "everything".
112    #[must_use]
113    pub fn keep(&self) -> Option<std::collections::HashSet<String>> {
114        self.fields.as_ref().map(|raw| {
115            raw.split(',')
116                .map(str::trim)
117                .filter(|s| !s.is_empty())
118                .map(str::to_owned)
119                .collect()
120        })
121    }
122}
123
124/// Clamp a requested page size into `1..=MAX_LIMIT`, defaulting when
125/// absent. Shared so every list endpoint agrees on the bounds — the
126/// menus list previously re-derived them and could have drifted.
127#[must_use]
128pub fn clamp_limit(requested: Option<usize>) -> usize {
129    clamp_page_size(requested, DEFAULT_LIMIT, MAX_LIMIT)
130}
131
132/// The page-size rule, for a surface with its own bounds (the MCP tools
133/// allow larger pages than the public API): `default` when absent, else
134/// clamped into `1..=max`.
135#[must_use]
136pub fn clamp_page_size(requested: Option<usize>, default: usize, max: usize) -> usize {
137    requested.unwrap_or(default).clamp(1, max)
138}
139
140/// Clamped `(limit, offset)` from a [`ListQuery`].
141#[must_use]
142pub fn paginate(q: &ListQuery) -> (usize, usize) {
143    (clamp_limit(q.limit), q.offset.unwrap_or(0))
144}
145
146/// Parsed sparse-field selector. `None` means "no selection — return
147/// every field"; `Some(set)` means "only these top-level keys".
148#[must_use]
149pub fn field_set(q: &ListQuery) -> Option<std::collections::HashSet<String>> {
150    q.fields.as_ref().map(|raw| {
151        raw.split(',')
152            .map(str::trim)
153            .filter(|s| !s.is_empty())
154            .map(str::to_owned)
155            .collect()
156    })
157}
158
159/// Apply a sparse-field filter in place. `meta` and `id` are always
160/// preserved so consumers can still walk the response.
161pub fn apply_fields(
162    obj: &mut serde_json::Map<String, serde_json::Value>,
163    keep: Option<&std::collections::HashSet<String>>,
164) {
165    let Some(keep) = keep else {
166        return;
167    };
168    obj.retain(|k, _| k == "id" || k == "meta" || keep.contains(k));
169}
170
171/// `(direction, field)` parsed from one `order=` segment.
172#[derive(Debug, Clone)]
173pub struct OrderSpec {
174    pub field: String,
175    pub descending: bool,
176    pub random: bool,
177}
178
179/// Parse `?order=` into a vector of [`OrderSpec`]s in declaration
180/// order. Empty input → empty vec (caller falls back to its default).
181#[must_use]
182pub fn parse_order(q: &ListQuery) -> Vec<OrderSpec> {
183    let Some(raw) = q.order.as_deref() else {
184        return Vec::new();
185    };
186    raw.split(',')
187        .map(str::trim)
188        .filter(|s| !s.is_empty())
189        .map(|seg| {
190            if seg == "random" {
191                return OrderSpec {
192                    field: String::new(),
193                    descending: false,
194                    random: true,
195                };
196            }
197            let descending = seg.starts_with('-');
198            let field = seg.trim_start_matches('-').to_owned();
199            OrderSpec {
200                field,
201                descending,
202                random: false,
203            }
204        })
205        .collect()
206}
207
208/// Parse `?order=`, refusing a field this endpoint cannot sort by.
209///
210/// Dropping an unrecognised field silently was the original behaviour,
211/// and it was worse than it sounds. Each comparator answers `continue`
212/// for a field it doesn't know, so an `?order=` naming *only* unknown
213/// fields compared every pair `Equal`; the sort became a no-op and the
214/// endpoint's documented default ordering was discarded along with it. A
215/// client that typo'd `?order=titel` got neither its ordering nor the
216/// default, with nothing said.
217///
218/// Refusing is also what this API already does one endpoint over:
219/// `/search/?type=bogus` is a `400` "so a typo doesn't look like 'no
220/// matches'". The same reasoning applies to a typo that looks like
221/// "wrong order".
222///
223/// `random` is always accepted — it names no field.
224///
225/// # Errors
226/// A message naming the offending field and listing the valid ones.
227pub fn parse_order_in(q: &ListQuery, allowed: &[&str]) -> Result<Vec<OrderSpec>, String> {
228    let specs = parse_order(q);
229    for spec in &specs {
230        if !spec.random && !allowed.contains(&spec.field.as_str()) {
231            return Err(format!(
232                "unknown `order` field `{}` — expected any of: {}, or `random`",
233                spec.field,
234                allowed.join(", "),
235            ));
236        }
237    }
238    Ok(specs)
239}
240
241/// Refuse a `?fields=` name the serializer never emits.
242///
243/// Same defect, different parameter: an unknown name was dropped, so
244/// `?fields=titel` returned `{"id":…,"meta":{…}}` — every object stripped
245/// to nothing, with no hint that the client had misspelled the one field
246/// it asked for.
247///
248/// Validated against the keys of a **serialized sample** rather than a
249/// hand-written list, so it cannot drift from what the endpoint actually
250/// returns. `id` and `meta` are always permitted: they are always kept in
251/// the output, so naming one is harmless even where a serializer omits
252/// it.
253///
254/// A caller with no rows to sample skips validation — there is nothing to
255/// filter, and guessing an allowlist from an empty page would mean
256/// inventing the very list this avoids.
257///
258/// # Errors
259/// A message naming the offending field and listing the valid ones.
260pub fn validate_fields(
261    requested: Option<&std::collections::HashSet<String>>,
262    sample: &serde_json::Map<String, serde_json::Value>,
263) -> Result<(), String> {
264    let Some(requested) = requested else {
265        return Ok(());
266    };
267    let known = |k: &str| k == "id" || k == "meta" || sample.contains_key(k);
268    let Some(bad) = requested.iter().find(|k| !known(k)) else {
269        return Ok(());
270    };
271    let mut valid: Vec<&str> = sample.keys().map(String::as_str).collect();
272    valid.sort_unstable();
273    Err(format!(
274        "unknown `fields` name `{bad}` — expected any of: {}",
275        valid.join(", "),
276    ))
277}
278
279/// The standard list envelope: `{ meta: { total_count, limit, offset }, items: [...] }`.
280#[derive(Debug, Serialize)]
281pub struct ListEnvelope {
282    pub meta: ListMeta,
283    pub items: Vec<serde_json::Value>,
284}
285
286#[derive(Debug, Default, Serialize)]
287pub struct ListMeta {
288    pub total_count: usize,
289    pub limit: usize,
290    pub offset: usize,
291    /// Whether another page exists after this one. A client used to have
292    /// to derive this from `offset + items.len() < total_count`, and get
293    /// it wrong at the boundary.
294    pub has_more: bool,
295    /// Offsets to walk with, rather than fully-qualified URLs: the server
296    /// sits behind a proxy often enough that it cannot reliably rebuild
297    /// its own public URL, and a wrong link is worse than none. `null` at
298    /// either end of the range.
299    #[serde(skip_serializing_if = "Option::is_none")]
300    pub next_offset: Option<usize>,
301    #[serde(skip_serializing_if = "Option::is_none")]
302    pub previous_offset: Option<usize>,
303    /// A fuzzy "did you mean?" suggestion, set only by the page
304    /// search when it returns no hits but a near-match title exists.
305    /// Omitted from the JSON otherwise.
306    #[serde(skip_serializing_if = "Option::is_none")]
307    pub did_you_mean: Option<String>,
308}
309
310impl ListMeta {
311    /// Build the envelope's meta, deriving the paging cursors once so
312    /// every list endpoint reports them identically.
313    #[must_use]
314    pub fn paged(total_count: usize, limit: usize, offset: usize) -> Self {
315        let end = offset.saturating_add(limit);
316        let has_more = end < total_count;
317        Self {
318            total_count,
319            limit,
320            offset,
321            has_more,
322            next_offset: has_more.then_some(end),
323            previous_offset: (offset > 0).then(|| offset.saturating_sub(limit)),
324            did_you_mean: None,
325        }
326    }
327}
328
329/// `axum::extract::Query`, rejecting in JSON.
330///
331/// axum's own extractor refuses a malformed query string with a
332/// `text/plain` body — `Failed to deserialize query string: invalid digit
333/// found in string`. Every *handler* on this API answers in the JSON
334/// envelope, and `docs/api.md` promises that unconditionally, so a client
335/// whose fetch wrapper parses failures as JSON works fine right up until
336/// someone types `?limit=abc`, at which point it raises a `SyntaxError`
337/// from its own parser instead of reporting the 400.
338///
339/// A malformed query value is not an exotic case: it is what a SPA sends
340/// whenever a route param arrives as the wrong type, and it is the same
341/// surface `?root=` was reported on.
342///
343/// The destructuring pattern is identical to axum's — `Query(q):
344/// Query<T>` — so switching a handler over is an import change.
345pub struct Query<T>(pub T);
346
347impl<T, S> axum::extract::FromRequestParts<S> for Query<T>
348where
349    T: serde::de::DeserializeOwned,
350    S: Send + Sync,
351{
352    type Rejection = crate::api::error::ApiError;
353
354    async fn from_request_parts(
355        parts: &mut axum::http::request::Parts,
356        state: &S,
357    ) -> Result<Self, Self::Rejection> {
358        match axum::extract::Query::<T>::from_request_parts(parts, state).await {
359            Ok(axum::extract::Query(v)) => Ok(Self(v)),
360            // serde's text is kept: it names the offending field where it
361            // can ("root: invalid digit…"), which is the only clue a
362            // client gets about *which* parameter it got wrong.
363            Err(e) => Err(crate::api::error::ApiError::bad_request(e.body_text())),
364        }
365    }
366}
367
368/// `axum::extract::Path`, rejecting in JSON.
369///
370/// Same defect as [`Query`]: `/api/v2/pages/abc/` answers `Invalid URL:
371/// Cannot parse \`abc\` to a \`i64\`` as `text/plain`.
372pub struct Path<T>(pub T);
373
374impl<T, S> axum::extract::FromRequestParts<S> for Path<T>
375where
376    T: serde::de::DeserializeOwned + Send,
377    S: Send + Sync,
378{
379    type Rejection = crate::api::error::ApiError;
380
381    async fn from_request_parts(
382        parts: &mut axum::http::request::Parts,
383        state: &S,
384    ) -> Result<Self, Self::Rejection> {
385        match axum::extract::Path::<T>::from_request_parts(parts, state).await {
386            Ok(axum::extract::Path(v)) => Ok(Self(v)),
387            Err(e) => Err(crate::api::error::ApiError::bad_request(e.body_text())),
388        }
389    }
390}
391
392#[cfg(test)]
393mod tests {
394    use super::*;
395
396    // `?root=&depth=&locale=` — a client rendering a URL template with
397    // unset values. Every one of these was a 400 before `empty_as_none`.
398    #[test]
399    fn an_empty_numeric_param_reads_as_absent() {
400        let q: ListQuery = serde_urlencoded::from_str("limit=&offset=").expect("parse");
401        assert_eq!(q.limit, None);
402        assert_eq!(q.offset, None);
403        assert_eq!(paginate(&q), (DEFAULT_LIMIT, 0));
404    }
405
406    #[test]
407    fn an_empty_string_param_reads_as_absent() {
408        let q: ListQuery = serde_urlencoded::from_str("fields=&order=&search=").expect("parse");
409        assert_eq!(q.fields, None);
410        assert_eq!(q.order, None);
411        assert_eq!(q.search, None);
412        assert!(field_set(&q).is_none(), "empty ?fields= must not select nothing");
413    }
414
415    #[test]
416    fn a_whitespace_only_param_reads_as_absent() {
417        let q: ListQuery = serde_urlencoded::from_str("limit=%20&search=%20").expect("parse");
418        assert_eq!(q.limit, None);
419        assert_eq!(q.search, None);
420    }
421
422    #[test]
423    fn a_real_value_still_parses() {
424        let q: ListQuery = serde_urlencoded::from_str("limit=5&offset=10&search=x").expect("parse");
425        assert_eq!(q.limit, Some(5));
426        assert_eq!(q.offset, Some(10));
427        assert_eq!(q.search.as_deref(), Some("x"));
428    }
429
430    #[test]
431    fn a_non_empty_unparseable_value_is_still_an_error() {
432        // Coercing `?limit=abc` to the default would hide a real client
433        // bug; only *emptiness* means "absent".
434        let r: Result<ListQuery, _> = serde_urlencoded::from_str("limit=abc");
435        assert!(r.is_err());
436    }
437
438    fn q_with_since(v: &str) -> ListQuery {
439        ListQuery {
440            updated_since: Some(v.to_owned()),
441            ..Default::default()
442        }
443    }
444
445    #[test]
446    fn updated_since_parses_rfc3339() {
447        let got = parse_updated_since(&q_with_since("2026-01-02T15:04:05Z")).expect("valid");
448        assert_eq!(
449            got.map(|d| d.to_rfc3339()),
450            Some("2026-01-02T15:04:05+00:00".to_owned()),
451        );
452    }
453
454    #[test]
455    fn updated_since_normalizes_an_offset_to_utc() {
456        let got = parse_updated_since(&q_with_since("2026-01-02T15:04:05+02:00")).expect("valid");
457        assert_eq!(
458            got.map(|d| d.to_rfc3339()),
459            Some("2026-01-02T13:04:05+00:00".to_owned()),
460        );
461    }
462
463    #[test]
464    fn updated_since_absent_is_none() {
465        assert_eq!(parse_updated_since(&ListQuery::default()), Ok(None));
466    }
467
468    #[test]
469    fn a_malformed_updated_since_is_an_error_not_a_full_result() {
470        // Silently ignoring it would tell a polling client that nothing
471        // had changed since a timestamp it never actually applied.
472        assert!(parse_updated_since(&q_with_since("yesterday")).is_err());
473        assert!(parse_updated_since(&q_with_since("2026-13-45")).is_err());
474    }
475
476    #[test]
477    fn paged_reports_the_next_offset_only_when_there_is_one() {
478        let m = ListMeta::paged(50, 20, 0);
479        assert!(m.has_more);
480        assert_eq!(m.next_offset, Some(20));
481        assert_eq!(m.previous_offset, None, "no page before the first");
482
483        let m = ListMeta::paged(50, 20, 40);
484        assert!(!m.has_more, "40 + 20 covers all 50");
485        assert_eq!(m.next_offset, None);
486        assert_eq!(m.previous_offset, Some(20));
487    }
488
489    #[test]
490    fn paged_handles_the_exact_boundary() {
491        // The off-by-one a client would have written by hand: the last
492        // full page must not advertise another one.
493        let m = ListMeta::paged(40, 20, 20);
494        assert!(!m.has_more);
495        assert_eq!(m.next_offset, None);
496    }
497
498    #[test]
499    fn paged_survives_an_offset_past_the_end() {
500        let m = ListMeta::paged(10, 20, 999_999);
501        assert!(!m.has_more);
502        assert_eq!(m.next_offset, None);
503        assert_eq!(m.previous_offset, Some(999_979));
504    }
505
506    #[test]
507    fn paginate_clamps_to_max() {
508        let q = ListQuery {
509            limit: Some(9999),
510            offset: None,
511            ..Default::default()
512        };
513        let (limit, offset) = paginate(&q);
514        assert_eq!(limit, MAX_LIMIT);
515        assert_eq!(offset, 0);
516    }
517
518    #[test]
519    fn paginate_default_when_unset() {
520        let q = ListQuery::default();
521        assert_eq!(paginate(&q), (DEFAULT_LIMIT, 0));
522    }
523
524    #[test]
525    fn paginate_floor_one_on_zero() {
526        let q = ListQuery {
527            limit: Some(0),
528            ..Default::default()
529        };
530        assert_eq!(paginate(&q).0, 1);
531    }
532
533    #[test]
534    fn field_set_parses_csv() {
535        let q = ListQuery {
536            fields: Some("title, slug,body".to_owned()),
537            ..Default::default()
538        };
539        let set = field_set(&q).expect("set present");
540        assert!(set.contains("title"));
541        assert!(set.contains("slug"));
542        assert!(set.contains("body"));
543    }
544
545    #[test]
546    fn apply_fields_keeps_meta_and_id() {
547        let mut obj: serde_json::Map<String, serde_json::Value> =
548            serde_json::from_str(r#"{"id":1,"meta":{},"title":"a","slug":"b"}"#).unwrap();
549        let keep: std::collections::HashSet<String> = ["slug".to_owned()].into_iter().collect();
550        apply_fields(&mut obj, Some(&keep));
551        assert!(obj.contains_key("id"));
552        assert!(obj.contains_key("meta"));
553        assert!(obj.contains_key("slug"));
554        assert!(!obj.contains_key("title"));
555    }
556
557    #[test]
558    fn parse_order_descending_prefix() {
559        let q = ListQuery {
560            order: Some("-published_at,title".to_owned()),
561            ..Default::default()
562        };
563        let specs = parse_order(&q);
564        assert_eq!(specs.len(), 2);
565        assert_eq!(specs[0].field, "published_at");
566        assert!(specs[0].descending);
567        assert_eq!(specs[1].field, "title");
568        assert!(!specs[1].descending);
569    }
570
571    #[test]
572    fn parse_order_random() {
573        let q = ListQuery {
574            order: Some("random".to_owned()),
575            ..Default::default()
576        };
577        let specs = parse_order(&q);
578        assert_eq!(specs.len(), 1);
579        assert!(specs[0].random);
580    }
581
582    #[test]
583    fn an_unknown_order_field_is_refused_by_name() {
584        // The whole point: a typo must not look like "wrong order".
585        let q = ListQuery {
586            order: Some("titel".to_owned()),
587            ..Default::default()
588        };
589        let err = parse_order_in(&q, &["title", "slug"]).expect_err("must refuse");
590        assert!(err.contains("titel"), "{err}");
591        assert!(err.contains("title"), "the valid names must be listed: {err}");
592    }
593
594    #[test]
595    fn one_bad_field_refuses_the_whole_ordering() {
596        // Accepting the good half would silently apply an ordering the
597        // client did not ask for.
598        let q = ListQuery {
599            order: Some("title,-titel".to_owned()),
600            ..Default::default()
601        };
602        assert!(parse_order_in(&q, &["title"]).is_err());
603    }
604
605    #[test]
606    fn known_fields_and_random_pass_through() {
607        let q = ListQuery {
608            order: Some("-title,random".to_owned()),
609            ..Default::default()
610        };
611        let specs = parse_order_in(&q, &["title"]).expect("accepted");
612        assert_eq!(specs.len(), 2);
613        assert!(specs[0].descending);
614        assert!(specs[1].random, "`random` names no field, so no allowlist applies");
615    }
616
617    #[test]
618    fn no_order_at_all_is_not_an_error() {
619        let q = ListQuery::default();
620        assert!(parse_order_in(&q, &["title"]).expect("accepted").is_empty());
621    }
622
623    fn sample() -> serde_json::Map<String, serde_json::Value> {
624        let mut m = serde_json::Map::new();
625        m.insert("title".to_owned(), serde_json::json!("T"));
626        m.insert("slug".to_owned(), serde_json::json!("t"));
627        m
628    }
629
630    #[test]
631    fn an_unknown_fields_name_is_refused_by_name() {
632        // Previously this returned `{id, meta}` — every object stripped
633        // to nothing, with no hint the name was misspelled.
634        let mut want = std::collections::HashSet::new();
635        want.insert("titel".to_owned());
636        let err = validate_fields(Some(&want), &sample()).expect_err("must refuse");
637        assert!(err.contains("titel"), "{err}");
638        assert!(err.contains("slug"), "the valid names must be listed: {err}");
639    }
640
641    #[test]
642    fn id_and_meta_are_always_nameable() {
643        // They are always kept in the output, so asking for one is
644        // harmless even where the serializer does not list it.
645        let want: std::collections::HashSet<String> =
646            ["id", "meta"].iter().map(|s| (*s).to_owned()).collect();
647        assert!(validate_fields(Some(&want), &sample()).is_ok());
648    }
649
650    #[test]
651    fn no_fields_parameter_validates_nothing() {
652        assert!(validate_fields(None, &sample()).is_ok());
653        assert!(validate_fields(None, &serde_json::Map::new()).is_ok());
654    }
655}