simplist

Struct HttpClient

Source 
pub struct HttpClient { /* private fields */ }
Expand description

an asynchronous, futures-based http client.

a class for sending http requests and receiving http responses from a resource identified by a uri. this class provides a simple, asynchronous, futures-based api.

if you’d like to use a synchronous, blocking api instead, HttpSyncClient may be easier to use. alternatively, you can emulate a blocking api on this struct by synchronously waiting for future results by calling wait() on all returned futures.

all examples here assume that you have an existing tokio reactor you can use. if you not already have a tokio core, a complete example demonstrating the initialization and usage of tokio together with this http client is available at https://github.com/hinaria/simplist/blob/master/examples/basic-async.rs.

§nightly

if you’re using a nightly compiler, you can significantly reduce the number of allocations that simplist performs by enabling the nightly feature. refer to the module-level docs for more information.

§methods

this struct provides two sets of operations for performing http operations: one for returning the response as a Vec<u8>, and another for returning the response as a String.

finally, there is a separate method, fn request(...) that takes a HttpRequest and allows you to manually set the http method, as well as set http headers.

rustdoc currently generates some pretty unreadable documentation for this struct, so we’ll summarize the available methods here.

§methods returning a Vec<u8>:

.
    fn options(url, Option<body>) -> Future<Item = Vec<u8>, Error = HttpError>;
    fn get    (url)               -> Future<Item = Vec<u8>, Error = HttpError>;
    fn post   (url, Option<body>) -> Future<Item = Vec<u8>, Error = HttpError>;
    fn put    (url, Option<body>) -> Future<Item = Vec<u8>, Error = HttpError>;
    fn delete (url)               -> Future<Item = Vec<u8>, Error = HttpError>;
    fn head   (url)               -> Future<Item = Vec<u8>, Error = HttpError>;
    fn trace  (url)               -> Future<Item = Vec<u8>, Error = HttpError>;
    fn connect(url)               -> Future<Item = Vec<u8>, Error = HttpError>;
    fn patch  (url, Option<body>) -> Future<Item = Vec<u8>, Error = HttpError>;

§methods returning a String<u8>:

.
    fn options_string(url, Option<body>) -> Future<Item = String, Error = HttpError>;
    fn get_string    (url)               -> Future<Item = String, Error = HttpError>;
    fn post_string   (url, Option<body>) -> Future<Item = String, Error = HttpError>;
    fn put_string    (url, Option<body>) -> Future<Item = String, Error = HttpError>;
    fn delete_string (url)               -> Future<Item = String, Error = HttpError>;
    fn head_string   (url)               -> Future<Item = String, Error = HttpError>;
    fn trace_string  (url)               -> Future<Item = String, Error = HttpError>;
    fn connect_string(url)               -> Future<Item = String, Error = HttpError>;
    fn patch_string  (url, Option<body>) -> Future<Item = String, Error = HttpError>;

§examples

§asynchronous, with await notation.

use simplist::HttpClient;

let http = HttpClient::new(handle);
let html = await http.get_string("https://hinaria.com")?;

println!("{:?}", html);
// => "<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\"> ..."

§asynchronous, with future callbacks.

use simplist::HttpClient;

let http   = HttpClient::new(handle);
let future = http.get_string("https://hinaria.com").and_then(|html| {
    println!("{:?}", html);
    Ok(())
}).map_err(|_| ());

handle.spawn(future);
// => "<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\"> ..."

§synchronous.

use simplist::HttpSyncClient;

let http = HttpSyncClient::new(handle);
let html = http.get_string("https://hinaria.com")?;

println!("{:?}", html);
// => "<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\"> ..."

Implementations§

Source§

impl HttpClient

Source

pub fn new(remote: Remote) -> HttpClient

creates a new http client.

this method is very cheap, and does not perform any kind of initialization.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);
Source

pub fn request( &self, request: HttpRequest, ) -> Box<dyn Future<Item = HttpResponse, Error = HttpError>>

sends a http request as an asynchronous operation.

§examples
use simplist::HttpClient;
use simplist::HttpMethod;

let http      = HttpClient::new(handle);
let url       = "https://hinaria.com".parse()?;
let operation = HttpRequest::with(url, HttpMethod::Get);
let response  = await http.request(operation)?;

assert_eq!(response.status(), StatusCode::Ok);
Source§

impl HttpClient

Source

pub fn options<TUrl, TContent>( &self, url: TUrl, content: Option<TContent>, ) -> OneOfFuture<Box<dyn Future<Item = Vec<u8>, Error = HttpError>>, FutureResult<Vec<u8>, HttpError>, Vec<u8>, HttpError>
where TUrl: IntoUrl, TContent: Into<HttpContent>,

sends an asynchronous http request, returning the response as a Vec<u8>.

the request body can be any type that is convertible to a HttpContent. refer to HttpContent to see a list of types that can be used.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);
let body = Some("{ id: 1234 }");

assert_eq!(
    &await http.post("https://hinaria.com/users/@me/database", body)?,
    &[60, 33, 68, 79, 67, 84, 89, 80, 69, 32, 104, 116, ...]);
