dinio_sdk/api/

certificates.rs

//! `/api/v1/certificates` (`../core/src/api/certificates.ts`), zone certificates only.
//! Platform certificates (no zone, `is_default`) are Admin-only and not covered.

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

use crate::api::PageRequest;
use crate::client::Client;
use crate::envelope::Page;
use crate::error::Result;
use crate::models::{Certificate, CertificateRenewal, NewCertificate};

/// Largest `per_page` Core accepts on this route (`int_query(..., 200)`).
const MAX_CERTIFICATES_PER_PAGE: u32 = 200;

#[derive(Serialize)]
struct ListQuery<'a> {
    #[serde(skip_serializing_if = "Option::is_none")]
    zone_id: Option<Uuid>,
    #[serde(skip_serializing_if = "Option::is_none")]
    name: Option<&'a str>,
    #[serde(flatten)]
    page: PageRequest,
}

/// TLS certificates of zones, from [`Client::certificates`].
///
/// Access is the zone's: its key, a member of the zone, or an Admin. Every name in a zone
/// certificate must be served by that zone. Certificates Core issues for redirects
/// (`source` = `Acme`) can be read here but not replaced or deleted.
pub struct Certificates<'a> {
    client: &'a Client,
}

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

    /// One page of the certificates of `zone_id`, or of every zone the caller can access
    /// when `None` (an Admin also sees platform certificates).
    ///
    /// `GET /api/v1/certificates[?zone_id=...]`
    ///
    /// # Errors
    ///
    /// [`ErrorCode::Forbidden`](crate::ErrorCode::Forbidden) if the caller has no access to
    /// `zone_id`.
    pub async fn list(
        &self,
        zone_id: Option<Uuid>,
        page: PageRequest,
    ) -> Result<Page<Certificate>> {
        let query = ListQuery {
            zone_id,
            name: None,
            page,
        };
        let request = self
            .client
            .request(Method::GET, &["certificates"])?
            .query(&query);
        let (items, meta) = self.client.send(request).await?;
        Ok(Page { items, meta })
    }

    /// All certificates [`list`](Self::list) would return, following pagination.
    ///
    /// `GET /api/v1/certificates`, as many times as there are pages.
    ///
    /// # Errors
    ///
    /// As [`list`](Self::list).
    pub async fn list_all(&self, zone_id: Option<Uuid>) -> Result<Vec<Certificate>> {
        let mut all = Vec::new();
        let mut page = 1;
        loop {
            let request = PageRequest {
                page: Some(page),
                per_page: Some(MAX_CERTIFICATES_PER_PAGE),
            };
            let Page { items, meta } = self.list(zone_id, request).await?;
            all.extend(items);
            match meta {
                Some(meta) if page < meta.total_pages => page += 1,
                _ => return Ok(all),
            }
        }
    }

    /// The visible certificates that cover a host name the way Relay picks them (exact
    /// name, or a wildcard one label up). Core allows one certificate per name, so this is
    /// normally zero or one.
    ///
    /// `GET /api/v1/certificates?name=...`
    pub async fn covering(&self, name: &str) -> Result<Vec<Certificate>> {
        let query = ListQuery {
            zone_id: None,
            name: Some(name),
            page: PageRequest::default(),
        };
        let request = self
            .client
            .request(Method::GET, &["certificates"])?
            .query(&query);
        Ok(self.client.send(request).await?.0)
    }

    /// One certificate by uuid.
    ///
    /// `GET /api/v1/certificates/:uuid`
    ///
    /// # Errors
    ///
    /// [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such certificate.
    pub async fn get(&self, uuid: Uuid) -> Result<Certificate> {
        let request = self
            .client
            .request(Method::GET, &["certificates", &uuid.to_string()])?;
        Ok(self.client.send(request).await?.0)
    }

    /// Uploads a certificate for names of a zone; every Relay gets it. Zone members and the
    /// zone key may do this.
    ///
    /// `POST /api/v1/certificates`
    ///
    /// # Errors
    ///
    /// * [`ErrorCode::Validation`](crate::ErrorCode::Validation) if the PEM cannot be
    ///   parsed, is expired, the key does not match, the chain is broken, or there are no
    ///   SAN names.
    /// * [`ErrorCode::Conflict`](crate::ErrorCode::Conflict) if a name is not served by the
    ///   zone, has a redirect with `tls` = `Auto` (switch it to `Manual` first), or is
    ///   already covered by another certificate.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use dinio_sdk::models::NewCertificate;
    ///
    /// # async fn example(client: &dinio_sdk::Client) -> dinio_sdk::Result<()> {
    /// let zone = client.zones().get("example.com").await?;
    /// let cert = client
    ///     .certificates()
    ///     .create(&NewCertificate {
    ///         chain_pem: std::fs::read_to_string("fullchain.pem").unwrap(),
    ///         key_pem: std::fs::read_to_string("privkey.pem").unwrap(),
    ///         zone_id: zone.uuid,
    ///     })
    ///     .await?;
    /// println!("{} valid until {}", cert.names.join(", "), cert.valid_to);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn create(&self, certificate: &NewCertificate) -> Result<Certificate> {
        let request = self
            .client
            .request(Method::POST, &["certificates"])?
            .json(certificate);
        Ok(self.client.send(request).await?.0)
    }

    /// Replaces chain and key under the same id (renewal). The same name rules as
    /// [`create`](Self::create) apply to the new chain.
    ///
    /// `PUT /api/v1/certificates/:uuid`
    ///
    /// # Errors
    ///
    /// * [`ErrorCode::ManagedCertificate`](crate::ErrorCode::ManagedCertificate) for a
    ///   certificate Core issued for a redirect.
    /// * As [`create`](Self::create).
    pub async fn replace(&self, uuid: Uuid, renewal: &CertificateRenewal) -> Result<Certificate> {
        let request = self
            .client
            .request(Method::PUT, &["certificates", &uuid.to_string()])?
            .json(renewal);
        Ok(self.client.send(request).await?.0)
    }

    /// Deletes a certificate. Relays fall back to the next match or their default.
    ///
    /// `DELETE /api/v1/certificates/:uuid`
    ///
    /// # Errors
    ///
    /// * [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such
    ///   certificate.
    /// * [`ErrorCode::ManagedCertificate`](crate::ErrorCode::ManagedCertificate) for a
    ///   certificate Core issued for a redirect.
    pub async fn delete(&self, uuid: Uuid) -> Result<()> {
        let request = self
            .client
            .request(Method::DELETE, &["certificates", &uuid.to_string()])?;
        self.client.send_empty(request).await
    }
}