Update litestream configuration (#729)

This changeset continues the `litestream` configuration updates
following:

1. #719
2. #727

Author: epompeii

lib/bencher_json/src/system/config/plus/litestream.rs

@@ -11,20 +11,36 @@ use serde::{Deserialize, Serialize};
 pub struct JsonLitestream {
     /// Disaster recovery replica
     pub replica: JsonReplica,
-    /// Snapshot interval
+    /// Snapshot configuration
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub snapshot_interval: Option<String>,
-    /// Snapshot retention
+    pub snapshot: Option<JsonSnapshot>,
+    /// Validation configuration
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub retention: Option<String>,
-    /// Validation interval
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub validation_interval: Option<String>,
+    pub validation: Option<JsonValidation>,
     /// Checkpoint configuration
     #[serde(skip_serializing_if = "Option::is_none")]
     pub checkpoint: Option<JsonCheckpoint>,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "schema", derive(JsonSchema))]
+pub struct JsonSnapshot {
+    /// How often new snapshots are created
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub interval: Option<String>,
+    /// How long snapshot & WAL files are kept
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub retention: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "schema", derive(JsonSchema))]
+pub struct JsonValidation {
+    /// How often to restore and validate replica data
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub interval: Option<String>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[cfg_attr(feature = "schema", derive(JsonSchema))]
 pub struct JsonCheckpoint {
@@ -113,7 +129,7 @@ mod db {
 
     use crate::system::config::LogLevel;
 
-    use super::{JsonCheckpoint, JsonLitestream, JsonReplica};
+    use super::{JsonCheckpoint, JsonLitestream, JsonReplica, JsonSnapshot, JsonValidation};
 
     impl JsonLitestream {
         pub fn into_yaml(
@@ -123,12 +139,13 @@ mod db {
         ) -> Result<String, serde_yaml::Error> {
             let Self {
                 replica,
-                snapshot_interval,
-                retention,
-                validation_interval,
+                snapshot,
+                validation,
                 checkpoint,
             } = self;
             let replica = LitestreamReplica::from(replica);
+            let snapshot = snapshot.map(LitestreamSnapshot::from);
+            let validation = validation.map(LitestreamValidation::from);
             let (min_checkpoint_page_count, checkpoint_interval, truncate_page_n) = checkpoint
                 .map_or((None, None, JsonCheckpoint::TRUNCATE_DISABLED), |c| {
                     let JsonCheckpoint {
@@ -149,16 +166,6 @@ mod db {
                 checkpoint_interval,
                 truncate_page_n,
             }];
-            let snapshot = match (snapshot_interval, retention) {
-                (None, None) => None,
-                (interval, retention) => Some(LitestreamSnapshot {
-                    interval,
-                    retention,
-                }),
-            };
-            let validation = validation_interval.map(|interval| LitestreamValidation {
-                interval: Some(interval),
-            });
             let logging = Some(LitestreamLogging {
                 level: Some(log_level.into()),
             });
@@ -298,6 +305,26 @@ mod db {
         }
     }
 
+    impl From<JsonSnapshot> for LitestreamSnapshot {
+        fn from(snapshot: JsonSnapshot) -> Self {
+            let JsonSnapshot {
+                interval,
+                retention,
+            } = snapshot;
+            Self {
+                interval,
+                retention,
+            }
+        }
+    }
+
+    impl From<JsonValidation> for LitestreamValidation {
+        fn from(validation: JsonValidation) -> Self {
+            let JsonValidation { interval } = validation;
+            Self { interval }
+        }
+    }
+
     #[derive(Debug, Clone, Serialize)]
     #[serde(rename_all = "kebab-case")]
     pub struct LitestreamLogging {
@@ -337,9 +364,8 @@ mod db {
                 secret_access_key: "secret_access_key".parse().unwrap(),
                 sync_interval: None,
             },
-            snapshot_interval: None,
-            retention: None,
-            validation_interval: None,
+            snapshot: None,
+            validation: None,
             checkpoint: None,
         };
         let path = PathBuf::from("/path/to/db");
@@ -374,9 +400,13 @@ logging:
                 secret_access_key: "secret_access_key".parse().unwrap(),
                 sync_interval: None,
             },
-            snapshot_interval: Some("1h".to_owned()),
-            retention: Some("24h".to_owned()),
-            validation_interval: Some("6h".to_owned()),
+            snapshot: Some(JsonSnapshot {
+                interval: Some("1h".to_owned()),
+                retention: Some("24h".to_owned()),
+            }),
+            validation: Some(JsonValidation {
+                interval: Some("6h".to_owned()),
+            }),
             checkpoint: None,
         };
         let path = PathBuf::from("/path/to/db");
@@ -416,9 +446,8 @@ logging:
                 secret_access_key: "secret_access_key".parse().unwrap(),
                 sync_interval: None,
             },
-            snapshot_interval: None,
-            retention: None,
-            validation_interval: None,
+            snapshot: None,
+            validation: None,
             checkpoint: Some(JsonCheckpoint {
                 interval: Some("5m".to_owned()),
                 min_page_count: Some(2000),
@@ -454,9 +483,8 @@ logging:
                 path: PathBuf::from("/path/to/replica"),
                 sync_interval: Some("5s".to_owned()),
             },
-            snapshot_interval: None,
-            retention: None,
-            validation_interval: None,
+            snapshot: None,
+            validation: None,
             checkpoint: None,
         };
         let path = PathBuf::from("/path/to/db");
@@ -489,9 +517,8 @@ logging:
                 key_path: None,
                 sync_interval: None,
             },
-            snapshot_interval: None,
-            retention: None,
-            validation_interval: None,
+            snapshot: None,
+            validation: None,
             checkpoint: None,
         };
         let path = PathBuf::from("/path/to/db");

services/api/openapi.json

@@ -11929,20 +11929,23 @@
               }
             ]
           },
