docs(example): get and save

Cargo.toml

@@ -15,9 +15,9 @@ unexpected_cfgs = { level = "warn", check-cfg = ['cfg(tarpaulin_include)'] }
 
 [dependencies]
 derive_more = { version = "1.0", features = [ 
-  "from", 
+  "constructor",
   "display", 
-  "constructor" 
+  "from" 
 ] }
 http = "1.1"
 path-clean = "1.0"
@@ -28,7 +28,10 @@ tempfile = "3.10"
 assert2 = "0.3"
 pretty_assertions = "1.4"
 test-log = "0.2"
-tokio = { version = "1.41", features = ["macros"] }
+tokio = { version = "1.41", features = [
+  "macros",
+  "rt-multi-thread"
+] }
 tokio-test = "0.4"
 
 [package.metadata.bin]

examples/get.rs

@@ -0,0 +1,82 @@
+// example to show fetching a URL and saving to a file
+
+use std::path::Path;
+
+#[tokio::main]
+async fn main() -> kxio::Result<()> {
+    let net = kxio::net::new();
+    let fs = kxio::fs::temp()?;
+
+    let url = "https://git.kemitix.net/kemitix/kxio/raw/branch/main/README.md";
+    let file_path = fs.base().join("README.md");
+
+    download_and_save(url, &file_path, &fs, &net).await?;
+
+    print_file(&file_path, &fs)?;
+
+    Ok(())
+}
+
+async fn download_and_save(
+    url: &str,
+    file_path: &Path,
+    fs: &kxio::fs::FileSystem,
+    net: &kxio::net::Net,
+) -> kxio::Result<()> {
+    println!("fetching: {url}");
+    let request = net.client().get(url);
+    let response = net.send(request).await?;
+    let body = response.text().await?;
+    println!("fetched {} bytes", body.bytes().len());
+
+    println!("writing file: {}", file_path.display());
+    let file = fs.file(file_path);
+    file.write(body)?;
+
+    Ok(())
+}
+
+fn print_file(file_path: &Path, fs: &kxio::fs::FileSystem) -> kxio::Result<()> {
+    println!("reading file: {}", file_path.display());
+    let file = fs.file(file_path);
+    let reader = file.reader()?;
+    let contents = reader.as_str();
+    println!("{contents}");
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn should_save_remote_body() {
+        //given
+        let net = kxio::net::mock();
+        let url = "http://localhost:8080";
+        net.on(net.client().get(url).build().expect("request"))
+            .respond(
+                net.response()
+                    .body("contents")
+                    .expect("response body")
+                    .into(),
+            )
+            .expect("mock");
+
+        let fs = kxio::fs::temp().expect("temp fs");
+        let file_path = fs.base().join("foo");
+
+        //when
+        download_and_save(url, &file_path, &fs, &net.into())
+            .await
+            .expect("system under test");
+
+        //then
+        let file = fs.file(&file_path);
+        let reader = file.reader().expect("reader");
+        let contents = reader.as_str();
+
+        assert_eq!(contents, "contents");
+    }
+}

justfile

@@ -7,6 +7,7 @@ build:
   cargo hack build
   cargo hack test
   cargo doc
+  cargo test --example get
 
 install-hooks:
   @echo "Installing git hooks"

src/net/mod.rs

@@ -7,15 +7,14 @@ mod system;
 
 pub use result::{Error, Result};
 
-pub use system::{MatchOn, Net};
+pub use system::{MatchOn, MockNet, Net};
-use system::{Mocked, Unmocked};
 
 /// Creates a new `Net`.
