docs(lib): Update docstrings for rustdoc output
This commit is contained in:
parent
569e10e509
commit
9ce0098bc0
1 changed files with 63 additions and 19 deletions
82
src/lib.rs
82
src/lib.rs
|
@ -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,
|
||||||
|
|
Loading…
Reference in a new issue