aion_package/declared_command/

contract.rs

//! The emitted form of a declared command, and the render that turns it plus
//! a parameter set into a process invocation.
//!
//! # Why the wire carries a template and not a string
//!
//! A command declared in AWL (`command <name>(…)` with `program`, `arg`,
//! `env`, `cwd`, `hardening` and `timeout` clauses) is a typed argument LIST.
//! The defect family the whole surface exists to close is the one where a
//! command is carried as text and re-split by whatever runs it: a value
//! containing a space becomes two arguments, a value beginning with `-`
//! becomes an option, a value containing a quote becomes anything at all.
//!
//! So the wire form is the emitter's own shapes with the parameter values
//! still absent: literal program words, one entry per argv slot, and a fill
//! template per slot whose holes name declared parameters. Nothing here is
//! ever joined into a command line, and nothing that reads it re-splits one.
//!
//! # One render, three callers
//!
//! [`DeclaredCommandContract::render`] is the ONLY place a declaration and a
//! parameter set become an argv. The AWL emitter calls it (mapping its
//! refusals back onto source spans), the server's declared-body dispatcher
//! calls it, and the `aion worker awl` executor calls it. A second
//! implementation anywhere would be a second answer to "what does this
//! command actually run".

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};

use super::error::{RenderError, shape_word};
use super::template::{ArgumentValue, FillTemplate};

/// The end-of-options marker the language knows. The bytes are the contract.
pub const END_OF_OPTIONS_MARKER: &str = "--";

/// One declared parameter of a command, as the emitter sees it.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct CommandParameterContract {
    /// The parameter's name — the only thing a hole may name.
    pub name: String,
    /// Whether the declared type is a list, and so whether a supplied value
    /// must be one.
    pub list: bool,
    /// The default this parameter takes when a parameter set omits it.
    ///
    /// A default is itself a template and may read parameters declared
    /// BEFORE it, which is why binding walks the declared order. Absence is a
    /// legal declared state: a parameter with neither a supplied value nor a
    /// default has nothing for this surface to invent, and refuses.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub default: Option<FillTemplate>,
}

/// One argv slot: the template that fills it and whether it may begin with a
/// dash.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct ArgvSlot {
    /// The fill that produces this slot's element (or elements, for the one
    /// list-typed tail).
    pub fill: FillTemplate,
    /// How a refusal names this slot: the argument's declared name, or its
    /// literal text.
    pub label: String,
    /// Whether an element beginning with `-` is admitted here.
    ///
    /// `false` means the receiving program is still reading options at this
    /// position and no `--` stands before it, so leading-dash bytes could not
    /// be told from an option. The condition is computed from the ARGUMENT
    /// LIST at compile time and travels here as a fact, never as a keyword an
    /// author could write to switch the refusal off.
    pub admits_leading_dash: bool,
}

/// One declared environment binding.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct EnvBindingContract {
    /// The variable name.
    pub name: String,
    /// The fill that produces its value.
    pub value: FillTemplate,
}

/// The emitted, executable form of one declared command.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct DeclaredCommandContract {
    /// The declaration's own name, carried so a refusal can say which command
    /// it is talking about.
    pub name: String,
    /// The declared parameters, in declared order.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub parameters: Vec<CommandParameterContract>,
    /// The invocation: the program and the subcommand words that qualify it,
    /// as literal argv elements. Never a fill — a caller-supplied value must
    /// never choose which program executes.
    pub program: Vec<String>,
    /// The argument slots, in declared order, which IS the argv order.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub args: Vec<ArgvSlot>,
    /// The declared environment bindings, in declared order.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub env: Vec<EnvBindingContract>,
    /// The declared working directory, verbatim — any `{workspace_root}`
    /// placeholder unexpanded, because expanding it is the executing side's
    /// act against ITS workspace.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cwd: Option<String>,
    /// The hardened `PATH`, if the declaration states one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub hardened_path: Option<FillTemplate>,
    /// The declared timeout in milliseconds, if the declaration states one.
    ///
    /// `None` means the declaration stated NONE, and that is a legal declared
    /// state. Nothing here substitutes a ceiling: a number this surface
    /// invented would be indistinguishable from one an author chose.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub timeout_ms: Option<i64>,
    /// Who owns the declared timeout, when there is one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub timeout_owner: Option<String>,
}

/// A resolved command line: the argv, the environment, the working directory
/// and the declared ceilings.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RenderedCommand {
    /// The argv, one whole element per entry. Never joined into a string.
    pub argv: Vec<String>,
    /// The environment bindings, in declared order.
    pub env: Vec<(String, String)>,
    /// The declared working directory, verbatim.
    pub cwd: Option<String>,
    /// The hardened `PATH`, if the declaration states one.
    pub hardened_path: Option<String>,
    /// The declared timeout in milliseconds, if the declaration states one.
    pub timeout_ms: Option<i64>,
    /// Who owns the declared timeout, when there is one.
    pub timeout_owner: Option<String>,
}

