From 2ce66b57659b76ab9c5e8c202f3db91978b9ca65 Mon Sep 17 00:00:00 2001 From: Igor Aleksanov Date: Tue, 8 Sep 2020 20:45:32 +0300 Subject: [PATCH 1/6] awc: Provide Reqwest-like crate doc-comment --- awc/src/lib.rs | 102 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 89 insertions(+), 13 deletions(-) diff --git a/awc/src/lib.rs b/awc/src/lib.rs index a98d6767d06..e4e21375905 100644 --- a/awc/src/lib.rs +++ b/awc/src/lib.rs @@ -4,24 +4,98 @@ clippy::borrow_interior_mutable_const, clippy::needless_doctest_main )] -//! An HTTP Client + +//! `awc` is a HTTP/WebSocket library implemented atop of `actix` stack. //! -//! ```rust -//! use actix_rt::System; -//! use awc::Client; +//! ## Making a GET request //! +//! ```rust +//! # use actix_rt::System; //! #[actix_rt::main] -//! async fn main() { -//! let mut client = Client::default(); +//! # async fn main() -> Result<(), awc::error::SendRequestError> { +//! let mut client = awc::Client::default(); +//! let response = client.get("http://www.rust-lang.org") // <- Create request builder +//! .header("User-Agent", "Actix-web") +//! .send() // <- Send http request +//! .await?; +//! +//! println!("Response: {:?}", response); +//! # Ok(()) +//! # } +//! ``` +//! +//! ## Making POST requests +//! +//! ### Raw body contents +//! +//! ```rust +//! # use actix_rt::System; +//! # #[actix_rt::main] +//! # async fn main() -> Result<(), awc::error::SendRequestError> { +//! let mut client = awc::Client::default(); +//! let response = client.post("http://httpbin.org/post") +//! .send_body("Raw body contents") +//! .await?; +//! # Ok(()) +//! # } +//! ``` +//! +//! ### Forms +//! +//! ```rust +//! # use actix_rt::System; +//! # #[actix_rt::main] +//! # async fn main() -> Result<(), awc::error::SendRequestError> { +//! let params = [("foo", "bar"), ("baz", "quux")]; +//! +//! let mut client = awc::Client::default(); +//! let response = client.post("http://httpbin.org/post") +//! .send_form(¶ms) +//! .await?; +//! # Ok(()) +//! # } +//! ``` +//! +//! ### JSON +//! +//! ```rust +//! # use std::collections::HashMap; +//! # use actix_rt::System; +//! # #[actix_rt::main] +//! # async fn main() -> Result<(), awc::error::SendRequestError> { +//! let mut map = HashMap::new(); +//! map.insert("lang", "rust"); +//! map.insert("body", "json"); //! -//! let response = client.get("http://www.rust-lang.org") // <- Create request builder -//! .header("User-Agent", "Actix-web") -//! .send() // <- Send http request -//! .await; +//! let mut client = awc::Client::default(); +//! let response = client.post("http://httpbin.org/post") +//! .send_json(&map) +//! .await?; +//! # Ok(()) +//! # } +//! ``` +//! +//! ## WebSocket support +//! +//! ``` +//! # use awc::{Client, ws}; +//! # #[actix_rt::main] +//! # async fn main() -> Result<(), Box> { +//! use futures_util::{sink::SinkExt, stream::StreamExt}; +//! let (_resp, mut connection) = Client::new() +//! .ws("ws://echo.websocket.org") +//! .connect() +//! .await?; //! -//! println!("Response: {:?}", response); -//! } +//! connection +//! .send(ws::Message::Text("Echo".to_string())) +//! .await?; +//! let response = connection.next().await.unwrap()?; +//! # assert_eq!(response, ws::Frame::Text("Echo".as_bytes().into())); +//! # Ok(()) +//! # } //! ``` + use std::cell::RefCell; use std::convert::TryFrom; use std::rc::Rc; @@ -51,7 +125,9 @@ pub use self::sender::SendClientRequest; use self::connect::{Connect, ConnectorWrapper}; -/// An HTTP Client +/// An asynchronous web Client. +/// +/// ## Examples /// /// ```rust /// use awc::Client; From 94d120a6815832c88709715f1da2667f2e858714 Mon Sep 17 00:00:00 2001 From: Igor Aleksanov Date: Wed, 9 Sep 2020 06:57:42 +0300 Subject: [PATCH 2/6] Note that awc is a Client library --- awc/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/awc/src/lib.rs b/awc/src/lib.rs index e4e21375905..b5c7c844c27 100644 --- a/awc/src/lib.rs +++ b/awc/src/lib.rs @@ -5,7 +5,7 @@ clippy::needless_doctest_main )] -//! `awc` is a HTTP/WebSocket library implemented atop of `actix` stack. +//! `awc` is a HTTP/WebSocket Client library implemented atop of `actix` stack. //! //! ## Making a GET request //! From 8d6eaae299a5f4b8c2095617b909545af3f4626a Mon Sep 17 00:00:00 2001 From: Igor Aleksanov Date: Wed, 9 Sep 2020 14:04:15 +0300 Subject: [PATCH 3/6] Apply suggestions from code review Improve wording Co-authored-by: Rob Ede --- awc/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/awc/src/lib.rs b/awc/src/lib.rs index b5c7c844c27..743adcf9ffe 100644 --- a/awc/src/lib.rs +++ b/awc/src/lib.rs @@ -5,7 +5,7 @@ clippy::needless_doctest_main )] -//! `awc` is a HTTP/WebSocket Client library implemented atop of `actix` stack. +//! `awc` is a HTTP and WebSocket client library built using the Actix ecosystem. //! //! ## Making a GET request //! @@ -125,7 +125,7 @@ pub use self::sender::SendClientRequest; use self::connect::{Connect, ConnectorWrapper}; -/// An asynchronous web Client. +/// An asynchronous HTTP and WebSocket client. /// /// ## Examples /// From 62aaf1fc4cd7f04ba0c14f4969c733e15ce545da Mon Sep 17 00:00:00 2001 From: Igor Aleksanov Date: Wed, 9 Sep 2020 14:07:37 +0300 Subject: [PATCH 4/6] Improve code in examples --- awc/src/lib.rs | 31 +++++++++++++------------------ 1 file changed, 13 insertions(+), 18 deletions(-) diff --git a/awc/src/lib.rs b/awc/src/lib.rs index 743adcf9ffe..80a0bcab2c4 100644 --- a/awc/src/lib.rs +++ b/awc/src/lib.rs @@ -10,11 +10,10 @@ //! ## Making a GET request //! //! ```rust -//! # use actix_rt::System; -//! #[actix_rt::main] +//! # #[actix_rt::main] //! # async fn main() -> Result<(), awc::error::SendRequestError> { //! let mut client = awc::Client::default(); -//! let response = client.get("http://www.rust-lang.org") // <- Create request builder +//! let response = client.get("https://www.rust-lang.org") // <- Create request builder //! .header("User-Agent", "Actix-web") //! .send() // <- Send http request //! .await?; @@ -29,11 +28,10 @@ //! ### Raw body contents //! //! ```rust -//! # use actix_rt::System; //! # #[actix_rt::main] //! # async fn main() -> Result<(), awc::error::SendRequestError> { //! let mut client = awc::Client::default(); -//! let response = client.post("http://httpbin.org/post") +//! let response = client.post("https://httpbin.org/post") //! .send_body("Raw body contents") //! .await?; //! # Ok(()) @@ -43,13 +41,12 @@ //! ### Forms //! //! ```rust -//! # use actix_rt::System; //! # #[actix_rt::main] //! # async fn main() -> Result<(), awc::error::SendRequestError> { //! let params = [("foo", "bar"), ("baz", "quux")]; //! //! let mut client = awc::Client::default(); -//! let response = client.post("http://httpbin.org/post") +//! let response = client.post("https://httpbin.org/post") //! .send_form(¶ms) //! .await?; //! # Ok(()) @@ -59,17 +56,16 @@ //! ### JSON //! //! ```rust -//! # use std::collections::HashMap; -//! # use actix_rt::System; //! # #[actix_rt::main] //! # async fn main() -> Result<(), awc::error::SendRequestError> { -//! let mut map = HashMap::new(); -//! map.insert("lang", "rust"); -//! map.insert("body", "json"); +//! let mut request = serde_json::json!({ +//! "lang": "rust", +//! "body": "json" +//! }); //! //! let mut client = awc::Client::default(); -//! let response = client.post("http://httpbin.org/post") -//! .send_json(&map) +//! let response = client.post("https://httpbin.org/post") +//! .send_json(&request) //! .await?; //! # Ok(()) //! # } @@ -78,20 +74,19 @@ //! ## WebSocket support //! //! ``` -//! # use awc::{Client, ws}; //! # #[actix_rt::main] //! # async fn main() -> Result<(), Box> { //! use futures_util::{sink::SinkExt, stream::StreamExt}; -//! let (_resp, mut connection) = Client::new() +//! let (_resp, mut connection) = awc::Client::new() //! .ws("ws://echo.websocket.org") //! .connect() //! .await?; //! //! connection -//! .send(ws::Message::Text("Echo".to_string())) +//! .send(awc::ws::Message::Text("Echo".to_string())) //! .await?; //! let response = connection.next().await.unwrap()?; -//! # assert_eq!(response, ws::Frame::Text("Echo".as_bytes().into())); +//! # assert_eq!(response, awc::ws::Frame::Text("Echo".as_bytes().into())); //! # Ok(()) //! # } //! ``` From c946ee7b4e7545014279b1384aed7ad06f4bfff5 Mon Sep 17 00:00:00 2001 From: Igor Aleksanov Date: Wed, 9 Sep 2020 14:14:55 +0300 Subject: [PATCH 5/6] Polish the docs appearance --- awc/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/awc/src/lib.rs b/awc/src/lib.rs index 80a0bcab2c4..41f69e62e2b 100644 --- a/awc/src/lib.rs +++ b/awc/src/lib.rs @@ -15,7 +15,7 @@ //! let mut client = awc::Client::default(); //! let response = client.get("https://www.rust-lang.org") // <- Create request builder //! .header("User-Agent", "Actix-web") -//! .send() // <- Send http request +//! .send() // <- Send http request //! .await?; //! //! println!("Response: {:?}", response); @@ -58,7 +58,7 @@ //! ```rust //! # #[actix_rt::main] //! # async fn main() -> Result<(), awc::error::SendRequestError> { -//! let mut request = serde_json::json!({ +//! let request = serde_json::json!({ //! "lang": "rust", //! "body": "json" //! }); From 1125fe69e046fd0f596a569c17ba995bd1786981 Mon Sep 17 00:00:00 2001 From: Igor Aleksanov Date: Wed, 9 Sep 2020 15:53:42 +0300 Subject: [PATCH 6/6] Use HTTP instead of HTTPS --- awc/src/lib.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/awc/src/lib.rs b/awc/src/lib.rs index 41f69e62e2b..7167dbb96a1 100644 --- a/awc/src/lib.rs +++ b/awc/src/lib.rs @@ -13,7 +13,7 @@ //! # #[actix_rt::main] //! # async fn main() -> Result<(), awc::error::SendRequestError> { //! let mut client = awc::Client::default(); -//! let response = client.get("https://www.rust-lang.org") // <- Create request builder +//! let response = client.get("http://www.rust-lang.org") // <- Create request builder //! .header("User-Agent", "Actix-web") //! .send() // <- Send http request //! .await?; @@ -31,7 +31,7 @@ //! # #[actix_rt::main] //! # async fn main() -> Result<(), awc::error::SendRequestError> { //! let mut client = awc::Client::default(); -//! let response = client.post("https://httpbin.org/post") +//! let response = client.post("http://httpbin.org/post") //! .send_body("Raw body contents") //! .await?; //! # Ok(()) @@ -46,7 +46,7 @@ //! let params = [("foo", "bar"), ("baz", "quux")]; //! //! let mut client = awc::Client::default(); -//! let response = client.post("https://httpbin.org/post") +//! let response = client.post("http://httpbin.org/post") //! .send_form(¶ms) //! .await?; //! # Ok(()) @@ -64,7 +64,7 @@ //! }); //! //! let mut client = awc::Client::default(); -//! let response = client.post("https://httpbin.org/post") +//! let response = client.post("http://httpbin.org/post") //! .send_json(&request) //! .await?; //! # Ok(())