feat: Add CommandInput (#252)

Add the new type CommandInput. This type supports serde and clap (using
`FromStr`) and is supposed to be used where users need to specify
commands which are to be executed.

There are 3 ways to define commands (here TOML is used):
- as one string: `command = "echo test"`
- as command and args as string array: `command = {command = "echo",
args = ["test1", "test2"] }`
- additionally specify error treatment: `command = {command = "echo",
args = ["test1", "test2"], on_failure = "ignore" }`

In the first example the full command and the args are split using
`shell_words` which requires special escaping or quoting when spaces are
contained. In the other examples every string is taken literally as
given (but TOML escapes may apply when parsing TOML).

This PR only adds the new type, using it on existing commands will be a
breaking change.

crates/core/Cargo.toml

@@ -32,7 +32,7 @@ edition = "2021"
 default = []
 cli = ["merge", "clap"]
 merge = ["dep:merge"]
-clap = ["dep:clap", "dep:shell-words"]
+clap = ["dep:clap"]
 webdav = ["dep:dav-server", "dep:futures"]
 
 [package.metadata.docs.rs]
@@ -88,7 +88,6 @@ dirs = "5.0.1"
 # cli support
 clap = { version = "4.5.16", optional = true, features = ["derive", "env", "wrap_help"] }
 merge = { version = "0.1.0", optional = true }
-shell-words = { version = "1.1.0", optional = true }
 
 # vfs support
 dav-server = { version = "0.7.0", default-features = false, optional = true }
@@ -107,6 +106,7 @@ gethostname = "0.5.0"
 humantime = "2.1.0"
 itertools = "0.13.0"
 quick_cache = "0.6.2"
+shell-words = "1.1.0"
 strum = { version = "0.26.3", features = ["derive"] }
 zstd = "0.13.2"
 
@@ -140,6 +140,7 @@ rustup-toolchain = "0.1.7"
 simplelog = "0.12.2"
 tar = "0.4.41"
 tempfile = { workspace = true }
+toml = "0.8.19"
 
 [lints]
 workspace = true

crates/core/src/error.rs

@@ -11,6 +11,7 @@ use std::{
     num::{ParseIntError, TryFromIntError},
     ops::RangeInclusive,
     path::{PathBuf, StripPrefixError},
+    process::ExitStatus,
     str::Utf8Error,
 };
 
@@ -220,6 +221,8 @@ pub enum CommandErrorKind {
     NotAllowedWithAppendOnly(String),
     /// Specify one of the keep-* options for forget! Please use keep-none to keep no snapshot.
     NoKeepOption,
+    /// {0:?}
+    FromParseError(#[from] shell_words::ParseError),
 }
 
 /// [`CryptoErrorKind`] describes the errors that can happen while dealing with Cryptographic functions
@@ -285,6 +288,10 @@ pub enum RepositoryErrorKind {
     PasswordCommandExecutionFailed,
     /// error reading password from command
     ReadingPasswordFromCommandFailed,
+    /// running command {0}:{1} was not successful: {2}
+    CommandExecutionFailed(String, String, std::io::Error),
+    /// running command {0}:{1} returned status: {2}
+    CommandErrorStatus(String, String, ExitStatus),
     /// error listing the repo config file
     ListingRepositoryConfigFileFailed,
     /// error listing the repo keys

crates/core/src/lib.rs

@@ -149,7 +149,7 @@ pub use crate::{
         PathList, SnapshotGroup, SnapshotGroupCriterion, SnapshotOptions, StringList,
     },
     repository::{
-        FullIndex, IndexedFull, IndexedIds, IndexedStatus, IndexedTree, OpenStatus, Repository,
-        RepositoryOptions,
+        CommandInput, FullIndex, IndexedFull, IndexedIds, IndexedStatus, IndexedTree, OpenStatus,
+        Repository, RepositoryOptions,
     },
 };

crates/core/src/repository.rs

@@ -1,8 +1,11 @@
 // Note: we need a fully qualified Vec here for clap, see https://github.com/clap-rs/clap/issues/4481
 #![allow(unused_qualifications)]
 
+mod command_input;
 mod warm_up;
 
+pub use command_input::CommandInput;
+
 use std::{
     cmp::Ordering,
     fs::File,

crates/core/src/repository/command_input.rs

@@ -0,0 +1,214 @@
+use std::{
+    fmt::{Debug, Display},
+    process::{Command, ExitStatus},
+    str::FromStr,
+};
+
+use log::{debug, error, trace, warn};
+use serde::{Deserialize, Serialize, Serializer};
+use serde_with::{serde_as, DisplayFromStr, PickFirst};
+
+use crate::{
+    error::{RepositoryErrorKind, RusticErrorKind},
+    RusticError, RusticResult,
+};
+
+/// A command to be called which can be given as CLI option as well as in config files
+/// `CommandInput` implements Serialize/Deserialize as well as FromStr.
+#[serde_as]
+#[derive(Debug, Default, Clone, PartialEq, Eq, Deserialize)]
+pub struct CommandInput(
+    // Note: we use _CommandInput here which itself impls FromStr in order to use serde_as PickFirst for CommandInput.
+    //#[serde(
+    //    serialize_with = "serialize_command",
+    //    deserialize_with = "deserialize_command"
+    //)]
+    #[serde_as(as = "PickFirst<(DisplayFromStr,_)>")] _CommandInput,
+);
+
+impl Serialize for CommandInput {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        // if on_failure is default, we serialize to the short `Display` version, else we serialize the struct
+        if self.0.on_failure == OnFailure::default() {
+            serializer.serialize_str(&self.to_string())
+        } else {
+            self.0.serialize(serializer)
+        }
+    }
+}
+
+impl From<Vec<String>> for CommandInput {
+    fn from(value: Vec<String>) -> Self {
+        Self(value.into())
+    }
+}
+
+impl From<CommandInput> for Vec<String> {
+    fn from(value: CommandInput) -> Self {
+        value.0.iter().cloned().collect()
+    }
+}
+
+impl CommandInput {
+    /// Returns if a command is set
+    #[must_use]
+    pub fn is_set(&self) -> bool {
+        !self.0.command.is_empty()
+    }
+
+    /// Returns the command
+    #[must_use]
+    pub fn command(&self) -> &str {
+        &self.0.command
+    }
+
+    /// Returns the command args
+    #[must_use]
+    pub fn args(&self) -> &[String] {
+        &self.0.args
+    }
+
+    /// Returns the error handling for the command
+    #[must_use]
+    pub fn on_failure(&self) -> OnFailure {
+        self.0.on_failure
+    }
+
+    /// Runs the command if it is set
+    ///
+    /// # Errors
+    ///
+    /// `RusticError` if return status cannot be read
+    pub fn run(&self, context: &str, what: &str) -> RusticResult<()> {
+        if !self.is_set() {
+            trace!("not calling command {context}:{what} - not set");
+            return Ok(());
+        }
+        debug!("calling command {context}:{what}: {self:?}");
+        let status = Command::new(self.command()).args(self.args()).status();
+        self.on_failure().handle_status(status, context, what)?;
+        Ok(())
+    }
+}
+
+impl FromStr for CommandInput {
+    type Err = RusticError;
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Ok(Self(_CommandInput::from_str(s)?))
+    }
+}
+
+impl Display for CommandInput {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        Display::fmt(&self.0, f)
+    }
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(default, rename_all = "kebab-case")]
+struct _CommandInput {
+    command: String,
+    args: Vec<String>,
+    on_failure: OnFailure,
+}
+
+impl _CommandInput {
+    fn iter(&self) -> impl Iterator<Item = &String> {
+        std::iter::once(&self.command).chain(self.args.iter())
+    }
+}
+
+impl From<Vec<String>> for _CommandInput {
+    fn from(mut value: Vec<String>) -> Self {
+        if value.is_empty() {
+            Self::default()
+        } else {
+            let command = value.remove(0);
+            Self {
+                command,
+                args: value,
+                ..Default::default()
+            }
+        }
+    }
+}
+
+impl FromStr for _CommandInput {
+    type Err = RusticError;
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Ok(split(s)?.into())
+    }
+}
+
+impl Display for _CommandInput {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let s = shell_words::join(self.iter());
+        f.write_str(&s)
+    }
+}
+
+/// Error handling for commands called as `CommandInput`
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum OnFailure {
+    /// errors in command calling will result in rustic errors
+    #[default]
+    Error,
+    /// errors in command calling will result in rustic warnings, but are otherwise ignored
+    Warn,
+    /// errors in command calling will be ignored
+    Ignore,
+}
+
+impl OnFailure {
+    fn eval<T>(self, res: RusticResult<T>) -> RusticResult<Option<T>> {
+        match res {
+            Err(err) => match self {
+                Self::Error => {
+                    error!("{err}");
+                    Err(err)
+                }
+                Self::Warn => {
+                    warn!("{err}");
+                    Ok(None)
+                }
+                Self::Ignore => Ok(None),
+            },
+            Ok(res) => Ok(Some(res)),
+        }
+    }
+
+    /// Handle a status of a called command depending on the defined error handling
+    pub fn handle_status(
+        self,
+        status: Result<ExitStatus, std::io::Error>,
+        context: &str,
+        what: &str,
+    ) -> RusticResult<()> {
+        let status = status.map_err(|err| {
+            RepositoryErrorKind::CommandExecutionFailed(context.into(), what.into(), err).into()
+        });
+        let Some(status) = self.eval(status)? else {
+            return Ok(());
+        };
+
+        if !status.success() {
+            let _: Option<()> = self.eval(Err(RepositoryErrorKind::CommandErrorStatus(
+                context.into(),
+                what.into(),
+                status,
+            )
+            .into()))?;
+        }
+        Ok(())
+    }
+}
+
+/// helper to split arguments
+// TODO: Maybe use special parser (winsplit?) for windows?
+fn split(s: &str) -> RusticResult<Vec<String>> {
+    Ok(shell_words::split(s).map_err(|err| RusticErrorKind::Command(err.into()))?)
+}

