1use serde::{Deserialize, Deserializer, Serialize};
6
7pub const MAX_LIMIT: usize = 100;
10pub const DEFAULT_LIMIT: usize = 20;
12
13pub 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
42pub 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#[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 #[serde(default, deserialize_with = "empty_string_as_none")]
65 pub fields: Option<String>,
66 #[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 #[serde(default, deserialize_with = "empty_string_as_none")]
81 pub updated_since: Option<String>,
82}
83
84pub 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#[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 #[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#[must_use]
128pub fn clamp_limit(requested: Option<usize>) -> usize {
129 clamp_page_size(requested, DEFAULT_LIMIT, MAX_LIMIT)
130}
131
132#[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#[must_use]
142pub fn paginate(q: &ListQuery) -> (usize, usize) {
143 (clamp_limit(q.limit), q.offset.unwrap_or(0))
144}
145
146#[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
159pub 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#[derive(Debug, Clone)]
173pub struct OrderSpec {
174 pub field: String,
175 pub descending: bool,
176 pub random: bool,
177}
178
179#[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
208pub 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
241pub 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#[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 pub has_more: bool,
295 #[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 #[serde(skip_serializing_if = "Option::is_none")]
307 pub did_you_mean: Option<String>,
308}
309
310impl ListMeta {
311 #[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
329pub 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 Err(e) => Err(crate::api::error::ApiError::bad_request(e.body_text())),
364 }
365 }
366}
367
368pub 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 #[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 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 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 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 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 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 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 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}