-          "retention": {
+          "snapshot": {
             "nullable": true,
-            "description": "Snapshot retention",
-            "type": "string"
-          },
-          "snapshot_interval": {
-            "nullable": true,
-            "description": "Snapshot interval",
-            "type": "string"
+            "description": "Snapshot configuration",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/JsonSnapshot"
+              }
+            ]
           },
-          "validation_interval": {
+          "validation": {
             "nullable": true,
-            "description": "Validation interval",
-            "type": "string"
+            "description": "Validation configuration",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/JsonValidation"
+              }
+            ]
           }
         },
         "required": [
@@ -15311,6 +15314,21 @@
           "username"
         ]
       },
+      "JsonSnapshot": {
+        "type": "object",
+        "properties": {
+          "interval": {
+            "nullable": true,
+            "description": "How often new snapshots are created",
+            "type": "string"
+          },
+          "retention": {
+            "nullable": true,
+            "description": "How long snapshot & WAL files are kept",
+            "type": "string"
+          }
+        }
+      },
       "JsonSpec": {
         "description": "A hardware spec",
         "type": "object",
@@ -16436,6 +16454,16 @@
           "uuid"
         ]
       },
+      "JsonValidation": {
+        "type": "object",
+        "properties": {
+          "interval": {
+            "nullable": true,
+            "description": "How often to restore and validate replica data",
+            "type": "string"
+          }
+        }
+      },
       "JsonVersion": {
         "type": "object",
         "properties": {

services/console/src/chunks/docs-reference/server-config/de/plus-disaster-recovery.mdx

@@ -24,10 +24,9 @@ Es gibt drei Replikations-`scheme`s:
 
 Alle drei Replikations-`scheme`s haben die folgenden zusätzlichen Optionen:
 
-- `retention`: (Optional) Die Dauer, die Schnappschuss- und WAL-Dateien aufbewahrt werden. Nach dem Ablauf der Aufbewahrungsfrist wird ein neuer Schnappschuss erstellt und der alte entfernt. WAL-Dateien, die vor dem ältesten Schnappschuss existieren, werden ebenfalls entfernt. Standardwert ist `24h`.
-- `retention_check_interval`: (Optional) Gibt an, wie oft Bencher überprüft, ob die Aufbewahrung durchgesetzt werden muss. Standardwert ist `1h`.
-- `snapshot_interval`: (Optional) Gibt an, wie oft neue Schnappschüsse erstellt werden. Dies wird verwendet, um die Zeit für die Wiederherstellung zu verkürzen, da neuere Schnappschüsse weniger WAL-Frames zum Anwenden haben. Die Aufbewahrung gilt auch für diese Schnappschüsse. Wenn Sie kein Schnappschussintervall festlegen, wird ein neuer Schnappschuss erstellt, wann immer die Aufbewahrung durchgeführt wird. Die Aufbewahrung erfolgt standardmäßig alle 24 Stunden.
-- `validation_interval`: (Optional) Wenn angegeben, wird Bencher automatisch wiederherstellen und validieren, dass die Daten auf der Replik mit der lokalen Kopie übereinstimmen. Standardmäßig deaktiviert. Das Aktivieren kann die Kosten für den Betrieb von Bencher erheblich erhöhen, da die meisten Cloud-Services Gebühren für Downloads erheben.
+- `snapshot.interval`: (Optional) Gibt an, wie oft neue Schnappschüsse erstellt werden. Dies wird verwendet, um die Zeit für die Wiederherstellung zu verkürzen, da neuere Schnappschüsse weniger WAL-Frames zum Anwenden haben. Die Aufbewahrung gilt auch für diese Schnappschüsse. Wenn Sie kein Schnappschussintervall festlegen, wird ein neuer Schnappschuss erstellt, wann immer die Aufbewahrung durchgeführt wird. Die Aufbewahrung erfolgt standardmäßig alle 24 Stunden.
+- `snapshot.retention`: (Optional) Die Dauer, die Schnappschuss- und WAL-Dateien aufbewahrt werden. Nach dem Ablauf der Aufbewahrungsfrist wird ein neuer Schnappschuss erstellt und der alte entfernt. WAL-Dateien, die vor dem ältesten Schnappschuss existieren, werden ebenfalls entfernt. Standardwert ist `24h`.
+- `validation.interval`: (Optional) Wenn angegeben, wird Bencher automatisch wiederherstellen und validieren, dass die Daten auf der Replik mit der lokalen Kopie übereinstimmen. Standardmäßig deaktiviert. Das Aktivieren kann die Kosten für den Betrieb von Bencher erheblich erhöhen, da die meisten Cloud-Services Gebühren für Downloads erheben.
 - `sync_interval`: (Optional) Häufigkeit, mit der Frames zur Replik übertragen werden. Standardwert ist `1s`. Eine höhere Frequenz kann die Kosten für Cloud-Speicher erheblich erhöhen.
 - `checkpoint.interval`: (Optional) Wie häufig Litestream einen nicht-blockierenden PASSIVE-Checkpoint durchführt, unabhängig von der Seitenanzahl. Litestream überspringt den Checkpoint, wenn Leser oder Schreiber aktiv sind. Standardwert ist `1m`.
 - `checkpoint.min_page_count`: (Optional) Mindestanzahl an WAL-Seiten, bevor ein nicht-blockierender PASSIVE-Checkpoint ausgelöst wird (~4KB pro Seite). Litestream überspringt den Checkpoint, wenn Leser oder Schreiber aktiv sind. Standardwert ist `1000` (~4MB).
@@ -37,6 +36,9 @@ Alle drei Replikations-`scheme`s haben die folgenden zusätzlichen Optionen:
 | :------------------------: | :-------: | :----------: | :----------: | :-----------------------------------------------------------------------------------------: |
 |          replica           | \{ ... \} |     ---      |      Ja      |                               Gibt ein Replikationsobjekt an.                               |
 |       replica.scheme       |   "s3"    |     ---      |      Ja      | Gibt das Replikationsschema an. Für alle anderen `replica`-Schlüssel siehe die obige Liste. |
+|     snapshot.interval      |   "1h"    |     ---      |     Nein     | Wie oft neue Schnappschüsse erstellt werden. Verkürzt die Wiederherstellungszeit. |
+|     snapshot.retention     |  "24h"    |     24h      |     Nein     | Wie lange Schnappschuss- und WAL-Dateien aufbewahrt werden, bevor sie ersetzt werden. |
+|    validation.interval     |   "6h"    |     ---      |     Nein     | Wie oft Replikdaten wiederhergestellt und gegen die lokale Kopie validiert werden. Standardmäßig deaktiviert. |
 |    checkpoint.interval     |   "1m"    |      1m      |     Nein     | Wie oft ein nicht-blockierender PASSIVE-Checkpoint ausgeführt wird. Wird übersprungen, wenn Leser/Schreiber aktiv sind. |
 | checkpoint.min_page_count  |   1000    |     1000     |     Nein     | Mindestanzahl WAL-Seiten (~4KB pro Seite) vor einem PASSIVE-Checkpoint. Wird übersprungen, wenn Leser/Schreiber aktiv sind. |
 | checkpoint.truncate_page_n |     0     |      0       |     Nein     | Seitenschwellenwert für einen blockierenden TRUNCATE-Checkpoint. **0 deaktiviert.** Werte ungleich Null können `database is locked`-Fehler unter Last verursachen. |

services/console/src/chunks/docs-reference/server-config/en/plus-disaster-recovery.mdx

@@ -24,10 +24,9 @@ There are three replication `scheme`s:
 
 All three replica `scheme`s have the following additional options:
 
-- `retention`: (Optional)  The amount of time that snapshot & WAL files will be kept. After the retention period, a new snapshot will be created and the old one will be removed. WAL files that exist before the oldest snapshot will also be removed. Defaults to `24h`.
-- `retention_check_interval`: (Optional) Specifies how often Bencher will check if retention needs to be enforced. Defaults to `1h`.
-- `snapshot_interval`: (Optional) Specifies how often new snapshots will be created. This is used to reduce the time to restore since newer snapshots will have fewer WAL frames to apply. Retention still applies to these snapshots. If you do not set a snapshot interval then a new snapshot will be created whenever retention is performed. Retention occurs every 24 hours by default.
-- `validation_interval`: (Optional) When specified, Bencher will automatically restore and validate that the data on the replica matches the local copy. Disabled by default. Enabling this may significantly increase the cost of running Bencher as most cloud services charge for downloads.
+- `snapshot.interval`: (Optional) Specifies how often new snapshots will be created. This is used to reduce the time to restore since newer snapshots will have fewer WAL frames to apply. Retention still applies to these snapshots. If you do not set a snapshot interval then a new snapshot will be created whenever retention is performed. Retention occurs every 24 hours by default.
+- `snapshot.retention`: (Optional) The amount of time that snapshot & WAL files will be kept. After the retention period, a new snapshot will be created and the old one will be removed. WAL files that exist before the oldest snapshot will also be removed. Defaults to `24h`.
+- `validation.interval`: (Optional) When specified, Bencher will automatically restore and validate that the data on the replica matches the local copy. Disabled by default. Enabling this may significantly increase the cost of running Bencher as most cloud services charge for downloads.
 - `sync_interval`: (Optional) Frequency in which frames are pushed to the replica. Defaults to `1s`. Increasing frequency can increase cloud storage costs significantly.
 - `checkpoint.interval`: (Optional) How often Litestream performs a non-blocking PASSIVE checkpoint regardless of page count. Litestream skips the checkpoint if readers or writers are active. Defaults to `1m`.
 - `checkpoint.min_page_count`: (Optional) Minimum number of WAL pages before a non-blocking PASSIVE checkpoint is triggered (~4KB per page). Litestream skips the checkpoint if readers or writers are active. Defaults to `1000` (~4MB).
@@ -37,6 +36,9 @@ All three replica `scheme`s have the following additional options:
 | :------------------------: | :-------: | :-----: | :------: | :---------------------------------------------------------------------------------: |
 |          replica           | \{ ... \} |   ---   |   Yes    |                             Specifies a replica object.                             |
 |       replica.scheme       |   "s3"    |   ---   |   Yes    | Specifies the replication scheme. For all other `replica` keys, see the list above. |
+|     snapshot.interval      |   "1h"    |   ---   |    No    | How often new snapshots are created. Reduces restore time. |
+|     snapshot.retention     |  "24h"    |   24h   |    No    | How long snapshot & WAL files are kept before being replaced. |
+|    validation.interval     |   "6h"    |   ---   |    No    | How often replica data is restored and validated against the local copy. Disabled by default. |
 |    checkpoint.interval     |   "1m"    |   1m    |    No    | How often a non-blocking PASSIVE checkpoint runs. Skipped if readers/writers are active. |
 | checkpoint.min_page_count  |   1000    |  1000   |    No    | Minimum WAL pages (~4KB each) before a PASSIVE checkpoint triggers. Skipped if readers/writers are active. |
 | checkpoint.truncate_page_n |     0     |    0    |    No    | Page threshold for a blocking TRUNCATE checkpoint. **0 disables.** Non-zero values may cause `database is locked` under load. |