docs(lib): Update docstrings for rustdoc output

This commit is contained in:
Vincent Ambo 2019-02-26 15:27:52 +01:00
parent 569e10e509
commit 9ce0098bc0

View file

@ -2,14 +2,41 @@
//! //!
//! This library provides a simplified API over the [cURL Rust //! This library provides a simplified API over the [cURL Rust
//! bindings][] that resemble that of higher-level libraries such as //! bindings][] that resemble that of higher-level libraries such as
//! [reqwest][]. //! [reqwest][]. All calls are synchronous.
//! //!
//! `crimp` is intended to be used in situations where HTTP client //! `crimp` is intended to be used in situations where HTTP client
//! functionality is desired without adding a significant number of //! functionality is desired without adding a significant number of
//! dependencies or sacrificing too much usability. //! dependencies or sacrificing too much usability.
//! //!
//! Using `crimp` to make HTTP requests is done using a simple
//! builder-pattern style API:
//!
//! ```rust
//! use crimp::{Method, Request};
//!
//! let response = Request::new(Method::Get, "http://httpbin.org/get").unwrap()
//! .user_agent("crimp test suite").unwrap()
//! .send().unwrap();
//!
//! assert_eq!(response.status, 200);
//! ```
//!
//! The `json` feature (enabled by default) adds support for
//! automatically serialising and deserialising request/response
//! bodies using `serde_json`.
//!
//! If a feature from the underlying cURL library is missing, the
//! `Request::raw` method can be used as an escape hatch to deal with
//! the handle directly. Should you find yourself doing this, please
//! [file an issue][].
//!
//! `crimp` does not currently expose functionality for re-using a
//! cURL Easy handle, meaning that keep-alive of HTTP connections and
//! the like is not supported.
//!
//! [cURL Rust bindings]: https://docs.rs/curl //! [cURL Rust bindings]: https://docs.rs/curl
//! [reqwest]: https://docs.rs/reqwest //! [reqwest]: https://docs.rs/reqwest
//! [file an issue]: https://github.com/tazjin/crimp/issues
extern crate curl; extern crate curl;
@ -17,22 +44,26 @@ extern crate curl;
#[cfg(feature = "json")] extern crate serde_json; #[cfg(feature = "json")] extern crate serde_json;
use curl::easy::{Easy, List, ReadError}; use curl::easy::{Easy, List, ReadError};
#[cfg(feature = "json")] use serde::Serialize;
#[cfg(feature = "json")] use serde::de::DeserializeOwned;
use std::collections::HashMap; use std::collections::HashMap;
use std::io::Write; use std::io::Write;
use std::string::{FromUtf8Error, ToString}; use std::string::{FromUtf8Error, ToString};
#[cfg(feature = "json")] use serde::Serialize;
#[cfg(feature = "json")] use serde::de::DeserializeOwned;
#[cfg(test)] #[cfg(test)]
mod tests; mod tests;
type CurlResult<T> = Result<T, curl::Error>;
/// HTTP method to use for the request. /// HTTP method to use for the request.
pub enum Method { pub enum Method {
Get, Post, Put, Patch, Delete Get, Post, Put, Patch, Delete
} }
/// Builder structure for an HTTP request.
///
/// This is the primary API-type in `crimp`. After creating a new
/// request its parameters are modified using the various builder
/// methods until it is consumed by `send()`.
pub struct Request<'a> { pub struct Request<'a> {
handle: Easy, handle: Easy,
headers: List, headers: List,
@ -49,16 +80,28 @@ enum Body<'a> {
} }
} }
/// HTTP responses structure containing response data and headers.
///
/// By default the `send()` function of the `Request` structure will
/// return a `Response<Vec<u8>>`. Convenience helpers exist for
/// decoding a string via `Response::as_string` or to a
/// `serde`-compatible type with `Response::as_json` (if the
/// `json`-feature is enabled).
#[derive(Debug)] #[derive(Debug)]
pub struct CurlResponse<T> { pub struct Response<T> {
/// HTTP status code of the response.
pub status: u32, pub status: u32,
/// HTTP headers returned from the remote.
pub headers: HashMap<String, String>, pub headers: HashMap<String, String>,
/// Body data from the HTTP response.
pub body: T, pub body: T,
} }
impl <'a> Request<'a> { impl <'a> Request<'a> {
/// Initiate an HTTP request with the given method and URL. /// Initiate an HTTP request with the given method and URL.
pub fn new(method: Method, url: &str) -> CurlResult<Self> { pub fn new(method: Method, url: &str) -> Result<Self, curl::Error> {
let mut handle = Easy::new(); let mut handle = Easy::new();
handle.url(url)?; handle.url(url)?;
@ -77,20 +120,21 @@ impl <'a> Request<'a> {
}) })
} }
/// Add a header to a request. /// Add an HTTP header to a request.
pub fn header(mut self, k: &str, v: &str) -> CurlResult<Self> { pub fn header(mut self, k: &str, v: &str) -> Result<Self, curl::Error> {
self.headers.append(&format!("{}: {}", k, v))?; self.headers.append(&format!("{}: {}", k, v))?;
Ok(self) Ok(self)
} }
/// Set the User-Agent for this request. /// Set the `User-Agent` for this request. By default this will be
pub fn user_agent<'b: 'a>(mut self, agent: &str) -> CurlResult<Self> { /// set to cURL's standard user agent.
pub fn user_agent<'b: 'a>(mut self, agent: &str) -> Result<Self, curl::Error> {
self.handle.useragent(agent)?; self.handle.useragent(agent)?;
Ok(self) Ok(self)
} }
/// Add a byte-array body to a request using the specified /// Add a byte-array body to a request using the specified
/// Content-Type. /// `Content-Type`.
pub fn body(mut self, content_type: &'a str, data: &'a [u8]) -> Self { pub fn body(mut self, content_type: &'a str, data: &'a [u8]) -> Self {
self.body = Body::Bytes { data, content_type }; self.body = Body::Bytes { data, content_type };
self self
@ -106,7 +150,7 @@ impl <'a> Request<'a> {
/// Send the HTTP request and return a response structure /// Send the HTTP request and return a response structure
/// containing the raw body. /// containing the raw body.
pub fn send(mut self) -> CurlResult<CurlResponse<Vec<u8>>> { pub fn send(mut self) -> Result<Response<Vec<u8>>, curl::Error> {
// Create structures in which to store the response data: // Create structures in which to store the response data:
let mut headers = HashMap::new(); let mut headers = HashMap::new();
let mut body = vec![]; let mut body = vec![];
@ -191,7 +235,7 @@ impl <'a> Request<'a> {
transfer.perform()?; transfer.perform()?;
} }
Ok(CurlResponse { Ok(Response {
status: self.handle.response_code()?, status: self.handle.response_code()?,
headers, headers,
body body
@ -199,13 +243,13 @@ impl <'a> Request<'a> {
} }
} }
impl CurlResponse<Vec<u8>> { impl Response<Vec<u8>> {
/// Attempt to parse the HTTP response body as a UTF-8 encoded /// Attempt to parse the HTTP response body as a UTF-8 encoded
/// string. /// string.
pub fn as_string(self) -> Result<CurlResponse<String>, FromUtf8Error> { pub fn as_string(self) -> Result<Response<String>, FromUtf8Error> {
let body = String::from_utf8(self.body)?; let body = String::from_utf8(self.body)?;
Ok(CurlResponse { Ok(Response {
body, body,
status: self.status, status: self.status,
headers: self.headers, headers: self.headers,
@ -214,10 +258,10 @@ impl CurlResponse<Vec<u8>> {
/// Attempt to deserialize the HTTP response body from JSON. /// Attempt to deserialize the HTTP response body from JSON.
#[cfg(feature = "json")] #[cfg(feature = "json")]
pub fn as_json<T: DeserializeOwned>(self) -> Result<CurlResponse<T>, serde_json::Error> { pub fn as_json<T: DeserializeOwned>(self) -> Result<Response<T>, serde_json::Error> {
let deserialized = serde_json::from_slice(&self.body)?; let deserialized = serde_json::from_slice(&self.body)?;
Ok(CurlResponse { Ok(Response {
body: deserialized, body: deserialized,
status: self.status, status: self.status,
headers: self.headers, headers: self.headers,