digitalocean_api/api/

droplet.rs

use self::droplet_fields::{Kernel, Networks, NextBackupWindow};
use super::snapshot::Snapshot;
use super::{ApiLinks, ApiMeta};
use super::{HasPagination, HasResponse, HasValue};
use super::{Image, Region, Size};
use crate::method::{Create, Delete, Get, List};
use crate::request::Request;
use crate::request::{DropletRequest, SnapshotRequest};
use crate::{ROOT_URL, STATIC_URL_ERROR};
use chrono::{DateTime, Utc};
use getset::{Getters, Setters};
use serde::Deserialize;
use serde::Serialize;
use std::fmt::Display;
use url::Url;

const DROPLETS_SEGMENT: &str = "droplets";
const REPORTS_SEGMENT: &str = "reports";
const DROPLET_NEIGHBORS_SEGMENT: &str = "droplet_neighbors";
const NEIGHBORS_SEGMENT: &str = "neighbors";
const SNAPSHOTS_SEGMENT: &str = "snapshots";
const BACKUPS_SEGMENT: &str = "backups";

/// A Droplet is a DigitalOcean virtual machine. By sending requests to the
/// Droplet endpoint, you can list, create, or delete Droplets.
///
/// Some of the attributes will have an object value. The region and image
/// objects will all contain the standard attributes of their associated types.
/// Find more information about each of these objects in their respective
/// sections.
///
/// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#domains)
#[derive(Deserialize, Serialize, Debug, Clone, Getters, Setters)]
#[get = "pub"]
pub struct Droplet {
    /// A unique identifier for each Droplet instance. This is automatically
    /// generated upon Droplet creation.
    id: usize,

    /// The human-readable name set for the Droplet instance.
    name: String,

    /// Memory of the Droplet in megabytes.
    memory: usize,

    /// The number of virtual CPUs.
    vcpus: usize,

    /// The size of the Droplet's disk in gigabytes.
    disk: usize,

    /// A boolean value indicating whether the Droplet has been locked,
    /// preventing actions by users.
    locked: bool,

    /// A time value given in ISO8601 combined date and time format that
    /// represents when the Droplet was created.
    created_at: DateTime<Utc>,

    /// A status string indicating the state of the Droplet instance. This may
    /// be "new", "active", "off", or "archive".
    status: String,

    /// An array of backup IDs of any backups that have been taken of the
    /// Droplet instance. Droplet backups are enabled at the time of the
    /// instance creation.
    backup_ids: Vec<usize>,

    /// An array of snapshot IDs of any snapshots created from the Droplet
    /// instance.
    snapshot_ids: Vec<usize>,

    /// An array of features enabled on this Droplet.
    features: Vec<String>,

    /// The region that the Droplet instance is deployed in. When setting a
    /// region, the value should be the slug identifier for the region. When
    /// you query a Droplet, the entire region object will be returned.
    region: Region,

    /// The base image used to create the Droplet instance. When setting an
    /// image, the value is set to the image id or slug. When querying the
    /// Droplet, the entire image object will be returned.
    image: Image,

    /// The current size object describing the Droplet. When setting a size,
    /// the value is set to the size slug. When querying the Droplet, the
    /// entire size object will be returned. Note that the disk volume of a
    /// Droplet may not match the size's disk due to Droplet resize actions.
    /// The disk attribute on the Droplet should always be referenced.
    size: Size,

    /// The unique slug identifier for the size of this Droplet.
    size_slug: String,

    /// The details of the network that are configured for the Droplet
    /// instance. This is an object that contains keys for IPv4 and IPv6.
    /// The value of each of these is an array that contains objects describing
    /// an individual IP resource allocated to the Droplet. These will define
    /// attributes like the IP address, netmask, and gateway of the specific
    /// network depending on the type of network it is.
    networks: Networks,

    /// The current kernel. This will initially be set to the kernel of the
    /// base image when the Droplet is created.
    kernel: Option<Kernel>,

    /// The details of the Droplet's backups feature, if backups are configured
    /// for the Droplet. This object contains keys for the start and end times
    /// of the window during which the backup will start.
    next_backup_window: Option<NextBackupWindow>,

