use std::{fmt, ops::Deref};
use axum::{extract::FromRequestParts, http::request::Parts};
use serde::Deserialize;
use crate::{
http::{
ApiProblem, ProblemCode, QueryParams, RequestContext, deserialize_bool_from_query,
deserialize_optional_u32_from_query,
},
pagination::{CursorPageRequest, OffsetPageRequest, PageLimits},
};
#[derive(Clone, Deserialize)]
pub struct CursorPaginationQuery {
#[serde(default, deserialize_with = "deserialize_optional_u32_from_query")]
page_size: Option<u32>,
cursor: Option<String>,
#[serde(default, deserialize_with = "deserialize_bool_from_query")]
include_total: bool,
}
impl fmt::Debug for CursorPaginationQuery {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("CursorPaginationQuery")
.field("page_size", &self.page_size)
.field("cursor", &self.cursor.as_ref().map(|_| "[REDACTED]"))
.field("include_total", &self.include_total)
.finish()
}
}
impl CursorPaginationQuery {
#[must_use]
pub const fn page_size(&self) -> Option<u32> {
self.page_size
}
#[must_use]
pub fn cursor(&self) -> Option<&str> {
self.cursor.as_deref()
}
#[must_use]
pub const fn include_total(&self) -> bool {
self.include_total
}
pub fn into_page_request(
self,
) -> Result<CursorPageRequest, crate::pagination::PaginationError> {
self.into_page_request_with_limits(PageLimits::default())
}
pub fn into_page_request_with_limits(
self,
limits: PageLimits,
) -> Result<CursorPageRequest, crate::pagination::PaginationError> {
CursorPageRequest::new_with_limits(self.page_size, self.cursor, self.include_total, limits)
}
}
#[derive(Debug, Clone, Deserialize)]
pub struct OffsetPaginationQuery {
#[serde(default, deserialize_with = "deserialize_optional_u32_from_query")]
page: Option<u32>,
#[serde(default, deserialize_with = "deserialize_optional_u32_from_query")]
page_size: Option<u32>,
}
impl OffsetPaginationQuery {
#[must_use]
pub const fn page(&self) -> Option<u32> {
self.page
}
#[must_use]
pub const fn page_size(&self) -> Option<u32> {
self.page_size
}
pub fn into_page_request(
self,
) -> Result<OffsetPageRequest, crate::pagination::PaginationError> {
self.into_page_request_with_limits(PageLimits::default())
}
pub fn into_page_request_with_limits(
self,
limits: PageLimits,
) -> Result<OffsetPageRequest, crate::pagination::PaginationError> {
OffsetPageRequest::new_with_limits(self.page, self.page_size, limits)
}
}
#[derive(Debug, Clone)]
pub struct CursorPagination(CursorPageRequest);
impl CursorPagination {
#[must_use]
pub const fn request(&self) -> &CursorPageRequest {
&self.0
}
#[must_use]
pub fn into_inner(self) -> CursorPageRequest {
self.0
}
}
impl AsRef<CursorPageRequest> for CursorPagination {
fn as_ref(&self) -> &CursorPageRequest {
self.request()
}
}
impl Deref for CursorPagination {
type Target = CursorPageRequest;
fn deref(&self) -> &Self::Target {
self.request()
}
}
#[derive(Debug, Clone)]
pub struct OffsetPagination(OffsetPageRequest);
impl OffsetPagination {
#[must_use]
pub const fn request(&self) -> &OffsetPageRequest {
&self.0
}
#[must_use]
pub fn into_inner(self) -> OffsetPageRequest {
self.0
}
}
impl AsRef<OffsetPageRequest> for OffsetPagination {
fn as_ref(&self) -> &OffsetPageRequest {
self.request()
}
}
impl Deref for OffsetPagination {
type Target = OffsetPageRequest;
fn deref(&self) -> &Self::Target {
self.request()
}
}
impl<S> FromRequestParts<S> for CursorPagination
where
S: Send + Sync,
{
type Rejection = ApiProblem;
async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
let limits = limits_from_parts(parts);
let query = QueryParams::<CursorPaginationQuery>::from_request_parts(parts, state)
.await?
.into_inner();
query
.into_page_request_with_limits(limits)
.map(Self)
.map_err(|error| {
ApiProblem::bad_request(ProblemCode::INVALID_PAGINATION, error.to_string())
.with_request_context(RequestContext::from_parts(parts))
})
}
}
impl<S> FromRequestParts<S> for OffsetPagination
where
S: Send + Sync,
{
type Rejection = ApiProblem;
async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
let limits = limits_from_parts(parts);
let query = QueryParams::<OffsetPaginationQuery>::from_request_parts(parts, state)
.await?
.into_inner();
query
.into_page_request_with_limits(limits)
.map(Self)
.map_err(|error| {
ApiProblem::bad_request(ProblemCode::INVALID_PAGINATION, error.to_string())
.with_request_context(RequestContext::from_parts(parts))
})
}
}
fn limits_from_parts(parts: &Parts) -> PageLimits {
parts
.extensions
.get::<PageLimits>()
.copied()
.unwrap_or_default()
}
#[cfg(test)]
mod tests {
use axum::{extract::Query, http::Uri};
use crate::pagination::{PageLimits, PaginationError};
use super::{CursorPagination, CursorPaginationQuery, OffsetPaginationQuery};
#[test]
fn pagination_query_uses_custom_limits() {
let query = CursorPaginationQuery {
page_size: None,
cursor: None,
include_total: true,
};
let request = query
.into_page_request_with_limits(PageLimits::new(25, 50).expect("limits should be valid"))
.expect("query should be valid");
assert_eq!(request.page_size(), 25);
assert!(request.include_total());
}
#[test]
fn pagination_query_debug_redacts_cursor() {
let cursor = "private-query-cursor";
let query = CursorPaginationQuery {
page_size: Some(10),
cursor: Some(cursor.to_owned()),
include_total: false,
};
let debug = format!("{query:?}");
assert!(debug.contains("[REDACTED]"));
assert!(!debug.contains(cursor));
assert_eq!(query.cursor(), Some(cursor));
}
#[test]
fn pagination_query_rejects_custom_limit_violations() {
let query = CursorPaginationQuery {
page_size: Some(51),
cursor: None,
include_total: false,
};
let result =
query.into_page_request_with_limits(PageLimits::new(25, 50).expect("valid limits"));
assert!(matches!(
result,
Err(PaginationError::PageSizeTooLarge { max: 50 })
));
}
#[test]
fn pagination_query_accepts_url_encoded_string_scalars() {
let uri: Uri = "/items?page_size=20&include_total=true"
.parse()
.expect("URI should parse");
let Query(query) = Query::<CursorPaginationQuery>::try_from_uri(&uri)
.expect("query string scalars should deserialize");
assert_eq!(query.page_size(), Some(20));
assert!(query.include_total());
}
#[test]
fn pagination_query_treats_empty_optional_numbers_as_absent() {
let uri: Uri = "/items?page_size=".parse().expect("URI should parse");
let Query(query) = Query::<CursorPaginationQuery>::try_from_uri(&uri)
.expect("empty optional number should deserialize");
assert_eq!(query.page_size(), None);
}
#[test]
fn offset_pagination_query_accepts_url_encoded_string_scalars() {
let uri: Uri = "/items?page=2&page_size=20"
.parse()
.expect("URI should parse");
let Query(query) = Query::<OffsetPaginationQuery>::try_from_uri(&uri)
.expect("query string scalars should deserialize");
assert_eq!(query.page(), Some(2));
assert_eq!(query.page_size(), Some(20));
}
#[test]
fn offset_pagination_query_uses_custom_limits() {
let query = OffsetPaginationQuery {
page: Some(2),
page_size: None,
};
let request = query
.into_page_request_with_limits(PageLimits::new(25, 50).expect("limits should be valid"))
.expect("query should be valid");
assert_eq!(request.page(), 2);
assert_eq!(request.page_size(), 25);
}
#[test]
fn pagination_wrapper_exposes_request_without_tuple_fields() {
let request = CursorPaginationQuery {
page_size: Some(10),
cursor: None,
include_total: false,
}
.into_page_request()
.expect("query should be valid");
let pagination = CursorPagination(request);
assert_eq!(pagination.page_size(), 10);
assert_eq!(pagination.request().page_size(), 10);
}
}