cloud_sdk/
pagination.rs

1//! Explicit provider-neutral pagination strategy state.
2
3mod budget;
4mod driver;
5mod link;
6mod local_async;
7mod numbered;
8mod offset;
9mod opaque;
10
11pub use budget::{
12    MAX_SNAPSHOT_ID_BYTES, PaginationBudget, PaginationLimits, PaginationProgress, SnapshotId,
13    SnapshotPolicy,
14};
15pub use driver::{PageStrategy, PagerControl, PagerDriver, PagerDriverError, PagerStep};
16pub use link::{ProviderLinkBinding, ProviderLinkExecutionError, ValidatedProviderLink};
17pub use numbered::{
18    NumberedPageBoundary, NumberedPageMetadata, NumberedPageObservation, NumberedPagination,
19    PageNumber,
20};
21pub use offset::{OffsetPageBoundary, OffsetPageMetadata, OffsetPageObservation, OffsetPagination};
22pub use opaque::{
23    CursorDigest, CursorHistory, MAX_OPAQUE_STATE_BYTES, PaginationCursor, PaginationMarker,
24};
25
26/// Pagination validation or transition error.
27#[derive(Clone, Copy, Debug, Eq, PartialEq)]
28pub enum PaginationError {
29    /// A required numeric bound was zero.
30    ZeroLimit,
31    /// An opaque state bound exceeds the SDK hard limit.
32    StateLimitTooLarge,
33    /// A page number was zero.
34    PageZero,
35    /// A page size was zero.
36    PageSizeZero,
37    /// Previous-page metadata was not immediately before the current page.
38    InvalidPreviousPage,
39    /// Next-page metadata was not immediately after the current page.
40    InvalidNextPage,
41    /// Last-page metadata contradicted the continuation state.
42    InvalidLastPage,
43    /// A response did not match the requested page or offset.
44    UnexpectedPosition,
45    /// A nonterminal response contained no entries.
46    EmptyPageWithContinuation,
47    /// Entry count or total metadata was incoherent.
48    InvalidEntryCount,
49    /// Provider page size changed during one traversal.
50    PageSizeChanged,
51    /// Stable provider traversal metadata changed.
52    TraversalChanged,
53    /// A continuation would exceed the request budget.
54    RequestBudgetExceeded,
55    /// Accepted entries would exceed the item budget.
56    ItemBudgetExceeded,
57    /// A required provider snapshot identifier was omitted.
58    SnapshotRequired,
59    /// A provider snapshot identifier was empty.
60    SnapshotIdEmpty,
61    /// A provider snapshot identifier exceeded its exact-byte bound.
62    SnapshotIdTooLong,
63    /// A provider snapshot identifier was supplied when forbidden.
64    SnapshotForbidden,
65    /// Snapshot presence or value changed during one traversal.
66    SnapshotChanged,
67    /// The traversal has no continuation.
68    Complete,
69    /// Opaque continuation state was omitted or empty.
70    MissingState,
71    /// Opaque continuation state exceeds its caller-selected limit.
72    StateTooLong,
73    /// Caller-owned destination storage is too small.
74    OutputTooSmall,
75    /// Cursor history has no remaining entry or byte budget.
76    HistoryBudgetExceeded,
77    /// A cursor repeated an earlier exact value.
78    CursorCycle,
79    /// One digest identified two distinct cursor values.
80    CursorDigestCollision,
81    /// One cursor value was supplied with different digests.
82    CursorDigestChanged,
83    /// A provider link was not valid UTF-8 or request-target syntax.
84    InvalidProviderLink,
85    /// A provider link changed the bound network scheme.
86    ProviderLinkSchemeChanged,
87    /// A provider link changed the bound authority.
88    ProviderLinkAuthorityChanged,
89    /// A provider link contained user information.
90    ProviderLinkUserinfo,
91    /// A provider link contained a fragment.
92    ProviderLinkFragment,
93    /// A provider link changed the bound operation path.
94    ProviderLinkPathChanged,
95    /// A provider link was used with another HTTP method.
96    ProviderLinkMethodChanged,
97    /// A provider link was used with another operation identifier.
98    ProviderLinkOperationChanged,
99}
100
101impl_static_error!(PaginationError,
102    Self::ZeroLimit => "pagination limits must be nonzero",
103    Self::StateLimitTooLarge => "opaque pagination state limit exceeds the hard limit",
104    Self::PageZero => "page number must be nonzero",
105    Self::PageSizeZero => "page size must be nonzero",
106    Self::InvalidPreviousPage => "previous-page metadata is invalid",
107    Self::InvalidNextPage => "next-page metadata is invalid",
108    Self::InvalidLastPage => "last-page metadata is invalid",
109    Self::UnexpectedPosition => "response position differs from the requested position",
110    Self::EmptyPageWithContinuation => "nonterminal response page is empty",
111    Self::InvalidEntryCount => "response entry count is invalid",
112    Self::PageSizeChanged => "response page size changed during traversal",
113    Self::TraversalChanged => "pagination metadata changed during traversal",
114    Self::RequestBudgetExceeded => "pagination request budget was exceeded",
115    Self::ItemBudgetExceeded => "pagination item budget was exceeded",
116    Self::SnapshotRequired => "provider snapshot identifier is required",
117    Self::SnapshotIdEmpty => "provider snapshot identifier is empty",
118    Self::SnapshotIdTooLong => "provider snapshot identifier exceeds the length limit",
119    Self::SnapshotForbidden => "provider snapshot identifier is forbidden",
120    Self::SnapshotChanged => "provider snapshot identifier changed during traversal",
121    Self::Complete => "pagination traversal is complete",
122    Self::MissingState => "opaque pagination state is missing",
123    Self::StateTooLong => "opaque pagination state exceeds the selected limit",
124    Self::OutputTooSmall => "pagination state output is too small",
125    Self::HistoryBudgetExceeded => "cursor history budget was exceeded",
126    Self::CursorCycle => "pagination cursor cycle was detected",
127    Self::CursorDigestCollision => "pagination cursor digest collision was detected",
128    Self::CursorDigestChanged => "pagination cursor digest changed for the same state",
129    Self::InvalidProviderLink => "provider pagination link is invalid",
130    Self::ProviderLinkSchemeChanged => "provider pagination link changed scheme",
131    Self::ProviderLinkAuthorityChanged => "provider pagination link changed authority",
132    Self::ProviderLinkUserinfo => "provider pagination link contains user information",
133    Self::ProviderLinkFragment => "provider pagination link contains a fragment",
134    Self::ProviderLinkPathChanged => "provider pagination link changed operation path",
135    Self::ProviderLinkMethodChanged => "provider pagination link changed HTTP method",
136    Self::ProviderLinkOperationChanged => "provider pagination link changed operation",
137);
138
139#[cfg(test)]
140mod tests;
cloud_sdk/pagination.rs

cloud_sdk/
pagination.rs
