feat(network-group): introduce Network Group API

Author: b4D8

src/v4/mod.rs

@@ -5,8 +5,10 @@
 mod error;
 pub use error::HttpError;
 
-pub type ErrorResponse = oauth10a::rest::ErrorResponse<HttpError>;
+pub type ErrorResponse = oauth10a::rest::ErrorResponse<Box<HttpError>>;
 
 pub mod addon_provider;
 pub mod functions;
+#[cfg(feature = "network-group")]
+pub mod network_group;
 pub mod products;

src/v4/network_group/delete.rs

@@ -0,0 +1,39 @@
+use oauth10a::rest::RestClient;
+
+use crate::{Client, EndpointError, RestError, v4::ErrorResponse};
+
+use super::{OwnerId, network_group_id::NetworkGroupId, peer::PeerId};
+
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    #[error(transparent)]
+    Endpoint(#[from] EndpointError),
+    #[error("failed to delete for owner '{0}', network group '{1}', peer id '{2}', {0}")]
+    Delete(String, NetworkGroupId, PeerId, RestError),
+    #[error(transparent)]
+    Status(#[from] ErrorResponse),
+}
+
+pub async fn delete(
+    client: &Client,
+    owner_id: &OwnerId,
+    ng_id: &NetworkGroupId,
+    peer_id: PeerId,
+) -> Result<(), Error> {
+    let endpoint = client.endpoint(format_args!(
+        "/v4/networkgroups/organisations/{owner_id}/networkgroups/{ng_id}/external-peers/{peer_id}"
+    ))?;
+
+    debug!(
+        %endpoint,
+        owner = %owner_id,
+        network_group = %ng_id,
+        peer = %peer_id,
+        "execute a request to delete peer from Network Group"
+    );
+
+    Ok(client
+        .delete(endpoint)
+        .await
+        .map_err(|e| Error::Delete(owner_id.to_owned(), *ng_id, peer_id, e))??)
+}

src/v4/network_group/mod.rs

@@ -0,0 +1,15 @@
+//! # Network Group module
+//!
+//! This module provide structures and helpers to interact with Clever Cloud's
+//! Network Group API.
+
+pub type MemberId = String;
+
+pub type OwnerId = String;
+
+pub mod delete;
+pub mod network_group_id;
+pub mod peer;
+pub mod wannabe_external_peer;
+pub mod wireguard;
+pub mod wireguard_configuration;

src/v4/network_group/network_group_id.rs

@@ -0,0 +1,80 @@
+use core::{fmt, str};
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+// NETWORK GROUP ID PARSE ERROR ////////////////////////////////////////////////
+
+#[derive(Debug, thiserror::Error)]
+enum NetworkGroupIdParseErrorKind {
+    #[error("expected `ng_` prefix")]
+    MissingPrefix,
+    #[error("invalid UUID, {0}")]
+    Uuid(uuid::Error),
+}
+
+#[derive(Debug, thiserror::Error)]
+#[error("invalid network group identifier: {kind}")]
+pub struct NetworkGroupIdParseError {
+    kind: NetworkGroupIdParseErrorKind,
+}
+
+// NETWORK GROUP ID ////////////////////////////////////////////////////////////
+
+/// A network group identifier.
+///
+/// It is represented as an hyphenate lowercased UUID prefixed with `ng_`.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct NetworkGroupId(Uuid);
+
+impl NetworkGroupId {
+    /// Returns the name of the file in which the peer identifier is stored.
+    pub fn ng_info_file_name(&self) -> PathBuf {
+        PathBuf::from(self.to_string()).with_extension("id")
+    }
+
+    /// Returns the associated Wireguard interface name.
+    pub fn wg_interface_name(&self) -> String {
+        let time_low = &self.0.to_string()[..8];
+        format!("wgcc{time_low}")
+    }
+}
+
+impl str::FromStr for NetworkGroupId {
+    type Err = NetworkGroupIdParseError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.strip_prefix("ng_") {
+            Some(s) => match s.parse::<uuid::fmt::Hyphenated>() {
+                Ok(hyphenated) => Ok(Self(hyphenated.into_uuid())),
+                Err(e) => Err(NetworkGroupIdParseError {
+                    kind: NetworkGroupIdParseErrorKind::Uuid(e),
+                }),
+            },
+            None => Err(NetworkGroupIdParseError {
+                kind: NetworkGroupIdParseErrorKind::MissingPrefix,
+            }),
+        }
+    }
+}
+
+impl fmt::Display for NetworkGroupId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "ng_{}", self.0.as_hyphenated())
+    }
+}
+
+impl<'de> Deserialize<'de> for NetworkGroupId {
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        String::deserialize(deserializer)?
+            .parse()
+            .map_err(serde::de::Error::custom)
+    }
+}
+
+impl Serialize for NetworkGroupId {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        self.to_string().serialize(serializer)
+    }
+}

