use std::fmt;
use serde::{Deserialize, Deserializer, Serialize};
use super::{DEFAULT_PAGE, DEFAULT_PAGE_SIZE, MAX_CURSOR_LENGTH, MAX_PAGE_SIZE, PaginationError};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub struct PageLimits {
default_page_size: u32,
max_page_size: u32,
max_cursor_length: usize,
}
impl<'de> Deserialize<'de> for PageLimits {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
struct PageLimitsWire {
default_page_size: u32,
max_page_size: u32,
max_cursor_length: usize,
}
let wire = PageLimitsWire::deserialize(deserializer)?;
Self {
default_page_size: wire.default_page_size,
max_page_size: wire.max_page_size,
max_cursor_length: wire.max_cursor_length,
}
.validate()
.map_err(serde::de::Error::custom)
}
}
impl PageLimits {
pub fn new(default_page_size: u32, max_page_size: u32) -> Result<Self, PaginationError> {
Self {
default_page_size,
max_page_size,
max_cursor_length: MAX_CURSOR_LENGTH,
}
.validate()
}
#[must_use]
pub const fn with_max_cursor_length(mut self, max_cursor_length: usize) -> Self {
self.max_cursor_length = max_cursor_length;
self
}
pub const fn default_page_size(&self) -> u32 {
self.default_page_size
}
pub const fn max_page_size(&self) -> u32 {
self.max_page_size
}
pub const fn max_cursor_length(&self) -> usize {
self.max_cursor_length
}
pub fn validate(self) -> Result<Self, PaginationError> {
if self.default_page_size == 0 {
return Err(PaginationError::DefaultPageSizeZero);
}
if self.max_page_size == 0 {
return Err(PaginationError::MaxPageSizeZero);
}
if self.default_page_size > self.max_page_size {
return Err(PaginationError::DefaultPageSizeTooLarge {
default: self.default_page_size,
max: self.max_page_size,
});
}
if self.max_cursor_length == 0 {
return Err(PaginationError::MaxCursorLengthZero);
}
Ok(self)
}
}
impl Default for PageLimits {
fn default() -> Self {
Self {
default_page_size: DEFAULT_PAGE_SIZE,
max_page_size: MAX_PAGE_SIZE,
max_cursor_length: MAX_CURSOR_LENGTH,
}
}
}
#[derive(Clone, PartialEq, Eq, Serialize)]
pub struct PageRequest {
page_size: u32,
cursor: Option<String>,
include_total: bool,
}
impl fmt::Debug for PageRequest {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PageRequest")
.field("page_size", &self.page_size)
.field("cursor", &self.cursor.as_ref().map(|_| "[REDACTED]"))
.field("include_total", &self.include_total)
.finish()
}
}
impl<'de> Deserialize<'de> for PageRequest {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
struct PageRequestWire {
page_size: u32,
#[serde(default)]
cursor: Option<String>,
#[serde(default)]
include_total: bool,
}
let wire = PageRequestWire::deserialize(deserializer)?;
Self::new(Some(wire.page_size), wire.cursor, wire.include_total)
.map_err(serde::de::Error::custom)
}
}
impl PageRequest {
pub fn new(
page_size: Option<u32>,
cursor: Option<String>,
include_total: bool,
) -> Result<Self, PaginationError> {
Self::new_with_limits(page_size, cursor, include_total, PageLimits::default())
}
pub fn new_with_limits(
page_size: Option<u32>,
cursor: Option<String>,
include_total: bool,
limits: PageLimits,
) -> Result<Self, PaginationError> {
let limits = limits.validate()?;
let page_size = page_size.unwrap_or(limits.default_page_size);
validate_page_size(page_size, limits.max_page_size)?;
if let Some(cursor) = cursor.as_deref() {
validate_query_cursor_length(cursor, limits.max_cursor_length)?;
}
Ok(Self {
page_size,
cursor,
include_total,
})
}
#[must_use]
pub const fn page_size(&self) -> 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
}
#[must_use]
pub fn into_cursor(self) -> Option<String> {
self.cursor
}
#[must_use]
pub fn limit_with_extra(&self) -> i64 {
i64::from(self.page_size) + 1
}
#[must_use]
pub fn offset_limit(&self) -> i64 {
i64::from(self.page_size)
}
}
impl Default for PageRequest {
fn default() -> Self {
Self {
page_size: DEFAULT_PAGE_SIZE,
cursor: None,
include_total: false,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub struct OffsetPageRequest {
page: u32,
page_size: u32,
}
impl<'de> Deserialize<'de> for OffsetPageRequest {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
struct OffsetPageRequestWire {
page: u32,
page_size: u32,
}
let wire = OffsetPageRequestWire::deserialize(deserializer)?;
Self::new(Some(wire.page), Some(wire.page_size)).map_err(serde::de::Error::custom)
}
}
impl OffsetPageRequest {
pub fn new(page: Option<u32>, page_size: Option<u32>) -> Result<Self, PaginationError> {
Self::new_with_limits(page, page_size, PageLimits::default())
}
pub fn new_with_limits(
page: Option<u32>,
page_size: Option<u32>,
limits: PageLimits,
) -> Result<Self, PaginationError> {
let limits = limits.validate()?;
let page = page.unwrap_or(DEFAULT_PAGE);
if page == 0 {
return Err(PaginationError::PageZero);
}
let page_size = page_size.unwrap_or(limits.default_page_size);
validate_page_size(page_size, limits.max_page_size)?;
Ok(Self { page, page_size })
}
#[must_use]
pub const fn page(&self) -> u32 {
self.page
}
#[must_use]
pub const fn page_size(&self) -> u32 {
self.page_size
}
#[must_use]
pub fn limit(&self) -> i64 {
i64::from(self.page_size)
}
#[must_use]
pub fn offset(&self) -> i64 {
i64::from(self.page - 1) * i64::from(self.page_size)
}
}
impl Default for OffsetPageRequest {
fn default() -> Self {
Self {
page: DEFAULT_PAGE,
page_size: DEFAULT_PAGE_SIZE,
}
}
}
#[derive(Clone, PartialEq, Eq, Serialize)]
pub struct CursorPage<T> {
items: Vec<T>,
page_size: u32,
next_cursor: Option<String>,
has_more: bool,
#[serde(skip_serializing_if = "Option::is_none")]
total: Option<u64>,
}
impl<T> fmt::Debug for CursorPage<T>
where
T: fmt::Debug,
{
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("CursorPage")
.field("items", &self.items)
.field("page_size", &self.page_size)
.field(
"next_cursor",
&self.next_cursor.as_ref().map(|_| "[REDACTED]"),
)
.field("has_more", &self.has_more)
.field("total", &self.total)
.finish()
}
}
impl<'de, T> Deserialize<'de> for CursorPage<T>
where
T: Deserialize<'de>,
{
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
struct CursorPageWire<T> {
items: Vec<T>,
page_size: u32,
#[serde(default)]
next_cursor: Option<String>,
has_more: bool,
#[serde(default)]
total: Option<u64>,
}
let wire = CursorPageWire::<T>::deserialize(deserializer)?;
Self::new(
wire.items,
wire.page_size,
wire.next_cursor,
wire.has_more,
wire.total,
)
.map_err(serde::de::Error::custom)
}
}
impl<T> CursorPage<T> {
pub fn new(
items: Vec<T>,
page_size: u32,
next_cursor: Option<String>,
has_more: bool,
total: Option<u64>,
) -> Result<Self, PaginationError> {
validate_cursor_page_parts(&items, page_size, next_cursor.as_deref(), has_more, total)?;
Ok(Self::from_valid_parts(
items,
page_size,
next_cursor,
has_more,
total,
))
}
fn from_valid_parts(
items: Vec<T>,
page_size: u32,
next_cursor: Option<String>,
has_more: bool,
total: Option<u64>,
) -> Self {
Self {
items,
page_size,
next_cursor,
has_more,
total,
}
}
#[must_use]
pub fn items(&self) -> &[T] {
&self.items
}
#[must_use]
pub const fn page_size(&self) -> u32 {
self.page_size
}
#[must_use]
pub fn next_cursor(&self) -> Option<&str> {
self.next_cursor.as_deref()
}
#[must_use]
pub const fn has_more(&self) -> bool {
self.has_more
}
#[must_use]
pub const fn total(&self) -> Option<u64> {
self.total
}
#[must_use]
pub fn into_items(self) -> Vec<T> {
self.items
}
#[must_use]
pub fn into_parts(self) -> (Vec<T>, u32, Option<String>, bool, Option<u64>) {
(
self.items,
self.page_size,
self.next_cursor,
self.has_more,
self.total,
)
}
#[must_use]
pub fn map_items<U>(self, mut mapper: impl FnMut(T) -> U) -> CursorPage<U> {
let (items, page_size, next_cursor, has_more, total) = self.into_parts();
CursorPage::from_valid_parts(
items.into_iter().map(&mut mapper).collect(),
page_size,
next_cursor,
has_more,
total,
)
}
pub fn try_map_items<U, E>(
self,
mut mapper: impl FnMut(T) -> Result<U, E>,
) -> Result<CursorPage<U>, E> {
let (items, page_size, next_cursor, has_more, total) = self.into_parts();
let items = items
.into_iter()
.map(&mut mapper)
.collect::<Result<_, _>>()?;
Ok(CursorPage::from_valid_parts(
items,
page_size,
next_cursor,
has_more,
total,
))
}
pub fn from_limit_plus_one<E>(
mut items: Vec<T>,
page_size: u32,
total: Option<u64>,
next_cursor: impl FnOnce(&T) -> Result<String, E>,
) -> Result<Self, E> {
let requested_page_size = page_size as usize;
let has_more = requested_page_size > 0 && items.len() > requested_page_size;
if has_more {
items.truncate(requested_page_size);
}
let next_cursor = if has_more {
match items.last() {
Some(last) => Some(next_cursor(last)?),
None => None,
}
} else {
None
};
Ok(Self::from_valid_parts(
items,
page_size,
next_cursor,
has_more,
total,
))
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct OffsetPage<T> {
items: Vec<T>,
page: u32,
page_size: u32,
total: u64,
}
impl<'de, T> Deserialize<'de> for OffsetPage<T>
where
T: Deserialize<'de>,
{
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
struct OffsetPageWire<T> {
items: Vec<T>,
page: u32,
page_size: u32,
total: u64,
}
let wire = OffsetPageWire::<T>::deserialize(deserializer)?;
Self::new(wire.items, wire.page, wire.page_size, wire.total)
.map_err(serde::de::Error::custom)
}
}
impl<T> OffsetPage<T> {
pub fn new(
items: Vec<T>,
page: u32,
page_size: u32,
total: u64,
) -> Result<Self, PaginationError> {
validate_offset_page_parts(&items, page, page_size, total)?;
Ok(Self::from_valid_parts(items, page, page_size, total))
}
fn from_valid_parts(items: Vec<T>, page: u32, page_size: u32, total: u64) -> Self {
Self {
items,
page,
page_size,
total,
}
}
#[must_use]
pub fn items(&self) -> &[T] {
&self.items
}
#[must_use]
pub const fn page(&self) -> u32 {
self.page
}
#[must_use]
pub const fn page_size(&self) -> u32 {
self.page_size
}
#[must_use]
pub const fn total(&self) -> u64 {
self.total
}
#[must_use]
pub fn into_items(self) -> Vec<T> {
self.items
}
#[must_use]
pub fn into_parts(self) -> (Vec<T>, u32, u32, u64) {
(self.items, self.page, self.page_size, self.total)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
#[serde(rename_all = "snake_case")]
pub enum SortDirection {
Asc,
Desc,
}
fn validate_page_size(page_size: u32, max_page_size: u32) -> Result<(), PaginationError> {
if page_size == 0 {
return Err(PaginationError::PageSizeZero);
}
if page_size > max_page_size {
return Err(PaginationError::PageSizeTooLarge { max: max_page_size });
}
Ok(())
}
fn validate_cursor_page_parts<T>(
items: &[T],
page_size: u32,
next_cursor: Option<&str>,
has_more: bool,
total: Option<u64>,
) -> Result<(), PaginationError> {
validate_page_size(page_size, u32::MAX)?;
if items.len() > page_size as usize {
return Err(PaginationError::PageItemsExceedPageSize {
items: items.len(),
page_size,
});
}
match (has_more, next_cursor) {
(true, None) => return Err(PaginationError::CursorRequiredForMoreResults),
(false, Some(_)) => return Err(PaginationError::CursorUnexpectedWithoutMoreResults),
_ => {}
}
if let Some(cursor) = next_cursor {
validate_query_cursor_length(cursor, MAX_CURSOR_LENGTH)?;
}
if let Some(total) = total
&& total < items.len() as u64
{
return Err(PaginationError::TotalLessThanItems {
total,
items: items.len(),
});
}
Ok(())
}
fn validate_offset_page_parts<T>(
items: &[T],
page: u32,
page_size: u32,
total: u64,
) -> Result<(), PaginationError> {
if page == 0 {
return Err(PaginationError::PageZero);
}
validate_page_size(page_size, u32::MAX)?;
if items.len() > page_size as usize {
return Err(PaginationError::PageItemsExceedPageSize {
items: items.len(),
page_size,
});
}
if total < items.len() as u64 {
return Err(PaginationError::TotalLessThanItems {
total,
items: items.len(),
});
}
Ok(())
}
fn validate_query_cursor_length(cursor: &str, max: usize) -> Result<(), PaginationError> {
if cursor.is_empty() {
return Err(PaginationError::CursorEmpty);
}
if cursor.len() > max {
return Err(PaginationError::CursorTooLarge { max });
}
if !cursor
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.'))
{
return Err(PaginationError::CursorInvalidCharacters);
}
Ok(())
}