-pub const fn new() -> Net<Unmocked> {
+pub const fn new() -> Net {
-    Net::<Unmocked>::new()
+    Net::new()
 }
 
 /// Creates a new `MockNet` for use in tests.
-pub fn mock() -> Net<Mocked> {
+pub fn mock() -> MockNet {
-    Net::<Mocked>::new()
+    Net::mock()
 }

src/net/result.rs

@@ -1,5 +1,4 @@
 //
-
 use derive_more::derive::From;
 
 /// Represents a error accessing the network.
@@ -9,14 +8,14 @@ pub enum Error {
     Request(String),
     #[display("Unexpected request: {0}", 0.to_string())]
     UnexpectedMockRequest(reqwest::Request),
+    RwLockLocked,
 }
 impl std::error::Error for Error {}
 impl Clone for Error {
     fn clone(&self) -> Self {
         match self {
             Self::Reqwest(req) => Self::Request(req.to_string()),
-            Self::Request(req) => Self::Request(req.clone()),
+            err => err.clone(),
-            Self::UnexpectedMockRequest(_) => todo!(),
         }
     }
 }

src/net/system.rs

@@ -1,12 +1,15 @@
 //
-use std::marker::PhantomData;
+use std::{marker::PhantomData, ops::Deref, sync::RwLock};
 
 use super::{Error, Result};
 
 pub trait NetType {}
 
+#[derive(Debug)]
 pub struct Mocked;
 impl NetType for Mocked {}
+
+#[derive(Debug)]
 pub struct Unmocked;
 impl NetType for Unmocked {}
 
@@ -21,44 +24,101 @@ pub enum MatchOn {
 }
 
 #[derive(Debug)]
-pub struct Plan {
+struct Plan {
     request: reqwest::Request,
     response: reqwest::Response,
     match_on: Vec<MatchOn>,
 }
 
-pub struct Net<T: NetType> {
+#[derive(Debug)]
-    _type: PhantomData<T>,
+pub struct Net {
-    plans: Plans,
+    inner: InnerNet<Unmocked>,
+    mock: Option<InnerNet<Mocked>>,
 }
-impl Net<Unmocked> {
+impl Net {
-    pub(crate) const fn new() -> Self {
+    // constructors
+    pub(super) const fn new() -> Self {
         Self {
-            _type: PhantomData,
+            inner: InnerNet::<Unmocked>::new(),
-            plans: vec![],
+            mock: None,
         }
     }
 
-    pub async fn send(&mut self, request: reqwest::RequestBuilder) -> Result<reqwest::Response> {
+    pub(super) const fn mock() -> MockNet {
+        MockNet {
+            inner: InnerNet::<Mocked>::new(),
+        }
+    }
+}
+impl Net {
+    // public interface
+    pub fn client(&self) -> reqwest::Client {
+        self.inner.client()
+    }
+
+    pub async fn send(&self, request: reqwest::RequestBuilder) -> Result<reqwest::Response> {
+        match &self.mock {
+            Some(mock) => mock.send(request).await,
+            None => self.inner.send(request).await,
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct MockNet {
+    inner: InnerNet<Mocked>,
+}
+impl Deref for MockNet {
+    type Target = InnerNet<Mocked>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.inner
+    }
+}
+impl From<MockNet> for Net {
+    fn from(mock_net: MockNet) -> Self {
+        Self {
+            inner: InnerNet::<Unmocked>::new(),
+            mock: Some(mock_net.inner),
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct InnerNet<T: NetType> {
+    _type: PhantomData<T>,
+    plans: RwLock<Plans>,
+}
+impl InnerNet<Unmocked> {
+    const fn new() -> Self {
+        Self {
+            _type: PhantomData,
+            plans: RwLock::new(vec![]),
+        }
+    }
+
+    pub async fn send(&self, request: reqwest::RequestBuilder) -> Result<reqwest::Response> {
         request.send().await.map_err(Error::from)
     }
 }
 
-impl<T: NetType> Net<T> {
+impl<T: NetType> InnerNet<T> {
     pub fn client(&self) -> reqwest::Client {
         Default::default()
     }
 }
-impl Net<Mocked> {
+impl InnerNet<Mocked> {
-    pub(crate) const fn new() -> Self {
+    const fn new() -> Self {
         Self {
             _type: PhantomData,
-            plans: vec![],
+            plans: RwLock::new(vec![]),
         }
     }
-    pub async fn send(&mut self, request: reqwest::RequestBuilder) -> Result<reqwest::Response> {
+
+    pub async fn send(&self, request: reqwest::RequestBuilder) -> Result<reqwest::Response> {
         let request = request.build()?;
-        let index = self.plans.iter().position(|plan| {
+        let read_plans = self.plans.read().map_err(|_| Error::RwLockLocked)?;
+        let index = read_plans.iter().position(|plan| {
             // METHOD
             (if plan.match_on.contains(&MatchOn::Method) {
                 plan.request.method() == request.method()
@@ -88,18 +148,22 @@ impl Net<Mocked> {
                 true
             })
         });
+        drop(read_plans);
         match index {
-            Some(i) => Ok(self.plans.remove(i).response),
+            Some(i) => {
+                let mut write_plans = self.plans.write().map_err(|_| Error::RwLockLocked)?;
+                Ok(write_plans.remove(i).response)
+            }
             None => Err(Error::UnexpectedMockRequest(request)),
         }
     }
 
-    /// Creates a [ResponseBuilder] to be extended and returned by a mocked network request.
+    /// Creates a [http::response::Builder] to be extended and returned by a mocked network request.
     pub fn response(&self) -> http::response::Builder {
         Default::default()
     }
 
-    pub fn on(&mut self, request: reqwest::Request) -> OnRequest {
+    pub fn on(&self, request: reqwest::Request) -> OnRequest {
         OnRequest {
             net: self,
             request,
@@ -108,30 +172,37 @@ impl Net<Mocked> {
     }
 
     fn _on(
-        &mut self,
+        &self,
         request: reqwest::Request,
         response: reqwest::Response,
         match_on: Vec<MatchOn>,
-    ) {
+    ) -> Result<()> {
-        self.plans.push(Plan {
+        let mut write_plans = self.plans.write().map_err(|_| Error::RwLockLocked)?;
+        write_plans.push(Plan {
             request,
             response,
             match_on,
-        })
+        });
+        Ok(())
     }
 
-    pub fn reset(&mut self) {
+    pub fn reset(&self) -> Result<()> {
-        self.plans = vec![];
+        let mut write_plans = self.plans.write().map_err(|_| Error::RwLockLocked)?;
+        write_plans.clear();
+        Ok(())
     }
 }
-impl<T: NetType> Drop for Net<T> {
+impl<T: NetType> Drop for InnerNet<T> {
     fn drop(&mut self) {
-        assert!(self.plans.is_empty())
+        let Ok(read_plans) = self.plans.read() else {
+            return;
+        };
+        assert!(read_plans.is_empty())
     }
 }
 
 pub struct OnRequest<'net> {
-    net: &'net mut Net<Mocked>,
+    net: &'net InnerNet<Mocked>,
     request: reqwest::Request,
     match_on: Vec<MatchOn>,
 }
@@ -143,7 +214,7 @@ impl<'net> OnRequest<'net> {
             match_on,
         }
     }
-    pub fn respond(self, response: reqwest::Response) {
+    pub fn respond(self, response: reqwest::Response) -> Result<()> {
         self.net._on(self.request, response, self.match_on)
     }
 }

tests/net.rs

@@ -1,11 +1,11 @@
 use assert2::let_assert;
 //
-use kxio::net::{Error, MatchOn};
+use kxio::net::{Error, MatchOn, Net};
 
 #[tokio::test]
 async fn test_get_url() {
     //given
-    let mut net = kxio::net::mock();
+    let net = kxio::net::mock();
     let client = net.client();
 
     let url = "https://www.example.com";
@@ -16,10 +16,15 @@ async fn test_get_url() {
         .body("Get OK")
         .expect("request body");
 
-    net.on(request).respond(my_response.into());
+    net.on(request)
+        .respond(my_response.into())
+        .expect("on request, respond");
 
     //when
-    let response = net.send(client.get(url)).await.expect("response");
+    let response = Net::from(net)
+        .send(client.get(url))
+        .await
+        .expect("response");
 
     //then
     assert_eq!(response.status(), http::StatusCode::OK);
@@ -29,7 +34,7 @@ async fn test_get_url() {
 #[tokio::test]
 async fn test_get_wrong_url() {
     //given
-    let mut net = kxio::net::mock();
+    let net = kxio::net::mock();
     let client = net.client();
 
     let url = "https://www.example.com";
@@ -40,7 +45,9 @@ async fn test_get_wrong_url() {
         .body("Get OK")
         .expect("request body");
 
-    net.on(request).respond(my_response.into());
+    net.on(request)
+        .respond(my_response.into())
+        .expect("on request, respond");
 
     //when
     let_assert!(
@@ -52,13 +59,13 @@ async fn test_get_wrong_url() {
     assert_eq!(invalid_request.url().to_string(), "https://some.other.url/");
 
     // remove pending unmatched request - we never meant to match against it
-    net.reset();
+    net.reset().expect("reset");
 }
 
 #[tokio::test]
 async fn test_post_url() {
     //given
-    let mut net = kxio::net::mock();
+    let net = kxio::net::mock();
     let client = net.client();
 
     let url = "https://www.example.com";
@@ -69,10 +76,15 @@ async fn test_post_url() {
         .body("Post OK")
         .expect("request body");
 
-    net.on(request).respond(my_response.into());
+    net.on(request)
+        .respond(my_response.into())
+        .expect("on request, respond");
 
     //when
-    let response = net.send(client.post(url)).await.expect("reponse");
+    let response = Net::from(net)
+        .send(client.post(url))
+        .await
+        .expect("reponse");
 
     //then
     assert_eq!(response.status(), http::StatusCode::OK);
@@ -82,7 +94,7 @@ async fn test_post_url() {
 #[tokio::test]
 async fn test_post_by_method() {
     //given
-    let mut net = kxio::net::mock();
+    let net = kxio::net::mock();
     let client = net.client();
 
     let url = "https://www.example.com";
@@ -98,11 +110,12 @@ async fn test_post_by_method() {
             MatchOn::Method,
             // MatchOn::Url
         ])
-        .respond(my_response.into());
+        .respond(my_response.into())
+        .expect("on request, respond");
 
     //when
     // This request is a different url - but should still match
-    let response = net
+    let response = Net::from(net)
         .send(client.post("https://some.other.url"))
         .await
         .expect("response");
@@ -115,7 +128,7 @@ async fn test_post_by_method() {
 #[tokio::test]
 async fn test_post_by_url() {
     //given
-    let mut net = kxio::net::mock();
+    let net = kxio::net::mock();
     let client = net.client();
 
     let url = "https://www.example.com";
@@ -131,11 +144,15 @@ async fn test_post_by_url() {
             // MatchOn::Method,
             MatchOn::Url,
         ])
-        .respond(my_response.into());
+        .respond(my_response.into())
+        .expect("on request, respond");
 
     //when
     // This request is a GET, not POST - but should still match
-    let response = net.send(client.get(url)).await.expect("response");
+    let response = Net::from(net)
+        .send(client.get(url))
+        .await
+        .expect("response");
 
     //then
     assert_eq!(response.status(), http::StatusCode::OK);
@@ -145,7 +162,7 @@ async fn test_post_by_url() {
 #[tokio::test]
 async fn test_post_by_body() {
     //given
-    let mut net = kxio::net::mock();
+    let net = kxio::net::mock();
     let client = net.client();
 
     let url = "https://www.example.com";
@@ -166,11 +183,12 @@ async fn test_post_by_body() {
             // MatchOn::Url
             MatchOn::Body,
         ])
-        .respond(my_response.into());
+        .respond(my_response.into())
+        .expect("on request, respond");
 
     //when
     // This request is a GET, not POST - but should still match
-    let response = net
+    let response = Net::from(net)
         .send(client.get("https://some.other.url").body("match on body"))
         .await
         .expect("response");
@@ -186,7 +204,7 @@ async fn test_post_by_body() {
 #[tokio::test]
 async fn test_post_by_headers() {
     //given
-    let mut net = kxio::net::mock();
+    let net = kxio::net::mock();
     let client = net.client();
 
     let url = "https://www.example.com";
@@ -208,11 +226,12 @@ async fn test_post_by_headers() {
             // MatchOn::Url
             MatchOn::Headers,
         ])
-        .respond(my_response.into());
+        .respond(my_response.into())
+        .expect("on request, respond");
 
     //when
     // This request is a GET, not POST - but should still match
-    let response = net
+    let response = Net::from(net)
         .send(
             client
                 .get("https://some.other.url")
@@ -234,7 +253,7 @@ async fn test_post_by_headers() {
 #[should_panic]
 async fn test_unused_post() {
     //given
-    let mut net = kxio::net::mock();
+    let net = kxio::net::mock();
     let client = net.client();
 
     let url = "https://www.example.com";
@@ -245,11 +264,13 @@ async fn test_unused_post() {
         .body("Post OK")
         .expect("request body");
 
-    net.on(request).respond(my_response.into());
+    net.on(request)
+        .respond(my_response.into())
+        .expect("on request, respond");
 
     //when
     // don't send the planned request
-    // let _response = net.send(client.post(url)).await.expect("send");
+    // let _response = Net::from(net).send(client.post(url)).await.expect("send");
 
     //then
     // Drop implementation for net should panic