src/v4/network_group/peer.rs

@@ -0,0 +1,126 @@
+use core::{fmt, str};
+
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+// PEER KIND ///////////////////////////////////////////////////////////////////
+
+#[derive(
+    Debug, Default, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Deserialize, Serialize,
+)]
+pub enum PeerKind {
+    #[default]
+    #[serde(rename = "CLEVER")]
+    Clever,
+    #[serde(rename = "EXTERNAL")]
+    External,
+}
+
+impl PeerKind {
+    /// Returns `true` if the peer kind is [`External`](PeerKind::External).
+    pub const fn is_external(&self) -> bool {
+        matches!(self, Self::External)
+    }
+
+    const fn prefix(self) -> Option<&'static str> {
+        match self {
+            Self::Clever => None,
+            Self::External => Some("external"),
+        }
+    }
+
+    const fn from_prefix(prefix: &str) -> Option<Self> {
+        match prefix.as_bytes() {
+            b"external" => Some(Self::External),
+            _ => None,
+        }
+    }
+}
+
+// PEER ID PARSE ERROR /////////////////////////////////////////////////////////
+
+#[derive(Debug, thiserror::Error)]
+enum PeerIdParseErrorKind {
+    #[error("unknown peer kind, {0}")]
+    PeerKind(String),
+    #[error("invalid UUID, {0}")]
+    Uuid(uuid::Error),
+}
+
+#[derive(Debug, thiserror::Error)]
+#[error("invalid peer identifier: {kind}")]
+pub struct PeerIdParseError {
+    kind: PeerIdParseErrorKind,
+}
+
+// PEER ID /////////////////////////////////////////////////////////////////////
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct PeerId {
+    peer_kind: PeerKind,
+    uuid: Uuid,
+}
+
+impl PeerId {
+    pub const fn peer_kind(&self) -> PeerKind {
+        self.peer_kind
+    }
+
+    pub const fn uuid(&self) -> &Uuid {
+        &self.uuid
+    }
+
+    pub const fn is_external(&self) -> bool {
+        self.peer_kind.is_external()
+    }
+}
+
+impl fmt::Display for PeerId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        if let Some(prefix) = self.peer_kind.prefix() {
+            write!(f, "{prefix}_")?;
+        }
+        write!(f, "{}", self.uuid.as_hyphenated())
+    }
+}
+
+impl str::FromStr for PeerId {
+    type Err = PeerIdParseError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let (s, peer_kind) = match s.split_once('_') {
+            None => (s, PeerKind::default()),
+            Some((prefix, s)) => match PeerKind::from_prefix(prefix) {
+                Some(peer_kind) => (s, peer_kind),
+                None => {
+                    return Err(PeerIdParseError {
+                        kind: PeerIdParseErrorKind::PeerKind(prefix.to_owned()),
+                    });
+                }
+            },
+        };
+        match s.parse::<uuid::fmt::Hyphenated>() {
+            Ok(hyphenated) => Ok(Self {
+                uuid: hyphenated.into_uuid(),
+                peer_kind,
+            }),
+            Err(e) => Err(PeerIdParseError {
+                kind: PeerIdParseErrorKind::Uuid(e),
+            }),
+        }
+    }
+}
+
+impl<'de> Deserialize<'de> for PeerId {
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        String::deserialize(deserializer)?
+            .parse()
+            .map_err(serde::de::Error::custom)
+    }
+}
+
+impl Serialize for PeerId {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        self.to_string().serialize(serializer)
+    }
+}