    /// An array of Tags the Droplet has been tagged with.
    tags: Vec<String>,

    /// A flat array including the unique identifier for each Block Storage
    /// volume attached to the Droplet.
    volume_ids: Vec<String>,
}

/// Fields which exists inside Droplets.
pub mod droplet_fields {
    use chrono::{DateTime, Utc};
    use serde::Deserialize;
    use serde::Serialize;
    use std::net::{Ipv4Addr, Ipv6Addr};

    /// This exists in the `networks` field of a droplet.
    #[derive(Deserialize, Serialize, Debug, Clone)]
    pub struct Networks {
        pub v4: Vec<NetworkV4>,
        pub v6: Vec<NetworkV6>,
    }

    /// These exist in the `networks` field of a droplet.
    #[derive(Deserialize, Serialize, Debug, Clone)]
    pub struct NetworkV4 {
        pub gateway: Ipv4Addr,
        pub ip_address: Ipv4Addr,
        pub netmask: Ipv4Addr,
        /// *Note:* Since `type` is a keyword in Rust `kind` is used instead.
        #[serde(rename = "type")]
        pub kind: String,
    }

    /// These exist in the `networks` field of a droplet.
    #[derive(Deserialize, Serialize, Debug, Clone)]
    pub struct NetworkV6 {
        pub gateway: Ipv6Addr,
        pub ip_address: Ipv6Addr,
        pub netmask: usize,
        /// *Note:* Since `type` is a keyword in Rust `kind` is used instead.
        #[serde(rename = "type")]
        pub kind: String,
    }

    /// This exists in the `next_backup_window` field of a droplet.
    #[derive(Deserialize, Serialize, Debug, Clone)]
    pub struct NextBackupWindow {
        pub end: DateTime<Utc>,
        pub start: DateTime<Utc>,
    }

    /// This exists in the `kernel` field of a droplet.
    #[derive(Deserialize, Serialize, Debug, Clone)]
    pub struct Kernel {
        pub id: usize,
        pub name: String,
        pub version: String,
    }
}

impl Droplet {
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn create<S, D>(name: S, region: S, size: S, image: D) -> DropletRequest<Create, Droplet>
    where
        S: AsRef<str> + Serialize + Display,
        D: Serialize + Display,
    {
        let mut url = ROOT_URL.clone();
        url.path_segments_mut()
            .expect(STATIC_URL_ERROR)
            .push(DROPLETS_SEGMENT);

        let mut req = Request::new(url);
        req.set_body(json!({
            "name": name,
            "region": region,
            "size": size,
            "image": format!("{}", image),
        }));
        req
    }

    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-multiple-droplets)
    pub fn create_multiple<S, D>(
        names: Vec<S>,
        region: S,
        size: S,
        image: D,
    ) -> DropletRequest<Create, Vec<Droplet>>
    where
        S: AsRef<str> + Serialize + Display,
        D: Serialize + Display,
    {
        let mut url = ROOT_URL.clone();
        url.path_segments_mut()
            .expect(STATIC_URL_ERROR)
            .push(DROPLETS_SEGMENT);

        let mut req = Request::new(url);
        req.set_body(json!({
            "names": names,
            "region": region,
            "size": size,
            "image": format!("{}", image),
        }));
        req
    }

    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#retrieve-an-existing-droplet-by-id)
    pub fn get(id: usize) -> DropletRequest<Get, Droplet> {
        let mut url = ROOT_URL.clone();
        url.path_segments_mut()
            .expect(STATIC_URL_ERROR)
            .push(DROPLETS_SEGMENT)
            .push(&id.to_string());

        Request::new(url)
    }

    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#list-all-droplets)
    pub fn list() -> DropletRequest<List, Vec<Droplet>> {
        let mut url = ROOT_URL.clone();
        url.path_segments_mut()
            .expect(STATIC_URL_ERROR)
            .push(DROPLETS_SEGMENT);

        Request::new(url)
    }

    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#listing-droplets-by-tag)
    pub fn list_by_tag<S: AsRef<str> + Serialize>(name: S) -> DropletRequest<List, Vec<Droplet>> {
        let mut url = ROOT_URL.clone();
        url.path_segments_mut()
            .expect(STATIC_URL_ERROR)
            .push(DROPLETS_SEGMENT);

        url.query_pairs_mut().append_pair("tag_name", name.as_ref());

        Request::new(url)
    }

    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#delete-a-droplet)
    pub fn delete(id: usize) -> DropletRequest<Delete, ()> {
        let mut url = ROOT_URL.clone();
        url.path_segments_mut()
            .expect(STATIC_URL_ERROR)
            .push(DROPLETS_SEGMENT)
            .push(&id.to_string());

        Request::new(url)
    }

    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#deleting-droplets-by-tag)
    pub fn delete_by_tag<S: AsRef<str> + Serialize>(name: S) -> DropletRequest<Delete, ()> {
        let mut url = ROOT_URL.clone();
        url.path_segments_mut()
            .expect(STATIC_URL_ERROR)
            .push(DROPLETS_SEGMENT);

        url.query_pairs_mut().append_pair("tag_name", name.as_ref());

        Request::new(url)
    }

    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#list-all-droplet-neighbors)
    pub fn neighbors() -> DropletRequest<Get, Vec<Vec<Droplet>>> {
        let mut url = ROOT_URL.clone();
        url.path_segments_mut()
            .expect(STATIC_URL_ERROR)
            .push(REPORTS_SEGMENT)
            .push(DROPLET_NEIGHBORS_SEGMENT);

        Request::new(url)
    }
}