crates/core/tests/command_input.rs

@@ -0,0 +1,94 @@
+use std::fs::File;
+
+use anyhow::Result;
+use rustic_core::CommandInput;
+use serde::{Deserialize, Serialize};
+use tempfile::tempdir;
+
+#[test]
+fn from_str() -> Result<()> {
+    let cmd: CommandInput = "echo test".parse()?;
+    assert_eq!(cmd.command(), "echo");
+    assert_eq!(cmd.args(), ["test"]);
+
+    let cmd: CommandInput = r#"echo "test test" test"#.parse()?;
+    assert_eq!(cmd.command(), "echo");
+    assert_eq!(cmd.args(), ["test test", "test"]);
+    Ok(())
+}
+
+#[cfg(not(windows))]
+#[test]
+fn from_str_failed() {
+    let failed_cmd: std::result::Result<CommandInput, _> = "echo \"test test".parse();
+    assert!(failed_cmd.is_err());
+}
+
+#[test]
+fn toml() -> Result<()> {
+    #[derive(Deserialize, Serialize)]
+    struct Test {
+        command1: CommandInput,
+        command2: CommandInput,
+        command3: CommandInput,
+        command4: CommandInput,
+    }
+
+    let test = toml::from_str::<Test>(
+        r#"
+            command1 = "echo test"
+            command2 = {command = "echo", args = ["test test"], on-failure = "error"}
+            command3 = {command = "echo", args = ["test test", "test"]}
+            command4 = {command = "echo", args = ["test test", "test"], on-failure = "warn"}
+        "#,
+    )?;
+
+    assert_eq!(test.command1.command(), "echo");
+    assert_eq!(test.command1.args(), ["test"]);
+    assert_eq!(test.command2.command(), "echo");
+    assert_eq!(test.command2.args(), ["test test"]);
+    assert_eq!(test.command3.command(), "echo");
+    assert_eq!(test.command3.args(), ["test test", "test"]);
+
+    let test_ser = toml::to_string(&test)?;
+    assert_eq!(
+        test_ser,
+        r#"command1 = "echo test"
+command2 = "echo 'test test'"
+command3 = "echo 'test test' test"
+
+[command4]
+command = "echo"
+args = ["test test", "test"]
+on-failure = "warn"
+"#
+    );
+    Ok(())
+}
+
+#[test]
+fn run_empty() -> Result<()> {
+    // empty command
+    let command: CommandInput = "".parse()?;
+    dbg!(&command);
+    assert!(!command.is_set());
+    command.run("test", "empty")?;
+    Ok(())
+}
+
+#[cfg(not(windows))]
+#[test]
+fn run_deletey() -> Result<()> {
+    // create a tmp file which will be removed by
+    let dir = tempdir()?;
+    let filename = dir.path().join("file");
+    let _ = File::create(&filename)?;
+    assert!(filename.exists());
+
+    let command: CommandInput = format!("rm {}", filename.to_str().unwrap()).parse()?;
+    assert!(command.is_set());
+    command.run("test", "test-call")?;
+    assert!(!filename.exists());
+
+    Ok(())
+}