[PATCH proxmox-backup 17/28] api: backup: provide retain-until timestamp for extended prune protection

[Christian Ebner <c.ebner@proxmox.com>]

Allows to protect snapshots from being pruned by providing a retention
timestamp during backup.

Pruning must now also parse the manifest if present, which adds some
additional overhead on snapshot forget operations. This is however not
a performance critical code path as prunes run either in a job anyways,
where a slight delay for each prune is acceptable or a single snapshot
forget via API/CLI.

However, as a side effect manifests which cannot be parsed can no
longer be pruned without manual intervention.

Signed-off-by: Christian Ebner <c.ebner@proxmox.com>
---
 pbs-datastore/src/backup_info.rs | 11 +++++++++++
 pbs-datastore/src/manifest.rs    | 27 +++++++++++++++++++++++++++
 src/api2/backup/environment.rs   |  4 ++++
 src/api2/backup/mod.rs           | 12 ++++++++++++
 4 files changed, 54 insertions(+)

diff --git a/pbs-datastore/src/backup_info.rs b/pbs-datastore/src/backup_info.rs
index f476d4469..13eb0cdf6 100644
--- a/pbs-datastore/src/backup_info.rs
+++ b/pbs-datastore/src/backup_info.rs
@@ -924,6 +924,17 @@ impl BackupDir {
             bail!("cannot remove protected snapshot"); // use special error type?
         }
 
+        if let Some((manifest, _size)) = self.load_manifest_optionally(false)? {
+            if let Some(retain_until) = manifest.retention_timestamp()? {
+                if retain_until > proxmox_time::epoch_i64() {
+                    bail!(
+                        "snapshot protected by retention until {}",
+                        proxmox_time::epoch_to_rfc3339(retain_until)?
+                    );
+                }
+            }
+        }
+
         if let DatastoreBackend::S3(s3_client) = backend {
             let path = self.relative_path();
             let snapshot_prefix = path
diff --git a/pbs-datastore/src/manifest.rs b/pbs-datastore/src/manifest.rs
index 11de1085b..a31c3ea7d 100644
--- a/pbs-datastore/src/manifest.rs
+++ b/pbs-datastore/src/manifest.rs
@@ -82,6 +82,33 @@ impl BackupManifest {
         Ok(())
     }
 
+    /// Set a retention timestamp for given manifest. Snapshot destruction is only allowed after
+    /// this time, the caller must assure a valid timestamp is passed and the caller has privileges
+    /// to do so. Providing `None` will clear the timestamp.
+    pub fn add_retention_timestamp(&mut self, timestamp: Option<i64>) {
+        match timestamp {
+            Some(timestamp) => self.unprotected["retain-until"] = timestamp.into(),
+            None => {
+                self.unprotected["retain-until"].take();
+            }
+        }
+    }
+
+    /// Parse the retention timestamp for given manifest, if set.
+    /// Returns `Ok(None)` if not set and errors when set but parsing failed.
+    pub fn retention_timestamp(&self) -> Result<Option<i64>, Error> {
+        match &self.unprotected["retain-until"] {
+            Value::Number(timestamp) => {
+                let retain_until = timestamp.as_i64().ok_or_else(|| {
+                    format_err!("unexpected value for retain-until timestamp: {timestamp}")
+                })?;
+                Ok(Some(retain_until))
+            }
+            Value::Null => Ok(None),
+            _ => bail!("unexpected value variant for retain-until timestamp"),
+        }
+    }
+
     pub fn files(&self) -> &[FileInfo] {
         &self.files[..]
     }
diff --git a/src/api2/backup/environment.rs b/src/api2/backup/environment.rs
index be70d74f8..ce2be070c 100644
--- a/src/api2/backup/environment.rs
+++ b/src/api2/backup/environment.rs
@@ -154,6 +154,7 @@ pub struct BackupEnvironment {
     pub backup_dir: BackupDir,
     pub last_backup: Option<BackupInfo>,
     pub backend: DatastoreBackend,
+    pub retain_until: Option<i64>,
     state: Arc<Mutex<SharedBackupState>>,
 }
 
@@ -166,6 +167,7 @@ impl BackupEnvironment {
         backup_dir: BackupDir,
         no_cache: bool,
         backup_lock_guards: BackupLockGuards,
+        retain_until: Option<i64>,
     ) -> Result<Self, Error> {
         let state = SharedBackupState {
             finished: BackupState::Active,
@@ -195,6 +197,7 @@ impl BackupEnvironment {
             last_backup: None,
             backend,
             state: Arc::new(Mutex::new(state)),
+            retain_until,
         })
     }
 
@@ -797,6 +800,7 @@ impl BackupEnvironment {
 
         // check for valid manifest and store stats
         manifest.unprotected["chunk_upload_stats"] = stats;
+        manifest.add_retention_timestamp(self.retain_until);
 
         for file_info in manifest.files() {
             let archive_name = file_info.filename.as_ref();
diff --git a/src/api2/backup/mod.rs b/src/api2/backup/mod.rs
index cb54d397c..cfce13943 100644
--- a/src/api2/backup/mod.rs
+++ b/src/api2/backup/mod.rs
@@ -52,6 +52,7 @@ pub const API_METHOD_UPGRADE_BACKUP: ApiMethod = ApiMethod::new(
             ("backup-type", false, &BACKUP_TYPE_SCHEMA),
             ("backup-id", false, &BACKUP_ID_SCHEMA),
             ("backup-time", false, &BACKUP_TIME_SCHEMA),
+            ("retain-until", true, &BACKUP_TIME_SCHEMA),
             ("debug", true, &BooleanSchema::new("Enable verbose debug logging.").schema()),
             ("benchmark", true, &BooleanSchema::new("Job is a benchmark (do not keep data).").schema()),
             ("no-cache", true, &BooleanSchema::new("Disable local datastore cache for network storages").schema()),
@@ -88,6 +89,16 @@ fn upgrade_to_backup_protocol(
         let store = required_string_param(&param, "store")?.to_owned();
         let backup_ns = optional_ns_param(&param)?;
         let backup_dir_arg = pbs_api_types::BackupDir::deserialize(&param)?;
+        let retain_until = match &param["retain-until"] {
+            Value::Number(timestamp) => {
+                let timestamp = timestamp
+                    .as_i64()
+                    .ok_or_else(|| format_err!("invalid retain-until timestamp"))?;
+                Some(timestamp)
+            }
+            Value::Null => None,
+            _ => bail!("unexpected retain-until timestamp variant"),
+        };
 
         let user_info = CachedUserInfo::new()?;
 
@@ -233,6 +244,7 @@ fn upgrade_to_backup_protocol(
                     backup_dir,
                     no_cache,
                     backup_lock_guards,
+                    retain_until,
                 )?;
 
                 env.debug = debug;
-- 
2.47.3