Rust idiomático#

/// Um id de container **validado uma vez**, à entrada. Todo o código a jusante recebe
/// `ContainerId` e não precisa de re-validar — e não há forma de construir um inválido.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct ContainerId(String);

#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum IdError {
    #[error("container id must not be empty")]
    Empty,
    #[error("container id too long ({0} > 64)")]
    TooLong(usize),
    #[error("invalid character {0:?} in container id")]
    BadChar(char),
    #[error("container id must not start with '-' or '.'")]
    BadStart,
}

impl TryFrom<&str> for ContainerId {
    type Error = IdError;

    fn try_from(s: &str) -> Result<Self, IdError> {
        if s.is_empty() {
            return Err(IdError::Empty);
        }
        if s.len() > 64 {
            return Err(IdError::TooLong(s.len()));
        }
        if s.starts_with(['-', '.']) {
            return Err(IdError::BadStart);
        }
        if let Some(c) = s.chars().find(|c| !(c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-'))) {
            return Err(IdError::BadChar(c));
        }
        Ok(Self(s.to_owned()))
    }
}

impl ContainerId {
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

#[derive(Debug)]
pub struct Created;
#[derive(Debug)]
pub struct Running;
#[derive(Debug)]
pub struct Stopped;

/// O parâmetro `S` é o estado. Cada método só existe no estado onde faz sentido, e
/// **consome** `self`: a fase antiga deixa de existir.
///
/// ```
/// use examples::ch02_idiomatico::{Container, ContainerId};
/// let id = ContainerId::try_from("web").unwrap();
/// let c = Container::new(id).start(4242).stop(0);
/// assert_eq!(c.exit_code(), 0);
/// ```
///
/// Isto **não compila** (`stop` só existe em `Container<Running>`):
///
/// ```compile_fail
/// use examples::ch02_idiomatico::{Container, ContainerId};
/// let c = Container::new(ContainerId::try_from("web").unwrap());
/// c.stop(0);
/// ```
///
/// Nem isto (`c` foi consumido pela primeira transição):
///
/// ```compile_fail
/// use examples::ch02_idiomatico::{Container, ContainerId};
/// let c = Container::new(ContainerId::try_from("web").unwrap());
/// let _r = c.start(1);
/// c.start(2);
/// ```
#[derive(Debug)]
pub struct Container<S> {
    id: ContainerId,
    pid: i32,
    exit_code: i32,
    _state: PhantomData<S>,
}

impl Container<Created> {
    pub fn new(id: ContainerId) -> Self {
        Self { id, pid: 0, exit_code: 0, _state: PhantomData }
    }
    pub fn start(self, pid: i32) -> Container<Running> {
        Container { id: self.id, pid, exit_code: 0, _state: PhantomData }
    }
}

impl Container<Running> {
    pub fn pid(&self) -> i32 {
        self.pid
    }
    pub fn stop(self, exit_code: i32) -> Container<Stopped> {
        Container { id: self.id, pid: self.pid, exit_code, _state: PhantomData }
    }
}

impl Container<Stopped> {
    pub fn exit_code(&self) -> i32 {
        self.exit_code
    }
    pub fn restart(self) -> Container<Created> {
        Container::new(self.id)
    }
}

impl<S> Container<S> {
    pub fn id(&self) -> &ContainerId {
        &self.id
    }
}

//! Typestate of a container's lifecycle (Sprint 5 — Damas: *correctness by
//! construction*). The states are **types**, and the illegal transitions **do not
//! compile** — instead of being caught (or not) at runtime by a `match` over
//! a [`Status`].
//!
//! The model: `Created → Running → Stopped → (restart) Created`. Each transition
//! **consumes** the previous phase, so an obsolete phase cannot be reused.
//!
//! ```
//! use delonix_model::typestate::Phase;
//! use delonix_model::records::Status;
//!
//! let created = Phase::new("abc123");            // Phase<Created>
//! assert_eq!(created.status(), Status::Created);
//! let running = created.start(4242);             // Created → Running
//! assert_eq!(running.pid(), 4242);
//! let stopped = running.stop(0);                 // Running → Stopped
//! assert_eq!(stopped.status(), Status::Stopped);
//! let _again = stopped.restart();                // Stopped → Created (reuses the id)
//! ```
//!
//! The invalid transitions are **compilation errors**, not runtime bugs:
//!
//! ```compile_fail
//! use delonix_model::typestate::Phase;
//! let created = Phase::new("abc123"); // Phase<Created>
//! created.stop(0);                    // ERROR: `stop` only exists on Phase<Running>
//! ```
//!
//! ```compile_fail
//! use delonix_model::typestate::Phase;
//! let running = Phase::new("abc123").start(1); // Phase<Running>
//! running.start(2);                            // ERROR: `start` only exists on Phase<Created>
//! ```
//!
//! ```compile_fail
//! use delonix_model::typestate::Phase;
//! let created = Phase::new("abc123");
//! let _running = created.start(1);
//! created.start(2);                  // ERROR: `created` was consumed by the 1st transition
//! ```

use crate::records::Status;
use std::marker::PhantomData;

/// State: created, still without a `pid`.
pub struct Created;
/// State: running, with a live init `pid`.
pub struct Running;
/// State: terminated, with an exit code.
pub struct Stopped;

/// A **typed** phase of the lifecycle. The `S` parameter is the current state; the
/// transition methods only exist in the phases where they are valid.
pub struct Phase<S> {
    id: String,
    pid: Option<i32>,
    code: Option<i32>,
    _state: PhantomData<S>,
}

#[derive(Debug, PartialEq, Eq)]
pub struct RunSpec {
    pub image: String,
    pub memory: Option<u64>,
    pub env: Vec<String>,
    pub read_only: bool,
}

#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum SpecError {
    #[error("an image is required")]
    NoImage,
    #[error("env entry {0:?} is not KEY=VALUE")]
    BadEnv(String),
}

#[derive(Debug, Default)]
pub struct RunSpecBuilder {
    image: Option<String>,
    memory: Option<u64>,
    env: Vec<String>,
    read_only: bool,
}

impl RunSpecBuilder {
    pub fn image(mut self, i: impl Into<String>) -> Self {
        self.image = Some(i.into());
        self
    }
    pub fn memory(mut self, bytes: u64) -> Self {
        self.memory = Some(bytes);
        self
    }
    pub fn env(mut self, kv: impl Into<String>) -> Self {
        self.env.push(kv.into());
        self
    }
    pub fn read_only(mut self, yes: bool) -> Self {
        self.read_only = yes;
        self
    }
    /// Toda a validação vive aqui — `RunSpec` só existe válido.
    pub fn build(self) -> Result<RunSpec, SpecError> {
        let image = self.image.ok_or(SpecError::NoImage)?;
        if let Some(bad) = self.env.iter().find(|e| !e.contains('=')) {
            return Err(SpecError::BadEnv(bad.clone()));
        }
        Ok(RunSpec { image, memory: self.memory, env: self.env, read_only: self.read_only })
    }
}

/// The single place an engine error becomes an exit code.
///
/// Pure on purpose: two places deciding the same number is how they start
/// disagreeing, and a table this small is only worth anything if it is the
/// whole truth.
pub fn for_error(e: &Error) -> i32 {
    match e {
        Error::NotFound(_) | Error::VmNotFound(_) => NOT_FOUND,
        Error::NotRunning(_) => NOT_RUNNING,
        Error::Conflict(_) => CONFLICT,
        Error::Unavailable(_) => UNAVAILABLE,
        Error::Timeout(_) => TIMEOUT,
        Error::Coded { inner, .. } => for_error(inner),
        // The KIND is inspected rather than the variant: `Error::Io` is the
        // wrapper every filesystem refusal arrives in, and EACCES inside it is
        // a different answer for the caller than a full disk or a bad path.
        Error::Io(e) if e.kind() == std::io::ErrorKind::PermissionDenied => NO_PERMISSION,
        Error::Io(_) => IO,
        Error::Json(_) | Error::Runtime { .. } => GENERIC,
        Error::Invalid(_) | Error::Registry(_) => GENERIC,
    }
}