impl DropletRequest<Create, Droplet> {
    /// An array containing the IDs or fingerprints of the SSH keys that you
    /// wish to embed in the Droplet's root account upon creation.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn ssh_keys<D>(mut self, val: Vec<D>) -> Self
    where
        D: Display + Serialize,
    {
        self.body_mut()["ssh_keys"] = json!(val);
        self
    }

    /// A boolean indicating whether automated backups should be enabled for
    /// the Droplet. Automated backups can only be enabled when the Droplet is
    /// created.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn backups(mut self, val: bool) -> Self {
        self.body_mut()["backups"] = json!(val);
        self
    }

    /// A boolean indicating whether IPv6 is enabled on the Droplet.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn ipv6(mut self, val: bool) -> Self {
        self.body_mut()["ipv6"] = json!(val);
        self
    }

    /// A boolean indicating whether private networking is enabled for the
    /// Droplet. Private networking is currently only available in certain
    /// regions.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn private_networking(mut self, val: bool) -> Self {
        self.body_mut()["private_networking"] = json!(val);
        self
    }

    /// A string containing 'user data' which may be used to configure the
    /// Droplet on first boot, often a 'cloud-config' file or Bash script.
    /// It must be plain text and may not exceed 64 KiB in size.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn user_data(mut self, val: bool) -> Self {
        self.body_mut()["user_data"] = json!(val);
        self
    }

    /// A boolean indicating whether to install the DigitalOcean agent
    /// for monitoring.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn monitoring(mut self, val: bool) -> Self {
        self.body_mut()["monitoring"] = json!(val);
        self
    }

    /// A flat array including the unique string identifier for each Block
    /// Storage volume to be attached to the Droplet. At the moment a volume
    /// can only be attached to a single Droplet.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn volumes(mut self, val: Vec<String>) -> Self {
        self.body_mut()["volumes"] = json!(val);
        self
    }

    /// A flat array of tag names as strings to apply to the Droplet after it
    /// is created. Tag names can either be existing or new tags.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn tags(mut self, val: Vec<String>) -> Self {
        self.body_mut()["tags"] = json!(val);
        self
    }
}

impl DropletRequest<Create, Vec<Droplet>> {
    /// An array containing the IDs or fingerprints of the SSH keys that you
    /// wish to embed in the Droplet's root account upon creation.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn ssh_keys<D>(mut self, val: Vec<D>) -> Self
    where
        D: Display + Serialize,
    {
        self.body_mut()["ssh_keys"] = json!(val);
        self
    }

