dinio_sdk/api/

redirects.rs

//! `/api/v1/redirects` (`../core/src/api/redirects.ts`). A redirect is addressed by its
//! host name and belongs to a zone; access is the zone's.

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

use crate::api::{MAX_PER_PAGE, PageRequest};
use crate::client::Client;
use crate::envelope::Page;
use crate::error::Result;
use crate::models::{NewRedirect, Redirect, RedirectPatch};

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

/// HTTP(S) redirects by host name, from [`Client::redirects`].
///
/// A redirect lives on a host name inside a zone, and access to it is access to that zone:
/// the zone's key, a member of the zone, or an Admin. Creating one makes Core add the DNS
/// records that point the name at the platform; deleting it removes them.
pub struct Redirects<'a> {
    client: &'a Client,
}

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

    /// One page of the redirects of `zone_id`, or of every zone the caller can access when
    /// `None` (a zone key: its zone; an Admin: all). Without `certificate` status; read one
    /// redirect with [`get`](Self::get) for that.
    ///
    /// `GET /api/v1/redirects[?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<Redirect>> {
        let query = ListQuery { zone_id, page };
        let request = self
            .client
            .request(Method::GET, &["redirects"])?
            .query(&query);
        let (items, meta) = self.client.send(request).await?;
        Ok(Page { items, meta })
    }

    /// All redirects [`list`](Self::list) would return, following pagination.
    ///
    /// `GET /api/v1/redirects`, as many times as there are pages.
    ///
    /// # Errors
    ///
    /// As [`list`](Self::list).
    pub async fn list_all(&self, zone_id: Option<Uuid>) -> Result<Vec<Redirect>> {
        let mut all = Vec::new();
        let mut page = 1;
        loop {
            let request = PageRequest {
                page: Some(page),
                per_page: Some(MAX_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),
            }
        }
    }

    /// One redirect by host name, with its `certificate` status for `tls` = `Auto`.
    ///
    /// `GET /api/v1/redirects/:name`
    ///
    /// # Errors
    ///
    /// [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such redirect.
    pub async fn get(&self, name: &str) -> Result<Redirect> {
        let request = self.client.request(Method::GET, &["redirects", name])?;
        Ok(self.client.send(request).await?.0)
    }

    /// Creates a redirect and the DNS records that point its name at the platform; Relay
    /// starts answering HTTP(S) requests for the name. With `tls` = `Auto`
    /// Core starts issuing a certificate right away. Returns it with the name normalized.
    ///
    /// `POST /api/v1/redirects`
    ///
    /// # Errors
    ///
    /// * [`ErrorCode::Conflict`](crate::ErrorCode::Conflict) if the name already has a
    ///   redirect, is not inside the zone, belongs to a more specific hosted zone or is
    ///   delegated away, already has A/AAAA/CNAME records of the user's own, or (`Auto`) is
    ///   covered by another certificate. [`ApiError::details`](crate::ApiError::details)
    ///   lists the reasons.
    /// * [`ErrorCode::Validation`](crate::ErrorCode::Validation) for a bad name, code or
    ///   URL.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use dinio_sdk::models::{NewRedirect, RedirectTls};
    /// use dinio_sdk::ops;
    ///
    /// # async fn example(client: &dinio_sdk::Client) -> dinio_sdk::Result<()> {
    /// let zone = ops::find_zone_for_host(client, "go.example.com").await?;
    /// let redirect = NewRedirect {
    ///     zone_id: zone.uuid,
    ///     name: "go.example.com".into(),
    ///     code: 302,
    ///     location: "https://example.com/landing".into(),
    ///     tls: Some(RedirectTls::Auto),
    /// };
    /// client.redirects().create(&redirect).await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn create(&self, redirect: &NewRedirect) -> Result<Redirect> {
        let request = self
            .client
            .request(Method::POST, &["redirects"])?
            .json(redirect);
        Ok(self.client.send(request).await?.0)
    }

    /// Changes a redirect's code, target and/or certificate source; fields left `None` stay
    /// as they are. Its DNS records do not change.
    ///
    /// `PATCH /api/v1/redirects/:name`
    ///
    /// # Errors
    ///
    /// * [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such redirect.
    /// * [`ErrorCode::Validation`](crate::ErrorCode::Validation) for a bad code or URL.
    /// * [`ErrorCode::Conflict`](crate::ErrorCode::Conflict) when switching to `Auto` while
    ///   another certificate covers the name.
    pub async fn update(&self, name: &str, patch: &RedirectPatch) -> Result<Redirect> {
        let request = self
            .client
            .request(Method::PATCH, &["redirects", name])?
            .json(patch);
        Ok(self.client.send(request).await?.0)
    }

    /// Deletes a redirect with its DNS records and its automatic certificate.
    ///
    /// `DELETE /api/v1/redirects/:name`
    ///
    /// # Errors
    ///
    /// [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such redirect.
    pub async fn delete(&self, name: &str) -> Result<()> {
        let request = self.client.request(Method::DELETE, &["redirects", name])?;
        self.client.send_empty(request).await
    }
}