From e786504e119fcf31764c14ccfd77a885a77d6180 Mon Sep 17 00:00:00 2001 From: Helight Date: Sun, 15 Nov 2026 16:56:59 +0100 Subject: [PATCH 1/4] feat(core): collections of a provisioner, declared in its manifest and listed by its status --- crates/berth-api/src/types.rs | 129 ++++++++++ crates/berth-core/src/plugins.rs | 357 ++++++++++++++++++++++++++- crates/berth-core/src/provisioner.rs | 119 +++++++++ docs/openapi/berth.openapi.json | 190 ++++++++++++++ docs/openapi/berth.operations.json | 190 ++++++++++++++ 5 files changed, 984 insertions(+), 1 deletion(-) diff --git a/crates/berth-api/src/types.rs b/crates/berth-api/src/types.rs index a0e9b53..b6c3e73 100644 --- a/crates/berth-api/src/types.rs +++ b/crates/berth-api/src/types.rs @@ -615,6 +615,11 @@ pub struct Action { /// What plugins add to it, in the order they run. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub steps: Vec, + /// The id of the provisioner's collection it belongs to, whose items it + /// makes, acts on or lists. The screens offer it there and not on the + /// provisioner's page. + #[serde(default, skip_serializing_if = "String::is_empty")] + pub collection: String, } impl Default for Action { @@ -633,6 +638,7 @@ impl Default for Action { available: true, why: String::new(), steps: vec![], + collection: String::new(), } } } @@ -1183,6 +1189,10 @@ pub struct ProvisionerInfo { /// Its plugin's own actions, such as listing images or pruning. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub actions: Vec, + /// What it holds that can be listed, such as storage pools, each with + /// the actions of its items. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub collections: Vec, /// Why it cannot be used here, as a sentence that says what to change. /// Empty when it can. #[serde(default, skip_serializing_if = "String::is_empty")] @@ -1276,6 +1286,125 @@ pub struct ProvisionerState { /// berth's records of what it made, with what its own list says. #[serde(default)] pub resources: Vec, + /// The items of each of its collections, by the collection's id, as its + /// status gave them. + #[serde(default, skip_serializing_if = "BTreeMap::is_empty")] + pub collections: BTreeMap>, +} + +/// A list of things a provisioner holds, such as the storage pools of a +/// server. Its items come with the provisioner's status, and its actions are +/// the provisioner's own: some make an item, some act on one item, whose +/// key fills their arguments, and some act on the whole list. +#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, ToSchema)] +pub struct Collection { + pub id: String, + /// What one item is called, such as `Storage pool`. + #[serde(default)] + pub label: String, + /// What several are called, such as `Storage pools`. + #[serde(default)] + pub plural: String, + #[serde(default, skip_serializing_if = "String::is_empty")] + pub help: String, + /// The group of the provisioner's page it is listed in. + #[serde(default, skip_serializing_if = "String::is_empty")] + pub group: String, + /// The names that identify an item, such as `pool` and `volume`. A + /// collection within another starts with that one's key. + pub key: Vec, + /// The collection whose items hold these, such as the pools that hold + /// volumes. Each item of that one lists those that belong to it. + #[serde(default, skip_serializing_if = "String::is_empty")] + pub within: String, + /// The kinds of resource that are its items, such as `machine`, in + /// place of items the status gives: its item actions are offered on + /// the page of each resource of those kinds the provisioner made. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub kinds: Vec, + /// The values each item shows besides its name, in order. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub columns: Vec, + /// The actions that make a new item. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub new: Vec, + /// The actions on one item. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub item: Vec, + /// The actions on the whole list, such as pruning. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub list: Vec, + /// The item action that removes one. + #[serde(default, skip_serializing_if = "String::is_empty")] + pub remove: String, + /// The action that prints the list for the command line, which the + /// screens show as the table instead. + #[serde(default, skip_serializing_if = "String::is_empty")] + pub show: String, +} + +/// A value an item of a collection shows. +#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, ToSchema)] +pub struct CollectionColumn { + pub name: String, + #[serde(default)] + pub label: String, +} + +/// An action of a provisioner as one of a collection's. +#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, ToSchema)] +pub struct CollectionAction { + /// The provisioner's action, by its name. + pub action: String, + /// What it is called where its item is known already, such as `Grow`. + /// The action's own label when empty. + #[serde(default, skip_serializing_if = "String::is_empty")] + pub label: String, + /// The argument of the action each part of the key fills, where its + /// name is not the part's own: `{"volume": "name"}`. + #[serde(default, skip_serializing_if = "BTreeMap::is_empty")] + pub arguments: BTreeMap, +} + +impl CollectionAction { + /// The argument of the action the part `part` of a key fills. + pub fn argument<'a>(&'a self, part: &'a str) -> &'a str { + self.arguments.get(part).map_or(part, String::as_str) + } +} + +/// One item of a collection, as the provisioner's status gives it. +#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, ToSchema)] +pub struct CollectionItem { + pub name: String, + /// The value of each part of the collection's key. + #[serde(default)] + pub key: BTreeMap, + /// The value of each column, by its name. + #[serde(default, skip_serializing_if = "BTreeMap::is_empty")] + pub columns: BTreeMap, + /// The item actions that cannot run on it, each with why not. + #[serde(default, skip_serializing_if = "BTreeMap::is_empty")] + pub unavailable: BTreeMap, +} + +impl Collection { + /// The label of a column, by its name. + pub fn column_label<'a>(&'a self, column: &'a CollectionColumn) -> &'a str { + match column.label.is_empty() { + true => &column.name, + false => &column.label, + } + } + + /// The action of the collection called `name`, of any of its sorts. + pub fn find(&self, name: &str) -> Option<&CollectionAction> { + self.new + .iter() + .chain(&self.item) + .chain(&self.list) + .find(|known| known.action == name) + } } /// A berth secret a resource is given in its environment, by name. Its diff --git a/crates/berth-core/src/plugins.rs b/crates/berth-core/src/plugins.rs index e2a884f..5e8bf84 100644 --- a/crates/berth-core/src/plugins.rs +++ b/crates/berth-core/src/plugins.rs @@ -177,6 +177,8 @@ pub struct Provisioner { pub kinds: Vec, /// Its own actions, each run with the verb `act`. pub actions: Vec, + /// What it holds that can be listed, with the actions of their items. + pub collections: Vec, /// Why berth does not run it, as a sentence that says what to change. pub refused: Option, } @@ -213,6 +215,7 @@ impl Provisioner { node: String::new(), kinds: self.kinds.clone(), actions: self.actions.clone(), + collections: self.collections.clone(), problem: self.refused.clone().unwrap_or_default(), } } @@ -482,6 +485,7 @@ fn provisioner_actions(entries: &Value, reading: berth_api::ops::Role) -> Vec Option (vec![], vec![]), None => ( provisioner_kinds(&entry["kinds"]), provisioner_actions(&entry["actions"], berth_api::ops::Role::View), ), }; + let (collections, refused) = match refused { + Some(refused) => (vec![], Some(refused)), + None => match provisioner_collections(&entry["collections"], &mut actions, &kinds) { + Ok(collections) => (collections, None), + Err(why) => ( + vec![], + Some(format!( + "{plugin}/{id} declares its collections wrong: {why}. Its manifest has to be fixed" + )), + ), + }, + }; let machine = kinds.iter().find(|kind| kind.id == MACHINE); let setup = match machine.map(|kind| kind.setup.as_str()) { Some("seed") => Setup::Seed, @@ -593,10 +609,172 @@ fn read_provisioner(plugin: &str, entry: &Value, dir: &Path) -> Option std::result::Result, String> { + let Some(entries) = entries.as_array() else { + return match entries.is_null() { + true => Ok(vec![]), + false => Err("collections is not a list".into()), + }; + }; + let mut collections: Vec = vec![]; + for entry in entries { + let mut collection: berth_api::Collection = serde_json::from_value(entry.clone()) + .map_err(|error| format!("a collection does not read: {error}"))?; + let id = collection.id.clone(); + if !valid_name(&id) { + return Err(format!("{id:?} is not a name for a collection")); + } + if collections.iter().any(|known| known.id == id) { + return Err(format!("the collection {id} is declared twice")); + } + if collection.label.is_empty() { + collection.label = id.clone(); + } + if collection.plural.is_empty() { + collection.plural = collection.label.clone(); + } + if collection.key.is_empty() || collection.key.iter().any(|part| !valid_name(part)) { + return Err(format!( + "the collection {id} needs a key of argument names, such as [\"pool\"]" + )); + } + let mut parent: Vec = vec![]; + if !collection.within.is_empty() { + let Some(holder) = collections + .iter() + .find(|known| known.id == collection.within) + else { + return Err(format!( + "the collection {id} is within {}, which is not declared before it", + collection.within + )); + }; + if !holder.kinds.is_empty() + || collection.key.len() <= holder.key.len() + || !collection.key.starts_with(&holder.key) + { + return Err(format!( + "the key of {id} has to start with the key of {}, {}, and name more", + holder.id, + holder.key.join(" ") + )); + } + parent = holder.key.clone(); + } + for kind in &collection.kinds { + if !kinds.iter().any(|known| &known.id == kind) { + return Err(format!("the collection {id} has items of no kind {kind}")); + } + } + if !collection.kinds.is_empty() + && (collection.key.len() != 1 + || !collection.within.is_empty() + || !collection.new.is_empty() + || !collection.list.is_empty()) + { + return Err(format!( + "the collection {id} of resources has a key of one name, and only item actions" + )); + } + let mut seen: Vec<&str> = vec![]; + for column in &collection.columns { + if column.name.is_empty() || seen.contains(&column.name.as_str()) { + return Err(format!( + "the columns of {id} need names, each once: {:?}", + column.name + )); + } + seen.push(&column.name); + } + // What fills an action's arguments: the whole key on an item, the + // key of the item it is within when new or on the list. + let sorts = [ + ("new", &collection.new, &parent), + ("item", &collection.item, &collection.key), + ("list", &collection.list, &parent), + ]; + for (sort, listed, filled) in sorts { + for used in listed { + let Some(action) = actions.iter_mut().find(|known| known.name == used.action) + else { + return Err(format!( + "{id} names the action {}, which the provisioner does not have", + used.action + )); + }; + if !action.collection.is_empty() && action.collection != id { + return Err(format!( + "the action {} is in the collections {} and {id}; it can be in one", + used.action, action.collection + )); + } + for part in used.arguments.keys() { + if !collection.key.contains(part) { + return Err(format!( + "{id} fills an argument of {} from {part}, which is not in its key", + used.action + )); + } + } + for part in filled { + let argument = used.argument(part); + if !action.arguments.iter().any(|known| known.name == argument) { + return Err(format!( + "{id} fills the argument {argument} of {} from its {sort}'s {part}, and {} has no argument {argument}", + used.action, used.action + )); + } + } + action.collection = id.clone(); + } + } + if !collection.remove.is_empty() + && !collection + .item + .iter() + .any(|known| known.action == collection.remove) + { + return Err(format!( + "{id} removes an item with {}, which is none of its item actions", + collection.remove + )); + } + if !collection.show.is_empty() { + let Some(action) = actions + .iter_mut() + .find(|known| known.name == collection.show) + else { + return Err(format!( + "{id} is shown by the action {}, which the provisioner does not have", + collection.show + )); + }; + if action.changes || !action.collection.is_empty() { + return Err(format!( + "{id} is shown by the action {}, which has to only read and be in no other collection", + collection.show + )); + } + action.collection = id.clone(); + } + collections.push(collection); + } + Ok(collections) +} + // ── Managing them ─────────────────────────────────────────────────────────── /// Where the user's own plugins are kept, under a configuration directory. @@ -1214,6 +1392,183 @@ mod tests { assert_eq!(extra.channels[0].keep, Some(berth_api::Keep::None)); } + /// The provisioner `vm` of a plugin whose manifest declares `collections` + /// beside a few actions and the kinds machine and instance. + fn with_collections(collections: &str) -> Provisioner { + let base = tempfile::tempdir().unwrap(); + let dir = base.path().join("plugins/cloud"); + fs::create_dir_all(dir.join("bin")).unwrap(); + fs::write(dir.join("bin/provision"), "#!/bin/sh\n").unwrap(); + let manifest = format!( + r#"{{"name": "berth-plugin-cloud", "berth": {{"provisioners": [ + {{"id": "vm", "command": "bin/provision", "protocol": 2, + "kinds": [{{"id": "machine", "setup": "apply"}}, {{"id": "instance"}}], + "actions": [ + {{"name": "pools", "changes": false}}, + {{"name": "new-pool", "arguments": [{{"name": "name"}}]}}, + {{"name": "grow-pool", "arguments": [{{"name": "pool"}}, {{"name": "size"}}]}}, + {{"name": "remove-pool", "arguments": [{{"name": "name"}}]}}, + {{"name": "new-volume", "arguments": [{{"name": "pool"}}, {{"name": "name"}}]}}, + {{"name": "remove-volume", "arguments": [{{"name": "pool"}}, {{"name": "name"}}]}}, + {{"name": "grow-disk", "arguments": [{{"name": "instance"}}, {{"name": "size"}}]}}, + {{"name": "clean"}}, {{"name": "check", "changes": false}}], + "collections": {collections}}}]}}}}"# + ); + fs::write(dir.join("package.json"), manifest).unwrap(); + load(&[base.path().join("plugins")]) + .remove(0) + .provisioners + .remove(0) + } + + #[test] + fn collections_name_their_actions_and_mark_them() { + let vm = with_collections( + r#"[{"id": "pools", "label": "Storage pool", "key": ["pool"], + "columns": [{"name": "driver", "label": "Driver"}], + "new": [{"action": "new-pool"}], "list": [{"action": "clean"}], + "item": [{"action": "grow-pool", "label": "Grow"}, + {"action": "remove-pool", "arguments": {"pool": "name"}}], + "remove": "remove-pool", "show": "pools"}, + {"id": "volumes", "label": "Volume", "plural": "Volumes", "key": ["pool", "volume"], + "within": "pools", "new": [{"action": "new-volume"}], + "item": [{"action": "remove-volume", "arguments": {"volume": "name"}}]}, + {"id": "disks", "key": ["instance"], "kinds": ["machine", "instance"], + "item": [{"action": "grow-disk"}]}]"#, + ); + assert!(vm.refused.is_none(), "{:?}", vm.refused); + let ids: Vec<&str> = vm + .collections + .iter() + .map(|known| known.id.as_str()) + .collect(); + assert_eq!(ids, ["pools", "volumes", "disks"]); + // The plural is the label when it is not given. + assert_eq!(vm.collections[0].plural, "Storage pool"); + assert_eq!(vm.collections[1].item[0].argument("volume"), "name"); + assert_eq!(vm.collections[1].item[0].argument("pool"), "pool"); + let marked: Vec<(&str, &str)> = vm + .actions + .iter() + .map(|action| (action.name.as_str(), action.collection.as_str())) + .collect(); + assert_eq!( + marked, + [ + ("pools", "pools"), + ("new-pool", "pools"), + ("grow-pool", "pools"), + ("remove-pool", "pools"), + ("new-volume", "volumes"), + ("remove-volume", "volumes"), + ("grow-disk", "disks"), + ("clean", "pools"), + ("check", "") + ] + ); + assert_eq!(vm.info("cloud", vec![]).collections, vm.collections); + } + + #[test] + fn a_collection_that_names_what_is_not_there_refuses_the_provisioner() { + for (collections, said) in [ + ( + r#"[{"id": "pools", "key": ["pool"], "item": [{"action": "shrink-pool"}]}]"#, + "pools names the action shrink-pool, which the provisioner does not have", + ), + ( + r#"[{"id": "pools", "key": ["pool"], "item": [{"action": "remove-pool"}]}]"#, + "remove-pool has no argument pool", + ), + ( + r#"[{"id": "pools", "key": ["pool"], + "item": [{"action": "remove-pool", "arguments": {"name": "name"}}]}]"#, + "from name, which is not in its key", + ), + ( + r#"[{"id": "volumes", "key": ["pool", "volume"], "within": "pools"}]"#, + "is within pools, which is not declared before it", + ), + ( + r#"[{"id": "pools", "key": ["pool"]}, + {"id": "volumes", "key": ["volume"], "within": "pools"}]"#, + "has to start with the key of pools", + ), + ( + r#"[{"id": "pools", "key": ["pool"]}, + {"id": "volumes", "key": ["pool", "volume"], "within": "pools", + "new": [{"action": "new-pool"}]}]"#, + "new-pool has no argument pool", + ), + ( + r#"[{"id": "disks", "key": ["instance"], "kinds": ["deployment"]}]"#, + "has items of no kind deployment", + ), + ( + r#"[{"id": "pools", "key": ["pool"], "remove": "remove-pool"}]"#, + "which is none of its item actions", + ), + ( + r#"[{"id": "pools", "key": ["pool"], "show": "clean"}]"#, + "has to only read", + ), + ( + r#"[{"id": "a", "key": ["pool"], "list": [{"action": "clean"}]}, + {"id": "b", "key": ["pool"], "list": [{"action": "clean"}]}]"#, + "clean is in the collections a and b", + ), + (r#"[{"id": "pools"}]"#, "does not read"), + (r#"[{"id": "pools", "key": []}]"#, "needs a key"), + (r#"{"pools": {}}"#, "collections is not a list"), + ] { + let vm = with_collections(collections); + let refused = vm.refused.unwrap_or_default(); + assert!(refused.contains(said), "{said:?} in {refused:?}"); + assert!( + refused.starts_with("cloud/vm declares its collections wrong: "), + "{refused}" + ); + assert!(vm.collections.is_empty()); + } + } + + #[test] + fn the_shipped_provisioners_declare_their_collections_right() { + let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../plugins"); + let plugins = load(&[root]); + for (plugin, provisioner, collections) in [ + ( + "incus", + "vm", + vec!["pools", "volumes", "images", "instances"], + ), + ( + "incus", + "container", + vec!["pools", "volumes", "images", "instances"], + ), + ("docker", "container", vec!["images", "volumes"]), + ] { + let found = plugins + .iter() + .find(|known| known.id == plugin) + .and_then(|known| { + known + .provisioners + .iter() + .find(|known| known.id == provisioner) + }) + .unwrap(); + assert!(found.refused.is_none(), "{:?}", found.refused); + let ids: Vec<&str> = found + .collections + .iter() + .map(|known| known.id.as_str()) + .collect(); + assert_eq!(ids, collections); + } + } + #[test] fn provisioners_are_read_and_their_commands_kept_inside_the_package() { let base = tempfile::tempdir().unwrap(); diff --git a/crates/berth-core/src/provisioner.rs b/crates/berth-core/src/provisioner.rs index ac7504e..49440db 100644 --- a/crates/berth-core/src/provisioner.rs +++ b/crates/berth-core/src/provisioner.rs @@ -391,6 +391,62 @@ pub(crate) fn details(answer: &Value) -> Vec { .collect() } +/// The text of a value of an answer: a string as it is, nothing as empty, +/// and anything else as JSON. +fn said(value: &Value) -> String { + match value { + Value::String(text) => text.clone(), + Value::Null => String::new(), + other => other.to_string(), + } +} + +/// The items of each collection in the `collections` of a status: those +/// given for a collection that is declared, each with every part of its key. +/// The key of one that names a single part may be left out: it is the +/// item's name. +pub(crate) fn items( + declared: &[berth_api::Collection], + given: &Value, +) -> BTreeMap> { + let mut found = BTreeMap::new(); + for collection in declared.iter().filter(|known| known.kinds.is_empty()) { + let Some(rows) = given[&collection.id].as_array() else { + continue; + }; + let texts = |value: &Value| -> BTreeMap { + value + .as_object() + .into_iter() + .flatten() + .map(|(key, value)| (key.clone(), said(value))) + .collect() + }; + let listed: Vec = rows + .iter() + .filter_map(|row| { + let name = said(&row["name"]); + let mut key = texts(&row["key"]); + if let [part] = collection.key.as_slice() { + key.entry(part.clone()).or_insert_with(|| name.clone()); + } + let whole = collection + .key + .iter() + .all(|part| key.get(part).is_some_and(|value| !value.is_empty())); + (whole && !name.is_empty()).then(|| berth_api::CollectionItem { + name, + key, + columns: texts(&row["columns"]), + unavailable: texts(&row["unavailable"]), + }) + }) + .collect(); + found.insert(collection.id.clone(), listed); + } + found +} + /// The page of a provisioner: what it says of itself now, and the resources /// berth made with it with what its own list says of them. `given` are values of its own arguments for this /// once, such as another server to ask. @@ -451,6 +507,7 @@ pub fn state( state.values.insert(argument.clone(), offered); } } + state.collections = items(&provisioner.collections, &answer["collections"]); } Err(error) => { state.state = "unreachable".into(); @@ -1154,3 +1211,65 @@ pub(crate) fn stream( .into()), } } + +#[cfg(test)] +mod tests { + use super::*; + use berth_api::{Collection, CollectionItem}; + + #[test] + fn the_items_of_a_status_are_taken_with_their_whole_key() { + let declared = vec![ + Collection { + id: "pools".into(), + key: vec!["pool".into()], + ..Collection::default() + }, + Collection { + id: "volumes".into(), + key: vec!["pool".into(), "volume".into()], + within: "pools".into(), + ..Collection::default() + }, + Collection { + id: "disks".into(), + key: vec!["instance".into()], + kinds: vec!["machine".into()], + ..Collection::default() + }, + ]; + let given = json!({ + "pools": [ + {"name": "default", "columns": {"driver": "zfs", "size": 100}, + "unavailable": {"remove-pool": "It holds volumes"}}, + {"name": ""} + ], + "volumes": [ + {"name": "data", "key": {"pool": "default", "volume": "data"}}, + {"name": "half", "key": {"volume": "half"}} + ], + "disks": [{"name": "berth-studio"}], + "unknown": [{"name": "x"}] + }); + let found = items(&declared, &given); + // The single part of a key is the name; a row without its whole key is left out. + assert_eq!( + found["pools"], + [CollectionItem { + name: "default".into(), + key: [("pool".to_owned(), "default".to_owned())].into(), + columns: [ + ("driver".to_owned(), "zfs".to_owned()), + ("size".to_owned(), "100".to_owned()) + ] + .into(), + unavailable: [("remove-pool".to_owned(), "It holds volumes".to_owned())].into(), + }] + ); + assert_eq!(found["volumes"].len(), 1); + assert_eq!(found["volumes"][0].key["pool"], "default"); + // Items of resources come from berth's records, and what is not declared is not taken. + assert_eq!(found.keys().collect::>(), ["pools", "volumes"]); + assert!(items(&declared, &Value::Null).is_empty()); + } +} diff --git a/docs/openapi/berth.openapi.json b/docs/openapi/berth.openapi.json index f541575..22f070f 100644 --- a/docs/openapi/berth.openapi.json +++ b/docs/openapi/berth.openapi.json @@ -119,6 +119,10 @@ "description": "False when it only reads, and may be called at any time.", "type": "boolean" }, + "collection": { + "description": "The id of the provisioner's collection it belongs to, whose items it\nmakes, acts on or lists. The screens offer it there and not on the\nprovisioner's page.", + "type": "string" + }, "confirm": { "description": "The question to answer yes to before it runs.", "type": [ @@ -384,6 +388,172 @@ ], "type": "object" }, + "Collection": { + "description": "A list of things a provisioner holds, such as the storage pools of a\nserver. Its items come with the provisioner's status, and its actions are\nthe provisioner's own: some make an item, some act on one item, whose\nkey fills their arguments, and some act on the whole list.", + "properties": { + "columns": { + "description": "The values each item shows besides its name, in order.", + "items": { + "$ref": "#/components/schemas/CollectionColumn" + }, + "type": "array" + }, + "group": { + "description": "The group of the provisioner's page it is listed in.", + "type": "string" + }, + "help": { + "type": "string" + }, + "id": { + "type": "string" + }, + "item": { + "description": "The actions on one item.", + "items": { + "$ref": "#/components/schemas/CollectionAction" + }, + "type": "array" + }, + "key": { + "description": "The names that identify an item, such as `pool` and `volume`. A\ncollection within another starts with that one's key.", + "items": { + "type": "string" + }, + "type": "array" + }, + "kinds": { + "description": "The kinds of resource that are its items, such as `machine`, in\nplace of items the status gives: its item actions are offered on\nthe page of each resource of those kinds the provisioner made.", + "items": { + "type": "string" + }, + "type": "array" + }, + "label": { + "description": "What one item is called, such as `Storage pool`.", + "type": "string" + }, + "list": { + "description": "The actions on the whole list, such as pruning.", + "items": { + "$ref": "#/components/schemas/CollectionAction" + }, + "type": "array" + }, + "new": { + "description": "The actions that make a new item.", + "items": { + "$ref": "#/components/schemas/CollectionAction" + }, + "type": "array" + }, + "plural": { + "description": "What several are called, such as `Storage pools`.", + "type": "string" + }, + "remove": { + "description": "The item action that removes one.", + "type": "string" + }, + "show": { + "description": "The action that prints the list for the command line, which the\nscreens show as the table instead.", + "type": "string" + }, + "within": { + "description": "The collection whose items hold these, such as the pools that hold\nvolumes. Each item of that one lists those that belong to it.", + "type": "string" + } + }, + "required": [ + "id", + "key" + ], + "type": "object" + }, + "CollectionAction": { + "description": "An action of a provisioner as one of a collection's.", + "properties": { + "action": { + "description": "The provisioner's action, by its name.", + "type": "string" + }, + "arguments": { + "additionalProperties": { + "type": "string" + }, + "description": "The argument of the action each part of the key fills, where its\nname is not the part's own: `{\"volume\": \"name\"}`.", + "propertyNames": { + "type": "string" + }, + "type": "object" + }, + "label": { + "description": "What it is called where its item is known already, such as `Grow`.\nThe action's own label when empty.", + "type": "string" + } + }, + "required": [ + "action" + ], + "type": "object" + }, + "CollectionColumn": { + "description": "A value an item of a collection shows.", + "properties": { + "label": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "CollectionItem": { + "description": "One item of a collection, as the provisioner's status gives it.", + "properties": { + "columns": { + "additionalProperties": { + "type": "string" + }, + "description": "The value of each column, by its name.", + "propertyNames": { + "type": "string" + }, + "type": "object" + }, + "key": { + "additionalProperties": { + "type": "string" + }, + "description": "The value of each part of the collection's key.", + "propertyNames": { + "type": "string" + }, + "type": "object" + }, + "name": { + "type": "string" + }, + "unavailable": { + "additionalProperties": { + "type": "string" + }, + "description": "The item actions that cannot run on it, each with why not.", + "propertyNames": { + "type": "string" + }, + "type": "object" + } + }, + "required": [ + "name" + ], + "type": "object" + }, "CommandLine": { "description": "A list of arguments, or one string for `sh -c`.", "oneOf": [ @@ -2026,6 +2196,13 @@ }, "type": "array" }, + "collections": { + "description": "What it holds that can be listed, such as storage pools, each with\nthe actions of its items.", + "items": { + "$ref": "#/components/schemas/Collection" + }, + "type": "array" + }, "description": { "type": "string" }, @@ -2151,6 +2328,19 @@ "ProvisionerState": { "description": "A provisioner's page: what it is, what it says of itself now, and what\nit holds.", "properties": { + "collections": { + "additionalProperties": { + "items": { + "$ref": "#/components/schemas/CollectionItem" + }, + "type": "array" + }, + "description": "The items of each of its collections, by the collection's id, as its\nstatus gave them.", + "propertyNames": { + "type": "string" + }, + "type": "object" + }, "details": { "items": { "$ref": "#/components/schemas/Detail" diff --git a/docs/openapi/berth.operations.json b/docs/openapi/berth.operations.json index 949d662..1c0d200 100644 --- a/docs/openapi/berth.operations.json +++ b/docs/openapi/berth.operations.json @@ -119,6 +119,10 @@ "description": "False when it only reads, and may be called at any time.", "type": "boolean" }, + "collection": { + "description": "The id of the provisioner's collection it belongs to, whose items it\nmakes, acts on or lists. The screens offer it there and not on the\nprovisioner's page.", + "type": "string" + }, "confirm": { "description": "The question to answer yes to before it runs.", "type": [ @@ -346,6 +350,172 @@ ], "type": "object" }, + "Collection": { + "description": "A list of things a provisioner holds, such as the storage pools of a\nserver. Its items come with the provisioner's status, and its actions are\nthe provisioner's own: some make an item, some act on one item, whose\nkey fills their arguments, and some act on the whole list.", + "properties": { + "columns": { + "description": "The values each item shows besides its name, in order.", + "items": { + "$ref": "#/components/schemas/CollectionColumn" + }, + "type": "array" + }, + "group": { + "description": "The group of the provisioner's page it is listed in.", + "type": "string" + }, + "help": { + "type": "string" + }, + "id": { + "type": "string" + }, + "item": { + "description": "The actions on one item.", + "items": { + "$ref": "#/components/schemas/CollectionAction" + }, + "type": "array" + }, + "key": { + "description": "The names that identify an item, such as `pool` and `volume`. A\ncollection within another starts with that one's key.", + "items": { + "type": "string" + }, + "type": "array" + }, + "kinds": { + "description": "The kinds of resource that are its items, such as `machine`, in\nplace of items the status gives: its item actions are offered on\nthe page of each resource of those kinds the provisioner made.", + "items": { + "type": "string" + }, + "type": "array" + }, + "label": { + "description": "What one item is called, such as `Storage pool`.", + "type": "string" + }, + "list": { + "description": "The actions on the whole list, such as pruning.", + "items": { + "$ref": "#/components/schemas/CollectionAction" + }, + "type": "array" + }, + "new": { + "description": "The actions that make a new item.", + "items": { + "$ref": "#/components/schemas/CollectionAction" + }, + "type": "array" + }, + "plural": { + "description": "What several are called, such as `Storage pools`.", + "type": "string" + }, + "remove": { + "description": "The item action that removes one.", + "type": "string" + }, + "show": { + "description": "The action that prints the list for the command line, which the\nscreens show as the table instead.", + "type": "string" + }, + "within": { + "description": "The collection whose items hold these, such as the pools that hold\nvolumes. Each item of that one lists those that belong to it.", + "type": "string" + } + }, + "required": [ + "id", + "key" + ], + "type": "object" + }, + "CollectionAction": { + "description": "An action of a provisioner as one of a collection's.", + "properties": { + "action": { + "description": "The provisioner's action, by its name.", + "type": "string" + }, + "arguments": { + "additionalProperties": { + "type": "string" + }, + "description": "The argument of the action each part of the key fills, where its\nname is not the part's own: `{\"volume\": \"name\"}`.", + "propertyNames": { + "type": "string" + }, + "type": "object" + }, + "label": { + "description": "What it is called where its item is known already, such as `Grow`.\nThe action's own label when empty.", + "type": "string" + } + }, + "required": [ + "action" + ], + "type": "object" + }, + "CollectionColumn": { + "description": "A value an item of a collection shows.", + "properties": { + "label": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "CollectionItem": { + "description": "One item of a collection, as the provisioner's status gives it.", + "properties": { + "columns": { + "additionalProperties": { + "type": "string" + }, + "description": "The value of each column, by its name.", + "propertyNames": { + "type": "string" + }, + "type": "object" + }, + "key": { + "additionalProperties": { + "type": "string" + }, + "description": "The value of each part of the collection's key.", + "propertyNames": { + "type": "string" + }, + "type": "object" + }, + "name": { + "type": "string" + }, + "unavailable": { + "additionalProperties": { + "type": "string" + }, + "description": "The item actions that cannot run on it, each with why not.", + "propertyNames": { + "type": "string" + }, + "type": "object" + } + }, + "required": [ + "name" + ], + "type": "object" + }, "Created": { "description": "What creating a resource answers: its record and the job that makes it.", "properties": { @@ -1544,6 +1714,13 @@ }, "type": "array" }, + "collections": { + "description": "What it holds that can be listed, such as storage pools, each with\nthe actions of its items.", + "items": { + "$ref": "#/components/schemas/Collection" + }, + "type": "array" + }, "description": { "type": "string" }, @@ -1669,6 +1846,19 @@ "ProvisionerState": { "description": "A provisioner's page: what it is, what it says of itself now, and what\nit holds.", "properties": { + "collections": { + "additionalProperties": { + "items": { + "$ref": "#/components/schemas/CollectionItem" + }, + "type": "array" + }, + "description": "The items of each of its collections, by the collection's id, as its\nstatus gave them.", + "propertyNames": { + "type": "string" + }, + "type": "object" + }, "details": { "items": { "$ref": "#/components/schemas/Detail" From 238b5b07b888f8fd4978edbfcf3dd6681e530008 Mon Sep 17 00:00:00 2001 From: Helight Date: Sun, 15 Nov 2026 16:56:59 +0100 Subject: [PATCH 2/4] feat(plugins): Incus pools, volumes and images and Docker images and volumes as collections --- plugins/docker/bin/provision | 74 +++++++++++++++ plugins/docker/package.json | 50 +++++++++++ plugins/incus/bin/provision | 93 ++++++++++++++++++- plugins/incus/package.json | 168 +++++++++++++++++++++++++++++++++++ tests/test_docker_plugin.py | 51 +++++++++++ tests/test_incus_plugin.py | 54 +++++++++++ 6 files changed, 489 insertions(+), 1 deletion(-) diff --git a/plugins/docker/bin/provision b/plugins/docker/bin/provision index 1646a59..61d35e1 100755 --- a/plugins/docker/bin/provision +++ b/plugins/docker/bin/provision @@ -481,9 +481,83 @@ def engine_status(cfg): 'message': f'Docker {server.get("Version") or ""} answers at {docker.where()}'.replace(' ', ' '), 'details': details, 'values': {'runtime': ['privileged', 'sysbox'] if SYSBOX in runtimes else ['privileged']}, + 'collections': collections_of(docker), } +def collections_of(docker): + """The images and volumes of the engine as rows of the collections the manifest declares, each + with the containers that use it. One the engine does not answer for is left out.""" + try: + containers = docker.json_lines('ps', '--all', '--no-trunc') + except Failure: + containers = [] + found = {} + for collection, rows in (('images', image_rows), ('volumes', volume_rows)): + try: + found[collection] = rows(docker, containers) + except Failure: + pass + return found + + +def users(names): + return ', '.join(names[:3]) + (f' and {len(names) - 3} more' if len(names) > 3 else '') + + +def image_rows(docker, containers): + rows = [] + for image in docker.json_lines('image', 'ls')[:ROWS]: + repository, tag, short = image.get('Repository') or '', image.get('Tag') or '', image.get('ID') or '' + short = short.split(':')[-1][:12] + named = repository not in ('', '') and tag not in ('', '') + name = f'{repository}:{tag}' if named else short + if not name: + continue + # A container names its image as it was given: by name, by name without the tag latest, or by its id. + given = {name, short} + if named and tag == 'latest': + given.add(repository) + used_by = [row.get('Names') or '' for row in containers + if (row.get('Image') or '') in given or (row.get('Image') or '').split(':')[-1].startswith(short)] + rows.append({'name': name, 'key': {'image': name}, + 'columns': {'id': short, 'size': image.get('Size') or '', 'created': image.get('CreatedSince') or '', + 'used_by': users(used_by) or 'nothing'}, + 'unavailable': {'remove-image': f'Docker refuses it while {users(used_by)} ' + + ('uses' if len(used_by) == 1 else 'use') + ' it'} + if used_by else {}}) + return rows + + +def volume_sizes(docker): + """The size of each volume, as docker system df reckons it, or none when it does not say.""" + done = docker.run('system', 'df', '--verbose', '--format', '{{json .}}', check=False) + try: + listed = json.loads(done.stdout or '{}').get('Volumes') or [] if done.returncode == 0 else [] + except (ValueError, AttributeError): + return {} + return {volume.get('Name'): volume.get('Size') or '' for volume in listed if isinstance(volume, dict)} + + +def volume_rows(docker, containers): + sizes = volume_sizes(docker) + rows = [] + for volume in docker.json_lines('volume', 'ls')[:ROWS]: + name = volume.get('Name') or '' + if not name: + continue + labels = dict(part.split('=', 1) for part in (volume.get('Labels') or '').split(',') if '=' in part) + used_by = [row.get('Names') or '' for row in containers + if name in [mount.strip() for mount in (row.get('Mounts') or '').split(',')]] + rows.append({'name': name, + 'columns': {'driver': volume.get('Driver') or 'local', 'size': sizes.get(name, ''), + 'made_for': labels.get('berth-host', ''), 'used_by': users(used_by) or 'nothing'}, + 'unavailable': {'remove-volume': f'Docker refuses it while {users(used_by)} ' + + ('uses' if len(used_by) == 1 else 'use') + ' it'} + if used_by else {}}) + return rows + + def status(request): cfg = settings(request) if not request.get('id'): diff --git a/plugins/docker/package.json b/plugins/docker/package.json index de5aefb..b03e8e3 100644 --- a/plugins/docker/package.json +++ b/plugins/docker/package.json @@ -102,6 +102,56 @@ ] } ], + "collections": [ + { + "id": "images", + "label": "Image", + "plural": "Images", + "group": "Engine", + "help": "The images the engine has. A new one is pulled from its registry, or is the image the plugin brings, built here.", + "key": ["image"], + "columns": [ + {"name": "id", "label": "ID"}, + {"name": "size", "label": "Size"}, + {"name": "created", "label": "Created"}, + {"name": "used_by", "label": "Used by"} + ], + "new": [ + {"action": "pull-image", "label": "Pull an image"}, + {"action": "build", "label": "Build berth's image"} + ], + "item": [ + {"action": "remove-image", "label": "Remove"} + ], + "list": [ + {"action": "prune"} + ], + "remove": "remove-image", + "show": "images" + }, + { + "id": "volumes", + "label": "Volume", + "plural": "Volumes", + "group": "Storage", + "help": "The named volumes of the engine, with the host berth made each for, if any, and the containers that use it. One kept with keep_volume stays here until it is removed.", + "key": ["volume"], + "columns": [ + {"name": "driver", "label": "Driver"}, + {"name": "size", "label": "Size"}, + {"name": "made_for", "label": "Made for"}, + {"name": "used_by", "label": "Used by"} + ], + "new": [ + {"action": "create-volume"} + ], + "item": [ + {"action": "remove-volume", "label": "Remove", "arguments": {"volume": "name"}} + ], + "remove": "remove-volume", + "show": "volumes" + } + ], "actions": [ {"name": "engine", "label": "Check the engine", "group": "Engine", "changes": false, "help": "Ask the Docker engine for its version, its runtimes and how many containers berth made there."}, {"name": "images", "label": "Images", "group": "Engine", "changes": false, "help": "The images the engine has, with their sizes."}, diff --git a/plugins/incus/bin/provision b/plugins/incus/bin/provision index c95a11c..d5a932b 100755 --- a/plugins/incus/bin/provision +++ b/plugins/incus/bin/provision @@ -552,7 +552,98 @@ def server_status(incus): return {'state': 'ready', 'message': f'Incus {environment.get("server_version") or ""} answers at {incus.server} and trusts berth' .replace(' ', ' '), - 'details': details, 'values': values} + 'details': details, 'values': values, 'collections': collections_of(incus)} + + +def collections_of(incus): + """The items of the collections the manifest declares, as rows berth shows in tables. One the + server does not answer for is left out, and the rest are still given.""" + found = {} + for collection, rows in (('pools', pool_rows), ('volumes', volume_rows), ('images', image_rows)): + try: + found[collection] = rows(incus) + except IncusError: + pass + return found + + +def users_of(used_by): + """What the used_by of Incus names, as 'instance web' or 'profile default'.""" + users = [] + for url in used_by or []: + parts = urllib.parse.urlparse(url).path.strip('/').split('/') + if len(parts) >= 3: + kind = {'instances': 'instance', 'profiles': 'profile', 'images': 'image', + 'storage-pools': 'volume'}.get(parts[1], parts[1]) + users.append(f'{kind} {parts[-1][:12] if kind == "image" else parts[-1]}') + return users + + +def pool_rows(incus): + rows = [] + for pool in (incus.call('GET', '/1.0/storage-pools', query={'recursion': 1}) or [])[:ROWS]: + name = pool.get('name') or '' + config = pool.get('config') or {} + total, used = space_of(incus, name) + known = total is not None + unavailable = {} + can, why = resizable(incus, pool) + if not can: + unavailable['resize-pool'] = why[:1].upper() + why[1:] + users = users_of(pool.get('used_by')) + if users: + unavailable['remove-pool'] = f'Incus removes only an empty pool, and {", ".join(users[:3])}' + \ + (f' and {len(users) - 3} more' if len(users) > 3 else '') + ' use it' + rows.append({'name': name, + 'columns': {'driver': pool.get('driver') or '?', 'source': config.get('source') or '', + 'size': gib(total) if known else config.get('size') or '?', + 'used': gib(used) if known else '?', + 'free': gib((total or 0) - (used or 0)) if known else '?'}, + 'unavailable': unavailable}) + return rows + + +def volume_rows(incus): + rows = [] + for pool in names(incus, '/1.0/storage-pools'): + for volume in incus.call('GET', f'/1.0/storage-pools/{pool}/volumes/custom', query={'recursion': 1}) or []: + if len(rows) >= ROWS: + return rows + name = volume.get('name') or '' + used = '' + try: + usage = (incus.call('GET', f'/1.0/storage-pools/{pool}/volumes/custom/{name}/state', + missing=True) or {}).get('usage') or {} + if usage.get('used') is not None: + used = gib(usage['used']) + except IncusError: + pass + users = [user.split(' ', 1)[1] for user in users_of(volume.get('used_by'))] + unavailable = {} + if users: + unavailable['remove-volume'] = f'Incus refuses it while {", ".join(users)} use' + \ + ('s' if len(users) == 1 else '') + ' it' + rows.append({'name': name, 'key': {'pool': pool, 'volume': name}, + 'columns': {'pool': pool, 'type': volume.get('content_type') or 'filesystem', + 'size': (volume.get('config') or {}).get('size') or 'no set size', + 'used': used, 'used_by': ', '.join(users) or 'nothing'}, + 'unavailable': unavailable}) + return rows + + +def image_rows(incus): + rows = [] + for image in (incus.call('GET', '/1.0/images', query={'recursion': 1}) or [])[:ROWS]: + fingerprint = (image.get('fingerprint') or '')[:12] + if not fingerprint: + continue + aliases = ', '.join(alias.get('name') or '' for alias in image.get('aliases') or []) + described = (image.get('properties') or {}).get('description') or '' + rows.append({'name': aliases or described or fingerprint, 'key': {'image': fingerprint}, + 'columns': {'fingerprint': fingerprint, 'type': image.get('type') or '?', + 'size': gib(image.get('size')), 'cached': 'yes' if image.get('cached') else 'no', + 'uploaded': (image.get('uploaded_at') or '')[:10]}}) + return rows # What change applies to an instance in place; the rest are fixed when it is made. diff --git a/plugins/incus/package.json b/plugins/incus/package.json index 63202b6..7a8c364 100644 --- a/plugins/incus/package.json +++ b/plugins/incus/package.json @@ -91,6 +91,90 @@ ] } ], + "collections": [ + { + "id": "pools", + "label": "Storage pool", + "plural": "Storage pools", + "group": "Storage", + "help": "The storage pools of the server, which hold the disks of machines, the cached images and the custom volumes.", + "key": ["pool"], + "columns": [ + {"name": "driver", "label": "Driver"}, + {"name": "source", "label": "Source"}, + {"name": "size", "label": "Size"}, + {"name": "used", "label": "Used"}, + {"name": "free", "label": "Free"} + ], + "new": [ + {"action": "create-pool"} + ], + "item": [ + {"action": "resize-pool", "label": "Grow"}, + {"action": "set-pool", "label": "Change a setting"}, + {"action": "remove-pool", "label": "Remove", "arguments": {"pool": "name"}} + ], + "remove": "remove-pool", + "show": "pools" + }, + { + "id": "volumes", + "label": "Volume", + "plural": "Volumes", + "group": "Storage", + "help": "The custom volumes of the storage pools in the project, which an instance can mount.", + "key": ["pool", "volume"], + "within": "pools", + "columns": [ + {"name": "pool", "label": "Pool"}, + {"name": "type", "label": "Type"}, + {"name": "size", "label": "Size"}, + {"name": "used", "label": "Used"}, + {"name": "used_by", "label": "Used by"} + ], + "new": [ + {"action": "create-volume"} + ], + "item": [ + {"action": "resize-volume", "label": "Resize"}, + {"action": "remove-volume", "label": "Remove", "arguments": {"volume": "name"}} + ], + "remove": "remove-volume", + "show": "volumes" + }, + { + "id": "images", + "label": "Cached image", + "plural": "Cached images", + "group": "Storage", + "help": "The images the server keeps in its project. Incus fetches one from images.linuxcontainers.org when a machine first needs it, and again after it is removed.", + "key": ["image"], + "columns": [ + {"name": "fingerprint", "label": "Fingerprint"}, + {"name": "type", "label": "Type"}, + {"name": "size", "label": "Size"}, + {"name": "cached", "label": "Cached"}, + {"name": "uploaded", "label": "Uploaded"} + ], + "item": [ + {"action": "remove-image", "label": "Remove"} + ], + "remove": "remove-image", + "show": "images" + }, + { + "id": "instances", + "label": "Instance", + "plural": "Instances", + "group": "Storage", + "help": "The machines and instances berth made with the provisioner, whose actions are on the page of each.", + "key": ["instance"], + "kinds": ["machine", "instance"], + "item": [ + {"action": "resize-disk"} + ] + } + ], "actions": [ {"name": "server", "label": "Check the server", "group": "Server", "changes": false, "help": "Ask the Incus server for its version, its kernel and its storage drivers, and whether it trusts berth's client certificate."}, {"name": "pools", "label": "Storage pools", "group": "Storage", "changes": false, "help": "The storage pools of the server as a table: each one's driver, source, size, used and free space, and whether it can grow, or why not."}, @@ -191,6 +275,90 @@ ] } ], + "collections": [ + { + "id": "pools", + "label": "Storage pool", + "plural": "Storage pools", + "group": "Storage", + "help": "The storage pools of the server, which hold the disks of machines, the cached images and the custom volumes.", + "key": ["pool"], + "columns": [ + {"name": "driver", "label": "Driver"}, + {"name": "source", "label": "Source"}, + {"name": "size", "label": "Size"}, + {"name": "used", "label": "Used"}, + {"name": "free", "label": "Free"} + ], + "new": [ + {"action": "create-pool"} + ], + "item": [ + {"action": "resize-pool", "label": "Grow"}, + {"action": "set-pool", "label": "Change a setting"}, + {"action": "remove-pool", "label": "Remove", "arguments": {"pool": "name"}} + ], + "remove": "remove-pool", + "show": "pools" + }, + { + "id": "volumes", + "label": "Volume", + "plural": "Volumes", + "group": "Storage", + "help": "The custom volumes of the storage pools in the project, which an instance can mount.", + "key": ["pool", "volume"], + "within": "pools", + "columns": [ + {"name": "pool", "label": "Pool"}, + {"name": "type", "label": "Type"}, + {"name": "size", "label": "Size"}, + {"name": "used", "label": "Used"}, + {"name": "used_by", "label": "Used by"} + ], + "new": [ + {"action": "create-volume"} + ], + "item": [ + {"action": "resize-volume", "label": "Resize"}, + {"action": "remove-volume", "label": "Remove", "arguments": {"volume": "name"}} + ], + "remove": "remove-volume", + "show": "volumes" + }, + { + "id": "images", + "label": "Cached image", + "plural": "Cached images", + "group": "Storage", + "help": "The images the server keeps in its project. Incus fetches one from images.linuxcontainers.org when a machine first needs it, and again after it is removed.", + "key": ["image"], + "columns": [ + {"name": "fingerprint", "label": "Fingerprint"}, + {"name": "type", "label": "Type"}, + {"name": "size", "label": "Size"}, + {"name": "cached", "label": "Cached"}, + {"name": "uploaded", "label": "Uploaded"} + ], + "item": [ + {"action": "remove-image", "label": "Remove"} + ], + "remove": "remove-image", + "show": "images" + }, + { + "id": "instances", + "label": "Instance", + "plural": "Instances", + "group": "Storage", + "help": "The machines and instances berth made with the provisioner, whose actions are on the page of each.", + "key": ["instance"], + "kinds": ["machine", "instance"], + "item": [ + {"action": "resize-disk"} + ] + } + ], "actions": [ {"name": "server", "label": "Check the server", "group": "Server", "changes": false, "help": "Ask the Incus server for its version, its kernel and its storage drivers, and whether it trusts berth's client certificate."}, {"name": "pools", "label": "Storage pools", "group": "Storage", "changes": false, "help": "The storage pools of the server as a table: each one's driver, source, size, used and free space, and whether it can grow, or why not."}, diff --git a/tests/test_docker_plugin.py b/tests/test_docker_plugin.py index e189954..7ec94b5 100644 --- a/tests/test_docker_plugin.py +++ b/tests/test_docker_plugin.py @@ -382,6 +382,57 @@ def test_status_without_an_id_is_the_engine(self): self.assertEqual(done.returncode, 1) self.assertIn('not reachable', done.stderr) + def test_status_gives_the_images_and_volumes_as_rows_with_what_uses_them(self): + lines = lambda *rows: [0, ''.join(json.dumps(row) + '\n' for row in rows), ''] + rules = [{'prefix': ['ps', '--all', '--no-trunc'], 'results': [lines( + {'Names': 'berth-studio', 'Image': 'berth-docker:0.2.0', 'Mounts': 'berth-studio-home'}, + {'Names': 'web', 'Image': 'debian', 'Mounts': ''})]}, + {'prefix': ['image', 'ls'], 'results': [lines( + {'Repository': 'berth-docker', 'Tag': '0.2.0', 'ID': 'sha256:1111aaaa2222bbbb', 'Size': '812MB', + 'CreatedSince': '2 days ago'}, + {'Repository': 'debian', 'Tag': 'latest', 'ID': '3333cccc4444', 'Size': '117MB', + 'CreatedSince': '3 weeks ago'}, + {'Repository': '', 'Tag': '', 'ID': '5555dddd6666', 'Size': '80MB', + 'CreatedSince': '2 months ago'})]}, + {'prefix': ['volume', 'ls'], 'results': [lines( + {'Name': 'berth-studio-home', 'Driver': 'local', 'Labels': 'berth-host=studio'}, + {'Name': 'wiki-data', 'Driver': 'local', 'Labels': ''})]}, + {'prefix': ['system', 'df'], 'results': [[0, json.dumps( + {'Volumes': [{'Name': 'berth-studio-home', 'Size': '2.4GB'}]}), '']]}] + done = self.run_verb('status', rules=rules) + self.assertEqual(done.returncode, 0, done.stderr) + collections = json.loads(done.stdout)['collections'] + images = {row['name']: row for row in collections['images']} + self.assertEqual(sorted(images), ['5555dddd6666', 'berth-docker:0.2.0', 'debian:latest']) + self.assertEqual(images['berth-docker:0.2.0']['columns'], + {'id': '1111aaaa2222', 'size': '812MB', 'created': '2 days ago', 'used_by': 'berth-studio'}) + self.assertEqual(images['berth-docker:0.2.0']['key'], {'image': 'berth-docker:0.2.0'}) + # A container that names debian uses debian:latest, which cannot be removed while it does. + self.assertEqual(images['debian:latest']['unavailable'], + {'remove-image': 'Docker refuses it while web uses it'}) + self.assertEqual(images['5555dddd6666']['unavailable'], {}) + volumes = {row['name']: row for row in collections['volumes']} + self.assertEqual(volumes['berth-studio-home']['columns'], + {'driver': 'local', 'size': '2.4GB', 'made_for': 'studio', 'used_by': 'berth-studio'}) + self.assertIn('remove-volume', volumes['berth-studio-home']['unavailable']) + self.assertEqual(volumes['wiki-data']['columns']['used_by'], 'nothing') + self.assertEqual(volumes['wiki-data']['unavailable'], {}) + + def test_the_manifest_puts_the_list_and_change_actions_in_collections(self): + [entry] = json.loads((PLUGIN / 'package.json').read_text())['berth']['provisioners'] + collections = {collection['id']: collection for collection in entry['collections']} + self.assertEqual(sorted(collections), ['images', 'volumes']) + images, volumes = collections['images'], collections['volumes'] + self.assertEqual([used['action'] for used in images['new']], ['pull-image', 'build']) + self.assertEqual([used['action'] for used in images['list']], ['prune']) + self.assertEqual((images['remove'], images['show']), ('remove-image', 'images')) + self.assertEqual(volumes['item'], [{'action': 'remove-volume', 'label': 'Remove', + 'arguments': {'volume': 'name'}}]) + named = {used['action'] for collection in collections.values() for sort in ('new', 'item', 'list') + for used in collection.get(sort, [])} | {collection['show'] for collection in collections.values()} + # Only checking the engine stays a loose action of the page. + self.assertEqual([action['name'] for action in entry['actions'] if action['name'] not in named], ['engine']) + def test_change_sets_new_limits(self): rules = [{'prefix': ['container', 'inspect'], 'results': [inspect(OURS)]}] done = self.run_verb('change', {'id': 'berth-studio'}, arguments={'cpus': '2', 'memory': '1GiB'}, rules=rules) diff --git a/tests/test_incus_plugin.py b/tests/test_incus_plugin.py index 0fbcf5a..47e490d 100644 --- a/tests/test_incus_plugin.py +++ b/tests/test_incus_plugin.py @@ -527,6 +527,60 @@ def test_status_without_an_id_is_the_server(self): rows = {row['label']: row['value'] for row in answer['details']} self.assertEqual((rows['Name'], rows['Storage'], rows['Kernel']), ('dock', 'zfs, dir', 'Linux 6.17.0')) + def test_status_gives_the_items_of_each_collection_as_rows(self): + gib = 1024 ** 3 + self.server.pools['fast']['used_by'] = ['/1.0/profiles/default', '/1.0/instances/web?project=default'] + self.server.volumes[('default', 'data')] = {'name': 'data', 'config': {'size': '10GiB'}, 'used': 2 * gib, + 'content_type': 'filesystem', + 'used_by': ['/1.0/instances/berth-studio?project=default']} + self.server.volumes[('fast', 'disk')] = {'name': 'disk', 'config': {}, 'content_type': 'block', + 'used_by': []} + code, answer, err = self.run_verb('status') + self.assertEqual(code, 0, err) + collections = answer['collections'] + self.assertEqual(sorted(collections), ['images', 'pools', 'volumes']) + pools = {row['name']: row for row in collections['pools']} + self.assertEqual(pools['default']['columns'], + {'driver': 'zfs', 'source': '/var/lib/incus/disks/default.img', 'size': '100.0 GiB', + 'used': '10.0 GiB', 'free': '90.0 GiB'}) + # Each row says which of its actions cannot run on it, and why. + self.assertEqual(pools['default']['unavailable'], {}) + self.assertEqual(pools['fast']['unavailable']['resize-pool'], + 'A dir pool has no size of its own, only the space of its file system') + self.assertEqual(pools['fast']['unavailable']['remove-pool'], + 'Incus removes only an empty pool, and profile default, instance web use it') + self.assertIn('/dev/sdb', pools['disk']['unavailable']['resize-pool']) + volumes = {(row['key']['pool'], row['key']['volume']): row for row in collections['volumes']} + self.assertEqual(volumes[('default', 'data')]['columns'], + {'pool': 'default', 'type': 'filesystem', 'size': '10GiB', 'used': '2.0 GiB', + 'used_by': 'berth-studio'}) + self.assertEqual(volumes[('default', 'data')]['unavailable'], + {'remove-volume': 'Incus refuses it while berth-studio uses it'}) + self.assertEqual(volumes[('fast', 'disk')]['columns']['size'], 'no set size') + self.assertEqual(volumes[('fast', 'disk')]['unavailable'], {}) + self.assertEqual(collections['images'], [{ + 'name': 'Ubuntu 26.04', 'key': {'image': 'abcdef123456'}, + 'columns': {'fingerprint': 'abcdef123456', 'type': 'container', 'size': '2.0 GiB', 'cached': 'yes', + 'uploaded': ''}}]) + # The key of an image removes it. + code, answer, err = self.act('remove-image', image='abcdef123456') + self.assertEqual(code, 0, err) + self.assertIn(('image-delete', 'abcdef1234567890'), self.server.events) + + def test_the_manifest_declares_the_collections_status_gives(self): + manifest = json.loads((PLUGIN / 'package.json').read_text()) + for provisioner in manifest['berth']['provisioners']: + actions = {action['name']: action for action in provisioner['actions']} + declared = {collection['id']: collection for collection in provisioner['collections']} + self.assertEqual(sorted(declared), ['images', 'instances', 'pools', 'volumes']) + for collection in declared.values(): + for sort in ('new', 'item', 'list'): + for used in collection.get(sort, []): + self.assertIn(used['action'], actions) + # Grow root disk is on the machines, not loose on the page. + self.assertEqual(declared['instances']['kinds'], ['machine', 'instance']) + self.assertEqual(declared['volumes']['within'], 'pools') + def test_volumes_and_pools_are_created_listed_and_removed(self): act = self.act code, answer, err = act('create-pool', name='bulk', driver='zfs', size='50GiB') From c2b9d2b36058c25c88678ae0dff867aa63d670af Mon Sep 17 00:00:00 2001 From: Helight Date: Sun, 15 Nov 2026 16:56:59 +0100 Subject: [PATCH 3/4] feat(ui): a provisioner's collections as tables, with each item's actions on its page --- crates/berth-tui/src/provisioners.rs | 1588 +++++++++++++++++++++++++- crates/berth/src/cli/pages.rs | 160 ++- crates/berth/src/cli/things.rs | 19 +- 3 files changed, 1713 insertions(+), 54 deletions(-) diff --git a/crates/berth-tui/src/provisioners.rs b/crates/berth-tui/src/provisioners.rs index ea5c4b8..830004d 100644 --- a/crates/berth-tui/src/provisioners.rs +++ b/crates/berth-tui/src/provisioners.rs @@ -5,13 +5,20 @@ //! with its state, its actions and its log: those of the server the screens //! use. What the tab asks for goes to the server, which tells the tab what //! came back. +//! +//! What a provisioner holds, such as storage pools, is listed as its +//! collections: each is a table of its items, and each item has a page with +//! the actions on it, whose arguments its key fills. use crate::event::{Code, Event, Key}; use crate::form::{self, Did, Form}; use crate::page::{self, Accepted, Arguments, Begin, Group, Item, Tone}; use crate::screen::{self, Platform}; use crate::theme; -use berth_api::{Action, ProvisionerInfo, ProvisionerState, Resource}; +use berth_api::{ + Action, Collection, CollectionAction, CollectionItem, ProvisionerInfo, ProvisionerState, + Resource, +}; use ratatui::{ style::Style, text::{Line, Span}, @@ -67,6 +74,10 @@ pub enum Asked { #[derive(Clone, Copy, Debug, PartialEq)] pub enum Entry { Action(usize), + /// A collection, by its place among the provisioner's. + Collection(usize), + /// An item of the table shown, by its place in it. + Item(usize), /// What the provisioner holds, by its place on the page. Resource(usize), /// A resource's log. @@ -81,6 +92,30 @@ pub struct ResourcePart { pub seen: Option>, } +/// What is known of an action before it is asked for: the values a key +/// fills, and the provisioner it runs on when it is offered on a resource's +/// page. +#[derive(Clone, Debug, Default, PartialEq)] +struct Filled { + provisioner: Option, + values: BTreeMap, + /// What its job is called, with the item it acts on. + title: String, +} + +/// A collection's table, or the page of one of its items, over the +/// provisioner's page. +#[derive(Clone, Debug, PartialEq)] +struct View { + collection: String, + /// On an item's page its key; on a table the key of the item it lists + /// the items of, or nothing for all. + key: BTreeMap, + item: bool, + /// The cursor of what it covers, for going back. + back: usize, +} + /// The page of one provisioner, or of one resource it made, as it was last /// heard of. pub struct Page { @@ -90,7 +125,20 @@ pub struct Page { pub resource: Option, /// None while it is asked. pub state: Option>, + /// The actions of what is shown: of the subject, or of a collection's + /// table or item with what their keys fill in `filled`. pub actions: Vec, + filled: Vec, + /// Every action of the subject, as it was given. + base: Vec, + /// On a resource's page, the provisioner's actions on it as an item. + extra: Vec<(Action, Filled)>, + /// The tables and items shown over the provisioner's page, the last on top. + views: Vec, + /// How many of a table's actions make a new item; they come first. + making: usize, + /// It is asked again, and what it said last is shown till it answers. + asking: bool, /// The page it was opened from, which Esc goes back to. back: Option>, cursor: usize, @@ -277,8 +325,25 @@ pub fn help(provisioner: Option<&ProvisionerInfo>, place: &str) -> String { if !kinds.is_empty() { text += &format!("It makes {}.\n\n", kinds.join(" and ")); } - if !provisioner.actions.is_empty() { - let names: Vec<&str> = provisioner.actions.iter().map(Action::title).collect(); + let held: Vec = provisioner + .collections + .iter() + .filter(|collection| collection.kinds.is_empty()) + .map(|collection| collection.plural.to_lowercase()) + .collect(); + if !held.is_empty() { + text += &format!( + "Its page lists its {}, each with its actions.\n\n", + held.join(", ") + ); + } + let names: Vec<&str> = provisioner + .actions + .iter() + .filter(|action| action.collection.is_empty()) + .map(Action::title) + .collect(); + if !names.is_empty() { text += &format!("Its actions: {}.\n\n", names.join(", ")); } if !provisioner.own.is_empty() { @@ -306,6 +371,12 @@ impl Page { back: None, state: None, actions: vec![], + filled: vec![], + base: vec![], + extra: vec![], + views: vec![], + making: 0, + asking: false, cursor: 0, question: None, arguments: None, @@ -498,9 +569,30 @@ impl Page { } /// The rows: how it is, its actions in their groups, and on a - /// provisioner's page what it holds, by kind. + /// provisioner's page its collections and what it holds, by kind. Over + /// it, the table or item shown. fn items(&self) -> Vec> { - let mut groups = page::groups(&self.actions, Entry::Action); + match self.views.last() { + Some(view) if view.item => return self.item_items(view), + Some(view) => return self.table_items(view), + None => {} + } + let mut groups = match self.resource { + Some(_) => page::groups(&self.actions, Entry::Action), + None => self.collection_groups(), + }; + for group in page::groups(&self.actions, Entry::Action) { + if self.resource.is_some() { + break; + } + match groups + .iter_mut() + .find(|known| known.title.eq_ignore_ascii_case(&group.title)) + { + Some(known) => known.rows.extend(group.rows), + None => groups.push(group), + } + } if self.resource.is_some() { let logs = matches!(&self.resource, Some(ResourcePart { seen: Some(Ok(seen)), .. }) if seen.verbs.iter().any(|verb| verb == "logs")); if logs { @@ -596,24 +688,38 @@ impl Page { } } - fn launch(&mut self, (index, values): page::Launch) -> Asked { - match self.actions.get(index) { - Some(action) if !action.available => Asked::Nothing(Some(format!( + fn launch(&mut self, (index, mut values): page::Launch) -> Asked { + let filled = self.filled.get(index).cloned().unwrap_or_default(); + values.extend(filled.values); + let action = self.actions.get(index).map(|action| { + let mut action = action.clone(); + if !filled.title.is_empty() { + action.label = filled.title.clone(); + } + Box::new(action) + }); + match (action, filled.provisioner) { + (Some(action), _) if !action.available => Asked::Nothing(Some(format!( "{} cannot run now: {}", action.title(), action.why ))), - Some(action) if self.resource.is_some() => Asked::RunResource { + (Some(action), Some(provisioner)) => Asked::Run { + provisioner, + action, + values, + }, + (Some(action), None) if self.resource.is_some() => Asked::RunResource { resource: self.id.clone(), - action: Box::new(action.clone()), + action, values, }, - Some(action) => Asked::Run { + (Some(action), None) => Asked::Run { provisioner: self.id.clone(), - action: Box::new(action.clone()), + action, values, }, - None => Asked::Nothing(None), + (None, _) => Asked::Nothing(None), } } @@ -661,6 +767,653 @@ impl Page { } } +/// An action of a collection where some of its key is known: the arguments +/// that key fills are given, and not asked for again. On an item, it says +/// why it cannot run on that one, and its question names it. +fn derive( + base: &[Action], + collection: &Collection, + used: &CollectionAction, + known: &BTreeMap, + item: Option<&CollectionItem>, + group: Option<&str>, +) -> Option<(Action, Filled)> { + let original = base.iter().find(|action| action.name == used.action)?; + let mut action = original.clone(); + let mut values = BTreeMap::new(); + for (part, value) in known { + let argument = used.argument(part); + if action.arguments.iter().any(|known| known.name == argument) { + values.insert(argument.to_owned(), value.clone()); + action.arguments.retain(|known| known.name != argument); + } + } + if !used.label.is_empty() { + action.label = used.label.clone(); + } + if let Some(group) = group { + action.group = group.to_owned(); + } + let mut title = original.title().to_owned(); + if let Some(item) = item { + title = format!("{title} {}", item.name); + if let Some(why) = item.unavailable.get(&used.action) + && action.available + { + action.available = false; + action.why = why.clone(); + } + let named = format!("{} {}", collection.label, item.name); + action.confirm = match (&action.confirm, used.action == collection.remove) { + (Some(question), _) => Some(format!("{named}: {question}")), + (None, true) => Some(format!("{named}: {}?", original.title())), + (None, false) => None, + }; + } + Some(( + action, + Filled { + provisioner: None, + values, + title, + }, + )) +} + +/// The line of an action's row over a provisioner's page: one that cannot +/// run says why. +fn view_line(action: &Action) -> String { + match action.available { + true => format!(" ▸ {}", action.title()), + false => format!( + " ▸ {} · {}", + action.title(), + screen::ellipsize(&action.why, 70) + ), + } +} + +/// Lines of cells in columns as wide as their widest, at most `limit`. +fn columns(cells: &[Vec], limit: usize) -> Vec { + let count = cells.iter().map(Vec::len).max().unwrap_or(0); + let widths: Vec = (0..count) + .map(|column| { + cells + .iter() + .filter_map(|row| row.get(column)) + .map(|cell| cell.chars().count().min(limit)) + .max() + .unwrap_or(0) + }) + .collect(); + cells + .iter() + .map(|row| { + let line: Vec = row + .iter() + .enumerate() + .map(|(column, cell)| { + format!( + "{: Option<&ProvisionerInfo> { + match (&self.resource, &self.state) { + (None, Some(Ok(state))) => Some(&state.provisioner), + _ => None, + } + } + + fn collection(&self, id: &str) -> Option<&Collection> { + self.info()? + .collections + .iter() + .find(|collection| collection.id == id) + } + + /// The items of a collection within the item whose key is `within`, or + /// all; none when the provisioner did not give them. + fn rows(&self, id: &str, within: &BTreeMap) -> Option> { + let Some(Ok(state)) = &self.state else { + return None; + }; + let all = state.collections.get(id)?; + Some( + all.iter() + .filter(|row| { + within + .iter() + .all(|(part, value)| row.key.get(part) == Some(value)) + }) + .collect(), + ) + } + + /// The item of a collection with this key. + fn found(&self, id: &str, key: &BTreeMap) -> Option<&CollectionItem> { + let Some(Ok(state)) = &self.state else { + return None; + }; + state + .collections + .get(id)? + .iter() + .find(|row| &row.key == key) + } + + /// How many items a collection has within `within`, as its row says it. + fn count(&self, id: &str, within: &BTreeMap) -> String { + match self.rows(id, within) { + Some(rows) => rows.len().to_string(), + None => "?".into(), + } + } + + /// The rows of collections, as `(title, entries)` groups: those of the + /// provisioner's page, or those within the item `within` is the key of. + fn collection_rows( + &self, + parent: &str, + within: &BTreeMap, + ) -> Vec> { + let Some(info) = self.info() else { + return vec![]; + }; + let shown: Vec<(usize, &Collection)> = info + .collections + .iter() + .enumerate() + .filter(|(_, collection)| collection.kinds.is_empty()) + .filter(|(_, collection)| parent.is_empty() || collection.within == parent) + .collect(); + let width = shown + .iter() + .map(|(_, collection)| collection.plural.chars().count()) + .max() + .unwrap_or(0); + let mut groups: Vec> = vec![]; + for (index, collection) in shown { + let title = match (parent.is_empty(), collection.group.is_empty()) { + (false, _) => format!("In this {}", self.label_of(parent).to_lowercase()), + (true, true) => "Collections".to_owned(), + (true, false) => collection.group.clone(), + }; + let row = ( + format!( + " ▸ {: group.rows.push(row), + None => groups.push(Group { + title, + rows: vec![row], + }), + } + } + groups + } + + fn collection_groups(&self) -> Vec> { + self.collection_rows("", &BTreeMap::new()) + } + + fn label_of(&self, id: &str) -> String { + self.collection(id) + .map_or_else(|| id.to_owned(), |collection| collection.label.clone()) + } + + /// What the lines over a view say while the provisioner is asked, or + /// when it could not be. + fn waiting(&self) -> Option<(String, Tone)> { + match &self.state { + _ if self.asking => Some((format!("Asking {}…", self.id), Tone::Muted)), + None => Some((format!("Asking {}…", self.id), Tone::Muted)), + Some(Err(error)) => Some((format!("✗ {error}"), Tone::Bad)), + Some(Ok(_)) => None, + } + } + + /// The rows of the actions shown over the provisioner's page, in groups. + fn view_groups(&self) -> Vec> { + let mut groups: Vec> = vec![]; + for (index, action) in self.actions.iter().enumerate() { + let title = page::group_of(action); + let row = (view_line(action), Entry::Action(index)); + match groups.iter_mut().find(|known| known.title == title) { + Some(group) => group.rows.push(row), + None => groups.push(Group { + title: title.to_owned(), + rows: vec![row], + }), + } + } + groups + } + + /// A collection's table: what it lists, a row for each item, and the + /// actions that make one or act on them all. + fn table_items(&self, view: &View) -> Vec> { + let Some(collection) = self.collection(&view.collection) else { + let line = self.waiting().unwrap_or_else(|| { + ( + format!("{} has no {}", self.id, view.collection), + Tone::Warn, + ) + }); + return page::items(&[line], vec![]); + }; + let mut title = format!("{} · {}", collection.plural, self.id); + if !view.key.is_empty() { + let name = self + .found(&collection.within, &view.key) + .map(|item| item.name.clone()) + .unwrap_or_else(|| view.key.values().cloned().collect::>().join("/")); + title += &format!( + " · in the {} {name}", + self.label_of(&collection.within).to_lowercase() + ); + } + let mut items = vec![Item::Note(title, Tone::Plain)]; + if let Some(line) = self.waiting() { + items.push(Item::Note(line.0, line.1)); + } + let rows = self.rows(&collection.id, &view.key); + match &rows { + None if self.waiting().is_none() => items.push(Item::Note( + "○ The provisioner did not list them. r asks again".into(), + Tone::Warn, + )), + None => {} + Some(rows) if rows.is_empty() => items.push(Item::Note( + format!("No {} yet", collection.plural.to_lowercase()), + Tone::Muted, + )), + Some(rows) => { + // A part of the key that is the table's own is not repeated. + let shown: Vec<&berth_api::CollectionColumn> = collection + .columns + .iter() + .filter(|column| !view.key.contains_key(&column.name)) + .collect(); + let mut cells = vec![ + std::iter::once(collection.label.clone()) + .chain( + shown + .iter() + .map(|column| collection.column_label(column).to_owned()), + ) + .collect::>(), + ]; + for row in rows { + cells.push( + std::iter::once(row.name.clone()) + .chain(shown.iter().map(|column| { + row.columns.get(&column.name).cloned().unwrap_or_default() + })) + .collect(), + ); + } + let lines = columns(&cells, 32); + items.push(Item::Blank); + items.push(Item::Heading(lines[0].clone())); + items.extend( + lines[1..] + .iter() + .enumerate() + .map(|(index, line)| Item::Pick(line.clone(), Entry::Item(index))), + ); + } + } + for group in self.view_groups() { + items.push(Item::Blank); + items.push(Item::Heading(group.title)); + items.extend( + group + .rows + .into_iter() + .map(|(line, entry)| Item::Pick(line, entry)), + ); + } + items + } + + /// An item's page: its values, its actions, and the collections within it. + fn item_items(&self, view: &View) -> Vec> { + let (Some(collection), Some(item)) = ( + self.collection(&view.collection), + self.found(&view.collection, &view.key), + ) else { + let line = self.waiting().unwrap_or_else(|| { + ( + format!( + "{} {} is no longer listed", + self.label_of(&view.collection), + view.key.values().cloned().collect::>().join("/") + ), + Tone::Warn, + ) + }); + return page::items(&[line], vec![]); + }; + let mut lines = vec![( + format!("{} {} · {}", collection.label, item.name, self.id), + Tone::Plain, + )]; + if let Some(line) = self.waiting() { + lines.push(line); + } + let width = collection + .columns + .iter() + .map(|column| collection.column_label(column).chars().count()) + .max() + .unwrap_or(0); + for column in &collection.columns { + let value = item.columns.get(&column.name).cloned().unwrap_or_default(); + if !value.is_empty() { + lines.push(( + format!(" {: (Vec, Vec, usize) { + if self.resource.is_some() { + let mut actions = self.base.clone(); + let mut filled = vec![Filled::default(); actions.len()]; + for (action, known) in &self.extra { + actions.push(action.clone()); + filled.push(known.clone()); + } + return (actions, filled, 0); + } + let Some(view) = self.views.last() else { + let actions: Vec = self + .base + .iter() + .filter(|action| action.collection.is_empty()) + .cloned() + .collect(); + let filled = vec![Filled::default(); actions.len()]; + return (actions, filled, 0); + }; + let Some(collection) = self.collection(&view.collection) else { + return (vec![], vec![], 0); + }; + let derived: Vec<(Action, Filled)> = match view.item { + true => { + let item = self.found(&collection.id, &view.key); + collection + .item + .iter() + .filter_map(|used| { + derive( + &self.base, + collection, + used, + &view.key, + item, + Some(&collection.label), + ) + }) + .collect() + } + false => { + let all = format!("All {}", collection.plural.to_lowercase()); + collection + .new + .iter() + .filter_map(|used| { + derive(&self.base, collection, used, &view.key, None, Some("New")) + }) + .chain(collection.list.iter().filter_map(|used| { + derive(&self.base, collection, used, &view.key, None, Some(&all)) + })) + .collect() + } + }; + let making = match view.item { + true => 0, + false => derived + .iter() + .filter(|(action, _)| collection.new.iter().any(|used| used.action == action.name)) + .count(), + }; + let (actions, filled) = derived.into_iter().unzip(); + (actions, filled, making) + } + + /// Show `view` over what is shown now. + fn push(&mut self, collection: String, key: BTreeMap, item: bool) { + self.views.push(View { + collection, + key, + item, + back: self.cursor, + }); + self.cursor = 0; + self.kept = None; + self.arrange(); + } + + /// Go back from the view on top to what it covers. + fn pop(&mut self) { + if let Some(view) = self.views.pop() { + self.cursor = view.back; + } + self.kept = None; + self.arrange(); + } + + /// Leave the pages of items that are no longer listed, as after one is removed. + fn prune(&mut self) { + if !matches!(self.state, Some(Ok(_))) { + return; + } + let gone = self.views.iter().position(|view| { + self.collection(&view.collection).is_none() + || (view.item && self.found(&view.collection, &view.key).is_none()) + }); + if let Some(gone) = gone { + self.cursor = self.views[gone].back; + self.views.truncate(gone); + self.kept = None; + // The table it was opened from selects the item that took its place. + let count = self + .table() + .and_then(|view| self.rows(&view.collection, &view.key)) + .map_or(0, |rows| rows.len()); + if count > 0 { + self.cursor = self.cursor.min(count - 1); + } + } + } + + /// The provisioner's actions on a resource it made of a kind one of its + /// collections has as items, with the resource's id as their key. + fn on_resource(&self, held: &berth_api::ListedResource) -> Vec<(Action, Filled)> { + let Some(info) = self.info() else { + return vec![]; + }; + let mut found = vec![]; + for collection in info + .collections + .iter() + .filter(|collection| collection.kinds.contains(&held.kind)) + { + let key: BTreeMap = collection + .key + .iter() + .map(|part| (part.clone(), held.id.clone())) + .collect(); + for used in &collection.item { + if let Some((action, mut filled)) = + derive(&self.base, collection, used, &key, None, None) + { + filled.provisioner = Some(self.id.clone()); + let name = match held.host.is_empty() { + true => &held.name, + false => &held.host, + }; + filled.title = format!("{} · {name}", action.title()); + found.push((action, filled)); + } + } + } + found + } + + /// The table shown, if one is. + fn table(&self) -> Option<&View> { + self.views.last().filter(|view| !view.item) + } + + /// `n` on a table: its one way to make an item, or the rows of those + /// there are to choose from. + fn make(&mut self) -> Asked { + let Some(collection) = self + .table() + .and_then(|view| self.collection(&view.collection)) + .cloned() + else { + return Asked::Other; + }; + match self.making { + 0 => Asked::Nothing(Some(format!("{} are not made here", collection.plural))), + 1 => self.begin(0, false), + _ => { + if let Some(at) = self + .entries() + .iter() + .position(|entry| *entry == Entry::Action(0)) + { + self.cursor = at; + } + let ways: Vec<&str> = self.actions[..self.making] + .iter() + .map(Action::title) + .collect(); + Asked::Nothing(Some(format!( + "Choose how to make one: {}", + ways.join(" or ") + ))) + } + } + } + + /// `x`: remove the item selected in a table, or the item shown, after + /// a question that names it. + fn remove(&mut self) -> Asked { + let Some(view) = self.views.last().cloned() else { + return Asked::Other; + }; + let Some(collection) = self.collection(&view.collection).cloned() else { + return Asked::Nothing(None); + }; + if collection.remove.is_empty() { + return Asked::Nothing(Some(format!("{} are not removed here", collection.plural))); + } + if view.item { + let index = self + .actions + .iter() + .position(|action| action.name == collection.remove); + return match index { + Some(index) => self.begin(index, false), + None => Asked::Nothing(None), + }; + } + let Some(Entry::Item(index)) = self.selected() else { + return Asked::Nothing(Some(format!( + "Choose the {} to remove", + collection.label.to_lowercase() + ))); + }; + let Some(item) = self + .rows(&collection.id, &view.key) + .and_then(|rows| rows.get(index).map(|row| (*row).clone())) + else { + return Asked::Nothing(None); + }; + let Some(used) = collection + .item + .iter() + .find(|used| used.action == collection.remove) + else { + return Asked::Nothing(None); + }; + let Some((action, filled)) = derive( + &self.base, + &collection, + used, + &item.key, + Some(&item), + Some(&collection.label), + ) else { + return Asked::Nothing(None); + }; + self.arrange(); + self.actions.push(action); + self.filled.push(filled); + self.begin(self.actions.len() - 1, false) + } + + /// Take in what the provisioner or the resource said, and its actions. + fn take( + &mut self, + state: Result, + actions: Result, String>, + ) { + self.asking = false; + self.state = Some(match (state, &actions) { + (Ok(state), Err(error)) => Err(format!( + "{} answered, but not with its actions: {error}", + state.provisioner.id + )), + (state, _) => state, + }); + self.base = actions.unwrap_or_default(); + self.prune(); + // An action being asked for keeps its place until it runs. + if self.question.is_none() && self.arguments.is_none() || self.views.is_empty() { + self.arrange(); + } + } +} + impl Tab { /// The selected provisioner of the list. /// None on the row that registers one. @@ -782,17 +1535,21 @@ impl Tab { state: Result, actions: Result, String>, ) { + // A resource's page keeps its provisioner's page, as after an action of + // the provisioner run there. + if let Some(back) = self + .page + .as_mut() + .filter(|page| page.id != id) + .and_then(|page| page.back.as_mut()) + .filter(|back| back.id == id) + { + return back.take(state, actions); + } let Some(page) = self.page.as_mut().filter(|page| page.id == id) else { return; }; - page.state = Some(match (state, &actions) { - (Ok(state), Err(error)) => Err(format!( - "{} answered, but not with its actions: {error}", - state.provisioner.id - )), - (state, _) => state, - }); - page.actions = actions.unwrap_or_default(); + page.take(state, actions); // A form that waits for the provisioner's action takes it now. let narrowed = match &page.state { Some(Ok(state)) => state.values.clone(), @@ -847,7 +1604,8 @@ impl Tab { )), (seen, _) => seen, }); - page.actions = actions.unwrap_or_default(); + page.base = actions.unwrap_or_default(); + page.arrange(); } /// The question waiting for an answer, for the screen to draw. @@ -940,33 +1698,101 @@ impl Tab { { Line::styled(text.clone(), muted) } + // What cannot run now is greyed over a provisioner's page, with why. + Item::Pick(text, Entry::Action(index)) + if !page.views.is_empty() + && page + .actions + .get(*index) + .is_some_and(|action| !action.available) => + { + Line::styled(text.clone(), muted) + } Item::Pick(text, _) => Line::styled(text.clone(), Style::new().fg(theme::TEXT)), }) .collect(); let help = match page.selected() { - Some(Entry::Action(index)) => page::help( - &page.actions[index], - &match &page.resource { - Some(_) => format!( - "berth resource run {} {}", - page.id, page.actions[index].name - ), - None => format!( - "berth provisioner run {} {}", - page.id, page.actions[index].name - ), - }, - ), - Some(Entry::Resource(index)) => { - let held = &page.held()[index]; - match (held.resource.is_empty(), held.kind.as_str()) { - (false, "machine") if !held.host.is_empty() => format!( - "The machine of {}, {} as the provisioner calls it. Enter opens its page, with its state, its actions and its log. It is looked after as that host too, on the host's page. From the command line: `berth resource show {}`", - held.host, held.id, held.resource - ), - (false, _) => format!( - "The {} {}, {} as the provisioner calls it. Enter opens its page, with its state, its actions and its log. From the command line: `berth resource show {}`", - held.kind, held.name, held.id, held.resource + Some(Entry::Action(index)) => { + let filled = page.filled.get(index).cloned().unwrap_or_default(); + let given: String = filled + .values + .iter() + .map(|(key, value)| format!(" {key}={value}")) + .collect(); + let name = &page.actions[index].name; + page::help( + &page.actions[index], + &match (&page.resource, &filled.provisioner) { + (_, Some(provisioner)) => { + format!("berth provisioner run {provisioner} {name}{given}") + } + (Some(_), None) => format!("berth resource run {} {name}", page.id), + (None, None) => format!("berth provisioner run {} {name}{given}", page.id), + }, + ) + } + Some(Entry::Collection(index)) => { + let collection = &page.info().expect("a collection is listed").collections[index]; + let mut text = collection.help.clone(); + if !text.is_empty() { + text += "\n\n"; + } + text += "Enter opens them as a table, and each of them with its actions."; + let mut keys = vec![]; + if !collection.new.is_empty() { + keys.push("n makes one"); + } + if !collection.remove.is_empty() { + keys.push("x removes the one selected"); + } + if !keys.is_empty() { + text += &format!(" There, {}.", keys.join(" and ")); + } + text += &format!( + "\n\nFrom the command line: `berth provisioner show {}`", + page.id + ); + if !collection.show.is_empty() { + text += &format!( + ", or `berth provisioner run {} {}` for these alone", + page.id, collection.show + ); + } + text + } + Some(Entry::Item(index)) => { + let view = page.table().expect("an item is in a table"); + let collection = page.collection(&view.collection).expect("it is listed"); + let row = page + .rows(&view.collection, &view.key) + .and_then(|rows| rows.get(index).copied()); + match row { + Some(row) => { + let mut text = + format!("The {} {}.", collection.label.to_lowercase(), row.name); + for (action, why) in &row.unavailable { + let title = page + .base + .iter() + .find(|known| &known.name == action) + .map_or(action.as_str(), Action::title); + text += &format!("\n\n{title} cannot run on it: {why}"); + } + text + "\n\nEnter opens it with its actions." + } + None => String::new(), + } + } + Some(Entry::Resource(index)) => { + let held = &page.held()[index]; + match (held.resource.is_empty(), held.kind.as_str()) { + (false, "machine") if !held.host.is_empty() => format!( + "The machine of {}, {} as the provisioner calls it. Enter opens its page, with its state, its actions and its log. It is looked after as that host too, on the host's page. From the command line: `berth resource show {}`", + held.host, held.id, held.resource + ), + (false, _) => format!( + "The {} {}, {} as the provisioner calls it. Enter opens its page, with its state, its actions and its log. From the command line: `berth resource show {}`", + held.kind, held.name, held.id, held.resource ), (true, _) => format!( "{} is listed by the provisioner, but berth has no record of it: it was made otherwise, or berth lost track of it. berth does not remove it; the provisioner's own tools do.", @@ -987,11 +1813,32 @@ impl Tab { page.id ), }; + let collection = page + .views + .last() + .and_then(|view| page.collection(&view.collection)); + let removes = collection.is_some_and(|collection| !collection.remove.is_empty()); + let keys = match (page.views.last(), page.making, removes) { + (None, _, _) if page.resource.is_none() => { + "↑↓ select · Enter open or run · r ask again · Esc back" + } + (None, _, _) => "↑↓ select · Enter run · r ask again · Esc back", + (Some(view), _, true) if view.item => { + "↑↓ select · Enter run · x remove · r refresh · Esc back" + } + (Some(view), _, false) if view.item => "↑↓ select · Enter run · r refresh · Esc back", + (Some(_), 0, true) => "↑↓ select · Enter open · x remove · r refresh · Esc back", + (Some(_), 0, false) => "↑↓ select · Enter open · r refresh · Esc back", + (Some(_), _, true) => { + "↑↓ select · Enter open · n new · x remove · r refresh · Esc back" + } + (Some(_), _, false) => "↑↓ select · Enter open · n new · r refresh · Esc back", + }; Shown { rows, selected: self.selected_row(), help, - keys: "↑↓ select · Enter run · r ask again · Esc back", + keys, } } @@ -1122,6 +1969,7 @@ impl Tab { if held.resource.is_empty() { return Asked::Nothing(Some(format!("berth has no record of {}", held.id))); } + let extra = page.on_resource(&held); let back = self.page.take().map(Box::new); let provisioner = back .as_ref() @@ -1133,13 +1981,47 @@ impl Tab { seen: None, }), back, + extra, ..Page::new(&held.resource) }); return Asked::OpenResource(held.resource); } Some(Entry::Logs) => return Asked::Logs(page.id.clone()), + Some(Entry::Collection(index)) => { + let Some(collection) = page.info().and_then(|info| info.collections.get(index)) + else { + return Asked::Nothing(None); + }; + let id = collection.id.clone(); + // Within an item, the table lists what that item holds. + let within = page + .views + .last() + .filter(|view| view.item) + .map(|view| view.key.clone()) + .unwrap_or_default(); + page.push(id, within, false); + } + Some(Entry::Item(index)) => { + let Some(view) = page.table().cloned() else { + return Asked::Nothing(None); + }; + let key = page + .rows(&view.collection, &view.key) + .and_then(|rows| rows.get(index).map(|row| row.key.clone())); + if let Some(key) = key { + page.push(view.collection, key, true); + } + } None => {} }, + Code::Char('n') if page.table().is_some() => return page.make(), + Code::Char('x') | Code::Delete if !page.views.is_empty() => return page.remove(), + // Over the provisioner's page, what it said stays till it answers. + Code::Char('r') if !page.views.is_empty() => { + page.asking = true; + return Asked::Open(page.id.clone()); + } Code::Char('r') => { let id = page.id.clone(); page.state = None; @@ -1149,6 +2031,7 @@ impl Tab { } return Asked::Open(id); } + Code::Esc | Code::Backspace | Code::Left if !page.views.is_empty() => page.pop(), Code::Esc | Code::Backspace | Code::Left => { // A resource's page goes back to its provisioner's, which is asked again. if let Some(back) = page.back.take() { @@ -1513,6 +2396,7 @@ mod tests { ..ListedResource::default() }, ], + ..ProvisionerState::default() }; // What arrives for another page is not taken. tab.opened("lab/old", Err("no".into()), Ok(vec![])); @@ -1718,4 +2602,616 @@ mod tests { .is_some_and(|page| page.resource.is_none()) ); } + + // ── Collections ───────────────────────────────────────────────────────── + + fn argument(name: &str) -> Argument { + Argument { + name: name.into(), + label: name.into(), + ..Argument::default() + } + } + + fn act(name: &str, label: &str, collection: &str, arguments: &[&str]) -> Action { + Action { + name: name.into(), + label: label.into(), + group: "Storage".into(), + collection: collection.into(), + arguments: arguments.iter().map(|name| argument(name)).collect(), + ..Action::default() + } + } + + fn used(action: &str, label: &str, arguments: &[(&str, &str)]) -> CollectionAction { + CollectionAction { + action: action.into(), + label: label.into(), + arguments: arguments + .iter() + .map(|(part, argument)| (part.to_string(), argument.to_string())) + .collect(), + } + } + + fn row(name: &str, key: &[(&str, &str)], columns: &[(&str, &str)]) -> CollectionItem { + let pairs = |pairs: &[(&str, &str)]| { + pairs + .iter() + .map(|(key, value)| (key.to_string(), value.to_string())) + .collect() + }; + CollectionItem { + name: name.into(), + key: pairs(key), + columns: pairs(columns), + unavailable: BTreeMap::new(), + } + } + + fn column(name: &str, label: &str) -> berth_api::CollectionColumn { + berth_api::CollectionColumn { + name: name.into(), + label: label.into(), + } + } + + /// The actions of a made-up Incus server, those of its collections among them. + fn server_actions() -> Vec { + let mut remove = act("remove-pool", "Remove storage pool", "pools", &["name"]); + remove.confirm = Some("Remove this storage pool?".into()); + vec![ + Action { + changes: false, + ..act("server", "Check the server", "", &[]) + }, + Action { + changes: false, + ..act("pools", "Storage pools", "pools", &[]) + }, + act( + "create-pool", + "New storage pool", + "pools", + &["name", "driver"], + ), + act( + "resize-pool", + "Grow storage pool", + "pools", + &["pool", "size"], + ), + act( + "set-pool", + "Change storage pool", + "pools", + &["pool", "key", "value"], + ), + remove, + act( + "create-volume", + "New volume", + "volumes", + &["pool", "name", "size"], + ), + act( + "remove-volume", + "Remove volume", + "volumes", + &["pool", "name"], + ), + act( + "resize-disk", + "Grow root disk", + "instances", + &["instance", "size"], + ), + ] + } + + fn server_collections() -> Vec { + vec![ + Collection { + id: "pools".into(), + label: "Storage pool".into(), + plural: "Storage pools".into(), + group: "Storage".into(), + key: vec!["pool".into()], + columns: vec![column("driver", "Driver"), column("size", "Size")], + new: vec![used("create-pool", "", &[])], + item: vec![ + used("resize-pool", "Grow", &[]), + used("set-pool", "Change a setting", &[]), + used("remove-pool", "Remove", &[("pool", "name")]), + ], + remove: "remove-pool".into(), + show: "pools".into(), + ..Collection::default() + }, + Collection { + id: "volumes".into(), + label: "Volume".into(), + plural: "Volumes".into(), + group: "Storage".into(), + key: vec!["pool".into(), "volume".into()], + within: "pools".into(), + columns: vec![column("pool", "Pool"), column("size", "Size")], + new: vec![used("create-volume", "", &[])], + item: vec![used("remove-volume", "Remove", &[("volume", "name")])], + remove: "remove-volume".into(), + ..Collection::default() + }, + Collection { + id: "instances".into(), + label: "Instance".into(), + plural: "Instances".into(), + key: vec!["instance".into()], + kinds: vec!["machine".into()], + item: vec![used("resize-disk", "", &[])], + ..Collection::default() + }, + ] + } + + fn server_state(pools: &[&str]) -> ProvisionerState { + let mut fast = row( + "fast", + &[("pool", "fast")], + &[("driver", "dir"), ("size", "200.0 GiB")], + ); + fast.unavailable.insert( + "resize-pool".into(), + "A dir pool has no size of its own".into(), + ); + let all = vec![ + row( + "default", + &[("pool", "default")], + &[("driver", "zfs"), ("size", "100.0 GiB")], + ), + fast, + ]; + ProvisionerState { + provisioner: ProvisionerInfo { + id: "incus-vm".into(), + label: "Incus virtual machine".into(), + collections: server_collections(), + ..ProvisionerInfo::default() + }, + state: "ready".into(), + collections: [ + ( + "pools".to_owned(), + all.into_iter() + .filter(|row| pools.contains(&row.name.as_str())) + .collect(), + ), + ( + "volumes".to_owned(), + vec![ + row( + "data", + &[("pool", "default"), ("volume", "data")], + &[("pool", "default"), ("size", "10GiB")], + ), + row( + "scratch", + &[("pool", "fast"), ("volume", "scratch")], + &[("pool", "fast"), ("size", "no set size")], + ), + ], + ), + ] + .into(), + resources: vec![ListedResource { + id: "berth-studio".into(), + kind: "machine".into(), + name: "studio".into(), + host: "studio".into(), + state: "running".into(), + resource: "r-studio".into(), + }], + ..ProvisionerState::default() + } + } + + /// A tab on the page of the made-up server, as it answered. + fn on_server() -> (Tab, Vec) { + let list = vec![ProvisionerInfo { + id: "incus-vm".into(), + ..ProvisionerInfo::default() + }]; + let mut tab = Tab::default(); + assert_eq!( + tab.key(key(Code::Enter), &list, &mut Nowhere), + Asked::Open("incus-vm".into()) + ); + tab.opened( + "incus-vm", + Ok(server_state(&["default", "fast"])), + Ok(server_actions()), + ); + (tab, list) + } + + /// Select the row that reads `line`. + fn choose(tab: &mut Tab, list: &[ProvisionerInfo], line: &str) { + let rows = text(&tab.shown(list, "here")); + let at = rows + .iter() + .position(|row| row.trim_end() == line) + .unwrap_or_else(|| panic!("{line:?} in {rows:?}")); + tab.select_row(at); + assert_eq!(tab.selected_row(), at, "{line:?} can be chosen"); + } + + fn typed(tab: &mut Tab, list: &[ProvisionerInfo], words: &str) { + for ch in words.chars() { + tab.key(key(Code::Char(ch)), list, &mut Nowhere); + } + } + + #[test] + fn a_collection_is_one_row_with_its_count_and_its_actions_are_not_loose() { + let (tab, list) = on_server(); + let shown = tab.shown(&list, "here"); + let rows = text(&shown); + let storage = rows.iter().position(|row| row == "Storage").unwrap(); + assert_eq!( + rows[storage + 1..storage + 4], + [ + " ▸ Storage pools 2", + " ▸ Volumes 2", + " ▸ Check the server" + ] + ); + // Neither the actions of a collection nor the collection of resources is a row. + for gone in [ + "Grow", + "New storage pool", + "Grow root disk", + "Instances", + "▸ Storage pools ", + ] { + assert!( + !rows + .iter() + .any(|row| row.contains(gone) && !row.ends_with("pools 2")), + "{gone:?} in {rows:?}" + ); + } + assert_eq!(rows[shown.selected], " ▸ Storage pools 2"); + assert!( + shown.help.contains("x removes the one selected"), + "{}", + shown.help + ); + assert!(shown.help.contains("berth provisioner run incus-vm pools")); + assert!(shown.keys.contains("Enter open")); + } + + #[test] + fn a_table_opens_an_item_whose_actions_have_its_key_and_say_why_not() { + let (mut tab, list) = on_server(); + choose(&mut tab, &list, " ▸ Storage pools 2"); + assert_eq!( + tab.key(key(Code::Enter), &list, &mut Nowhere), + Asked::Nothing(None) + ); + let shown = tab.shown(&list, "here"); + let rows = text(&shown); + assert_eq!(rows[0], "Storage pools · incus-vm"); + for line in [ + " Storage pool Driver Size", + " default zfs 100.0 GiB", + " fast dir 200.0 GiB", + "New", + " ▸ New storage pool", + ] { + assert!(rows.iter().any(|row| row == line), "{line:?} in {rows:?}"); + } + // The first item is selected, and Enter opens it. + assert_eq!(rows[shown.selected], " default zfs 100.0 GiB"); + assert!(shown.keys.contains("n new") && shown.keys.contains("x remove")); + tab.key(key(Code::Down), &list, &mut Nowhere); + tab.key(key(Code::Enter), &list, &mut Nowhere); + let shown = tab.shown(&list, "here"); + let rows = text(&shown); + assert_eq!(rows[0], "Storage pool fast · incus-vm"); + assert!(rows.contains(&" Driver dir".to_owned()), "{rows:?}"); + assert!( + rows.contains(&" ▸ Grow · A dir pool has no size of its own".to_owned()), + "{rows:?}" + ); + // What cannot run on it is greyed, and says why when it is chosen. + let grow = rows + .iter() + .position(|row| row.starts_with(" ▸ Grow")) + .unwrap(); + assert_eq!(shown.rows[grow].style.fg, Some(theme::MUTED)); + assert_eq!(rows[shown.selected], rows[grow]); + assert_eq!( + tab.key(key(Code::Enter), &list, &mut Nowhere), + Asked::Nothing(Some( + "Grow cannot run now: A dir pool has no size of its own".into() + )) + ); + // Its other action asks only for what the pool does not fill. + tab.key(key(Code::Down), &list, &mut Nowhere); + let help = tab.shown(&list, "here").help; + assert!( + help.contains("berth provisioner run incus-vm set-pool pool=fast"), + "{help}" + ); + tab.key(key(Code::Enter), &list, &mut Nowhere); + let (actions, dialog) = tab.arguments().unwrap(); + assert_eq!(actions[dialog.action].arguments[dialog.index].name, "key"); + typed(&mut tab, &list, "description"); + tab.key(key(Code::Enter), &list, &mut Nowhere); + typed(&mut tab, &list, "fast disks"); + let Asked::Run { + provisioner, + action, + values, + } = tab.key(key(Code::Enter), &list, &mut Nowhere) + else { + panic!("not run"); + }; + assert_eq!( + (provisioner.as_str(), action.name.as_str(), action.title()), + ("incus-vm", "set-pool", "Change storage pool fast") + ); + assert_eq!( + values, + [ + ("key".to_owned(), "description".to_owned()), + ("pool".to_owned(), "fast".to_owned()), + ("value".to_owned(), "fast disks".to_owned()) + ] + .into() + ); + // Esc goes back to the table, with its row selected, and then to the page. + tab.key(key(Code::Esc), &list, &mut Nowhere); + let shown = tab.shown(&list, "here"); + assert_eq!( + text(&shown)[shown.selected], + " fast dir 200.0 GiB" + ); + tab.key(key(Code::Esc), &list, &mut Nowhere); + let shown = tab.shown(&list, "here"); + assert_eq!(text(&shown)[shown.selected], " ▸ Storage pools 2"); + } + + #[test] + fn x_removes_the_item_selected_after_a_question_that_names_it() { + let (mut tab, list) = on_server(); + choose(&mut tab, &list, " ▸ Storage pools 2"); + tab.key(key(Code::Enter), &list, &mut Nowhere); + tab.key(key(Code::Down), &list, &mut Nowhere); + assert_eq!( + tab.key(key(Code::Char('x')), &list, &mut Nowhere), + Asked::Nothing(None) + ); + assert_eq!( + tab.question(), + Some("Storage pool fast: Remove this storage pool?") + ); + let Asked::Run { action, values, .. } = tab.key(key(Code::Char('y')), &list, &mut Nowhere) + else { + panic!("not run"); + }; + assert_eq!(action.name, "remove-pool"); + assert_eq!(values, [("name".to_owned(), "fast".to_owned())].into()); + // After its job the provisioner is asked again: the table has one fewer. + tab.opened( + "incus-vm", + Ok(server_state(&["default"])), + Ok(server_actions()), + ); + let rows = text(&tab.shown(&list, "here")); + assert!( + !rows.iter().any(|row| row.starts_with(" fast")), + "{rows:?}" + ); + // On a row that is no item, x says what to choose. + choose(&mut tab, &list, " ▸ New storage pool"); + assert_eq!( + tab.key(key(Code::Char('x')), &list, &mut Nowhere), + Asked::Nothing(Some("Choose the storage pool to remove".into())) + ); + } + + #[test] + fn the_page_of_an_item_that_is_gone_goes_back_to_its_table_when_asked_again() { + let (mut tab, list) = on_server(); + choose(&mut tab, &list, " ▸ Storage pools 2"); + tab.key(key(Code::Enter), &list, &mut Nowhere); + tab.key(key(Code::Down), &list, &mut Nowhere); + tab.key(key(Code::Enter), &list, &mut Nowhere); + // r asks the provisioner again and keeps what is shown. + assert_eq!( + tab.key(key(Code::Char('r')), &list, &mut Nowhere), + Asked::Open("incus-vm".into()) + ); + assert_eq!(text(&tab.shown(&list, "here"))[1], "Asking incus-vm…"); + tab.opened( + "incus-vm", + Ok(server_state(&["default"])), + Ok(server_actions()), + ); + let shown = tab.shown(&list, "here"); + let rows = text(&shown); + assert_eq!(rows[0], "Storage pools · incus-vm"); + assert_eq!(rows[shown.selected], " default zfs 100.0 GiB"); + } + + #[test] + fn the_volumes_of_a_pool_are_listed_on_its_page_and_made_there_without_asking_for_it() { + let (mut tab, list) = on_server(); + choose(&mut tab, &list, " ▸ Storage pools 2"); + tab.key(key(Code::Enter), &list, &mut Nowhere); + tab.key(key(Code::Enter), &list, &mut Nowhere); + let rows = text(&tab.shown(&list, "here")); + assert_eq!(rows[0], "Storage pool default · incus-vm"); + let at = rows + .iter() + .position(|row| row == "In this storage pool") + .unwrap(); + assert_eq!(rows[at + 1], " ▸ Volumes 1"); + tab.select_row(at + 1); + tab.key(key(Code::Enter), &list, &mut Nowhere); + let rows = text(&tab.shown(&list, "here")); + assert_eq!(rows[0], "Volumes · incus-vm · in the storage pool default"); + // The pool is the table's own, so it is no column, and the other pool's volume is not there. + assert!(rows.contains(&" Volume Size".to_owned()), "{rows:?}"); + assert!(rows.contains(&" data 10GiB".to_owned()), "{rows:?}"); + assert!(!rows.iter().any(|row| row.contains("scratch"))); + // n asks for the name and size, not the pool. + tab.key(key(Code::Char('n')), &list, &mut Nowhere); + let (actions, dialog) = tab.arguments().unwrap(); + assert_eq!(actions[dialog.action].arguments[dialog.index].name, "name"); + typed(&mut tab, &list, "logs"); + tab.key(key(Code::Enter), &list, &mut Nowhere); + let Asked::Run { action, values, .. } = tab.key(key(Code::Enter), &list, &mut Nowhere) + else { + panic!("not run"); + }; + assert_eq!(action.name, "create-volume"); + assert_eq!( + (values["pool"].as_str(), values["name"].as_str()), + ("default", "logs") + ); + // A volume's page removes it with both parts of its key. + tab.key(key(Code::Enter), &list, &mut Nowhere); + assert_eq!(text(&tab.shown(&list, "here"))[0], "Volume data · incus-vm"); + tab.key(key(Code::Char('x')), &list, &mut Nowhere); + assert_eq!(tab.question(), Some("Volume data: Remove volume?")); + let Asked::Run { values, .. } = tab.key(key(Code::Char('y')), &list, &mut Nowhere) else { + panic!("not run"); + }; + assert_eq!( + values, + [ + ("name".to_owned(), "data".to_owned()), + ("pool".to_owned(), "default".to_owned()) + ] + .into() + ); + } + + #[test] + fn all_volumes_are_a_table_too_and_a_new_one_there_asks_for_its_pool() { + let (mut tab, list) = on_server(); + choose(&mut tab, &list, " ▸ Volumes 2"); + tab.key(key(Code::Enter), &list, &mut Nowhere); + let rows = text(&tab.shown(&list, "here")); + assert_eq!(rows[0], "Volumes · incus-vm"); + for line in [ + " Volume Pool Size", + " data default 10GiB", + " scratch fast no set size", + ] { + assert!(rows.contains(&line.to_owned()), "{line:?} in {rows:?}"); + } + // With the pool to ask for too it takes a form, which starts with the pool. + tab.key(key(Code::Char('n')), &list, &mut Nowhere); + let form = tab.form().expect("a form"); + assert_eq!(form.wanted(), "create-volume"); + assert!(tab.arguments().is_none()); + } + + #[test] + fn n_on_a_table_with_several_ways_to_make_one_selects_them() { + let (mut tab, list) = on_server(); + let mut actions = server_actions(); + actions.push(act("build", "Build the image", "pools", &[])); + let mut state = server_state(&["default"]); + state.provisioner.collections[0] + .new + .push(used("build", "Build one", &[])); + state.provisioner.collections[0].remove.clear(); + tab.opened("incus-vm", Ok(state), Ok(actions)); + choose(&mut tab, &list, " ▸ Storage pools 1"); + tab.key(key(Code::Enter), &list, &mut Nowhere); + assert_eq!( + tab.key(key(Code::Char('n')), &list, &mut Nowhere), + Asked::Nothing(Some( + "Choose how to make one: New storage pool or Build one".into() + )) + ); + let shown = tab.shown(&list, "here"); + assert_eq!(text(&shown)[shown.selected], " ▸ New storage pool"); + assert!(shown.keys.contains("n new") && !shown.keys.contains("x remove")); + tab.key(key(Code::Down), &list, &mut Nowhere); + let Asked::Run { action, .. } = tab.key(key(Code::Enter), &list, &mut Nowhere) else { + panic!("not run"); + }; + assert_eq!(action.name, "build"); + tab.key(key(Code::Up), &list, &mut Nowhere); + tab.key(key(Code::Up), &list, &mut Nowhere); + assert_eq!( + tab.key(key(Code::Char('x')), &list, &mut Nowhere), + Asked::Nothing(Some("Storage pools are not removed here".into())) + ); + } + + #[test] + fn a_machine_has_the_provisioners_actions_on_it_on_its_page() { + let (mut tab, list) = on_server(); + choose( + &mut tab, + &list, + " studio berth-studio running", + ); + assert_eq!( + tab.key(key(Code::Enter), &list, &mut Nowhere), + Asked::OpenResource("r-studio".into()) + ); + let seen = Resource { + id: "r-studio".into(), + provisioner: "incus-vm".into(), + kind: "machine".into(), + name: "studio".into(), + state: "running".into(), + ..Resource::default() + }; + tab.opened_resource("r-studio", Ok(seen), Ok(vec![])); + let rows = text(&tab.shown(&list, "here")); + assert!(rows.contains(&" ▸ Grow root disk".to_owned()), "{rows:?}"); + choose(&mut tab, &list, " ▸ Grow root disk"); + assert!( + tab.shown(&list, "here") + .help + .contains("berth provisioner run incus-vm resize-disk instance=berth-studio") + ); + tab.key(key(Code::Enter), &list, &mut Nowhere); + let (actions, dialog) = tab.arguments().unwrap(); + assert_eq!(actions[dialog.action].arguments[dialog.index].name, "size"); + typed(&mut tab, &list, "80GiB"); + let Asked::Run { + provisioner, + action, + values, + } = tab.key(key(Code::Enter), &list, &mut Nowhere) + else { + panic!("not run"); + }; + assert_eq!( + (provisioner.as_str(), action.title()), + ("incus-vm", "Grow root disk · studio") + ); + assert_eq!(values["instance"], "berth-studio"); + // The provisioner's answer after its job is kept for its page. + tab.opened( + "incus-vm", + Ok(server_state(&["default"])), + Ok(server_actions()), + ); + assert_eq!( + tab.key(key(Code::Esc), &list, &mut Nowhere), + Asked::Open("incus-vm".into()) + ); + assert!(text(&tab.shown(&list, "here")).contains(&" ▸ Storage pools 1".to_owned())); + } } diff --git a/crates/berth/src/cli/pages.rs b/crates/berth/src/cli/pages.rs index e4854cc..07462c7 100644 --- a/crates/berth/src/cli/pages.rs +++ b/crates/berth/src/cli/pages.rs @@ -220,9 +220,18 @@ pub fn provisioner( text += &format!(" {name:<16} {id} {}\n", notes.join(" · ")); } } + text += &collections(state); let mut groups: Vec<(&str, Vec<&Action>)> = vec![]; for action in actions { - let title = berth_tui::page::group_of(action); + // The actions of a collection are listed under its name. + let title = info + .collections + .iter() + .find(|collection| collection.id == action.collection) + .map_or_else( + || berth_tui::page::group_of(action), + |collection| collection.plural.as_str(), + ); match groups .iter_mut() .find(|(known, _)| known.eq_ignore_ascii_case(title)) @@ -247,6 +256,72 @@ pub fn provisioner( text } +/// Each collection of a provisioner as a table of its items, with what +/// cannot be done to each and why. +fn collections(state: &ProvisionerState) -> String { + let mut text = String::new(); + for collection in &state.provisioner.collections { + if !collection.kinds.is_empty() { + continue; + } + let Some(items) = state.collections.get(&collection.id) else { + if state.state == "ready" { + text += &format!("\n{}\n not listed\n", collection.plural); + } + continue; + }; + text += &format!("\n{} ({})\n", collection.plural, items.len()); + if items.is_empty() { + text += " none\n"; + continue; + } + let mut cells: Vec> = vec![ + std::iter::once(collection.label.to_uppercase()) + .chain( + collection + .columns + .iter() + .map(|column| collection.column_label(column).to_uppercase()), + ) + .collect(), + ]; + for item in items { + cells.push( + std::iter::once(item.name.clone()) + .chain( + collection.columns.iter().map(|column| { + item.columns.get(&column.name).cloned().unwrap_or_default() + }), + ) + .collect(), + ); + } + let widths: Vec = (0..cells[0].len()) + .map(|column| { + cells + .iter() + .map(|row| row[column].chars().count()) + .max() + .unwrap_or(0) + }) + .collect(); + for row in &cells { + let line: Vec = row + .iter() + .zip(&widths) + .map(|(cell, width)| format!("{cell: String { let mut text = format!( @@ -413,6 +488,89 @@ mod tests { assert_eq!(lines, ["2 pools", " default zfs", " fast-ssd dir"]); } + #[test] + fn a_provisioners_collections_are_tables_and_their_actions_listed_under_them() { + let pools = berth_api::Collection { + id: "pools".into(), + label: "Pool".into(), + plural: "Storage pools".into(), + key: vec!["pool".into()], + columns: vec![ + berth_api::CollectionColumn { + name: "driver".into(), + label: "Driver".into(), + }, + berth_api::CollectionColumn { + name: "size".into(), + label: "Size".into(), + }, + ], + ..Default::default() + }; + let disks = berth_api::Collection { + id: "disks".into(), + plural: "Disks".into(), + kinds: vec!["machine".into()], + ..Default::default() + }; + let item = |name: &str, driver: &str, size: &str| berth_api::CollectionItem { + name: name.into(), + columns: [ + ("driver".to_owned(), driver.to_owned()), + ("size".to_owned(), size.to_owned()), + ] + .into(), + ..Default::default() + }; + let mut fast = item("fast", "dir", "200.0 GiB"); + fast.unavailable.insert( + "resize-pool".into(), + "a dir pool has no size of its own".into(), + ); + let state = ProvisionerState { + provisioner: ProvisionerInfo { + id: "incus-vm".into(), + collections: vec![pools, disks], + ..Default::default() + }, + state: "ready".into(), + collections: [( + "pools".to_owned(), + vec![item("default", "zfs", "100.0 GiB"), fast], + )] + .into(), + ..Default::default() + }; + let actions = [ + Action { + name: "resize-pool".into(), + label: "Grow storage pool".into(), + group: "Storage".into(), + collection: "pools".into(), + ..Action::default() + }, + Action { + name: "server".into(), + label: "Check the server".into(), + group: "Server".into(), + ..Action::default() + }, + ]; + let text = provisioner(&state, &actions, &BTreeMap::new()); + for line in [ + "\nStorage pools (2)\n", + " POOL DRIVER SIZE\n", + " default zfs 100.0 GiB\n", + " fast dir 200.0 GiB\n", + " fast: no resize-pool: a dir pool has no size of its own\n", + " Storage pools\n resize-pool Grow storage pool\n", + " Server\n server Check the server\n", + ] { + assert!(text.contains(line), "{line:?} in\n{text}"); + } + assert!(!text.contains("Disks"), "{text}"); + } + #[test] fn a_resource_is_described_with_what_can_be_done_to_it() { let found = Resource { diff --git a/crates/berth/src/cli/things.rs b/crates/berth/src/cli/things.rs index a57671f..56868b0 100644 --- a/crates/berth/src/cli/things.rs +++ b/crates/berth/src/cli/things.rs @@ -377,18 +377,23 @@ fn logs(client: &Client, host: &str, id: &str, follow: bool, tail: Option) /// A subject's actions as a table, and under it why each that cannot run /// now cannot, which is too long for a column. pub fn print_actions(actions: &[berth_api::Action]) { - let mut table = Table::new(&["action", "group", "label", "available"]); + // A provisioner's actions say which of its collections each belongs to. + let collected = actions.iter().any(|action| !action.collection.is_empty()); + let mut table = match collected { + true => Table::new(&["action", "group", "collection", "label", "available"]), + false => Table::new(&["action", "group", "label", "available"]), + }; for action in actions { let available = match action.available { true => styled("yes", Style::Good), false => styled("no", Style::Warn), }; - table.row(vec![ - action.name.clone(), - action.group.clone(), - action.label.clone(), - available, - ]); + let mut row = vec![action.name.clone(), action.group.clone()]; + if collected { + row.push(action.collection.clone()); + } + row.extend([action.label.clone(), available]); + table.row(row); } table.print("Nothing to do"); let refused: Vec<&berth_api::Action> = actions From f3f2144aea32da3367e8dc4c335a6369df0740a3 Mon Sep 17 00:00:00 2001 From: Helight Date: Sun, 15 Nov 2026 16:56:59 +0100 Subject: [PATCH 4/4] docs: collections of a provisioner --- .../docs/(guide)/extend/writing-plugins.mdx | 81 ++++++++++++++++++- tests/e2e/e2e_provisioners.py | 30 ++++++- 2 files changed, 108 insertions(+), 3 deletions(-) diff --git a/docs/content/docs/(guide)/extend/writing-plugins.mdx b/docs/content/docs/(guide)/extend/writing-plugins.mdx index a911e99..bdf3c02 100644 --- a/docs/content/docs/(guide)/extend/writing-plugins.mdx +++ b/docs/content/docs/(guide)/extend/writing-plugins.mdx @@ -275,6 +275,7 @@ Its type is `PLUGIN/ID`, here `lab/vm`. berth runs it as each provisioner regist arguments: { type: 'Argument[]', description: 'Its own arguments, which say where it is, such as a server. berth keeps their values as the settings of the provisioner, and every call gets them.' }, kinds: { type: 'Kind[]', description: 'What it makes. The kind machine makes the machines of hosts.' }, actions: { type: 'Action[]', description: 'Its own actions, each run with the verb act.' }, + collections: { type: 'Collection[]', description: 'What it holds that people browse, such as storage pools, each with the actions of its items. See Collections.' }, }} /> @@ -329,6 +330,69 @@ It also takes these: An action runs where berth runs, as the provisioner does, so it has no terminal and no user. An argument with `"secret": true` is not shown as it is typed and is masked in the job's output. +### Collections + +A collection is a list of things the provisioner holds, such as the storage pools of a server, its volumes or its images. The provisioner's page shows each as one row with the number of its items. Enter opens a table of them, and each item has a page with the actions that act on it. Its actions are the provisioner's own, declared in `actions` as usual. A collection lists the ones that belong to it in `new`, `item` and `list`, and the page offers them there and not as rows of their own. `berth provisioner run` runs them as any other action, and `berth provisioner show` prints each collection as a table. + +The Incus plugin declares its pools and the volumes in them: + +```json +"collections": [ + { + "id": "pools", "label": "Storage pool", "plural": "Storage pools", "group": "Storage", + "key": ["pool"], + "columns": [{"name": "driver", "label": "Driver"}, {"name": "size", "label": "Size"}], + "new": [{"action": "create-pool"}], + "item": [ + {"action": "resize-pool", "label": "Grow"}, + {"action": "remove-pool", "label": "Remove", "arguments": {"pool": "name"}} + ], + "remove": "remove-pool", + "show": "pools" + }, + { + "id": "volumes", "label": "Volume", "plural": "Volumes", "group": "Storage", + "key": ["pool", "volume"], "within": "pools", + "new": [{"action": "create-volume"}], + "item": [{"action": "remove-volume", "label": "Remove", "arguments": {"volume": "name"}}], + "remove": "remove-volume" + } +] +``` + + + +Each entry of `new`, `item` and `list` names an action: + +| Field | Means | +| --- | --- | +| `action` | The name of the provisioner's action | +| `label` | What it is called where the item is known, such as `Grow`. The action's own label when empty | +| `arguments` | The argument each part of the key fills where its name is not the part's own, such as `{"volume": "name"}` | + +On an item's page, the key fills the arguments of its actions, and they are not asked for again. A new item or an action on the list of a collection that is `within` another has the key of that item filled when it starts from that item's page. From the provisioner's page, it asks for that key too. The page of a pool lists the volumes in it, and the provisioner's page lists all of them. + +A collection with `kinds` has the resources of those kinds that berth made with the provisioner as its items, in place of items that `status` gives. It has a key of one name, which takes the provisioner's id of the resource, and only `item` actions. Those are offered on the page of each such resource. The Incus plugin offers its action that grows a root disk on each machine and instance this way. + +berth checks the collections when it loads the plugin. If a collection refers to an action, an argument, a kind or a collection that is not there, the provisioner cannot be used, and berth says what to fix. Each action belongs to one collection at most. + ### Arguments Each entry of `arguments`, of the provisioner, of a kind or of an action, is one value it takes. @@ -419,7 +483,7 @@ Each verb adds to it and answers like this: | --- | --- | --- | | `create` | `token`. For a machine, `seed` or `access`. For another kind, `environment`, and `spec` when the kind has one | `id`, and optionally `address`, `port` and `endpoints` | | `status` | `id` | `state`, which is `running`, `stopped` or `gone`, and optionally `address` and `endpoints`. berth shows `gone` as `missing` | -| `status` | nothing | The provisioner itself: `state` (`ready` unless it says otherwise), `message`, `details`, `values` | +| `status` | nothing | The provisioner itself: `state` (`ready` unless it says otherwise), `message`, `details`, `values`, `collections` | | `destroy` | `id` | `{}` | | `start`, `stop` | `id` | `{}`, and optionally `state` and `endpoints` | | `change` | `id`, the new values in `arguments`, `changed` with the names of the arguments whose value is new, and `environment`. For a kind with a specification, `spec`: the new one, or the one berth has | `state`, and optionally `endpoints` | @@ -463,6 +527,21 @@ A kind with `exec` among its verbs gets berth's action `exec` ([Run a command in `details` is a list of rows, each `{"label": …, "value": …}`, which berth shows as they are, such as a pool and how full it is. `values` names, by argument, the values an argument takes here, such as `{"pool": ["default", "fast"]}`. berth offers those in place of what the manifest says. +`collections` gives the items of each [collection](#collections), by its id. An item has a `name` and a `key` with a value for each part. Its `columns` hold its values by name. `unavailable` gives the item actions that cannot run on it, each with why not. The key of a collection whose key has one part may be left out: it is the name. berth leaves out an item without its whole key, and a collection left out of the answer is shown as not listed. + +```json +"collections": { + "pools": [ + {"name": "default", "columns": {"driver": "zfs", "size": "100.0 GiB"}}, + {"name": "fast", "columns": {"driver": "dir", "size": "200.0 GiB"}, + "unavailable": {"resize-pool": "A dir pool has no size of its own"}} + ], + "volumes": [ + {"name": "data", "key": {"pool": "default", "volume": "data"}, "columns": {"size": "10GiB"}} + ] +} +``` + A `status` without an `id` that fails is shown as `unreachable`, with the reason. Answer it quickly: berth asks it each time the provisioner's page opens. A `seed` provisioner also receives the cloud seed with `create`: diff --git a/tests/e2e/e2e_provisioners.py b/tests/e2e/e2e_provisioners.py index 01b2476..2f2e65a 100644 --- a/tests/e2e/e2e_provisioners.py +++ b/tests/e2e/e2e_provisioners.py @@ -37,7 +37,11 @@ elif verb == 'status': print(json.dumps({'message': f'The lab at {place} answers', 'details': [{'label': 'Benches', 'value': '3'}], - 'values': {'shelf': ['top', 'bottom']}})) + 'values': {'shelf': ['top', 'bottom']}, + 'collections': {'shelves': [ + {'name': 'top', 'columns': {'dust': 'little'}}, + {'name': 'bottom', 'columns': {'dust': 'thick'}, + 'unavailable': {'tidy': 'The bottom shelf is out of reach'}}]}})) elif verb == 'list': print(json.dumps({'resources': [{'id': 'box-1', 'kind': 'machine', 'name': 'attic', 'state': 'running'}]})) elif verb in ('create', 'change') and request.get('kind') == 'deployment': @@ -69,6 +73,8 @@ if request.get('id'): print(json.dumps({'message': f'{request["kind"]} {request["id"]} has 1 service', 'details': [{'label': 'web', 'value': 'running'}]})) + elif action['name'] == 'tidy': + print(json.dumps({'message': f'Tidied the {action["arguments"]["shelf"]} shelf'})) elif action['name'] == 'look': print(json.dumps({'message': f'Looked around {place}', 'details': [{'label': 'Dust', 'value': 'little'}]})) else: @@ -94,7 +100,11 @@ {'name': 'sweep', 'label': 'Sweep', 'confirm': 'Sweep the lab?', 'arguments': [{'name': 'shelf', 'values': ['top', 'bottom'], 'default': 'top'}, {'name': 'code', 'secret': True}]}, + {'name': 'tidy', 'label': 'Tidy a shelf', 'group': 'Lab', 'arguments': [{'name': 'shelf'}]}, ], + 'collections': [{'id': 'shelves', 'label': 'Shelf', 'plural': 'Shelves', 'key': ['shelf'], + 'columns': [{'name': 'dust', 'label': 'Dust'}], + 'item': [{'action': 'tidy', 'label': 'Tidy'}]}], }, { 'id': 'old', 'label': 'Old box', 'command': 'bin/provision', 'setup': 'apply', }]}, @@ -150,6 +160,15 @@ def test_its_settings_page_and_actions_from_the_command_line(self): 'Machines berth made with it', ' attic box-1 running · berth has no record of it', ' look'): self.assertIn(line, page) + # Its collection is a table, with what cannot be done to an item and why. + for line in ('Shelves (2)\n', ' SHELF DUST\n', ' top little\n', + ' bottom: no tidy: The bottom shelf is out of reach\n', ' Shelves\n tidy'): + self.assertIn(line, page) + actions = json.loads(self.berth('provisioner', 'actions', 'box', '-o', 'json').stdout) + self.assertEqual({action['name']: action.get('collection', '') for action in actions}['tidy'], 'shelves') + self.assertRegex(self.berth('provisioner', 'actions', 'box').stdout, r'(?m)^tidy\s+Lab\s+shelves\s+Tidy a shelf') + tidied = self.berth('provisioner', 'run', 'box', 'tidy', 'shelf=top', '--yes').stdout + self.assertIn('Tidied the top shelf', tidied) # For this once, another place. self.assertIn('The lab at cellar answers', self.berth('provisioner', 'show', 'box', 'place=cellar').stdout) looked = self.berth('provisioner', 'run', 'box', 'look').stdout @@ -169,9 +188,13 @@ def test_through_berth_serve_an_action_that_changes_something_is_a_job(self): page = serve.call('GET', '/v1/provisioners/box') self.assertEqual((page['state'], page['message']), ('ready', 'The lab at attic answers')) self.assertEqual(page['values'], {'shelf': ['top', 'bottom']}) + self.assertEqual([found['id'] for found in page['provisioner']['collections']], ['shelves']) + self.assertEqual(page['collections']['shelves'][1], + {'name': 'bottom', 'key': {'shelf': 'bottom'}, 'columns': {'dust': 'thick'}, + 'unavailable': {'tidy': 'The bottom shelf is out of reach'}}) actions = serve.call('GET', '/v1/provisioners/box/actions') self.assertEqual([action['name'] for action in actions], - ['new-deployment', 'settings', 'look', 'sweep', 'adopt', 'remove']) + ['new-deployment', 'settings', 'look', 'sweep', 'tidy', 'adopt', 'remove']) looked = serve.call('POST', '/v1/provisioners/box/actions/look') self.assertEqual(looked['result']['message'], 'Looked around attic') acted = serve.call('POST', '/v1/provisioners/box/actions/sweep', @@ -525,6 +548,9 @@ def test_the_engine_answers_and_lists_its_runtimes(self): self.assertIn('Runtimes', page) volumes = station.berth('provisioner', 'run', 'docker', 'volumes').stdout self.assertIn(f'volumes at {endpoint}', volumes) + # The engine's images and volumes are tables of their own on the page. + self.assertRegex(page, r'(?m)^Images \(\d+\)$') + self.assertRegex(page, r'(?m)^Volumes \(\d+\)$') def test_a_compose_deployment_is_made_changed_and_removed(self): station = Workstation('provisioners-compose', ssh_key=False, trust=False)