Struct Fetcher

pub struct Fetcher { /* private fields */ }

A Fetcher describes a machine for driving a fetching process.

The Fetcher can be constructed using Fetcher::new, providing a FetcherConfig.

It builds a Target that it attempts to reach:

• Number of replicas that it should successfully fetch from, where a replica is any seed node that the repository is potentially seeded by.
• A set of preferred seeds that it should successfully fetch from.

If either of these targets are reached, then the fetch process can be considered complete – with preference given to the preferred seeds target.

To drive the Fetcher, it must be provided with nodes to fetch from. These are added via the FetcherConfig. Note that the nodes provided are retrieved in the order they are provided.

Before candidate nodes can be fetched from, the caller needs to mark them as connected to. To get the next available node we call Fetcher::next_node. Once the caller attempts to connect to this node and retrieves its Address, then it can mark it as ready to fetch by calling Fetcher::ready_to_fetch.

To then retrieve the next available node for fetching, the caller uses Fetcher::next_fetch.

To mark that fetch as complete, we call Fetcher::fetch_complete, with the result. At this point, the Fetcher returns a ControlFlow to let the caller know if they should continue processing nodes, to reach the desired target, or they can exit the loop knowing they have successfully reached the target.

The caller may also call Fetcher::fetch_failed to mark a fetch for a given node as failed – this is useful for reasons when the caller cannot connect to the node for fetching.

Finally, if the caller wishes to exit from the fetching process and get the final set of results, they may call Fetcher::finish.

Implementations

impl Fetcher

pub fn new(config: FetcherConfig) -> Result<Fetcher, FetcherError>

Construct a new Fetcher from the FetcherConfig.

pub fn next_node(&mut self) -> Option<PublicKey>

Get the next candidate NodeId to attempt connection and/or retrieving their connection session.

pub fn next_fetch(&mut self) -> Option<(PublicKey, Address)>

Get the next NodeId and Address for performing a fetch from.

Note that this NodeId must have been added to the Fetcher using the Fetcher::ready_to_fetch method.

pub fn fetch_failed(&mut self, node: PublicKey, reason: impl ToString)

Mark a fetch as failed for the NodeId, using the provided reason.

pub fn fetch_complete( &mut self, node: PublicKey, result: FetchResult, ) -> ControlFlow<Success, Progress>

Mark a fetch as complete for the NodeId, with the provided FetchResult.

If the target for the Fetcher has been reached, then a Success is returned via ControlFlow::Break. Otherwise, Progress is returned via ControlFlow::Continue.

The caller decides whether they wish to continue the fetching process.

pub fn finish(self) -> FetcherResult

Complete the Fetcher process returning a FetcherResult.

Which variant of the result is returned is determined by whether the Fetcher’s target was reached.

pub fn ready_to_fetch(&mut self, node: PublicKey, addr: Address)

Mark the node as ready to fetch, by providing its Address.

This will prime the node for fetching.

pub fn progress(&self) -> Progress

Get the latest Progress of the Fetcher.

pub fn target(&self) -> &Target

Get the Target that the Fetcher is aiming to reach.

Trait Implementations

impl Debug for Fetcher

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.