Rust essencial#

/// `&str` empresta: quem chama continua dono da `String`.
pub fn is_valid_name(name: &str) -> bool {
    !name.is_empty() && name.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-')
}

/// `String` por valor MOVE: depois da chamada o chamador já não a pode usar.
pub fn into_label(name: String) -> String {
    format!("delonix.io/name={name}")
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Status {
    Created,
    Running { pid: i32 },
    Stopped { exit_code: i32 },
}

impl Status {
    /// `match` **exaustivo**: se acrescentares uma variante, isto deixa de compilar até
    /// decidires o que fazer com ela — é o que substitui os `default:` silenciosos de outras linguagens.
    pub fn describe(&self) -> String {
        match self {
            Self::Created => "created".to_owned(),
            Self::Running { pid } => format!("running (pid {pid})"),
            Self::Stopped { exit_code: 0 } => "exited cleanly".to_owned(),
            Self::Stopped { exit_code } => format!("exited with {exit_code}"),
        }
    }
}

#[derive(Debug, PartialEq, Eq)]
pub enum ParseError {
    Empty,
    NotANumber(String),
    Negative(i64),
}

/// Converte `"64M"`, `"2G"`, `"512"` em bytes. Cada `?` devolve o erro ao chamador.
pub fn parse_size(s: &str) -> Result<u64, ParseError> {
    let s = s.trim();
    if s.is_empty() {
        return Err(ParseError::Empty);
    }
    let (digits, mult) = match s.chars().last() {
        Some('K') => (&s[..s.len() - 1], 1u64 << 10),
        Some('M') => (&s[..s.len() - 1], 1 << 20),
        Some('G') => (&s[..s.len() - 1], 1 << 30),
        _ => (s, 1),
    };
    let n: i64 = digits.parse().map_err(|_| ParseError::NotANumber(s.to_owned()))?;
    let n = u64::try_from(n).map_err(|_| ParseError::Negative(n))?;
    Ok(n.saturating_mul(mult)) // saturating: input hostil não pode dar overflow silencioso
}

/// Mesma forma que o `VmBackend` do delonix: o motor fala com a *interface*, e cada
/// hypervisor é uma implementação — nunca um `if provider == "libvirt"` espalhado.
pub trait Backend {
    fn id(&self) -> &'static str;
    fn boot(&self, name: &str) -> Result<u32, String>;
}

#[derive(Debug)]
pub struct Local;
#[derive(Debug)]
pub struct Remote {
    pub endpoint: String,
}

impl Backend for Local {
    fn id(&self) -> &'static str {
        "local"
    }
    fn boot(&self, _name: &str) -> Result<u32, String> {
        Ok(1)
    }
}

impl Backend for Remote {
    fn id(&self) -> &'static str {
        "remote"
    }
    fn boot(&self, name: &str) -> Result<u32, String> {
        if self.endpoint.is_empty() {
            return Err(format!("cannot boot {name}: no endpoint"));
        }
        Ok(2)
    }
}

/// Genérico sobre o trait (despacho estático, sem custo) …
pub fn boot_static<B: Backend>(b: &B, name: &str) -> Result<u32, String> {
    b.boot(name)
}

/// … ou por `dyn` quando o backend só se conhece em runtime (um registo de backends).
pub fn boot_all(backends: &[Box<dyn Backend>], name: &str) -> Vec<(&'static str, Result<u32, String>)> {
    backends.iter().map(|b| (b.id(), b.boot(name))).collect()
}

/// The virtualization mechanism behind a microVM. Allows having Cloud
/// Hypervisor and libvirt/KVM side by side (chosen per VM).
pub trait VmBackend {
    /// Stable identifier persisted in the [`Vm`].
    fn id(&self) -> &'static str;
    /// `true` if the backend has the required tools installed.
    fn available(&self) -> bool;
    /// Creates the network (if applicable) and boots the VM from the `overlay`. The overlay
    /// creation and idempotency are handled by [`create`]. `on` receives the
    /// sub-stages (network/define/start) for a progress UI.
    fn boot(
        &self,
        vmdir: &Path,
        cfg: &VmConfig,
        overlay: &str,
        on: &dyn Fn(CreateStage),
    ) -> delonix_model::Result<Boot>;
    /// Is the VM still alive?
    fn is_running(&self, vm: &Vm) -> bool;
    /// Current IP of the VM (may change/resolve later via DHCP).
    fn ip(&self, vm: &Vm) -> Option<String>;

    /// Is [`VmBackend::ip`] a PREDICTION rather than an OBSERVATION?
    ///
    /// Default `false`: libvirt reads a real DHCP lease, so an address there is
    /// evidence that the guest booted far enough to ask for one. Cloud
    /// Hypervisor overrides it — its address is computed from the MAC before
    /// the guest runs at all, so it is evidence of nothing.
    ///
    /// Whoever waits for a boot needs this to know when "it has an IP" is an
    /// answer and when it is only an arithmetic identity. It lives on the
    /// backend rather than in a `backend.contains("cloud-hypervisor")` at the
    /// call site for the reason ADR-0008 gives: the knowledge belongs to the
    /// backend that does the predicting.
    fn ip_is_predicted(&self) -> bool {
        false
    }
    // … (excerto)