cloud_sdk/
pagination.rs

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

cloud_sdk/
pagination.rs