impl DeclaredCommandContract {
    /// Every parameter name this command declares, in declared order.
    #[must_use]
    pub fn parameter_names(&self) -> Vec<&str> {
        self.parameters
            .iter()
            .map(|parameter| parameter.name.as_str())
            .collect()
    }

    /// Resolve this command against `supplied`.
    ///
    /// `supplied` must name only parameters this command declares — a name it
    /// does not is refused rather than ignored, because a value nothing
    /// consumes is a value nobody reviewed. A caller holding a WIDER set (an
    /// action's parameters, say, of which the command uses some) narrows it
    /// first with [`Self::parameter_names`].
    ///
    /// # Errors
    ///
    /// Returns the first refusal the resolution earns: an undeclared or
    /// missing argument, a shape mismatch against a declared type, or a
    /// leading-dash operand standing where the program still reads options.
    pub fn render(
        &self,
        supplied: &BTreeMap<String, ArgumentValue>,
    ) -> Result<RenderedCommand, RenderError> {
        let bound = self.bind(supplied)?;

        let mut argv = self.program.clone();
        for slot in &self.args {
            for element in resolve(&slot.fill, &bound) {
                // THE CURE, at the bytes. Read off the slot's recorded
                // position, never off a declared property, so a declaration
                // cannot exempt itself.
                if !slot.admits_leading_dash && element.starts_with('-') {
                    return Err(RenderError::LeadingDashOperand {
                        command: self.name.clone(),
                        argument: slot.label.clone(),
                        element,
                        marker: END_OF_OPTIONS_MARKER,
                    });
                }
                argv.push(element);
            }
        }

        Ok(RenderedCommand {
            argv,
            env: self
                .env
                .iter()
                .map(|binding| (binding.name.clone(), join(&resolve(&binding.value, &bound))))
                .collect(),
            cwd: self.cwd.clone(),
            hardened_path: self
                .hardened_path
                .as_ref()
                .map(|path| join(&resolve(path, &bound))),
            timeout_ms: self.timeout_ms,
            timeout_owner: self.timeout_owner.clone(),
        })
    }

    /// Every declared parameter's value: supplied, or its declared default.
    fn bind(
        &self,
        supplied: &BTreeMap<String, ArgumentValue>,
    ) -> Result<BTreeMap<String, ArgumentValue>, RenderError> {
        for name in supplied.keys() {
            if !self.parameters.iter().any(|item| item.name == *name) {
                return Err(RenderError::ArgumentUndeclared {
                    command: self.name.clone(),
                    parameter: name.clone(),
                });
            }
        }

        let mut bound: BTreeMap<String, ArgumentValue> = BTreeMap::new();
        for parameter in &self.parameters {
            // No third branch, deliberately: a parameter with neither a
            // supplied value nor a declared default has nothing for this
            // surface to invent.
            let value = if let Some(value) = supplied.get(&parameter.name) {
                if value.is_list() != parameter.list {
                    return Err(RenderError::ArgumentTypeMismatch {
                        command: self.name.clone(),
                        parameter: parameter.name.clone(),
                        observed: value.describe(),
                        declared: shape_word(parameter.list),
                        supplied: shape_word(value.is_list()),
                    });
                }
                value.clone()
            } else {
                let Some(default) = &parameter.default else {
                    return Err(RenderError::ArgumentMissing {
                        command: self.name.clone(),
                        parameter: parameter.name.clone(),
                    });
                };
                ArgumentValue::Scalar(join(&resolve(default, &bound)))
            };
            bound.insert(parameter.name.clone(), value);
        }
        Ok(bound)
    }
}

/// A fill resolved against bound values, as whole argv elements.
///
/// One element for every shape but the variadic tail: a fill that is exactly
/// one list-bound hole becomes one element per item, which is the only way a
/// list reaches an argv. Every other fill is one element, whatever it
/// contains — a space inside a value is a space inside that one element and
/// never a new argument, because nothing re-splits it.
fn resolve(fill: &FillTemplate, bound: &BTreeMap<String, ArgumentValue>) -> Vec<String> {
    if let Some(name) = fill.sole_hole()
        && let Some(ArgumentValue::List(items)) = bound.get(name)
    {
        return items.clone();
    }
    let mut element = String::new();
    for piece in &fill.pieces {
        match piece {
            super::template::FillPiece::Literal { text } => element.push_str(text),
            super::template::FillPiece::Hole { parameter } => match bound.get(parameter.as_str()) {
                Some(ArgumentValue::Scalar(value)) => element.push_str(value),
                // A list written into a larger word is refused at the AWL
                // check layer, so this arm is reached only by a caller that
                // skipped the checker; joining is then the least surprising
                // answer and is never silent, because the check refusal
                // already named it.
                Some(ArgumentValue::List(items)) => element.push_str(&items.join(" ")),
                None => {}
            },
        }
    }
    vec![element]
}

/// One string from resolved elements, for the places an argv element is not
/// what is wanted: an environment value and a `PATH` are each one string.
fn join(elements: &[String]) -> String {
    elements.join(" ")
}