Struct PageStream 

pub struct PageStream<'a, T> { /* private fields */ }

Available on crate feature client only.

An asynchronous crawl over every page of a list endpoint.

Following the Link: <…>; rel="next" header is only most of the job. The specification also describes what to do when the result set changes underneath the crawl:

While a client crawls over the pages … a new object might be created on the server. The client detects this: the X-Total-Count will be higher on the next call. Even so, the client does not have to retry any requests when this happens because only the last page will be different.

When there are for example 1000 objects matching a query … while crawling over the pages one of these objects is updated. The client detects this: X-Total-Count will be lower in the next request. It is advised to redo the previous GET with the offset lowered by 1 (if the offset was not 0) and after that continue crawling the ‘next’ page links.

PageStream does both, and reports the correction it made through PageStream::corrections so a pull that keeps shifting is visible rather than silent.

while let Some(location) = stream.next().await? {
    println!("{}", location.id);
}
println!("{} objects over {} pages", stream.seen(), stream.pages_fetched());

Spec: 2.3.0 §transport_and_format_paginated_response

Implementations

impl<'a, T: DeserializeOwned> PageStream<'a, T>

pub fn new( transport: &'a Transport, peer: &'a Peer, module: ModuleId, routing: RoutingHeaders, first: Url, ) -> Self

Starts a crawl at first.

pub const fn bridging(self, kind: ObjectKind) -> Self

Translates every page out of the peer’s OCPI version into the canonical model.

kind says which object the endpoint carries. A peer that already speaks the canonical version costs nothing: the translation is skipped, not applied as an identity.

pub const fn with_max_pages(self, max_pages: usize) -> Self

Caps how many pages this crawl will fetch.

pub async fn next(&mut self) -> Result<Option<T>, OcpiError>

The next object, fetching another page when the buffer runs dry.

Errors

Propagates transport, decoding and OCPI-level errors from the page fetch.

pub async fn collect_all(self) -> Result<Vec<T>, OcpiError>

Collects the whole list.

Errors

Propagates any error from PageStream::next.

pub const fn pages_fetched(&self) -> usize

How many pages have been fetched.

pub const fn seen(&self) -> usize

How many objects have been yielded.

pub const fn corrections(&self) -> usize

How many times the crawl was rewound because X-Total-Count shrank.

A non-zero count means objects were changing while the crawl ran.

pub const fn total_count(&self) -> Option<u64>

The total the peer reported for the query, from the most recent page.