footing 0.6.1

Feature-gated foundations for Rust backend services
Documentation
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)]
/// Represents pagination query.
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]
    /// Returns the page size.
    pub const fn page_size(&self) -> Option<u32> {
        self.page_size
    }

    #[must_use]
    /// Returns the cursor.
    pub fn cursor(&self) -> Option<&str> {
        self.cursor.as_deref()
    }

    #[must_use]
    /// Returns the include total.
    pub const fn include_total(&self) -> bool {
        self.include_total
    }

    /// Consumes this value and returns page request.
    pub fn into_page_request(
        self,
    ) -> Result<CursorPageRequest, crate::pagination::PaginationError> {
        self.into_page_request_with_limits(PageLimits::default())
    }

    /// Consumes this value and returns page request with limits.
    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)]
/// Represents offset pagination query.
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]
    /// Returns the page.
    pub const fn page(&self) -> Option<u32> {
        self.page
    }

    #[must_use]
    /// Returns the page size.
    pub const fn page_size(&self) -> Option<u32> {
        self.page_size
    }

    /// Consumes this value and returns page request.
    pub fn into_page_request(
        self,
    ) -> Result<OffsetPageRequest, crate::pagination::PaginationError> {
        self.into_page_request_with_limits(PageLimits::default())
    }

    /// Consumes this value and returns page request with limits.
    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)]
/// Represents pagination.
pub struct CursorPagination(CursorPageRequest);

impl CursorPagination {
    #[must_use]
    /// Returns the request.
    pub const fn request(&self) -> &CursorPageRequest {
        &self.0
    }

    #[must_use]
    /// Consumes this value and returns inner.
    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)]
/// Represents offset pagination.
pub struct OffsetPagination(OffsetPageRequest);

impl OffsetPagination {
    #[must_use]
    /// Returns the request.
    pub const fn request(&self) -> &OffsetPageRequest {
        &self.0
    }

    #[must_use]
    /// Consumes this value and returns inner.
    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);
    }
}