src/v4/network_group/wannabe_external_peer.rs

@@ -0,0 +1,100 @@
+use core::net::IpAddr;
+
+use oauth10a::rest::RestClient;
+use serde::{Deserialize, Serialize};
+
+use crate::{Client, EndpointError, RestError, v4::ErrorResponse};
+
+use super::{
+    MemberId, OwnerId, network_group_id::NetworkGroupId, peer::PeerId,
+    wireguard::WireGuardPublicKey,
+};
+
+// PEER ROLE ///////////////////////////////////////////////////////////////////
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PeerRole {
+    #[serde(rename = "CLIENT")]
+    Client,
+    #[serde(rename = "SERVER")]
+    Server,
+}
+
+// PEER CREATED ////////////////////////////////////////////////////////////////
+
+/// Response from [`WannabePeer`] and [`WannabeExternalPeer`] requests.
+#[derive(Debug, Deserialize)]
+pub struct PeerCreated {
+    #[serde(rename = "peerId")]
+    pub peer_id: PeerId,
+}
+
+// ERROR ///////////////////////////////////////////////////////////////////////
+
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    #[error(transparent)]
+    Endpoint(#[from] EndpointError),
+    #[error("failed to post Wannabe External Peer for owner '{0}', network group '{1}', {0}")]
+    Post(String, NetworkGroupId, RestError),
+    #[error(transparent)]
+    Status(#[from] ErrorResponse),
+}
+
+// WANNABE EXTERNAL PEER ///////////////////////////////////////////////////////
+
+/// Request to join a Network Group as an external peer.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct WannabeExternalPeer {
+    /// Label of a Network Group peer.
+    #[serde(rename = "label")]
+    pub label: String,
+    /// The public IP v4 or v6 on which the peer is listening,
+    /// when `peer_role` is [`PeerRole::Server`].
+    #[serde(rename = "ip", skip_serializing_if = "Option::is_none")]
+    pub ip: Option<IpAddr>,
+    /// The public TCP or UDP port number on which the peer is listening,
+    /// when `peer_role` is [`PeerRole::Server`].
+    #[serde(rename = "port", skip_serializing_if = "Option::is_none")]
+    pub port: Option<u16>,
+    /// The role of this peer in the Network Group.
+    #[serde(rename = "peerRole")]
+    pub peer_role: PeerRole,
+    /// Base64-encoded WireGuard public key of the peer.
+    #[serde(rename = "publicKey")]
+    pub public_key: WireGuardPublicKey,
+    /// Host name of the peer.
+    #[serde(rename = "hostname", skip_serializing_if = "Option::is_none")]
+    pub hostname: Option<String>,
+    /// Event that created the peer within the Network Group.
+    #[serde(rename = "parentEvent", skip_serializing_if = "Option::is_none")]
+    pub parent_event: Option<String>,
+    /// Unique ID of a Network Group member.
+    #[serde(rename = "parentMember")]
+    pub parent_member: MemberId,
+}
+
+impl WannabeExternalPeer {
+    pub async fn post(
+        &self,
+        client: &Client,
+        owner_id: &OwnerId,
+        ng_id: &NetworkGroupId,
+    ) -> Result<PeerCreated, Error> {
+        let endpoint = client.endpoint(format_args!(
+            "/v4/networkgroups/organisations/{owner_id}/networkgroups/{ng_id}/external-peers"
+        ))?;
+
+        debug!(
+            %endpoint,
+            owner = %owner_id,
+            network_group = %ng_id,
+            "execute a request to join Network Group"
+        );
+
+        Ok(client
+            .post(endpoint, self)
+            .await
+            .map_err(|e| Error::Post(owner_id.to_owned(), *ng_id, e))??)
+    }
+}