Source

pub fn options_string<TUrl, TContent>( &self, url: TUrl, content: Option<TContent>, ) -> OneOfFuture<Box<dyn Future<Item = String, Error = HttpError>>, FutureResult<String, HttpError>, String, HttpError>
where TUrl: IntoUrl, TContent: Into<HttpContent>,

sends an asynchronous http request, returning the response as a String.

the request body can be any type that is convertible to a HttpContent. refer to HttpContent to see a list of types that can be used.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);
let body = Some("{ id: 1234 }");

assert_eq!(
    &await http.post_string("https://hinaria.com/users/@me/database", body)?,
    "<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\"> ...");
Source§

impl HttpClient

Source

pub fn get<TUrl>( &self, url: TUrl, ) -> OneOfFuture<Box<dyn Future<Item = Vec<u8>, Error = HttpError>>, FutureResult<Vec<u8>, HttpError>, Vec<u8>, HttpError>
where TUrl: IntoUrl,

sends an asynchronous http request, returning the response as a Vec<u8>.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);

assert_eq!(
    &await http.get("https://hinaria.com")?,
    &[60, 33, 68, 79, 67, 84, 89, 80, 69, 32, 104, 116, ...]);
Source

pub fn get_string<TUrl>( &self, url: TUrl, ) -> OneOfFuture<Box<dyn Future<Item = String, Error = HttpError>>, FutureResult<String, HttpError>, String, HttpError>
where TUrl: IntoUrl,

sends an asynchronous http request, returning the response as a String.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);

assert_eq!(
    await http.get_string("https://hinaria.com")?,
    "<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\"> ...");
Source§

impl HttpClient

Source

pub fn post<TUrl, TContent>( &self, url: TUrl, content: Option<TContent>, ) -> OneOfFuture<Box<dyn Future<Item = Vec<u8>, Error = HttpError>>, FutureResult<Vec<u8>, HttpError>, Vec<u8>, HttpError>
where TUrl: IntoUrl, TContent: Into<HttpContent>,

sends an asynchronous http request, returning the response as a Vec<u8>.

the request body can be any type that is convertible to a HttpContent. refer to HttpContent to see a list of types that can be used.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);
let body = Some("{ id: 1234 }");

assert_eq!(
    &await http.post("https://hinaria.com/users/@me/database", body)?,
    &[60, 33, 68, 79, 67, 84, 89, 80, 69, 32, 104, 116, ...]);
Source

pub fn post_string<TUrl, TContent>( &self, url: TUrl, content: Option<TContent>, ) -> OneOfFuture<Box<dyn Future<Item = String, Error = HttpError>>, FutureResult<String, HttpError>, String, HttpError>
where TUrl: IntoUrl, TContent: Into<HttpContent>,

sends an asynchronous http request, returning the response as a String.

the request body can be any type that is convertible to a HttpContent. refer to HttpContent to see a list of types that can be used.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);
let body = Some("{ id: 1234 }");

assert_eq!(
    &await http.post_string("https://hinaria.com/users/@me/database", body)?,
    "<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\"> ...");
Source§

impl HttpClient

Source

pub fn put<TUrl, TContent>( &self, url: TUrl, content: Option<TContent>, ) -> OneOfFuture<Box<dyn Future<Item = Vec<u8>, Error = HttpError>>, FutureResult<Vec<u8>, HttpError>, Vec<u8>, HttpError>
where TUrl: IntoUrl, TContent: Into<HttpContent>,

sends an asynchronous http request, returning the response as a Vec<u8>.

the request body can be any type that is convertible to a HttpContent. refer to HttpContent to see a list of types that can be used.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);
let body = Some("{ id: 1234 }");

assert_eq!(
    &await http.post("https://hinaria.com/users/@me/database", body)?,
    &[60, 33, 68, 79, 67, 84, 89, 80, 69, 32, 104, 116, ...]);
Source

pub fn put_string<TUrl, TContent>( &self, url: TUrl, content: Option<TContent>, ) -> OneOfFuture<Box<dyn Future<Item = String, Error = HttpError>>, FutureResult<String, HttpError>, String, HttpError>
where TUrl: IntoUrl, TContent: Into<HttpContent>,

sends an asynchronous http request, returning the response as a String.

the request body can be any type that is convertible to a HttpContent. refer to HttpContent to see a list of types that can be used.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);
let body = Some("{ id: 1234 }");

assert_eq!(
    &await http.post_string("https://hinaria.com/users/@me/database", body)?,
    "<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\"> ...");
Source§

impl HttpClient

Source

pub fn delete<TUrl>( &self, url: TUrl, ) -> OneOfFuture<Box<dyn Future<Item = Vec<u8>, Error = HttpError>>, FutureResult<Vec<u8>, HttpError>, Vec<u8>, HttpError>
where TUrl: IntoUrl,

sends an asynchronous http request, returning the response as a Vec<u8>.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);

assert_eq!(
    &await http.get("https://hinaria.com")?,
    &[60, 33, 68, 79, 67, 84, 89, 80, 69, 32, 104, 116, ...]);
