cloud_sdk/
pagination.rs

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

cloud_sdk/
pagination.rs
