feat(net)!: net api: net.{get,post,etc..}(url) alternative to net.send(request)

examples/get.rs

@@ -61,10 +61,6 @@ async fn download_and_save_to_file(
 ) -> kxio::Result<()> {
     println!("fetching: {url}");
 
-    // Uses the network abstraction to create a perfectly normal `reqwest::ResponseBuilder`.
-    // `kxio::net::RequestBuilder` is an alias.
-    let request: kxio::net::RequestBuilder = net.client().get(url);
-
     // Rather than calling `.build().send()?` on the request, pass it to the `net`
     // This allows the `net` to either make the network request as normal, or, if we are
     // under test, to handle the request as the test dictates.
@@ -72,7 +68,13 @@ async fn download_and_save_to_file(
     // a real network request being made, even under test conditions. Only ever use the
     // `net.send(...)` function to keep your code testable.
     // `kxio::net::Response` is an alias for `reqwest::Response`.
-    let response: kxio::net::Response = net.send(request).await?;
+    let response: kxio::net::Response = net.get(url).header("key", "value").send().await?;
+    // Other options:
+    //   Uses the network abstraction to create a perfectly normal `reqwest::ResponseBuilder`.
+    //   `kxio::net::RequestBuilder` is an alias.
+    // let response = net.send(net.client().get(url)).await?;
+    //
+    // let response = net.post(url).body("{}").send().await?;
 
     let body = response.text().await?;
     println!("fetched {} bytes", body.bytes().len());
@@ -118,7 +120,12 @@ mod tests {
         let url = "http://localhost:8080";
 
         // declare what response should be made for a given request
-        mock_net.on().get(url).respond(StatusCode::OK).body("contents");
+        mock_net
+            .on()
+            .get(url)
+            .respond(StatusCode::OK)
+            .body("contents")
+            .expect("valid mock");
 
         // Create a temporary directory that will be deleted with `fs` goes out of scope
         let fs = kxio::fs::temp().expect("temp fs");

src/net/mod.rs

@@ -84,9 +84,9 @@
 //! # async fn main() -> net::Result<()> {
 //! # let mock_net = net::mock();
 //! mock_net.on().get("https://example.com")
-//!     .respond().status(StatusCode::OK).body("");
+//!     .respond(StatusCode::OK).body("");
 //! mock_net.on().get("https://example.com/foo")
-//!     .respond().status(StatusCode::INTERNAL_SERVER_ERROR).body("Mocked response");
+//!     .respond(StatusCode::INTERNAL_SERVER_ERROR).body("Mocked response");
 //! # mock_net.reset();
 //! # Ok(())
 //! # }

src/net/system.rs

@@ -4,13 +4,14 @@ use std::{
     cell::RefCell, collections::HashMap, marker::PhantomData, ops::Deref, rc::Rc, sync::Arc,
 };
 
+use bytes::Bytes;
 use derive_more::derive::{Display, From};
-use http::{Method, StatusCode};
+use http::StatusCode;
-use reqwest::Client;
+use reqwest::{Client, RequestBuilder};
 use tokio::sync::Mutex;
 use url::Url;
 
-use crate::net::{Request, RequestBuilder, Response};
+use crate::net::{Request, Response};
 
 use super::{Error, Result};
 
@@ -28,7 +29,7 @@ struct Plan {
 impl Plan {
     fn matches(&self, request: &Request) -> bool {
         self.match_request.iter().all(|criteria| match criteria {
-            MatchRequest::Method(method) => request.method() == method,
+            MatchRequest::Method(method) => request.method() == http::Method::from(method),
             MatchRequest::Url(uri) => request.url() == uri,
             MatchRequest::Header { name, value } => {
                 request
@@ -70,6 +71,7 @@ impl Net {
     /// let client = net.client();
     /// let request = client.get("https://hyper.rs");
     /// ```
+    #[must_use]
     pub fn client(&self) -> Client {
         Default::default()
     }
@@ -77,6 +79,10 @@ impl Net {
     /// Constructs the Request and sends it to the target URL, returning a
     /// future Response.
     ///
+    /// However, if this request is from a [Net] that was created from a [MockNet],
+    /// then the request will be matched and any stored response returned, or an
+    /// error if no matched request was found.
+    ///
     /// # Errors
     ///
     /// This method fails if there was an error while sending request,
@@ -113,6 +119,42 @@ impl Net {
             None => Err(Error::UnexpectedMockRequest(request)),
         }
     }
+
+    /// Starts building an http DELETE request for the URL.
+    #[must_use]
+    pub fn delete(&self, url: impl Into<String>) -> ReqBuilder {
+        ReqBuilder::new(self, NetMethod::Delete, url)
+    }
+
+    /// Starts building an http GET request for the URL.
+    #[must_use]
+    pub fn get(&self, url: impl Into<String>) -> ReqBuilder {
+        ReqBuilder::new(self, NetMethod::Get, url)
+    }
+
+    /// Starts building an http HEAD request for the URL.
+    #[must_use]
+    pub fn head(&self, url: impl Into<String>) -> ReqBuilder {
+        ReqBuilder::new(self, NetMethod::Head, url)
+    }
+
+    /// Starts building an http PATCH request for the URL.
+    #[must_use]
+    pub fn patch(&self, url: impl Into<String>) -> ReqBuilder {
+        ReqBuilder::new(self, NetMethod::Patch, url)
+    }
+
+    /// Starts building an http POST request for the URL.
+    #[must_use]
+    pub fn post(&self, url: impl Into<String>) -> ReqBuilder {
+        ReqBuilder::new(self, NetMethod::Post, url)
+    }
+
+    /// Starts building an http PUT request for the URL.
+    #[must_use]
+    pub fn put(&self, url: impl Into<String>) -> ReqBuilder {
+        ReqBuilder::new(self, NetMethod::Put, url)
+    }
 }
 impl MockNet {
     pub async fn try_from(net: Net) -> std::result::Result<Self, super::Error> {
@@ -125,6 +167,111 @@ impl MockNet {
     }
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum NetMethod {
+    Delete,
+    Get,
+    Head,
+    Patch,
+    Post,
+    Put,
+}
+impl From<&NetMethod> for http::Method {
+    fn from(value: &NetMethod) -> Self {
+        match value {
+            NetMethod::Delete => http::Method::DELETE,
+            NetMethod::Get => http::Method::GET,
+            NetMethod::Head => http::Method::HEAD,
+            NetMethod::Patch => http::Method::PATCH,
+            NetMethod::Post => http::Method::POST,
+            NetMethod::Put => http::Method::PUT,
+        }
+    }
+}
+
+/// A builder for an http request.
+pub struct ReqBuilder<'net> {
+    net: &'net Net,
+    url: String,
+    method: NetMethod,
+    headers: Vec<(String, String)>,
+    body: Option<Bytes>,
+}
+impl<'net> ReqBuilder<'net> {
+    #[must_use]
+    fn new(net: &'net Net, method: NetMethod, url: impl Into<String>) -> Self {
+        Self {
+            net,
+            url: url.into(),
+            method,
+            headers: vec![],
+            body: None,
+        }
+    }
+
+    /// Constructs the Request and sends it to the target URL, returning a
+    /// future Response.
+    ///
+    /// However, if this request is from a [Net] that was created from a [MockNet],
+    /// then the request will be matched and any stored response returned, or an
+    /// error if no matched request was found.
+    ///
+    /// # Errors
+    ///
+    /// This method fails if there was an error while sending request,
+    /// redirect loop was detected or redirect limit was exhausted.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use kxio::net::Result;
+    /// # async fn run() -> Result<()> {
+    /// let net = kxio::net::new();
+    /// let response = net.get("https://hyper.rs")
+    ///   .header("foo", "bar")
+    ///   .body("{}")
+    ///   .send().await?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub async fn send(self) -> Result<Response> {
+        let client = self.net.client();
+        // Method
+        let mut req = match self.method {
+            NetMethod::Delete => client.delete(self.url),
+            NetMethod::Get => client.get(self.url),
+            NetMethod::Head => client.head(self.url),
+            NetMethod::Patch => client.patch(self.url),
+            NetMethod::Post => client.post(self.url),
+            NetMethod::Put => client.put(self.url),
+        };
+        // Headers
+        for (name, value) in self.headers.into_iter() {
+            req = req.header(name, value);
+        }
+        // Body
+        if let Some(bytes) = self.body {
+            req = req.body(bytes);
+        }
+
+        self.net.send(req).await
+    }
+
+    /// Adds the header and value to the request.
+    #[must_use]
+    pub fn header(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
+        self.headers.push((name.into(), value.into()));
+        self
+    }
+
+    /// Sets the request body.
+    #[must_use]
+    pub fn body(mut self, bytes: impl Into<Bytes>) -> Self {
+        self.body = Some(bytes.into());
+        self
+    }
+}
+
 /// A struct for defining the expected requests and their responses that should be made
 /// during a test.
 ///
@@ -142,7 +289,7 @@ impl MockNet {
 /// let client = mock_net.client();
 /// // define an expected requet, and the response that should be returned
 /// mock_net.on().get("https://hyper.rs")
-///     .respond().status(StatusCode::OK).body("Ok");
+///     .respond(StatusCode::OK).body("Ok");
 /// let net: kxio::net::Net = mock_net.into();
 /// // use 'net' in your program, by passing it as a reference
 ///
@@ -182,7 +329,7 @@ impl MockNet {
     /// let mock_net = kxio::net::mock();
     /// let client = mock_net.client();
     /// mock_net.on().get("https://hyper.rs")
-    ///     .respond().status(StatusCode::OK).body("Ok");
+    ///     .respond(StatusCode::OK).body("Ok");
     /// # Ok(())
     /// # }
     /// ```
@@ -242,7 +389,7 @@ impl Drop for Net {
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum MatchRequest {
-    Method(Method),
+    Method(NetMethod),
     Url(Url),
     Header { name: String, value: String },
     Body(bytes::Bytes),
@@ -293,37 +440,43 @@ impl<'net> WhenRequest<'net, WhenBuildRequest> {
         }
     }
 
+    /// Starts mocking a GET http request.
     #[must_use]
     pub fn get(self, url: impl Into<String>) -> Self {
-        self._url(Method::GET, url)
+        self._url(NetMethod::Get, url)
     }
 
+    /// Starts mocking a POST http request.
     #[must_use]
     pub fn post(self, url: impl Into<String>) -> Self {
-        self._url(Method::POST, url)
+        self._url(NetMethod::Post, url)
     }
 
+    /// Starts mocking a PUT http request.
     #[must_use]
     pub fn put(self, url: impl Into<String>) -> Self {
-        self._url(Method::PUT, url)
+        self._url(NetMethod::Put, url)
     }
 
+    /// Starts mocking a DELETE http request.
     #[must_use]
     pub fn delete(self, url: impl Into<String>) -> Self {
-        self._url(Method::DELETE, url)
+        self._url(NetMethod::Delete, url)
     }
 
+    /// Starts mocking a HEAD http request.
     #[must_use]
     pub fn head(self, url: impl Into<String>) -> Self {
-        self._url(Method::HEAD, url)
+        self._url(NetMethod::Head, url)
     }
 
+    /// Starts mocking a PATCH http request.
     #[must_use]
     pub fn patch(self, url: impl Into<String>) -> Self {
-        self._url(Method::PATCH, url)
+        self._url(NetMethod::Patch, url)
     }
 
-    fn _url(mut self, method: http::Method, url: impl Into<String>) -> Self {
+    fn _url(mut self, method: NetMethod, url: impl Into<String>) -> Self {
         self.match_on.push(MatchRequest::Method(method));
         match Url::parse(&url.into()) {
             Ok(url) => {
@@ -336,6 +489,9 @@ impl<'net> WhenRequest<'net, WhenBuildRequest> {
         self
     }
 
+    /// Specifies a header that the mock will match against.
+    ///
+    /// Any request that does not have this header will not match the mock.
     #[must_use]
     pub fn header(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
         self.match_on.push(MatchRequest::Header {
@@ -345,12 +501,16 @@ impl<'net> WhenRequest<'net, WhenBuildRequest> {
         self
     }
 
+    /// Specifies the body that the mock will match against.
+    ///
+    /// Any request that does not have this body will not match the mock.
     #[must_use]
     pub fn body(mut self, body: impl Into<bytes::Bytes>) -> Self {
         self.match_on.push(MatchRequest::Body(body.into()));
         self
     }
 
+    /// Specifies the http Status Code that will be returned for the matching request.
     #[must_use]
     pub fn respond(self, status: StatusCode) -> WhenRequest<'net, WhenBuildResponse> {
         WhenRequest::<WhenBuildResponse> {
@@ -363,6 +523,7 @@ impl<'net> WhenRequest<'net, WhenBuildRequest> {
     }
 }
 impl<'net> WhenRequest<'net, WhenBuildResponse> {
+    /// Specifies a header that will be on the response sent for the matching request.
     #[must_use]
     pub fn header(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
         let name = name.into();
@@ -371,6 +532,7 @@ impl<'net> WhenRequest<'net, WhenBuildResponse> {
         self
     }
 
+    /// Specifies headers that will be on the response sent for the matching request.
     #[must_use]
     pub fn headers(mut self, headers: impl Into<HashMap<String, String>>) -> Self {
         let h: HashMap<String, String> = headers.into();
@@ -380,11 +542,13 @@ impl<'net> WhenRequest<'net, WhenBuildResponse> {
         self
     }
 
-    pub fn body(mut self, body: impl Into<bytes::Bytes>) {
+    /// Specifies the body of the response sent for the matching request.
+    pub fn body(mut self, body: impl Into<bytes::Bytes>) -> Result<()> {
         self.respond_with.push(RespondWith::Body(body.into()));
-        self.mock().expect("valid mock");
+        self.mock()
     }
 
+    /// Marks a response that has no body as complete.
     pub fn mock(self) -> Result<()> {
         if let Some(error) = self.error {
             return Err(crate::net::Error::InvalidMock(error));

tests/net.rs

@@ -10,23 +10,19 @@ use assert2::let_assert;
 async fn test_get_url() {
     //given
     let mock_net = kxio::net::mock();
-    let client = mock_net.client();
 
     let url = "https://www.example.com";
 
     mock_net
         .on()
-        .get("https://www.example.com")
+        .get(url)
         .respond(StatusCode::OK)
         .header("foo", "bar")
         .headers(HashMap::new())
         .body("Get OK");
 
     //when
-    let response = Net::from(mock_net)
+    let response = Net::from(mock_net).get(url).send().await.expect("response");
-        .send(client.get(url))
-        .await
-        .expect("response");
 
     //then
     assert_eq!(response.status(), http::StatusCode::OK);
@@ -41,10 +37,7 @@ async fn test_post_url() {
 
     let url = "https://www.example.com";
 
-    net.on()
+    net.on().post(url).respond(StatusCode::OK).body("post OK");
-        .post(url)
-        .respond(StatusCode::OK)
-        .body("post OK");
 
     //when
     let response = Net::from(net)
@@ -65,10 +58,7 @@ async fn test_put_url() {
 
     let url = "https://www.example.com";
 
-    net.on()
+    net.on().put(url).respond(StatusCode::OK).body("put OK");
-        .put(url)
-        .respond(StatusCode::OK)
-        .body("put OK");
 
     //when
     let response = Net::from(net).send(client.put(url)).await.expect("reponse");
@@ -110,10 +100,7 @@ async fn test_head_url() {
 
     let url = "https://www.example.com";
 
-    net.on()
+    net.on().head(url).respond(StatusCode::OK).body("head OK");
-        .head(url)
-        .respond(StatusCode::OK)
-        .body("head OK");
 
     //when
     let response = Net::from(net)
@@ -134,10 +121,7 @@ async fn test_patch_url() {
 
     let url = "https://www.example.com";
 
-    net.on()
+    net.on().patch(url).respond(StatusCode::OK).body("patch OK");
-        .patch(url)
-        .respond(StatusCode::OK)
-        .body("patch OK");
 
     //when
     let response = Net::from(net)
@@ -158,10 +142,7 @@ async fn test_get_wrong_url() {
 
     let url = "https://www.example.com";
 
-    net.on()
+    net.on().get(url).respond(StatusCode::OK).body("Get OK");
-        .get(url)
-        .respond(StatusCode::OK)
-        .body("Get OK");
 
     let net = Net::from(net);