chore: prepare initial crate release (#14)

Maciek · Maciej Wójcik · Adam Ciarciński · web-flow · commit df5fcc244623 · 2023-10-02T15:29:04.000+02:00
* update crate metadata

* update readme

* update docs

* add a release workflow

* bump version

---------

Co-authored-by: Maciej Wójcik &lt;wojcik91@gmail.com&gt;
Co-authored-by: Adam Ciarciński &lt;aciarcinski@teonite.com&gt;
diff --git a/.github/release.yml b/.github/release.yml
@@ -0,0 +1,16 @@
+changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+  categories:
+    - title: Breaking Changes 🛠
+      labels:
+        - Semver-Major
+        - breaking-change
+    - title: Exciting New Features 🎉
+      labels:
+        - Semver-Minor
+        - enhancement
+    - title: Other Changes
+      labels:
+        - "*"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,18 @@
+name: Create a new GitHub release
+on:
+  push:
+    tags:
+      - v*.*.*
+
+jobs:
+  create-release:
+    runs-on: self-hosted
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Create release
+        uses: softprops/action-gh-release@v1
+        if: startsWith(github.ref, 'refs/tags/')
+        with:
+          draft: true
+          generate_release_notes: true
diff --git a/.gitignore b/.gitignore
@@ -1 +1,2 @@
 /target
+.idea/
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,8 +1,14 @@
 [package]
-name = "wireguard_rs"
-version = "0.1.0"
+name = "defguard_wireguard_rs"
+version = "0.2.0"
 edition = "2021"
-
+description = "A unified multi-platform high-level API for managing WireGuard interfaces"
+license = "Apache-2.0"
+readme = "README.md"
+homepage = "https://github.com/DefGuard/wireguard-rs"
+repository = "https://github.com/DefGuard/wireguard-rs"
+keywords = ["wireguard", "network", "vpn"]
+categories = ["network-programming"]
 
 [dependencies]
 base64 = "0.21"
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
     <img src="docs/header.png" alt="defguard">
  </p>
 
-**wireguard-rs** is a Rust library providing a unified high-level API for managing WireGuard interfaces using native OS kernel and userspace WireGuard protocol implementations.
+**defguard_wireguard_rs** is a multi-platform Rust library providing a unified high-level API for managing WireGuard interfaces using native OS kernel and userspace WireGuard protocol implementations.
 It can be used to create your own [WireGuard:tm:](https://www.wireguard.com/) VPN servers or clients for secure and private networking.
 
 It was developed as part of [defguard](https://github.com/defguard/defguard) security platform and used in the [gateway/server](https://github.com/defguard/gateway) as well as [desktop client](https://github.com/defguard/client).
@@ -18,6 +18,11 @@ It was developed as part of [defguard](https://github.com/defguard/defguard) sec
   - macOS
   - FreeBSD
 
+### Note on `wireguard-go`
+If you intend to use the userspace WireGuard implementation you should note that currently the library assumes 
+that the `wireguard-go` binary will be available at runtime. There are some sanity checks when instantiating the API, 
+but installing it is outside the scope of this project.
+
 ## Examples
 
 * Client: https://github.com/DefGuard/wireguard-rs/blob/main/examples/client.rs
diff --git a/docs/header.png b/docs/header.png
diff --git a/examples/client.rs b/examples/client.rs
@@ -1,7 +1,7 @@
 use std::{net::SocketAddr, str::FromStr};
 
-use wireguard_rs::{
-    wgapi::WGApi, InterfaceConfiguration, IpAddrMask, Key, Peer, WireguardInterfaceApi,
+use defguard_wireguard_rs::{
+    host::Peer, key::Key, net::IpAddrMask, InterfaceConfiguration, WGApi, WireguardInterfaceApi,
 };
 use x25519_dalek::{EphemeralSecret, PublicKey};
 
diff --git a/examples/server.rs b/examples/server.rs
@@ -1,7 +1,7 @@
 use std::str::FromStr;
 
-use wireguard_rs::{
-    wgapi::WGApi, InterfaceConfiguration, IpAddrMask, Key, Peer, WireguardInterfaceApi,
+use defguard_wireguard_rs::{
+    host::Peer, key::Key, net::IpAddrMask, InterfaceConfiguration, WGApi, WireguardInterfaceApi,
 };
 use x25519_dalek::{EphemeralSecret, PublicKey};
 
diff --git a/examples/userspace.rs b/examples/userspace.rs
@@ -1,11 +1,12 @@
+use defguard_wireguard_rs::{
+    host::Peer, key::Key, net::IpAddrMask, InterfaceConfiguration, WireguardApiUserspace,
+    WireguardInterfaceApi,
+};
 use std::{
     io::{stdin, stdout, Read, Write},
     net::SocketAddr,
     str::FromStr,
 };
-use wireguard_rs::{
-    InterfaceConfiguration, IpAddrMask, Key, Peer, WireguardApiUserspace, WireguardInterfaceApi,
-};
 use x25519_dalek::{EphemeralSecret, PublicKey};
 
 fn pause() {
diff --git a/src/bsd/nvlist.rs b/src/bsd/nvlist.rs
@@ -1,5 +1,5 @@
-// https://github.com/freebsd/freebsd-src/tree/main/sys/contrib/libnv
-// https://github.com/freebsd/freebsd-src/blob/main/sys/sys/nv.h
+//! `nvlist` implementation in Rust.
+
 use std::{error::Error, ffi::CStr, fmt};
 
 /// `NV_HEADER_SIZE` is for both: `nvlist_header` and `nvpair_header`.
diff --git a/src/error.rs b/src/error.rs
@@ -1,3 +1,5 @@
+//! Interface management errors
+
 use thiserror::Error;
 
 #[derive(Debug, Error)]
diff --git a/src/host.rs b/src/host.rs
@@ -1,3 +1,5 @@
+//! Host interface configuration
+
 use std::{
     collections::HashMap,
     io::{self, BufRead, BufReader, Read},
@@ -14,6 +16,7 @@ use netlink_packet_wireguard::{
 
 use crate::{key::Key, net::IpAddrMask};
 
+/// WireGuard peer representation.
 #[derive(Debug, Default, PartialEq, Clone)]
 pub struct Peer {
     pub public_key: Key,
@@ -28,6 +31,7 @@ pub struct Peer {
 }
 
 impl Peer {
+    /// Create new `Peer` with a given `public_key`.
     #[must_use]
     pub fn new(public_key: Key) -> Self {
         Self {
@@ -153,6 +157,7 @@ impl Peer {
     }
 }
 
+/// WireGuard host representation.
 #[derive(Debug, Default)]
 pub struct Host {
     pub listen_port: u16,
@@ -162,6 +167,7 @@ pub struct Host {
 }
 
 impl Host {
+    /// Create new `Host` with a given `listen_port` and `private_key`.
     #[must_use]
     pub fn new(listen_port: u16, private_key: Key) -> Self {
         Self {
diff --git a/src/key.rs b/src/key.rs
@@ -1,3 +1,5 @@
+//! Public key utilities
+
 use std::{
     error, fmt,
     hash::{Hash, Hasher},
@@ -8,6 +10,7 @@ use base64::{prelude::BASE64_STANDARD, DecodeError, Engine};
 
 const KEY_LENGTH: usize = 32;
 
+/// WireGuard key representation in binary form.
 #[derive(Clone, Default)]
 pub struct Key([u8; KEY_LENGTH]);
 
@@ -31,6 +34,7 @@ impl fmt::Display for KeyError {
 }
 
 impl Key {
+    /// Create a new key from buffer.
     #[must_use]
     pub fn new(buf: [u8; KEY_LENGTH]) -> Self {
         Self(buf)
@@ -46,6 +50,7 @@ impl Key {
         self.0.as_slice()
     }
 
+    /// Converts `Key` to `String` of lower case hexadecimal digits.
     #[must_use]
     pub fn to_lower_hex(&self) -> String {
         let mut hex = String::with_capacity(64);
@@ -62,6 +67,11 @@ impl Key {
         hex
     }
 
+    /// Converts a text string of hexadecimal digits to `Key`.
+    ///
+    /// # Errors
+    /// Will return `KeyError` if text string has wrong length,
+    /// or contains an invalid character.
     pub fn decode<T: AsRef<[u8]>>(hex: T) -> Result<Self, KeyError> {
         let hex = hex.as_ref();
         let length = hex.len();
diff --git a/src/lib.rs b/src/lib.rs
@@ -1,3 +1,54 @@
+//! # `defguard_wireguard_rs`
+//!
+//! `defguard_wireguard_rs` is a multi-platform Rust library providing a unified high-level API
+//! for managing WireGuard interfaces using native OS kernel and userspace WireGuard protocol implementations.
+//!
+//! It can be used to create your own [WireGuard:tm:](https://www.wireguard.com/) VPN servers or clients for secure and private networking.
+//!
+//! It was developed as part of [defguard](https://github.com/defguard/defguard) security platform and used in the [gateway/server](https://github.com/defguard/gateway) as well as [desktop client](https://github.com/defguard/client).
+//!
+//! ## Example
+//!
+//! ```no_run
+//! use x25519_dalek::{EphemeralSecret, PublicKey};
+//! use defguard_wireguard_rs::{InterfaceConfiguration, WGApi, WireguardInterfaceApi, host::Peer};
+//! # use defguard_wireguard_rs::error::WireguardInterfaceError;
+//!
+//! // Create new API struct for interface
+//! let ifname: String = if cfg!(target_os = "linux") || cfg!(target_os = "freebsd") {
+//!     "wg0".into()
+//! } else {
+//!     "utun3".into()
+//! };
+//! let wgapi = WGApi::new(ifname.clone(), false)?;
+//!
+//! // Create host interfaces
+//! wgapi.create_interface()?;
+//!
+//! // Configure host interface
+//! let interface_config = InterfaceConfiguration {
+//!     name: ifname.clone(),
+//!     prvkey: "AAECAwQFBgcICQoLDA0OD/Dh0sO0pZaHeGlaSzwtHg8=".to_string(),
+//!     address: "10.6.0.30".to_string(),
+//!     port: 12345,
+//!     peers: vec![],
+//! };
+//! wgapi.configure_interface(&interface_config)?;
+//!
+//! // Create, add & remove peers
+//! for _ in 0..32 {
+//!     let secret = EphemeralSecret::random();
+//!     let key = PublicKey::from(&secret);
+//!     let peer = Peer::new(key.as_ref().try_into().unwrap());
+//!     wgapi.configure_peer(&peer)?;
+//!     wgapi.remove_peer(&peer.public_key)?;
+//! }
+//!
+//! // Remove host interface
+//! wgapi.remove_interface()?;
+//! # Ok::<(), WireguardInterfaceError>(())
+//! ```
+
 #[cfg(target_os = "freebsd")]
 pub mod bsd;
 pub mod error;
@@ -6,7 +57,7 @@ pub mod key;
 pub mod net;
 #[cfg(target_os = "linux")]
 pub mod netlink;
-pub mod wgapi;
+mod wgapi;
 
 #[cfg(target_os = "freebsd")]
 mod wgapi_freebsd;
@@ -21,23 +72,24 @@ extern crate log;
 
 use std::process::Output;
 
-// public reexports
+use self::{
+    error::WireguardInterfaceError,
+    host::{Host, Peer},
+    key::Key,
+    net::IpAddrMask,
+};
+
+// public re-exports
+pub use wgapi::WGApi;
 #[cfg(target_os = "freebsd")]
 pub use wgapi_freebsd::WireguardApiFreebsd;
 #[cfg(target_os = "linux")]
 pub use wgapi_linux::WireguardApiLinux;
 #[cfg(target_family = "unix")]
 pub use wgapi_userspace::WireguardApiUserspace;
-pub use {
-    self::error::WireguardInterfaceError,
-    host::{Host, Peer},
-    key::Key,
-    net::{IpAddrMask, IpAddrParseError},
-    wgapi::WGApi,
-    wireguard_interface::WireguardInterfaceApi,
-};
+pub use wireguard_interface::WireguardInterfaceApi;
 
-/// Wireguard Interface configuration
+/// Host WireGuard interface configuration
 #[derive(Debug, Clone)]
 pub struct InterfaceConfiguration {
     pub name: String,
@@ -63,8 +115,8 @@ impl TryFrom<&InterfaceConfiguration> for Host {
     }
 }
 
-/// Util function which checks external command output status.
-pub fn check_command_output_status(output: Output) -> Result<(), WireguardInterfaceError> {
+/// Utility function which checks external command output status.
+fn check_command_output_status(output: Output) -> Result<(), WireguardInterfaceError> {
     if !output.status.success() {
         let stdout = String::from_utf8(output.stdout).expect("Invalid UTF8 sequence in stdout");
         let stderr = String::from_utf8(output.stderr).expect("Invalid UTF8 sequence in stderr");
diff --git a/src/net.rs b/src/net.rs
diff --git a/src/netlink.rs b/src/netlink.rs
diff --git a/src/wgapi.rs b/src/wgapi.rs
diff --git a/src/wgapi_userspace.rs b/src/wgapi_userspace.rs