Source

pub fn delete_string<TUrl>( &self, url: TUrl, ) -> OneOfFuture<Box<dyn Future<Item = String, Error = HttpError>>, FutureResult<String, HttpError>, String, HttpError>
where TUrl: IntoUrl,

sends an asynchronous http request, returning the response as a String.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);

assert_eq!(
    await http.get_string("https://hinaria.com")?,
    "<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\"> ...");
Source§

impl HttpClient

Source

pub fn head<TUrl>( &self, url: TUrl, ) -> OneOfFuture<Box<dyn Future<Item = Vec<u8>, Error = HttpError>>, FutureResult<Vec<u8>, HttpError>, Vec<u8>, HttpError>
where TUrl: IntoUrl,

sends an asynchronous http request, returning the response as a Vec<u8>.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);

assert_eq!(
    &await http.get("https://hinaria.com")?,
    &[60, 33, 68, 79, 67, 84, 89, 80, 69, 32, 104, 116, ...]);
Source

pub fn head_string<TUrl>( &self, url: TUrl, ) -> OneOfFuture<Box<dyn Future<Item = String, Error = HttpError>>, FutureResult<String, HttpError>, String, HttpError>
where TUrl: IntoUrl,

sends an asynchronous http request, returning the response as a String.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);

assert_eq!(
    await http.get_string("https://hinaria.com")?,
    "<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\"> ...");
Source§

impl HttpClient

Source

pub fn trace<TUrl>( &self, url: TUrl, ) -> OneOfFuture<Box<dyn Future<Item = Vec<u8>, Error = HttpError>>, FutureResult<Vec<u8>, HttpError>, Vec<u8>, HttpError>
where TUrl: IntoUrl,

sends an asynchronous http request, returning the response as a Vec<u8>.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);

assert_eq!(
    &await http.get("https://hinaria.com")?,
    &[60, 33, 68, 79, 67, 84, 89, 80, 69, 32, 104, 116, ...]);
Source

pub fn trace_string<TUrl>( &self, url: TUrl, ) -> OneOfFuture<Box<dyn Future<Item = String, Error = HttpError>>, FutureResult<String, HttpError>, String, HttpError>
where TUrl: IntoUrl,

sends an asynchronous http request, returning the response as a String.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);

assert_eq!(
    await http.get_string("https://hinaria.com")?,
    "<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\"> ...");
Source§

impl HttpClient

Source

pub fn connect<TUrl>( &self, url: TUrl, ) -> OneOfFuture<Box<dyn Future<Item = Vec<u8>, Error = HttpError>>, FutureResult<Vec<u8>, HttpError>, Vec<u8>, HttpError>
where TUrl: IntoUrl,

sends an asynchronous http request, returning the response as a Vec<u8>.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);

assert_eq!(
    &await http.get("https://hinaria.com")?,
    &[60, 33, 68, 79, 67, 84, 89, 80, 69, 32, 104, 116, ...]);
Source

pub fn connect_string<TUrl>( &self, url: TUrl, ) -> OneOfFuture<Box<dyn Future<Item = String, Error = HttpError>>, FutureResult<String, HttpError>, String, HttpError>
where TUrl: IntoUrl,

sends an asynchronous http request, returning the response as a String.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);

assert_eq!(
    await http.get_string("https://hinaria.com")?,
    "<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\"> ...");
Source§

impl HttpClient

Source

pub fn patch<TUrl, TContent>( &self, url: TUrl, content: Option<TContent>, ) -> OneOfFuture<Box<dyn Future<Item = Vec<u8>, Error = HttpError>>, FutureResult<Vec<u8>, HttpError>, Vec<u8>, HttpError>
where TUrl: IntoUrl, TContent: Into<HttpContent>,

sends an asynchronous http request, returning the response as a Vec<u8>.

the request body can be any type that is convertible to a HttpContent. refer to HttpContent to see a list of types that can be used.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);
let body = Some("{ id: 1234 }");

assert_eq!(
    &await http.post("https://hinaria.com/users/@me/database", body)?,
    &[60, 33, 68, 79, 67, 84, 89, 80, 69, 32, 104, 116, ...]);
Source

pub fn patch_string<TUrl, TContent>( &self, url: TUrl, content: Option<TContent>, ) -> OneOfFuture<Box<dyn Future<Item = String, Error = HttpError>>, FutureResult<String, HttpError>, String, HttpError>
where TUrl: IntoUrl, TContent: Into<HttpContent>,

sends an asynchronous http request, returning the response as a String.

the request body can be any type that is convertible to a HttpContent. refer to HttpContent to see a list of types that can be used.

§examples
use simplist::HttpClient;

let http = HttpClient::new(handle);
let body = Some("{ id: 1234 }");

assert_eq!(
    &await http.post_string("https://hinaria.com/users/@me/database", body)?,
    "<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\"> ...");

Trait Implementations§

Source§

impl Clone for HttpClient

Source§

fn clone(&self) -> HttpClient

Returns a duplicate of the value. Read more
1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for HttpClient

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.