use std::{fmt, ops::Deref};
use axum::{
extract::{FromRequestParts, Query},
http::request::Parts,
};
use serde::Deserialize;
use crate::{
http::{
ApiProblem, ProblemCode, RequestContext, deserialize_bool_from_query,
deserialize_optional_u32_from_query,
},
pagination::{OffsetPageRequest, PageLimits, PageRequest},
};
#[derive(Clone, Deserialize)]
pub struct PaginationQuery {
#[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 PaginationQuery {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PaginationQuery")
.field("page_size", &self.page_size)
.field("cursor", &self.cursor.as_ref().map(|_| "[REDACTED]"))
.field("include_total", &self.include_total)
.finish()
}
}
impl PaginationQuery {
#[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<PageRequest, crate::pagination::PaginationError> {
self.into_page_request_with_limits(PageLimits::default())
}
pub fn into_page_request_with_limits(
self,
limits: PageLimits,
) -> Result<PageRequest, crate::pagination::PaginationError> {
PageRequest::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 Pagination(PageRequest);
impl Pagination {
#[must_use]
pub const fn request(&self) -> &PageRequest {
&self.0
}
#[must_use]
pub fn into_inner(self) -> PageRequest {
self.0
}
}
impl AsRef<PageRequest> for Pagination {
fn as_ref(&self) -> &PageRequest {
self.request()
}
}
impl Deref for Pagination {
type Target = PageRequest;
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 Pagination
where
S: Send + Sync,
{
type Rejection = ApiProblem;
async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
let context = context_from_parts(parts);
let limits = limits_from_parts(parts);
let Query(query) = Query::<PaginationQuery>::from_request_parts(parts, state)
.await
.map_err(|rejection| {
ApiProblem::bad_request(
ProblemCode::from_static("invalid_query"),
rejection.to_string(),
)
.with_request_context(&context)
})?;
query
.into_page_request_with_limits(limits)
.map(Self)
.map_err(|error| {
ApiProblem::bad_request(
ProblemCode::from_static("invalid_pagination"),
error.to_string(),
)
.with_request_context(&context)
})
}
}
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 context = context_from_parts(parts);
let limits = limits_from_parts(parts);
let Query(query) = Query::<OffsetPaginationQuery>::from_request_parts(parts, state)
.await
.map_err(|rejection| {
ApiProblem::bad_request(
ProblemCode::from_static("invalid_query"),
rejection.to_string(),
)
.with_request_context(&context)
})?;
query
.into_page_request_with_limits(limits)
.map(Self)
.map_err(|error| {
ApiProblem::bad_request(
ProblemCode::from_static("invalid_pagination"),
error.to_string(),
)
.with_request_context(&context)
})
}
}
fn context_from_parts(parts: &Parts) -> RequestContext {
parts
.extensions
.get::<RequestContext>()
.cloned()
.unwrap_or_else(|| RequestContext::from_headers(&parts.headers))
}
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::{OffsetPaginationQuery, Pagination, PaginationQuery};
#[test]
fn pagination_query_uses_custom_limits() {
let query = PaginationQuery {
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 = PaginationQuery {
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 = PaginationQuery {
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::<PaginationQuery>::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::<PaginationQuery>::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 = PaginationQuery {
page_size: Some(10),
cursor: None,
include_total: false,
}
.into_page_request()
.expect("query should be valid");
let pagination = Pagination(request);
assert_eq!(pagination.page_size(), 10);
assert_eq!(pagination.request().page_size(), 10);
}
}