dinio_sdk/api/

zones.rs

//! `/api/v1/zones` (`../core/src/api/zones.ts`). A zone ref is its uuid or its name.

use std::time::Duration;

use reqwest::Method;
use serde_json::json;

use crate::api::{IssuedKey, MAX_PER_PAGE, PageRequest};
use crate::auth::Secret;
use crate::client::Client;
use crate::envelope::Page;
use crate::error::Result;
use crate::models::{Discovery, ImportReport, Zone, ZoneFileFormat};

/// Zone routes, from [`Client::zones`].
///
/// A zone is addressed by its uuid or its name (`"example.com"`). Access: a personal key
/// reaches the zones its user is a member of; a zone key only its own zone.
pub struct Zones<'a> {
    client: &'a Client,
}

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

    /// Zones visible to the caller. Core paginates only for an Admin; everyone else gets
    /// their whole list on one page. Prefer [`list_all`](Self::list_all) unless you page
    /// yourself.
    ///
    /// `GET /api/v1/zones`
    pub async fn list(&self, page: PageRequest) -> Result<Page<Zone>> {
        let request = self.client.request(Method::GET, &["zones"])?.query(&page);
        let (items, meta) = self.client.send(request).await?;
        Ok(Page { items, meta })
    }

    /// All visible zones, following pagination.
    ///
    /// `GET /api/v1/zones`, as many times as there are pages.
    pub async fn list_all(&self) -> Result<Vec<Zone>> {
        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(request).await?;
            all.extend(items);
            match meta {
                Some(meta) if page < meta.total_pages => page += 1,
                _ => return Ok(all),
            }
        }
    }

    /// One zone by uuid or name.
    ///
    /// `GET /api/v1/zones/:ref`
    ///
    /// # Errors
    ///
    /// [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such zone.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # async fn example(client: &dinio_sdk::Client) -> dinio_sdk::Result<()> {
    /// let zone = client.zones().get("example.com").await?;
    /// println!("{} is {}", zone.name, zone.uuid);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn get(&self, zone: &str) -> Result<Zone> {
        let request = self.client.request(Method::GET, &["zones", zone])?;
        Ok(self.client.send(request).await?.0)
    }

    /// Creates a zone; the caller becomes its Owner and Core adds the apex SOA and NS.
    /// Not allowed with a zone-scoped key.
    ///
    /// A name directly below a free domain
    /// ([`FreeDomains::list`](crate::api::FreeDomains::list)) is a lease: one label of
    /// 3–63 characters, not reserved, not taken, and at most the free domains' `limit`
    /// leases per user. Core then also delegates the name from the free domain.
    ///
    /// `POST /api/v1/zones`
    ///
    /// # Errors
    ///
    /// * [`ErrorCode::Conflict`](crate::ErrorCode::Conflict) if the zone already exists,
    ///   or a lease breaks a rule (`details` says which, e.g. the lease limit).
    /// * [`ErrorCode::Validation`](crate::ErrorCode::Validation) if the name is not a valid
    ///   domain name.
    /// * [`ErrorCode::Forbidden`](crate::ErrorCode::Forbidden) with a zone key, or for a
    ///   free domain itself (Admin only).
    pub async fn create(&self, name: &str) -> Result<Zone> {
        let request = self
            .client
            .request(Method::POST, &["zones"])?
            .json(&json!({ "name": name }));
        Ok(self.client.send(request).await?.0)
    }

    /// Issues a new zone-scoped key (`dz_…`) and returns it. Core shows the key only in
    /// this response and keeps just its hash, so store it now. A previous key of the zone
    /// stops working immediately; if it is the key this client uses, build a new client with
    /// the new key. Allowed for the zone's own key, its Owner or Administrator, and Admin.
    ///
    /// `POST /api/v1/zones/:ref/api-key`
    ///
    /// # Errors
    ///
    /// [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such zone.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # async fn example(client: &dinio_sdk::Client) -> dinio_sdk::Result<()> {
    /// let key = client.zones().create_api_key("example.com").await?;
    /// // Show the key to the user now; Core never returns it again.
    /// println!("{}", key.expose());
    /// # Ok(())
    /// # }
    /// ```
    pub async fn create_api_key(&self, zone: &str) -> Result<Secret> {
        let request = self
            .client
            .request(Method::POST, &["zones", zone, "api-key"])?;
        let (issued, _): (IssuedKey, _) = self.client.send(request).await?;
        Ok(issued.api_key)
    }

    /// Revokes the zone's key; the zone then has none
    /// ([`Zone::has_api_key`] is `false`). Same access as
    /// [`create_api_key`](Self::create_api_key).
    ///
    /// `DELETE /api/v1/zones/:ref/api-key`
    ///
    /// # Errors
    ///
    /// [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such zone.
    pub async fn revoke_api_key(&self, zone: &str) -> Result<Zone> {
        let request = self
            .client
            .request(Method::DELETE, &["zones", zone, "api-key"])?;
        Ok(self.client.send(request).await?.0)
    }

    /// Deletes the zone with all its records, geo bans and health checks. Irreversible.
    /// Allowed for the zone's Owner, an Admin or the zone's own key; a delegated
    /// Administrator may not.
    ///
    /// `DELETE /api/v1/zones/:ref`
    ///
    /// # Errors
    ///
    /// * [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such zone.
    /// * [`ErrorCode::Forbidden`](crate::ErrorCode::Forbidden) if the caller is not the
    ///   Owner.
    pub async fn delete(&self, zone: &str) -> Result<()> {
        let request = self.client.request(Method::DELETE, &["zones", zone])?;
        self.client.send_empty(request).await
    }

    /// The zone as a file, exactly as Core writes it. `Json` is the dinio-zone document
    /// (parse it into [`ZoneDocument`](crate::models::ZoneDocument) if needed); `Bind`
    /// and `Csv` carry only name, ttl, type and data. Reading is enough, so it works on
    /// a suspended zone too.
    ///
    /// `GET /api/v1/zones/:ref/export?format=`
    ///
    /// # Errors
    ///
    /// [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such zone.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use dinio_sdk::models::ZoneFileFormat;
    ///
    /// # async fn example(client: &dinio_sdk::Client) -> dinio_sdk::Result<()> {
    /// let zone_file = client.zones().export("example.com", ZoneFileFormat::Bind).await?;
    /// std::fs::write("example.com.zone", zone_file).expect("write");
    /// # Ok(())
    /// # }
    /// ```
    pub async fn export(&self, zone: &str, format: ZoneFileFormat) -> Result<String> {
        let request = self
            .client
            .request(Method::GET, &["zones", zone, "export"])?
            .query(&[("format", format.as_wire())]);
        self.client.send_file(request).await
    }

    /// Merges a zone file into the zone: adds what the zone lacks, never changes or
    /// deletes anything. SOA and apex NS in the file are skipped. Records are written in
    /// one transaction (all or none); redirects of a dinio-zone document afterwards, each
    /// on its own. With `dry_run` Core checks everything and writes nothing.
    ///
    /// `POST /api/v1/zones/:ref/import?format=&dry_run=`
    ///
    /// # Errors
    ///
    /// * [`ErrorCode::ImportFailed`](crate::ErrorCode::ImportFailed) if any record is
    ///   refused: nothing was written, and
    ///   [`ApiError::import_report`](crate::ApiError::import_report) has the report. A dry
    ///   run returns the same report as `Ok` instead.
    /// * [`ErrorCode::PayloadTooLarge`](crate::ErrorCode::PayloadTooLarge) for a file over
    ///   2 MiB (at most 10 000 records).
    /// * [`ErrorCode::Validation`](crate::ErrorCode::Validation) if a dinio-zone document
    ///   does not have the expected shape.
    /// * [`ErrorCode::Suspended`](crate::ErrorCode::Suspended) for a suspended zone.
    /// * [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such zone.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use dinio_sdk::models::ZoneFileFormat;
    ///
    /// # async fn example(client: &dinio_sdk::Client) -> dinio_sdk::Result<()> {
    /// let file = std::fs::read_to_string("example.com.zone").expect("read");
    /// let zones = client.zones();
    /// let preview = zones.import("example.com", ZoneFileFormat::Bind, file.clone(), true).await?;
    /// if !preview.has_errors() {
    ///     let report = zones.import("example.com", ZoneFileFormat::Bind, file, false).await?;
    ///     println!("{} records created", report.records.created);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub async fn import(
        &self,
        zone: &str,
        format: ZoneFileFormat,
        file: String,
        dry_run: bool,
    ) -> Result<ImportReport> {
        let mut request = self
            .client
            .request(Method::POST, &["zones", zone, "import"])?
            .query(&[("format", format.as_wire())]);
        if dry_run {
            request = request.query(&[("dry_run", "true")]);
        }
        let content_type = match format {
            ZoneFileFormat::Json => "application/json",
            ZoneFileFormat::Bind => "text/dns; charset=utf-8",
            ZoneFileFormat::Csv => "text/csv; charset=utf-8",
        };
        let request = request
            .header(reqwest::header::CONTENT_TYPE, content_type)
            .body(file);
        Ok(self.client.send(request).await?.0)
    }

    /// Asks the zone's current nameservers (the previous provider's) about the names a
    /// zone usually has and returns a proposal to review, trim and pass to
    /// [`import`](Self::import). Writes nothing. Finds common names only, not every
    /// record (AXFR is refused almost everywhere). Takes up to about a minute, so the
    /// request waits at least 90 s whatever the client's timeout.
    ///
    /// `nameservers` (host names or addresses, at most 8) are needed once the delegation
    /// already points to Dinio; empty means "ask the delegation".
    ///
    /// `POST /api/v1/zones/:ref/discover`
    ///
    /// # Errors
    ///
    /// * [`ErrorCode::DiscoveryFailed`](crate::ErrorCode::DiscoveryFailed) if no usable
    ///   nameserver answered; typically the delegation already points to Dinio, so give the
    ///   previous provider's nameservers.
    /// * [`ErrorCode::Conflict`](crate::ErrorCode::Conflict) while a discovery of the zone
    ///   is running.
    /// * [`ErrorCode::Suspended`](crate::ErrorCode::Suspended) for a suspended zone.
    /// * [`ErrorCode::NotFound`](crate::ErrorCode::NotFound) if there is no such zone.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use dinio_sdk::models::ZoneFileFormat;
    ///
    /// # async fn example(client: &dinio_sdk::Client) -> dinio_sdk::Result<()> {
    /// let found = client.zones().discover("example.com", &[]).await?;
    /// let mut document = found.document;
    /// document.records.retain(|r| r.record_type != "TXT");
    /// let file = serde_json::to_string(&document).expect("serializable");
    /// client.zones().import("example.com", ZoneFileFormat::Json, file, false).await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn discover(&self, zone: &str, nameservers: &[String]) -> Result<Discovery> {
        let mut request = self
            .client
            .request(Method::POST, &["zones", zone, "discover"])?
            .timeout(self.client.timeout().max(DISCOVER_TIMEOUT));
        if !nameservers.is_empty() {
            request = request.json(&json!({ "nameservers": nameservers }));
        }
        Ok(self.client.send(request).await?.0)
    }
}

/// Core's discovery budget is 60 s; the rest covers the request around it.
const DISCOVER_TIMEOUT: Duration = Duration::from_secs(90);