From fcedd6981930917c0a02b74e378b5e6205d05781 Mon Sep 17 00:00:00 2001 From: jayjamesjay Date: Thu, 27 Jun 2024 10:06:50 +0200 Subject: [PATCH] improve docs --- examples/chunked.rs | 4 ++-- examples/get.rs | 4 ++-- examples/head.rs | 4 ++-- examples/post.rs | 10 +++++----- examples/request_builder_get.rs | 18 +++++++++--------- src/lib.rs | 5 ++++- src/request.rs | 26 +++++++++++++++----------- src/stream.rs | 13 ++++++++----- 8 files changed, 47 insertions(+), 37 deletions(-) diff --git a/examples/chunked.rs b/examples/chunked.rs index 99c490a..8e258b2 100644 --- a/examples/chunked.rs +++ b/examples/chunked.rs @@ -1,11 +1,11 @@ use http_req::request; fn main() { - //Sends a HTTP GET request and processes the response. + // Sends a HTTP GET request and processes the response. let mut body = Vec::new(); let res = request::get("https://jigsaw.w3.org/HTTP/ChunkedScript", &mut body).unwrap(); - //Prints details about the response. + // Prints details about the response. println!("Status: {} {}", res.status_code(), res.reason()); println!("Headers: {}", res.headers()); //println!("{}", String::from_utf8_lossy(&body)); diff --git a/examples/get.rs b/examples/get.rs index a14c8a7..a1d4856 100644 --- a/examples/get.rs +++ b/examples/get.rs @@ -1,10 +1,10 @@ use http_req::request; fn main() { - //Container for body of a response. + // Container for body of a response. let mut body = Vec::new(); - //Sends a HTTP GET request and processes the response. Saves body of the response to `body` variable. + // Sends a HTTP GET request and processes the response. Saves body of the response to `body` variable. let res = request::get("https://www.rust-lang.org/learn", &mut body).unwrap(); //Prints details about the response. diff --git a/examples/head.rs b/examples/head.rs index 922e278..c20e80a 100644 --- a/examples/head.rs +++ b/examples/head.rs @@ -1,10 +1,10 @@ use http_req::request; fn main() { - //Sends a HTTP HEAD request and processes the response. + // Sends a HTTP HEAD request and processes the response. let res = request::head("https://www.rust-lang.org/learn").unwrap(); - //Prints details about the response. + // Prints the details about the response. println!("Status: {} {}", res.status_code(), res.reason()); println!("Headers: {}", res.headers()); } diff --git a/examples/post.rs b/examples/post.rs index fadfb9d..e1f498b 100644 --- a/examples/post.rs +++ b/examples/post.rs @@ -1,17 +1,17 @@ use http_req::request; fn main() { - //Container for body of a response. + // Container for body of a response. let mut res_body = Vec::new(); - //Body of a request. + // Body of a request. const REQ_BODY: &[u8; 27] = b"field1=value1&field2=value2"; - //Sends a HTTP POST request and processes the response. + // Sends a HTTP POST request and processes the response. let res = request::post("https://httpbin.org/post", REQ_BODY, &mut res_body).unwrap(); - //Prints details about the response. + // Prints details about the response. println!("Status: {} {}", res.status_code(), res.reason()); println!("Headers: {}", res.headers()); - println!("{}", String::from_utf8_lossy(&res_body)); + //println!("{}", String::from_utf8_lossy(&res_body)); } diff --git a/examples/request_builder_get.rs b/examples/request_builder_get.rs index da13231..e52be18 100644 --- a/examples/request_builder_get.rs +++ b/examples/request_builder_get.rs @@ -11,35 +11,35 @@ use std::{ }; fn main() { - //Parses a URI and assigns it to a variable `addr`. + // Parses a URI and assigns it to a variable `addr`. let addr: Uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap(); - //Containers for a server's response. + // Containers for a server's response. let raw_head; let mut body = Vec::new(); - //Prepares a request message. + // Prepares a request message. let request_msg = RequestBuilder::new(&addr) .header("Connection", "Close") .parse(); - //Connects to a server. Uses information from `addr`. + // Connects to a server. Uses information from `addr`. let mut stream = Stream::new(&addr, Some(Duration::from_secs(60))).unwrap(); stream = Stream::try_to_https(stream, &addr, None).unwrap(); - //Makes a request to server - sends a prepared message. + // Makes a request to server. Sends the prepared message. stream.write_all(&request_msg).unwrap(); - //Wraps the stream in BufReader to make it easier to read from it. - //Reads a response from the server and saves the head to `raw_head`, and the body to `body`. + // Wraps the stream in BufReader to make it easier to read from it. + // Reads a response from the server and saves the head to `raw_head`, and the body to `body`. let mut stream = BufReader::new(stream); raw_head = stream::read_head(&mut stream); stream.read_to_end(&mut body).unwrap(); - //Parses and processes the response. + // Parses and processes the response. let response = Response::from_head(&raw_head).unwrap(); - //Prints infromation about the response. + // Prints infromation about the response. println!("Status: {} {}", response.status_code(), response.reason()); println!("Headers: {}", response.headers()); //println!("{}", String::from_utf8_lossy(&body)); diff --git a/src/lib.rs b/src/lib.rs index 3f806de..2de2c9e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,5 +1,8 @@ //! Simple HTTP client with built-in HTTPS support. -//! Currently it's in heavy development and may frequently change. +//! +//! By default uses [rust-native-tls](https://github.com/sfackler/rust-native-tls), +//! which relies on TLS framework provided by OS on Windows and macOS, and OpenSSL +//! on all other platforms. But it also supports [rus-tls](https://crates.io/crates/rustls). //! //! ## Example //! Basic GET request diff --git a/src/request.rs b/src/request.rs index d41f40d..63d120a 100644 --- a/src/request.rs +++ b/src/request.rs @@ -26,7 +26,9 @@ pub enum Method { POST, PUT, DELETE, + CONNECT, OPTIONS, + TRACE, PATCH, } @@ -40,7 +42,9 @@ impl fmt::Display for Method { POST => "POST", PUT => "PUT", DELETE => "DELETE", + CONNECT => "CONNECT", OPTIONS => "OPTIONS", + TRACE => "TRACE", PATCH => "PATCH", }; @@ -303,7 +307,7 @@ impl<'a> Request<'a> { /// let mut writer = Vec::new(); /// let uri: Uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap(); /// - /// let response = Request::new(&uri).send(&mut writer).unwrap();; + /// let request = Request::new(&uri); /// ``` pub fn new(uri: &'a Uri) -> Request<'a> { let mut builder = RequestBuilder::new(&uri); @@ -328,7 +332,7 @@ impl<'a> Request<'a> { /// /// let uri: Uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap(); /// - /// let response = Request::new(&uri) + /// let request = Request::new(&uri) /// .method(Method::HEAD); /// ``` pub fn method(&mut self, method: T) -> &mut Self @@ -348,7 +352,7 @@ impl<'a> Request<'a> { /// /// let uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap(); /// - /// let response = Request::new(&uri) + /// let request = Request::new(&uri) /// .version(HttpVersion::Http10); /// ``` @@ -375,7 +379,7 @@ impl<'a> Request<'a> { /// headers.insert("Host", "rust-lang.org"); /// headers.insert("Connection", "Close"); /// - /// let response = Request::new(&uri) + /// let request = Request::new(&uri) /// .headers(headers); /// ``` pub fn headers(&mut self, headers: T) -> &mut Self @@ -395,7 +399,7 @@ impl<'a> Request<'a> { /// /// let uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap(); /// - /// let response = Request::new(&uri) + /// let request = Request::new(&uri) /// .header("Accept-Language", "en-US"); /// ``` pub fn header(&mut self, key: &T, val: &U) -> &mut Self @@ -417,7 +421,7 @@ impl<'a> Request<'a> { /// let uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap(); /// const body: &[u8; 27] = b"field1=value1&field2=value2"; /// - /// let response = Request::new(&uri) + /// let request = Request::new(&uri) /// .method(Method::POST) /// .header("Content-Length", &body.len()) /// .body(body); @@ -446,7 +450,7 @@ impl<'a> Request<'a> { /// let uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap(); /// const time: Option = Some(Duration::from_secs(10)); /// - /// let response = Request::new(&uri) + /// let request = Request::new(&uri) /// .connect_timeout(time); /// ``` pub fn connect_timeout(&mut self, timeout: Option) -> &mut Self @@ -472,7 +476,7 @@ impl<'a> Request<'a> { /// let uri: Uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap(); /// const time: Option = Some(Duration::from_secs(15)); /// - /// let response = Request::new(&uri) + /// let request = Request::new(&uri) /// .read_timeout(time); /// ``` pub fn read_timeout(&mut self, timeout: Option) -> &mut Self @@ -498,7 +502,7 @@ impl<'a> Request<'a> { /// let uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap(); /// const time: Option = Some(Duration::from_secs(5)); /// - /// let response = Request::new(&uri) + /// let request = Request::new(&uri) /// .write_timeout(time); /// ``` pub fn write_timeout(&mut self, timeout: Option) -> &mut Self @@ -520,7 +524,7 @@ impl<'a> Request<'a> { /// let uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap(); /// const time: Duration = Duration::from_secs(5); /// - /// let response = Request::new(&uri) + /// let request = Request::new(&uri) /// .timeout(time); /// ``` pub fn timeout(&mut self, timeout: T) -> &mut Self @@ -541,7 +545,7 @@ impl<'a> Request<'a> { /// let uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap(); /// let path = Path::new("./foo/bar.txt"); /// - /// let response = Request::new(&uri) + /// let request = Request::new(&uri) /// .root_cert_file_pem(&path); /// ``` pub fn root_cert_file_pem(&mut self, file_path: &'a Path) -> &mut Self { diff --git a/src/stream.rs b/src/stream.rs index f0c8d87..da0c6d3 100644 --- a/src/stream.rs +++ b/src/stream.rs @@ -226,11 +226,14 @@ where /// Exexcutes a function in a loop until operation is completed or deadline is exceeded. /// /// It checks if a timeout was exceeded every iteration, therefore it limits -/// how many time a specific function can be called before deadline. -/// However a deadline may be exceeded if a single function call takes too much time. -/// -/// Function `func` needs to return `true` when the operation is complete. -/// +/// how many time a specific function can be called before deadline. +/// For the `execute_with_deadline` to meet the deadline, each call +/// to `func` needs finish before the deadline. +/// +/// Key information about function `func`: +/// - is provided with information about remaining time +/// - must ensure that its execution will not take more time than specified in `remaining_time` +/// - needs to return `true` when the operation is complete pub fn execute_with_deadline(deadline: Instant, mut func: F) where F: FnMut(Duration) -> bool,