feat(config): Add hooks (#1218)

This PR adds `run-before`, `run-after`, `run-failure` and `run-finally` hooks for: - all commands in the `[global.hooks]` config profile section - commands accessing the repository in the `[repository.hooks]` config profile section - the `backup` command specifically in the `[backup.hooks]` config profile section - specific backup sources in the `[backup.snapshots.hooks]` section Note: This PR includes only calling the given commands. If there is the wish for supplying information to the commands (env variables or parameter substitution), this should be covered by a separate feature request/PR. closes #902 --------- Signed-off-by: simonsan <[email protected]> Co-authored-by: simonsan <[email protected]>
rustic-rs · Oct 5, 2024 · cb3903b · cb3903b
1 parent 7aff9dc
commit cb3903b
Show file tree

Hide file tree

Showing 75 changed files with 1,625 additions and 447 deletions.
diff --git a/.gitignore b/.gitignore
@@ -5,3 +5,8 @@ mutants.out
 cargo-test*
 coverage/*lcov
 .testscompletions-*
+
+# Ignore generated test files
+/tests/generated/*.toml
+/tests/generated/*.log
+/tests/generated/test-restore
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -106,6 +106,7 @@ toml = "0.8"
 abscissa_core = { version = "0.7.0", default-features = false, features = ["testing"] }
 assert_cmd = "2.0.16"
 dircmp = "0.2"
+insta = { version = "1.40.0", features = ["ron"] }
 predicates = "3.1.2"
 pretty_assertions = "1.4"
 quickcheck = "1"

diff --git a/config/README.md b/config/README.md
@@ -14,6 +14,27 @@ This specification covers all the available sections and attributes in the
 variable names. Users can customize their backup behavior by modifying these
 attributes according to their needs.
 
+## Table of Contents
+
+- [Merge Precedence](#merge-precedence)
+- [Profiles](#profiles)
+- [Sections and Attributes](#sections-and-attributes)
+  - [Global Options `[global]`](#global-options-global)
+  - [Global Hooks `[global.hooks]`](#global-hooks-globalhooks)
+  - [Global Options - env variables `[global.env]`](#global-options---env-variables-globalenv)
+  - [Repository Options `[repository]`](#repository-options-repository)
+  - [Repository Options (Additional) `[repository.options]`](#repository-options-additional-repositoryoptions)
+  - [Repository Options for cold repo (Additional) `[repository.options-cold]`](#repository-options-for-cold-repo-additional-repositoryoptions-cold)
+  - [Repository Options for hot repo (Additional) `[repository.options-hot]`](#repository-options-for-hot-repo-additional-repositoryoptions-hot)
+  - [Repository Hooks `[repository.hooks]`](#repository-hooks-repositoryhooks)
+  - [Snapshot-Filter Options `[snapshot-filter]`](#snapshot-filter-options-snapshot-filter)
+  - [Backup Options `[backup]`](#backup-options-backup)
+  - [Backup Hooks `[backup.hooks]`](#backup-hooks-backuphooks)
+  - [Backup Snapshots `[[backup.snapshots]]`](#backup-snapshots-backupsnapshots)
+  - [Forget Options `[forget]`](#forget-options-forget)
+  - [Copy Targets `[copy]`](#copy-targets-copy)
+  - [WebDAV Options `[webdav]`](#webdav-options-webdav)
+
 ## Merge Precedence
 
 The merge precedence for values is:
@@ -64,6 +85,20 @@ If you want to contribute your own configuration, please
 | progress-interval | The interval at which progress indicators are shown.                              | "100ms"       | "1m"              | RUSTIC_PROGRESS_INTERVAL | --progress-interval |
 | use-profiles      | Array of profiles to use. Allows to recursively use other profiles.               | Empty array   | ["2nd", "3rd"]    | RUSTIC_USE_PROFILE       | --use-profile, -P   |
 
+### Global Hooks `[global.hooks]`
+
+These external commands are run before and after each commands, respectively.
+
+**Note**: There are also repository hooks, which should be used for commands
+needed to set up the repository (like mounting the repo dir), see below.
+
+| Attribute   | Description                                       | Default Value | Example Value | Environment Variable |
+| ----------- | ------------------------------------------------- | ------------- | ------------- | -------------------- |
+| run-before  | Run the given commands before execution           | not set       | ["echo test"] |                      |
+| run-after   | Run the given commands after successful execution | not set       | ["echo test"] |                      |
+| run-failed  | Run the given commands after failed execution     | not set       | ["echo test"] |                      |
+| run-finally | Run the given commands after every execution      | not set       | ["echo test"] |                      |
+
 ### Global Options - env variables `[global.env]`
 
 All given environment variables are set before processing. This is handy to
@@ -115,6 +150,13 @@ upper snake case and prefix with "RUSTIC_REPO_OPTHOT_".
 
 see Repository Options
 
+### Repository Hooks `[repository.hooks]`
+
+These external commands are run before and after each repository-accessing
+commands, respectively.
+
+See [Global Hooks](#global-hooks-globalhooks).
+
 ### Snapshot-Filter Options `[snapshot-filter]`
 
 | Attribute          | Description                                                            | Default Value | Example Value            | CLI Option           |
@@ -173,14 +215,26 @@ can be overwritten in the source-specific configuration, see below.
 | time                  | Set the time saved in the snapshot.                                                     | current time          |               | --time                  |
 | with-atime            | If true, includes file access time (atime) in the backup.                               | false                 |               | --with-atime            |
 
+### Backup Hooks `[backup.hooks]`
+
+These external commands are run before and after each backup, respectively.
+
+**Note**: Global hooks and repository hooks are run additionaly.
+
+See [Global Hooks](#global-hooks-globalhooks).
+
 ### Backup Snapshots `[[backup.snapshots]]`
 
 **Note**: All of the backup options mentioned before can also be used as
-source-specific option and then only apply to this source.
+snapshot-specific option and then only apply to this snapshot.
+
+| Attribute | Description                                                   | Default Value | Example Value                                                          |
+| --------- | ------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------- |
+| sources   | Array of source directories or file(s) to back up.            | []            | ["/dir1", "/dir2"]                                                     |
+| hooks     | Hooks to run before and after backing up the defined sources. | Not set       | { run-before = [], run-after = [], run-failed = [], run-finally = [] } |
 
-| Attribute | Description                                        | Default Value | Example Value      |
-| --------- | -------------------------------------------------- | ------------- | ------------------ |
-| sources   | Array of source directories or file(s) to back up. | []            | ["/dir1", "/dir2"] |
+Source-specific hooks are called additionally to global, repository and backup
+hooks when backing up the defined sources into a snapshot.
 
 ### Forget Options `[forget]`
 

diff --git a/config/full.toml b/config/full.toml
@@ -16,6 +16,16 @@ progress-interval = "100ms"
 dry-run = false
 check-index = false
 
+# Global hooks: The given commands are called for every command
+[global.hooks]
+run-before = [
+  # long form giving command and args explicitely and allow to specify failure behavior
+  { command = "echo", args = ["before"], on-failure = "warn" }, # allowed values for on-failure: "error" (default), "warn", "ignore"
+] # Default: []
+run-after = ["echo after"] # Run after if successful, short version, default: []
+run-failed = ["echo failed"] # Default: []
+run-finally = ["echo finally"] # Always run after, default: []
+
 # Global env variables: These are set by rustic before calling a subcommand, e.g. rclone or commands
 # defined in the repository options.
 [global.env]
@@ -65,6 +75,13 @@ throttle = "10kB,10MB" # limit and burst per second; only opendal backends; Defa
 [repository.options-cold]
 # see [repository.options]
 
+# Repository hooks: The given commands are called for commands accessing the repository.
+[repository.hooks]
+run-before = ["echo before"] # Default: []
+run-after = ["echo after"] # Run after if successful, default: []
+run-failed = ["echo failed"] # Default: []
+run-finally = ["echo finally"] # Always run after, default: []
+
 # Snapshot-filter options: These options apply to all commands that use snapshot filters
 [snapshot-filter]
 filter-hosts = ["host1", "host2"] # Default: []
@@ -114,12 +131,26 @@ no-scan = false
 quiet = false
 skip-identical-parent = false
 
+# Backup hooks: The given commands are called for the `backup` command
+[backup.hooks]
+run-before = ["echo before"] # Default: []
+run-after = ["echo after"] # Run after if successful, default: []
+run-failed = ["echo failed"] # Default: []
+run-finally = ["echo finally"] # Always run after, default: []
+
 # Backup options for specific sources - all above options are also available here and replace them for the given source
 [[backup.snapshots]]
 sources = ["/path/to/source1"]
 label = "label" # Default: not set
 # .. and so on. see [backup]
 
+# Source-specific hooks: The given commands when backing up the defined source
+[backup.snapshots.hooks]
+run-before = ["echo before"] # Default: []
+run-after = ["echo after"] # Run after if successful, default: []
+run-failed = ["echo failed"] # Default: []
+run-finally = ["echo finally"] # Always run after, default: []
+
 [[backup.snapshots]]
 sources = [
   "/path/to/source2",

diff --git a/config/hooks.toml b/config/hooks.toml
@@ -0,0 +1,35 @@
+# Hooks configuration
+#
+# Hooks are commands that are run during certain events in the application lifecycle.
+# They can be used to run custom scripts or commands before or after certain actions.
+# The hooks are run in the order they are defined in the configuration file.
+# The hooks are divided into 4 categories: global, repository, backup,
+# and specific backup sources.
+#
+# You can also read a more detailed explanation of the hooks in the documentation:
+# https://rustic.cli.rs/docs/commands/misc/hooks.html
+#
+# Please make sure to check the in-repository documentation for the config files
+# available at: https://github.com/rustic-rs/rustic/blob/main/config/README.md
+#
+[global.hooks]
+run-before = []
+run-after = []
+run-failed = []
+run-finally = []
+
+[repository.hooks]
+run-before = []
+run-after = []
+run-failed = []
+run-finally = []
+
+[backup.hooks]
+run-before = []
+run-after = []
+run-failed = []
+run-finally = []
+
+[[backup.snapshots]]
+sources = []
+hooks = { run-before = [], run-after = [], run-failed = [], run-finally = [] }