Crate adventure

A general method of the common pattern for network requests.

This crate defines a general interface of the request-response pattern like HTTP request, and provides a number of composable constructs to work with it at the high-level.

Examples

use std::time::Duration;

use adventure::prelude::*;
use adventure::response::LocalFuture01ResponseObj;
use futures::Future;
use reqwest::{r#async::Client, Error};
use serde::Deserialize;

// declare the request and the desired output.
struct GetRepo<'a> {
    owner: &'a str,
    repo: &'a str,
};

#[derive(Deserialize)]
struct Repository {
    id: u64,
    name: String,
    full_name: String,
    description: String,
}

// describe the relation of request, result, and error.
impl BaseRequest for GetRepo<'_> {
    type Ok = Repository;
    type Error = Error;
}

impl<'a> Request<&'a Client> for GetRepo<'_> {
    // convenient wrapper for boxed futures
    type Response = LocalFuture01ResponseObj<'a, Self::Ok, Self::Error>;

    // implement how to send the request and extract the result.
    fn send(mut self: Pin<&mut Self>, client: &'a Client) -> Self::Response {
        let url = format!("https://api.github.com/repos/{}/{}", self.owner, self.repo);
        let resp = client.get(&url)
            .header("Accept", "application/vnd.github.v3+json")
            .send()
            .and_then(|mut r| r.json());
        LocalFuture01ResponseObj::new(resp)
    }
}

// this is for `retry()` method.
impl RetriableRequest for GetRepo<'_> {
    fn should_retry(&self, err: &Self::Error, next_duration: Duration) -> bool {
        err.is_server_error()
    }
}

// let's try it

use tokio::runtime::current_thread::block_on_all;

let client = Client::new();
let request = GetRepo { owner: "spoqa", repo: "adventure" };
let response = request
    .retry()
    .send_once(&client);
let repo = block_on_all(response.into_future())?;
assert_eq!(repo.description, "Helps your great adventure for the various type of requests.");

Modules

oneshot

paginator

prelude

A prelude of the adventure for the crate which want to try with it.

repeat

request

A base trait represents a request.

response

A trait of responses and common adaptors.

retry

Structs

Paginator

A stream over the pages that consists the entire set from the request.

Traits

BaseRequest

Trait to represent types of the request, and their expected output and error types.

OneshotRequest

A request that can be sent just once.

PagedRequest

A request able to send subsequent requests to enumerate the entire result.

Request

A generalized request-response interface, regardless how client works.

Response

Trait to represent types of the response, and the task to receive it. A convenience for futures that return Result values that includes a variety of adapters tailored to such futures.

RetriableRequest

A request able to decide to send itself again if the previous attempt has failed.