    /// A boolean indicating whether automated backups should be enabled for
    /// the Droplet. Automated backups can only be enabled when the Droplet is
    /// created.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn backups(mut self, val: bool) -> Self {
        self.body_mut()["backups"] = json!(val);
        self
    }

    /// A boolean indicating whether IPv6 is enabled on the Droplet.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn ipv6(mut self, val: bool) -> Self {
        self.body_mut()["ipv6"] = json!(val);
        self
    }

    /// A boolean indicating whether private networking is enabled for the
    /// Droplet. Private networking is currently only available in certain
    /// regions.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn private_networking(mut self, val: bool) -> Self {
        self.body_mut()["private_networking"] = json!(val);
        self
    }

    /// A string containing 'user data' which may be used to configure the
    /// Droplet on first boot, often a 'cloud-config' file or Bash script.
    /// It must be plain text and may not exceed 64 KiB in size.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn user_data(mut self, val: bool) -> Self {
        self.body_mut()["user_data"] = json!(val);
        self
    }

    /// A boolean indicating whether to install the DigitalOcean agent
    /// for monitoring.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn monitoring(mut self, val: bool) -> Self {
        self.body_mut()["monitoring"] = json!(val);
        self
    }

    /// A flat array including the unique string identifier for each Block
    /// Storage volume to be attached to the Droplet. At the moment a volume
    /// can only be attached to a single Droplet.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn volumes(mut self, val: Vec<String>) -> Self {
        self.body_mut()["volumes"] = json!(val);
        self
    }

    /// A flat array of tag names as strings to apply to the Droplet after it
    /// is created. Tag names can either be existing or new tags.
    ///
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#create-a-new-droplet)
    pub fn tags(mut self, val: Vec<String>) -> Self {
        self.body_mut()["tags"] = json!(val);
        self
    }
}

impl DropletRequest<Get, Droplet> {
    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#list-snapshots-for-a-droplet)
    pub fn snapshots(mut self) -> SnapshotRequest<List, Vec<Snapshot>> {
        self.url_mut()
            .path_segments_mut()
            .expect(STATIC_URL_ERROR)
            .push(SNAPSHOTS_SEGMENT);

        self.transmute()
    }

    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#list-backups-for-a-droplet)
    pub fn backups(mut self) -> SnapshotRequest<List, Vec<Snapshot>> {
        self.url_mut()
            .path_segments_mut()
            .expect(STATIC_URL_ERROR)
            .push(BACKUPS_SEGMENT);

        self.transmute()
    }

    /// [Digital Ocean Documentation.](https://developers.digitalocean.com/documentation/v2/#list-neighbors-for-a-droplet)
    pub fn neighbors(mut self) -> DropletRequest<List, Vec<Droplet>> {
        self.url_mut()
            .path_segments_mut()
            .expect(STATIC_URL_ERROR)
            .push(NEIGHBORS_SEGMENT);

        self.transmute()
    }
}

/// Response type returned from Digital Ocean.
#[derive(Deserialize, Serialize, Debug, Clone)]
pub struct DropletResponse {
    droplet: Droplet,
}

impl HasResponse for Droplet {
    type Response = DropletResponse;
}

impl HasValue for DropletResponse {
    type Value = Droplet;

    fn value(self) -> Droplet {
        self.droplet
    }
}

/// Response type returned from Digital Ocean.
#[derive(Deserialize, Serialize, Debug, Clone)]
pub struct DropletListResponse {
    droplets: Vec<Droplet>,
    links: ApiLinks,
    meta: ApiMeta,
}

impl HasResponse for Vec<Droplet> {
    type Response = DropletListResponse;
}

impl HasPagination for DropletListResponse {
    fn next_page(&self) -> Option<Url> {
        self.links.next()
    }
}

impl HasValue for DropletListResponse {
    type Value = Vec<Droplet>;

    fn value(self) -> Vec<Droplet> {
        self.droplets
    }
}

/// Response type returned from Digital Ocean
#[derive(Deserialize, Serialize, Debug, Clone)]
pub struct DropletNeighborsResponse {
    neighbors: Vec<Vec<Droplet>>,
}

impl HasResponse for Vec<Vec<Droplet>> {
    type Response = DropletNeighborsResponse;
}

impl HasValue for DropletNeighborsResponse {
    type Value = Vec<Vec<Droplet>>;

    fn value(self) -> Vec<Vec<Droplet>> {
        self.neighbors
    }
}