Initial commit

Author: brummer-simon

Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "reachable"
+version = "0.2.0"
+edition = "2021"
+authors = ["Simon Brummer <[email protected]>"]
+description = "Check if a Target (ICMP, TCP, custom) is reachable."
+license = "MPL-2.0"
+readme = "README.md"
+repository = "https://github.com/brummer-simon/reachable.git"
+keywords = ["network", "async"]
+categories = ["network-programming"]
+
+[dependencies]
+dns-lookup = {version = "1.0.7"}
+futures    = {version = "0.3.17", optional = true}
+tokio      = {version = "1.12.0", optional = true, features = ["rt-multi-thread", "sync", "time", "macros"]}
+
+[dev-dependencies]
+mockall = {version = "0.10.2"}
+
+[features]
+default = ["async"]
+async   = ["futures", "tokio"]
+
+[workspace]
+members = [
+    "examples/usage",
+    "examples/async_usage",
+    "examples/async_usage_custom_target",
+]

LICENSE

@@ -1,2 +1,47 @@
 # reachable
-Rust crate to check if a system is reachable over the network. 
+
+Rust crate to check if a "Target" is available. The crate comes with the trait
+"Target" and ICMP/TCP based implementations of it. Additionally, the crate offers
+an async task Executor to perform availability checks of "Targets" on a regular basis.
+
+## Usage
+
+With this crate you can easily check if a computer is currently reachable over the network.
+Since all targets are implementations of trait "Target" the entire behavior is customizable.
+For example, it is easy to implement a custom Target to check if a Process is
+running or not.
+
+## Example (from examples/async_usage/src/main.rs)
+
+```rust
+use std::str::FromStr;
+use std::thread::sleep;
+use std::time::Duration;
+
+use reachable::*;
+
+fn main() {
+    // Setup AsyncTargets
+    let icmp_target = IcmpTarget::from_str("www.google.de").unwrap();
+    let tcp_target = TcpTarget::from_str("www.google.de:80").unwrap();
+
+    let handler = |target: &dyn Target, status, old_status, error| {
+        print!("Target \"{}\"", target.get_id());
+        print!(", old status \"{}\"", old_status);
+        print!(", new status \"{}\"", status);
+        match error {
+            None => println!(""),
+            Some(err) => println!(", Error: \"{}\"", err),
+        }
+    };
+
+    // Spawn Async executor
+    let mut exec = AsyncTargetExecutor::new();
+    exec.start(vec![
+        AsyncTarget::from((icmp_target, handler, Duration::from_secs(1))),
+        AsyncTarget::from((tcp_target, handler, Duration::from_secs(1))),
+    ]);
+    sleep(Duration::from_secs(3));
+    exec.stop();
+}
+```

README.md

@@ -0,0 +1,10 @@
+[package]
+name = "async_usage"
+version = "0.1.0"
+edition = "2021"
+authors = ["Simon Brummer <[email protected]>"]
+license = "MPL-2.0"
+description = "Example: async usage of reachable"
+
+[dependencies]
+reachable = {path = "../..", features = ["async"]}

examples/async_usage/Cargo.toml

@@ -0,0 +1,36 @@
+use std::str::FromStr;
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+//
+// Author: Simon Brummer ([email protected])
+
+use std::thread::sleep;
+use std::time::Duration;
+
+use reachable::*;
+
+fn main() {
+    // Setup AsyncTargets
+    let icmp_target = IcmpTarget::from_str("www.google.de").unwrap();
+    let tcp_target = TcpTarget::from_str("www.google.de:80").unwrap();
+
+    let handler = |target: &dyn Target, status, old_status, error| {
+        print!("Target \"{}\"", target.get_id());
+        print!(", old status \"{}\"", old_status);
+        print!(", new status \"{}\"", status);
+        match error {
+            None => println!(""),
+            Some(err) => println!(", Error: \"{}\"", err),
+        }
+    };
+
+    // Spawn Async executor
+    let mut exec = AsyncTargetExecutor::new();
+    exec.start(vec![
+        AsyncTarget::from((icmp_target, handler, Duration::from_secs(1))),
+        AsyncTarget::from((tcp_target, handler, Duration::from_secs(1))),
+    ]);
+    sleep(Duration::from_secs(3));
+    exec.stop();
+}

examples/async_usage/src/main.rs

@@ -0,0 +1,10 @@
+[package]
+name = "async_usage_custom_target"
+version = "0.1.0"
+edition = "2021"
+authors = ["Simon Brummer <[email protected]>"]
+license = "MPL-2.0"
+description = "Example: async usage of reachable with custom target"
+
+[dependencies]
+reachable = {path = "../..", features = ["async"]}

examples/async_usage_custom_target/Cargo.toml

@@ -0,0 +1,42 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+//
+// Author: Simon Brummer ([email protected])
+
+use std::thread::sleep;
+use std::time::Duration;
+
+use reachable::*;
+
+struct MyTarget;
+
+// Implement trait Target for custom type
+impl Target for MyTarget {
+    fn get_id(&self) -> String {
+        String::from("MyTarget")
+    }
+
+    fn check_availability(&self) -> Result<Status, CheckTargetError> {
+        Ok(Status::Available)
+    }
+}
+
+fn main() {
+    // Setup custom Target for async availability check execution
+    let my_target = MyTarget {};
+
+    let handler = |target: &dyn Target, status, old_status, _error| {
+        print!("Target \"{}\"", target.get_id());
+        print!(", old status \"{}\"", old_status);
+        println!(", new status \"{}\"", status);
+    };
+
+    let targets = vec![AsyncTarget::from((my_target, handler, Duration::from_secs(1)))];
+
+    // Spawn async executor
+    let mut exec = AsyncTargetExecutor::new();
+    exec.start(targets);
+    sleep(Duration::from_secs(3));
+    exec.stop();
+}

examples/async_usage_custom_target/src/main.rs

@@ -0,0 +1,10 @@
+[package]
+name = "usage"
+version = "0.1.0"
+edition = "2021"
+authors = ["Simon Brummer <[email protected]>"]
+license = "MPL-2.0"
+description = "Example: usage of reachable"
+
+[dependencies]
+reachable = {path = "../.."}

examples/usage/Cargo.toml

@@ -0,0 +1,18 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+//
+// Author: Simon Brummer ([email protected])
+
+use std::str::FromStr;
+
+use reachable::*;
+
+fn main() {
+    // Construct ICMP Target and if its availability
+    let icmp_target = IcmpTarget::from_str("www.google.de").unwrap();
+    match icmp_target.check_availability() {
+        Ok(status) => println!("{} is {}", icmp_target.get_id(), status),
+        Err(error) => println!("Check failed for {} reason {}", icmp_target.get_id(), error),
+    }
+}

examples/usage/src/main.rs

@@ -0,0 +1,18 @@
+# General formatting
+max_width = 120
+empty_item_single_line = false
+struct_lit_single_line = false
+
+# Comment related
+comment_width = 120
+wrap_comments = true
+normalize_comments = true
+
+# Import related
+reorder_imports = true
+group_imports = "StdExternalCrate"
+imports_granularity = "Module"
+
+# Warning related
+report_fixme = "Always"
+report_todo = "Always"