cloud_sdk/
pagination.rs

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

cloud_sdk/
pagination.rs
