[PATCH proxmox-backup v2 24/43] 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 as dedicated worker
tasks or a single snapshot forget via API/CLI, for both cases the
additional parsing overhead on each snapshot prune is acceptable.

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 |  9 ++++++
 pbs-datastore/src/manifest.rs    | 50 ++++++++++++++++++++++++++++++++
 src/api2/backup/environment.rs   | 14 +++++++++
 src/api2/backup/mod.rs           | 12 ++++++++
 4 files changed, 85 insertions(+)

diff --git a/pbs-datastore/src/backup_info.rs b/pbs-datastore/src/backup_info.rs
index f476d4469..ac3ea8378 100644
--- a/pbs-datastore/src/backup_info.rs
+++ b/pbs-datastore/src/backup_info.rs
@@ -924,6 +924,15 @@ 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.active_retention_lock()? {
+                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 4d482c252..548e419c6 100644
--- a/pbs-datastore/src/manifest.rs
+++ b/pbs-datastore/src/manifest.rs
@@ -82,6 +82,56 @@ impl BackupManifest {
         Ok(())
     }
 
+    /// Set or extend a retention time for given manifest. The given retention timestamp must be
+    /// greater than any already set timestamp on the manifest. Snapshot destruction is only allowed
+    /// after this time.
+    ///
+    /// The caller must assure a valid timestamp is passed, it does not exceed datastore wide
+    /// retention restrictions and required privileges to modify the timestamp are met.
+    pub fn modify_retention_timestamp(&mut self, timestamp: i64) -> Result<(), Error> {
+        if let Some(previous) = self.retention_timestamp()? {
+            if timestamp < previous {
+                bail!(
+                    "cannot shorten retention time to {}, locked until {}",
+                    proxmox_time::epoch_to_rfc3339_utc(timestamp)?,
+                    proxmox_time::epoch_to_rfc3339_utc(previous)?,
+                );
+            }
+        }
+
+        self.unprotected["retain-until"] = timestamp.into();
+
+        Ok(())
+    }
+
+    /// 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"),
+        }
+    }
+
+    /// Check if the manifest has a retention lock and if the lock is still active.
+    ///
+    /// Errors when parsing the retention timestamp fails.
+    pub fn active_retention_lock(&self) -> Result<Option<i64>, Error> {
+        if let Some(retain_until) = self.retention_timestamp()? {
+            if retain_until >= proxmox_time::epoch_i64() {
+                return Ok(Some(retain_until));
+            }
+        }
+        Ok(None)
+    }
+
     pub fn files(&self) -> &[FileInfo] {
         &self.files[..]
     }
diff --git a/src/api2/backup/environment.rs b/src/api2/backup/environment.rs
index be70d74f8..7b772c44f 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,
         })
     }
 
@@ -798,6 +801,17 @@ impl BackupEnvironment {
         // check for valid manifest and store stats
         manifest.unprotected["chunk_upload_stats"] = stats;
 
+        // Strip any retention timestamp from the client side uploaded manifest,
+        // only allow the retention calculated server side.
+        // This also covers dropping any pre-existing retentions from the source
+        // during push syncs, if not stripped by the client already.
+        if !manifest.unprotected["retain-until"].take().is_null() {
+            self.log("stripped 'retain-until' from client provided manifest");
+        }
+        if let Some(retain_until) = self.retain_until {
+            manifest.modify_retention_timestamp(retain_until)?;
+        }
+
         for file_info in manifest.files() {
             let archive_name = file_info.filename.as_ref();
             match state.uploaded_archives.get(archive_name) {
diff --git a/src/api2/backup/mod.rs b/src/api2/backup/mod.rs
index d658e8c17..7d2236c9e 100644
--- a/src/api2/backup/mod.rs
+++ b/src/api2/backup/mod.rs
@@ -53,6 +53,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()),
@@ -89,6 +90,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()?;
 
@@ -234,6 +245,7 @@ fn upgrade_to_backup_protocol(
                     backup_dir,
                     no_cache,
                     backup_lock_guards,
+                    retain_until,
                 )?;
 
                 env.debug = debug;
-- 
2.47.3