simplist 0.0.5 - Docs.rs

use std::cell::RefCell;

use futures::Future;
use futures::future::FutureResult;
use hina;
use hina::result::ResultExt;
use hina::task::OneOfFuture;
use hyper::Body;
use hyper::client::Client;
use hyper::client::HttpConnector;
use tokio_core::reactor::CoreId;
use tokio_core::reactor::Remote;

use simplist::HttpContent;
use simplist::HttpError;
use simplist::HttpMethod;
use simplist::HttpRequest;
use simplist::HttpResponse;
use simplist::HttpSyncResponse;
use simplist::IntoUrl;
use simplist::Url;



thread_local! {
    static THREAD_LOCAL_DATA: RefCell<Option<ThreadData>> = RefCell::new(None);
}

struct ThreadData {
    core:   CoreId,
    client: Client<HttpConnector, Body>,
}



/// 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`](struct.HttpSyncClient.html) 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](https://docs.rs/simplist/) 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>`](https://doc.rust-lang.org/std/vec/struct.Vec.html), and another for returning the response as a
/// [`String`](https://doc.rust-lang.org/std/string/struct.String.html).
///
/// finally, there is a separate method, [`fn request(...)`](struct.HttpClient.html#method.request) that takes a
/// [`HttpRequest`](struct.HttpRequest.html) 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>`](https://doc.rust-lang.org/std/vec/struct.Vec.html):
///
/// ```
/// .
///     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>`](https://doc.rust-lang.org/std/string/struct.String.html):
///
/// ```
/// .
///     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\"> ..."
/// ```
#[derive(Clone, Debug)]
pub struct HttpClient {
    remote: Remote,
}

impl 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);
    /// ```
    pub fn new(remote: Remote) -> HttpClient  {
        HttpClient { remote }
    }

    /// 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);
    /// ```
    pub fn request(&self, request: HttpRequest) -> Box<Future<Item = HttpResponse, Error = HttpError>> {
        let request         = request.into();
        let (send, receive) = hina::task::sync::source();

        self.remote.spawn(|handle| {
            THREAD_LOCAL_DATA.with(|data| {
                let core        = handle.id();
                let mut storage = data.borrow_mut();


                // initialize the hyper http client if it does not exist, or if it does not belong to this core.
                if storage.is_none() || storage.as_ref().unwrap().core != core {
                    *storage = Some(ThreadData {
                        core:   core,
                        client: Client::new(handle),
                    })
                }


                // perform the request.
                let data = storage
                    .as_ref()
                    .expect(d!["invariant broken: thread local data was none."]);

                data.client.request(request)
                    .map    (HttpResponse::new)
                    .map_err(From::from)
                    .then   (|x| { send.done(x).consume(); Ok(()) })
            })
        });

        Box::new(receive)
    }

    fn run_bytes<TBody>(&self, url: Url, method: HttpMethod, content: Option<TBody>) -> Box<Future<Item = Vec<u8>, Error = HttpError>>
        where TBody: Into<HttpContent> {

        let request = HttpRequest::new()
            .with_url(url)
            .with_method(method)
            .with_body(content);

        let future  = self.request(request).and_then(|response| {
            match response.status_code() {
                0...399 => OneOfFuture::A(response.read_as_bytes()),
                _       => OneOfFuture::B(hina::task::failed(HttpError::Status(response.status()))),
            }
        });

        Box::new(future)
    }

    fn run_string<TBody>(&self, url: Url, method: HttpMethod, content: Option<TBody>) -> Box<Future<Item = String, Error = HttpError>>
        where TBody: Into<HttpContent> {

        Box::new(
            self.run_bytes(url, method, content)
                .and_then (|x| String::from_utf8(x).map_err(From::from)))
    }
}



/// a synchronous, blocking http client.
///
/// a class for sending http requests and receiving http responses from a resource identified by a uri. this class uses
/// tokio behind the scenes, but exposes a blocking, synchronous api.
///
/// 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-sync.rs.
///
/// # methods
///
/// this struct provides two sets of operations for performing http operations: one for returning the response as a
/// [`Vec<u8>`](https://doc.rust-lang.org/std/vec/struct.Vec.html), and another for returning the response as a
/// [`String`](https://doc.rust-lang.org/std/string/struct.String.html).
///
/// finally, there is a separate method, [`fn request(...)`](struct.HttpSyncClient.html#method.request) that takes a
/// [`HttpRequest`](struct.HttpRequest.html) 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>`](https://doc.rust-lang.org/std/vec/struct.Vec.html):
///
/// ```
/// .
///     fn options(url, Option<body>) -> Result<Vec<u8>, HttpError>;
///     fn get    (url)               -> Result<Vec<u8>, HttpError>;
///     fn post   (url, Option<body>) -> Result<Vec<u8>, HttpError>;
///     fn put    (url, Option<body>) -> Result<Vec<u8>, HttpError>;
///     fn delete (url)               -> Result<Vec<u8>, HttpError>;
///     fn head   (url)               -> Result<Vec<u8>, HttpError>;
///     fn trace  (url)               -> Result<Vec<u8>, HttpError>;
///     fn connect(url)               -> Result<Vec<u8>, HttpError>;
///     fn patch  (url, Option<body>) -> Result<Vec<u8>, HttpError>;
/// ```
///
/// ## methods returning a [`String<u8>`](https://doc.rust-lang.org/std/string/struct.String.html):
///
/// ```
/// .
///     fn options_string(url, Option<body>) -> Result<String, HttpError>;
///     fn get_string    (url)               -> Result<String, HttpError>;
///     fn post_string   (url, Option<body>) -> Result<String, HttpError>;
///     fn put_string    (url, Option<body>) -> Result<String, HttpError>;
///     fn delete_string (url)               -> Result<String, HttpError>;
///     fn head_string   (url)               -> Result<String, HttpError>;
///     fn trace_string  (url)               -> Result<String, HttpError>;
///     fn connect_string(url)               -> Result<String, HttpError>;
///     fn patch_string  (url, Option<body>) -> Result<String, HttpError>;
/// ```
///
/// # examples
///
/// ```
/// 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\"> ..."
/// ```
#[derive(Clone, Debug)]
pub struct HttpSyncClient {
    underlying: HttpClient,
}

