mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! What a command says about the payload it answers with.
//!
//! # Why this is not in the file that publishes the rest of the contract
//!
//! Inputs, effects, failures and the envelope are each a handful of lines
//! reading from somewhere else: the parser, a short table, the closed category
//! set. The payload is different in kind — it is a description of every field
//! of every command, and it grew until it was most of the file it lived in and
//! pushed that file against the ceiling this project holds every file to.
//!
//! The cut follows the subject rather than the line count. Everything here
//! answers one question, "what comes back", and nothing here is consulted by
//! the parts that answer the other four.

use serde_json::{json, Value};

/// The table itself, whose entries are the reason this module exists.
mod shapes;

use shapes::all as described_shapes;

/// Fields a described payload carries only sometimes, and what brings them.
///
/// # Why this is not simply variation
///
/// [`DATA_SHAPE_VARIES`] is for a command that answers with a different set of
/// fields depending on what was asked, where publishing any one set would be
/// wrong most of the time. This is the narrower case: the set is the same
/// except that one field arrives when something specific is asked for. Filing
/// that as variation would throw away a description that is correct and useful,
/// and tell a caller to validate nothing when almost everything is fixed.
///
/// # Why it is written rather than inferred
///
/// The proof that holds these tables runs each command and compares field names
/// in both directions. A field that appears in one invocation and not another
/// makes that comparison fail against one of them no matter which is right, so
/// the proof has to be told which absences are allowed. Being told is the whole
/// value: an absence nobody declared is a shape nobody checked.
///
/// This exists because a review found `meta commands --with-globals` emitting a
/// field the table did not describe. The table said the shape was fixed, the
/// command disagreed when a real and valid flag was passed, and the proof did
/// not notice because it ran the command one way.
const CONDITIONAL_FIELDS: &[(&str, &str, &str)] = &[
    (
        "meta commands",
        "globals",
        "arrives only with `--with-globals`, because the invocation-wide flags are \
         published once here rather than repeated under all sixty-three commands",
    ),
    (
        "conn test",
        "warning",
        "arrives only when the server gave cause for one, so its absence is the \
         ordinary answer and never a field that went missing",
    ),
];

/// Every declared absence, as command and field, for a proof to walk.
#[must_use]
pub fn conditional_fields() -> Vec<(&'static str, &'static str)> {
    CONDITIONAL_FIELDS
        .iter()
        .map(|(leaf, field, _)| (*leaf, *field))
        .collect()
}

/// Whether one field of one command's payload is allowed to be absent.
#[must_use]
pub fn field_is_conditional(command: &str, field: &str) -> bool {
    CONDITIONAL_FIELDS
        .iter()
        .any(|(leaf, name, _)| *leaf == command && *name == field)
}

/// Commands whose payload shape is decided by the arguments, not by the command.
///
/// A third answer was needed because two were not enough to be honest. A fixed
/// list of fields is right for most commands and false for these: `meta schema`
/// answers with a list when asked for everything, with a contract when asked
/// about one command, with a different contract when asked about a group, and
/// with a longer one when that command marks absence in some field. Publishing
/// any one of those as *the* shape would be a table that is wrong four times
/// out of five.
///
/// Saying only that the shape is not published would also be wrong, because it
/// reads as work not yet done rather than as a property of the command. A
/// caller told the reason can decide what to do about it; a caller told the
/// limit cannot tell the two apart.
const DATA_SHAPE_VARIES: &[(&str, &str)] = &[(
    "meta schema",
    "this command answers with a different set of fields depending on what was asked: a listing \
     when nothing is named, a contract when a command is named, a shorter one when a group is \
     named, and one further field when the named command marks absence; validate the answer you \
     asked for rather than a single published shape",
)];

/// The published fields of one command's `data`, or the limit stated for it.
///
/// Written as one answer rather than two so a caller never has to branch on
/// whether the description exists: the field is always there, and it either
/// describes the payload or says in that same place that it does not.
#[must_use]
pub fn data_shape_of(command: &str) -> Value {
    if let Some((_, why)) = DATA_SHAPE_VARIES.iter().find(|(name, _)| *name == command) {
        return json!({ "shape_varies_by_input": why });
    }

    let Some((_, fields)) = described_shapes().find(|(name, _)| *name == command) else {
        return json!({
            "declared_limit": "the fields of `data` are not published for this command in this \
                 build; a caller that must validate them reads them from an answer and not from \
                 here",
        });
    };

    let mut shape = serde_json::Map::new();
    for (field, about) in *fields {
        // A field that only sometimes arrives is said to only sometimes arrive.
        // Publishing it beside the always-present ones with no mark would tell
        // a caller to expect it every time, which is a smaller lie than leaving
        // it out and still a lie.
        let described = CONDITIONAL_FIELDS
            .iter()
            .find(|(leaf, name, _)| *leaf == command && name == field)
            .map_or_else(
                || (*about).to_owned(),
                |(_, _, when)| format!("{about}; {when}"),
            );
        shape.insert((*field).to_owned(), Value::String(described));
    }
    Value::Object(shape)
}

/// Every command whose `data` this build describes, for a proof to walk.
///
/// Published as a function rather than left to the constant so the proof that
/// counts the covered commands and the proof that runs each of them read the
/// same list, and neither can drift from what a caller is actually told.
#[must_use]
pub fn commands_with_published_data() -> Vec<&'static str> {
    described_shapes().map(|(name, _)| *name).collect()
}

/// Every command that publishes a reason instead of a shape, for a proof to walk.
#[must_use]
pub fn commands_whose_data_varies() -> Vec<&'static str> {
    DATA_SHAPE_VARIES.iter().map(|(name, _)| *name).collect()
}