dinio_sdk/api/

client_identities.rs

//! `/api/v1/client-identities` (`../core/src/api/client_identities.ts`). An identity is
//! owned by the user who created it (`../core/src/api/ownership.ts`).

use reqwest::Method;
use serde::Serialize;
use uuid::Uuid;

use crate::client::Client;
use crate::error::{Error, Result};
use crate::models::{ClientIdentity, ClientIdentityPatch, NewClientIdentity};

/// Optional filters for [`ClientIdentities::list`].
#[derive(Debug, Clone, Default, Serialize)]
pub struct ClientIdentityFilter {
    /// Only the identity with this uuid.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub uuid: Option<Uuid>,
    /// Only the identity with exactly this `identify` value.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub identify: Option<String>,
}

/// Client identity routes, from [`Client::client_identities`].
///
/// With a personal key you see and change only your own identities (all of them as an
/// Admin). A zone key has no access: every route answers
/// [`ErrorCode::Forbidden`](crate::ErrorCode::Forbidden).
pub struct ClientIdentities<'a> {
    client: &'a Client,
}

impl<'a> ClientIdentities<'a> {
    pub(crate) fn new(client: &'a Client) -> Self {
        Self { client }
    }

    /// The caller's identities, all at once (Core does not paginate them).
    ///
    /// `GET /api/v1/client-identities`
    pub async fn list(&self, filter: &ClientIdentityFilter) -> Result<Vec<ClientIdentity>> {
        let request = self
            .client
            .request(Method::GET, &["client-identities"])?
            .query(filter);
        Ok(self.client.send(request).await?.0)
    }

    /// One identity, by uuid or by its `identify` value (e.g. `203.0.113.10`).
    ///
    /// `GET /api/v1/client-identities/:ref`
    ///
    /// # Errors
    ///
    /// * [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such identity.
    /// * [`ErrorCode::Forbidden`](crate::ErrorCode::Forbidden) if it belongs to another
    ///   user.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # async fn example(client: &dinio_sdk::Client) -> dinio_sdk::Result<()> {
    /// let identity = client.client_identities().get("203.0.113.10").await?;
    /// println!("{} is {}", identity.identify, identity.uuid);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn get(&self, identity: &str) -> Result<ClientIdentity> {
        let request = self
            .client
            .request(Method::GET, &["client-identities", identity])?;
        Ok(self.client.send(request).await?.0)
    }

    /// Creates an identity owned by the caller; Relay starts recognising the client. For
    /// `Hostname`/`Path` the returned identity carries the `identify` Core generated.
    ///
    /// `POST /api/v1/client-identities`
    ///
    /// # Errors
    ///
    /// * [`Error::InvalidInput`] if `identify` is given for `Hostname`/`Path`, or missing
    ///   for `Ip`/`None` (checked before sending).
    /// * [`ErrorCode::Conflict`](crate::ErrorCode::Conflict) if the IP address is already
    ///   in use, by anyone.
    /// * [`ErrorCode::Validation`](crate::ErrorCode::Validation) if `identify` is not an IP
    ///   address.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use dinio_sdk::models::{ClientIdentityType, NewClientIdentity};
    ///
    /// # async fn example(client: &dinio_sdk::Client) -> dinio_sdk::Result<()> {
    /// let new = NewClientIdentity {
    ///     identify: None,
    ///     id_type: ClientIdentityType::Path,
    ///     name: Some("phone".into()),
    /// };
    /// let identity = client.client_identities().create(&new).await?;
    /// println!("DoH path part: {}", identity.identify);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn create(&self, identity: &NewClientIdentity) -> Result<ClientIdentity> {
        match (identity.id_type.generates_identify(), &identity.identify) {
            (true, Some(_)) => {
                return Err(Error::InvalidInput(format!(
                    "Core generates identify for a {} identity; leave it out",
                    identity.id_type
                )));
            }
            (false, None) => {
                return Err(Error::InvalidInput(format!(
                    "a {} identity needs identify (the client's IP address)",
                    identity.id_type
                )));
            }
            _ => {}
        }
        let request = self
            .client
            .request(Method::POST, &["client-identities"])?
            .json(identity);
        Ok(self.client.send(request).await?.0)
    }

    /// Changes an identity; fields left `None` stay as they are.
    ///
    /// `PATCH /api/v1/client-identities/:uuid`
    ///
    /// # Errors
    ///
    /// * [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such identity.
    /// * [`ErrorCode::Forbidden`](crate::ErrorCode::Forbidden) if it belongs to another
    ///   user.
    /// * [`ErrorCode::Suspended`](crate::ErrorCode::Suspended) if the identity or its
    ///   owner is suspended.
    /// * [`ErrorCode::Conflict`](crate::ErrorCode::Conflict) if the new `identify` is in
    ///   use.
    /// * [`ErrorCode::Validation`](crate::ErrorCode::Validation) if the result would not
    ///   pair `identify` and `id_type` correctly (see [`ClientIdentityPatch`]).
    pub async fn update(&self, uuid: Uuid, patch: &ClientIdentityPatch) -> Result<ClientIdentity> {
        let request = self
            .client
            .request(Method::PATCH, &["client-identities", &uuid.to_string()])?
            .json(patch);
        Ok(self.client.send(request).await?.0)
    }

    /// Replaces the generated `identify` of a `Hostname`/`Path` identity with a new one.
    /// The old value stops working on Relay, so every device configured with it needs the
    /// new one.
    ///
    /// `POST /api/v1/client-identities/:uuid/identify`
    ///
    /// # Errors
    ///
    /// * [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such identity.
    /// * [`ErrorCode::Forbidden`](crate::ErrorCode::Forbidden) if it belongs to another
    ///   user.
    /// * [`ErrorCode::Suspended`](crate::ErrorCode::Suspended) if the identity or its
    ///   owner is suspended.
    /// * [`ErrorCode::Validation`](crate::ErrorCode::Validation) for an `Ip`/`None`
    ///   identity, whose `identify` is an address, not generated.
    pub async fn regenerate_identify(&self, uuid: Uuid) -> Result<ClientIdentity> {
        let request = self.client.request(
            Method::POST,
            &["client-identities", &uuid.to_string(), "identify"],
        )?;
        Ok(self.client.send(request).await?.0)
    }

    /// Deletes an identity.
    ///
    /// `DELETE /api/v1/client-identities/:uuid`
    ///
    /// # Errors
    ///
    /// * [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such identity.
    /// * [`ErrorCode::Forbidden`](crate::ErrorCode::Forbidden) if it belongs to another
    ///   user.
    /// * [`ErrorCode::Conflict`](crate::ErrorCode::Conflict) while sinkhole lists are
    ///   linked to it; remove the links first
    ///   ([`SinkholeLinks::delete`](crate::api::SinkholeLinks::delete)).
    pub async fn delete(&self, uuid: Uuid) -> Result<()> {
        let request = self
            .client
            .request(Method::DELETE, &["client-identities", &uuid.to_string()])?;
        self.client.send_empty(request).await
    }
}