impl HttpSyncClient {
    /// creates a new http client.
    ///
    /// this method is very cheap, and does not perform any kind of initialization.
    ///
    /// # examples
    ///
    /// ```
    /// use simplist::HttpSyncClient;
    ///
    /// let http = HttpSyncClient::new(handle);
    /// ```
    pub fn new(remote: Remote) -> HttpSyncClient  {
        HttpSyncClient {
            underlying: HttpClient::new(remote),
        }
    }

    /// sends a http request.
    ///
    /// # 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  = http.request(operation)?;
    ///
    /// assert_eq!(response.status(), StatusCode::Ok);
    /// ```
    pub fn request(&self, request: HttpRequest) -> Result<HttpSyncResponse, HttpError> {
        self.underlying.request(request)
            .wait()
            .map (HttpSyncResponse::new)
    }
}


macro_rules! http_client_methods {
    () => {};

    // :: [content = no] implementation for methods with no content body
    (no-content, $method_variant: path, $method_name: ident, $string_method_name: ident) => {
        impl HttpClient {
            /// sends an asynchronous http request, returning the response as a
            /// [`Vec<u8>`](https://doc.rust-lang.org/std/vec/struct.Vec.html).
            ///
            /// # 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, ...]);
            /// ```
            pub fn $method_name<TUrl>(&self, url: TUrl) -> OneOfFuture<Box<Future<Item = Vec<u8>, Error = HttpError>>, FutureResult<Vec<u8>, HttpError>, Vec<u8>, HttpError>
                where TUrl: IntoUrl {

                match url.as_url() {
                    Ok(url) => OneOfFuture::A(self.run_bytes(url, $method_variant, Option::None::<&'static [u8]>)),
                    Err(e)  => OneOfFuture::B(hina::task::failed(e)),
                }
            }

            /// sends an asynchronous http request, returning the response as a
            /// [`String`](https://doc.rust-lang.org/std/string/struct.String.html).
            ///
            /// # 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\"> ...");
            /// ```
            pub fn $string_method_name<TUrl>(&self, url: TUrl) -> OneOfFuture<Box<Future<Item = String, Error = HttpError>>, FutureResult<String, HttpError>, String, HttpError>
                where TUrl: IntoUrl {

                match url.as_url() {
                    Ok(url) => OneOfFuture::A(self.run_string(url, $method_variant, Option::None::<&'static [u8]>)),
                    Err(e)  => OneOfFuture::B(hina::task::failed(e)),
                }
            }
        }

        impl HttpSyncClient {
            /// sends an http request, returning the response as a
            /// [`Vec<u8>`](https://doc.rust-lang.org/std/vec/struct.Vec.html).
            ///
            /// # examples
            ///
            /// ```
            /// use simplist::HttpSyncClient;
            ///
            /// let http = HttpSyncClient::new(handle);
            ///
            /// assert_eq!(
            ///     &http.get("https://hinaria.com")?,
            ///     &[60, 33, 68, 79, 67, 84, 89, 80, 69, 32, 104, 116, ...]);
            /// ```
            pub fn $method_name<TUrl>(&self, url: TUrl) -> Result<Vec<u8>, HttpError>
                where TUrl: IntoUrl {

                self.underlying.$method_name(url).wait()
            }

            /// sends an asynchronous http request, returning the response as a
            /// [`String`](https://doc.rust-lang.org/std/string/struct.String.html).
            ///
            /// # examples
            ///
            /// ```
            /// use simplist::HttpSyncClient;
            ///
            /// let http = HttpSyncClient::new(handle);
            ///
            /// assert_eq!(
            ///     http.get_string("https://hinaria.com")?,
            ///     "<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\"> ...");
            /// ```
            pub fn $string_method_name<TUrl>(&self, url: TUrl) -> Result<String, HttpError>
                where TUrl: IntoUrl {

                self.underlying.$string_method_name(url).wait()
            }
        }
    };

    // :: [content = yes] implementation for methods with a content body
    (x, $method_variant: path, $method_name: ident, $string_method_name: ident) => {
        impl HttpClient {
            /// sends an asynchronous http request, returning the response as a
            /// [`Vec<u8>`](https://doc.rust-lang.org/std/vec/struct.Vec.html).
            ///
            /// the request body can be any type that is convertible to a [`HttpContent`](struct.HttpContent.html).
            /// refer to [`HttpContent`](struct.HttpContent.html) 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, ...]);
            /// ```
            pub fn $method_name<TUrl, TContent>(&self, url: TUrl, content: Option<TContent>) -> OneOfFuture<Box<Future<Item = Vec<u8>, Error = HttpError>>, FutureResult<Vec<u8>, HttpError>, Vec<u8>, HttpError>
                where TUrl:     IntoUrl,
                      TContent: Into<HttpContent>, {

                match url.as_url() {
                    Ok(url) => OneOfFuture::A(self.run_bytes(url, $method_variant, content)),
                    Err(e)  => OneOfFuture::B(hina::task::failed(e)),
                }
            }

            /// sends an asynchronous http request, returning the response as a
            /// [`String`](https://doc.rust-lang.org/std/string/struct.String.html).
            ///
            /// the request body can be any type that is convertible to a [`HttpContent`](struct.HttpContent.html).
            /// refer to [`HttpContent`](struct.HttpContent.html) 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\"> ...");
            /// ```
            pub fn $string_method_name<TUrl, TContent>(&self, url: TUrl, content: Option<TContent>) -> OneOfFuture<Box<Future<Item = String, Error = HttpError>>, FutureResult<String, HttpError>, String, HttpError>
                where TUrl:     IntoUrl,
                      TContent: Into<HttpContent>, {

                match url.as_url() {
                    Ok(url) => OneOfFuture::A(self.run_string(url, $method_variant, content)),
                    Err(e)  => OneOfFuture::B(hina::task::failed(e)),
                }
            }
        }

        impl HttpSyncClient {
            /// sends an asynchronous http request, returning the response as a
            /// [`Vec<u8>`](https://doc.rust-lang.org/std/vec/struct.Vec.html).
            ///
            /// the request body can be any type that is convertible to a [`HttpContent`](struct.HttpContent.html).
            /// refer to [`HttpContent`](struct.HttpContent.html) to see a list of types that can be used.
            ///
            /// # examples
            ///
            /// ```
            /// use simplist::HttpSyncClient;
            ///
            /// let http = HttpSyncClient::new(handle);
            /// let body = Some("{ id: 1234 }");
            ///
            /// assert_eq!(
            ///     &http.post("https://hinaria.com/users/@me/database", body)?,
            ///     &[60, 33, 68, 79, 67, 84, 89, 80, 69, 32, 104, 116, ...]);
            /// ```
            pub fn $method_name<TUrl, TContent>(&self, url: TUrl, content: Option<TContent>) -> Result<Vec<u8>, HttpError>
                where TUrl:     IntoUrl,
                      TContent: Into<HttpContent>, {

                self.underlying.$method_name(url, content).wait()
            }

            /// sends an asynchronous http request, returning the response as a
            /// [`String`](https://doc.rust-lang.org/std/string/struct.String.html).
            ///
            /// the request body can be any type that is convertible to a [`HttpContent`](struct.HttpContent.html).
            /// refer to [`HttpContent`](struct.HttpContent.html) to see a list of types that can be used.
            ///
            /// # examples
            ///
            /// ```
            /// use simplist::HttpSyncClient;
            ///
            /// let http = HttpSyncClient::new(handle);
            /// let body = Some("{ id: 1234 }");
            ///
            /// assert_eq!(
            ///     &http.post_string("https://hinaria.com/users/@me/database", body)?,
            ///     "<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\"> ...");
            /// ```
            pub fn $string_method_name<TUrl, TContent>(&self, url: TUrl, content: Option<TContent>) -> Result<String, HttpError>
                where TUrl:     IntoUrl,
                      TContent: Into<HttpContent>, {

                self.underlying.$string_method_name(url, content).wait()
            }
        }
    };

    ([no-content, $method_variant: path, $method_name: ident, $string_method_name: ident], $($rest:tt)*) => {
        http_client_methods!(no-content, $method_variant, $method_name, $string_method_name);
        http_client_methods!($($rest)*);
    };

    ([x,          $method_variant: path, $method_name: ident, $string_method_name: ident], $($rest:tt)*) => {
        http_client_methods!(x, $method_variant, $method_name, $string_method_name);
        http_client_methods!($($rest)*);
    };
}

http_client_methods!(
    [x,          HttpMethod::Options, options, options_string],
    [no-content, HttpMethod::Get,     get,     get_string    ],
    [x,          HttpMethod::Post,    post,    post_string   ],
    [x,          HttpMethod::Put,     put,     put_string    ],
    [no-content, HttpMethod::Delete,  delete,  delete_string ],
    [no-content, HttpMethod::Head,    head,    head_string   ],
    [no-content, HttpMethod::Trace,   trace,   trace_string  ],
    [no-content, HttpMethod::Connect, connect, connect_string],
    [x,          HttpMethod::Patch,   patch,   patch_string  ],
);