client-cli: merge cardano-database-v2 command into 'v1' command

.github/workflows/test-client.yml

@@ -167,6 +167,18 @@ jobs:
         shell: bash
         run: .github/workflows/scripts/verify-cardano-db-restoration.sh ./bin/cdb-download-output.txt "${{ matrix.extra_args }}"
 
+      - name: Remove downloaded artifacts to free up disk space (Linux, Windows)
+        if: runner.os != 'macOS'
+        shell: bash
+        working-directory: ./bin
+        run: rm --force db/immutable/*.{chunk,primary,secondary}
+
+      - name: Remove downloaded artifacts to free up disk space (macOs)
+        if: runner.os == 'macOS'
+        shell: bash
+        working-directory: ./bin
+        run: sudo rm -rf db/
+
       - name: Mithril Stake Distribution / list and get last hash
         shell: bash
         working-directory: ./bin
@@ -226,20 +238,20 @@ jobs:
         shell: bash
         working-directory: ./bin
         run: |
-          ./mithril-client ${{ steps.prepare.outputs.debug_level }} --unstable --origin-tag CI cardano-db-v2 snapshot list
-          echo "CARDANO_DATABASE_V2_SNAPSHOT_HASH=$(./mithril-client --unstable --origin-tag CI cardano-db-v2 snapshot list --json | jq -r '.[0].hash')" >> $GITHUB_ENV
+          ./mithril-client ${{ steps.prepare.outputs.debug_level }} --unstable --origin-tag CI cardano-db snapshot list --backend v2
+          echo "CARDANO_DATABASE_V2_SNAPSHOT_HASH=$(./mithril-client --unstable --origin-tag CI cardano-db snapshot list --backend v2 --json | jq -r '.[0].hash')" >> $GITHUB_ENV
 
       - name: Cardano Database V2 Snapshot / show snapshot
         if: steps.aggregator_capability_unix.outputs.cardano_database_v2_enabled == 'true' || steps.aggregator_capability_windows.outputs.cardano_database_v2_enabled == 'true'
         shell: bash
         working-directory: ./bin
-        run: ./mithril-client --unstable --origin-tag CI cardano-db-v2 snapshot show $CARDANO_DATABASE_V2_SNAPSHOT_HASH
+        run: ./mithril-client --unstable --origin-tag CI cardano-db snapshot show --backend v2 $CARDANO_DATABASE_V2_SNAPSHOT_HASH
 
       - name: Cardano Database V2 Snapshot / download & restore latest (Full restoration)
         if: steps.aggregator_capability_unix.outputs.cardano_database_v2_enabled == 'true' || steps.aggregator_capability_windows.outputs.cardano_database_v2_enabled == 'true'
         shell: bash
         working-directory: ./bin
-        run: ./mithril-client ${{ steps.prepare.outputs.debug_level }} --unstable --origin-tag CI cardano-db-v2 download $CARDANO_DATABASE_V2_SNAPSHOT_HASH ${{ matrix.extra_args }} 2>&1 | tee cdb-v2-download-output.txt
+        run: ./mithril-client ${{ steps.prepare.outputs.debug_level }} --unstable --origin-tag CI cardano-db download --backend v2 $CARDANO_DATABASE_V2_SNAPSHOT_HASH ${{ matrix.extra_args }} 2>&1 | tee cdb-v2-download-output.txt
 
       - name: Cardano Database V2 Snapshot / verify Cardano node starts successfully
         if: runner.os == 'Linux' && steps.aggregator_capability_unix.outputs.cardano_database_v2_enabled == 'true'
@@ -301,6 +313,10 @@ jobs:
         shell: bash
         run: ${{ steps.command.outputs.mithril_client }} ${{ steps.prepare.outputs.debug_level }} --origin-tag CI cardano-db download $CDB_SNAPSHOT_DIGEST --download-dir /app ${{ matrix.extra_args }}
 
+      - name: Remove downloaded artifacts to free up disk space
+        shell: bash
+        run: rm --force /app/db/immutable/*.{chunk,primary,secondary}
+
       - name: Mithril Stake Distribution / list and get last hash
         shell: bash
         run: |
@@ -351,18 +367,18 @@ jobs:
         if: steps.aggregator_capability.outputs.cardano_database_v2_enabled == 'true'
         shell: bash
         run: |
-          ${{ steps.command.outputs.mithril_client }} --unstable --origin-tag CI cardano-db-v2 snapshot list
-          echo "CARDANO_DATABASE_V2_SNAPSHOT_HASH=$(${{ steps.command.outputs.mithril_client }} --unstable --origin-tag CI cardano-db-v2 snapshot list --json | jq -r '.[0].hash')" >> $GITHUB_ENV
+          ${{ steps.command.outputs.mithril_client }} --unstable --origin-tag CI cardano-db snapshot list --backend v2
+          echo "CARDANO_DATABASE_V2_SNAPSHOT_HASH=$(${{ steps.command.outputs.mithril_client }} --unstable --origin-tag CI cardano-db snapshot list --backend v2 --json | jq -r '.[0].hash')" >> $GITHUB_ENV
 
       - name: Cardano Database V2 Snapshot / show snapshot
         if: steps.aggregator_capability.outputs.cardano_database_v2_enabled == 'true'
         shell: bash
-        run: ${{ steps.command.outputs.mithril_client }} --unstable --origin-tag CI cardano-db-v2 snapshot show $CARDANO_DATABASE_V2_SNAPSHOT_HASH
+        run: ${{ steps.command.outputs.mithril_client }} --unstable --origin-tag CI cardano-db snapshot show --backend v2 $CARDANO_DATABASE_V2_SNAPSHOT_HASH
 
       - name: Cardano Database V2 Snapshot / download & restore latest (Full restoration)
         if: steps.aggregator_capability.outputs.cardano_database_v2_enabled == 'true'
         shell: bash
-        run: ${{ steps.command.outputs.mithril_client }} ${{ steps.prepare.outputs.debug_level }} --origin-tag CI --unstable cardano-db-v2 download $CARDANO_DATABASE_V2_SNAPSHOT_HASH --download-dir /app ${{ matrix.extra_args }}
+        run: ${{ steps.command.outputs.mithril_client }} ${{ steps.prepare.outputs.debug_level }} --origin-tag CI --unstable cardano-db download --backend v2 $CARDANO_DATABASE_V2_SNAPSHOT_HASH --download-dir /app ${{ matrix.extra_args }}
 
   test-mithril-client-wasm:
     strategy:

CHANGELOG.md

@@ -15,6 +15,14 @@ As a minor extension, we have adopted a slightly different versioning convention
 
 - Support for recording client types in Mithril client library, CLI and WASM in the aggregator metrics.
 
+- **UNSTABLE** New api for client-cli partial cardano database restoration:
+
+  - Allow switching of backend with parameter `--backend [v1,v2]` to `cardano-database` snapshot list, snapshot show and download subcommands
+    - backend `v1` (default): support full database restoration only
+    - backend `v2` (require `--unstable`): support full and partial database restoration
+  - Add `--start`, `--end`, `--allow-override` to `cardano-database download` subcommand, supported only with `--backend v2`
+  - Deprecated `cardano-database-v2` subcommand
+
 - Crates versions:
 
 | Crate | Version |

docs/website/root/manual/develop/nodes/mithril-client.md

@@ -222,7 +222,7 @@ Commands:
   mithril-stake-distribution  Mithril stake distribution management (alias: msd)
   cardano-transaction         Cardano transactions management (alias: ctx)
   cardano-stake-distribution  Cardano stake distribution management (alias: csd)
-  cardano-db-v2               [unstable] Cardano db v2 management (alias: cdbv2)
+  cardano-db-v2               Deprecated, use `cardano-db` instead
   help                        Print this message or the help of the given subcommand(s)
 
 Options:
@@ -514,7 +514,7 @@ Here are the subcommands available:
 | **help**     | Prints this message or the help for the given subcommand(s) |
 | **list**     | Lists available Cardano stake distributions                 |
 
-### Cardano DB V2 (`unstable`, will replace `Cardano DB` in the future)
+### Cardano DB V2 (Deprecated, use `cardano-db` with option `--backend v2` instead)
 
 | Subcommand        | Performed action                                            |
 | ----------------- | ----------------------------------------------------------- |
@@ -547,27 +547,33 @@ Here is a list of the available parameters:
 
 `cardano-db snapshot show` command:
 
-| Parameter | Command line (long) | Command line (short) | Environment variable | Description                                                                   | Default value | Example |     Mandatory      |
-| --------- | ------------------- | :------------------: | -------------------- | ----------------------------------------------------------------------------- | ------------- | ------- | :----------------: |
-| `json`    | `--json`            |          -           | -                    | Enable JSON output for command results                                        | `false`       | -       |         -          |
-| `digest`  | -                   |          -           | -                    | Digest of the Cardano db snapshot to show or `latest` for the latest artifact | -             | -       | :heavy_check_mark: |
+| Parameter | Command line (long) | Command line (short) | Environment variable | Description                                                                                                                     | Default value | Example |     Mandatory      |
+| --------- | ------------------- | :------------------: | -------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------- | :----------------: |
+| `json`    | `--json`            |          -           | -                    | Enable JSON output for command results                                                                                          | `false`       | -       |         -          |
+| `backend` | `--backend`         |         `-b`         | -                    | Backend to use, either: `v1` (default, full database restoration only) or `v2` (unstable, full or partial database restoration) | `v1`          | -       |         -          |
+| `digest`  | -                   |          -           | -                    | Digest of the Cardano db snapshot to show or `latest` for the latest artifact                                                   | -             | -       | :heavy_check_mark: |
 
 `cardano-db snapshot list` command:
 
-| Parameter | Command line (long) | Command line (short) | Environment variable | Description                            | Default value | Example | Mandatory |
-| --------- | ------------------- | :------------------: | -------------------- | -------------------------------------- | ------------- | ------- | :-------: |
-| `json`    | `--json`            |          -           | -                    | Enable JSON output for command results | `false`       | -       |     -     |
+| Parameter | Command line (long) | Command line (short) | Environment variable | Description                                                                                                                     | Default value | Example | Mandatory |
+| --------- | ------------------- | :------------------: | -------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------- | :-------: |
+| `json`    | `--json`            |          -           | -                    | Enable JSON output for command results                                                                                          | `false`       | -       |     -     |
+| `backend` | `--backend`         |         `-b`         | -                    | Backend to use, either: `v1` (default, full database restoration only) or `v2` (unstable, full or partial database restoration) | `v1`          | -       |     -     |
 
 `cardano-db download` command:
 
 | Parameter                    | Command line (long)            | Command line (short) | Environment variable         | Description                                                                                                                         | Default value | Example |     Mandatory      |
 | ---------------------------- | ------------------------------ | :------------------: | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------- | :----------------: |
 | `json`                       | `--json`                       |          -           | -                            | Enable JSON output for command results                                                                                              | `false`       | -       |         -          |
+| `backend`                    | `--backend`                    |         `-b`         | -                            | Backend to use, either: `v1` (default, full database restoration only) or `v2` (unstable, full or partial database restoration)     | `v1`          | -       |         -          |
 | `digest`                     | -                              |          -           | -                            | Digest of the Cardano db snapshot to download or `latest` for the latest artifact                                                   | -             | -       | :heavy_check_mark: |
 | `download_dir`               | `--download-dir`               |          -           | -                            | Directory where the immutable and ancillary files will be downloaded                                                                | -             | -       |         -          |
 | `genesis_verification_key`   | `--genesis-verification-key`   |          -           | `GENESIS_VERIFICATION_KEY`   | Genesis verification key to check the certificate chain                                                                             | -             | -       | :heavy_check_mark: |
 | `include_ancillary`          | `--include-ancillary`          |          -           | -                            | Include ancillary files in the download, if set the `ancillary_verification_key` is required in order to verify the ancillary files | `false`       | -       |         -          |
 | `ancillary_verification_key` | `--ancillary-verification-key` |          -           | `ANCILLARY_VERIFICATION_KEY` | Ancillary verification key to verify the ancillary files                                                                            | -             | -       |         -          |
+| `start`                      | `--start`                      |          -           | -                            | [backend `v2` only] The first immutable file number to download                                                                     | -             | -       |         -          |
+| `end`                        | `--end`                        |          -           | -                            | [backend `v2` only] The last immutable file number to download                                                                      | -             | -       |         -          |
+| `allow_override`             | `--allow-override`             |          -           | -                            | [backend `v2` only] Allow existing files in the download directory to be overridden                                                 | `false`       | -       |         -          |
 
 `mithril-stake-distribution list` command:
 
@@ -622,19 +628,37 @@ Here is a list of the available parameters:
 
 `cardano-db-v2 snapshot show` command:
 
+:::warning
+
+Deprecated, use `cardano-db snapshot show` with option `--backend v2` instead
+
+:::
+
 | Parameter | Command line (long) | Command line (short) | Environment variable | Description                                                                 | Default value | Example |     Mandatory      |
 | --------- | ------------------- | :------------------: | -------------------- | --------------------------------------------------------------------------- | ------------- | ------- | :----------------: |
 | `json`    | `--json`            |          -           | -                    | Enable JSON output for command results                                      | `false`       | -       |         -          |
 | `hash`    | -                   |          -           | -                    | Hash of the Cardano db snapshot to show or `latest` for the latest artifact | -             | -       | :heavy_check_mark: |
 
 `cardano-db-v2 snapshot list` command:
 
+:::warning
+
+Deprecated, use `cardano-db snapshot list` with option `--backend v2` instead
+
+:::
+
 | Parameter | Command line (long) | Command line (short) | Environment variable | Description                            | Default value | Example | Mandatory |
 | --------- | ------------------- | :------------------: | -------------------- | -------------------------------------- | ------------- | ------- | :-------: |
 | `json`    | `--json`            |          -           | -                    | Enable JSON output for command results | `false`       | -       |     -     |
 
 `cardano-db-v2 download` command:
 
+:::warning
+
+Deprecated, use `cardano-db download` with option `--backend v2` instead
+
+:::
+
 | Parameter                    | Command line (long)            | Command line (short) | Environment variable         | Description                                                                                                                         | Default value | Example |     Mandatory      |
 | ---------------------------- | ------------------------------ | :------------------: | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------- | :----------------: |
 | `json`                       | `--json`                       |          -           | -                            | Enable JSON output for command results                                                                                              | `false`       | -       |         -          |

mithril-client-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mithril-client-cli"
-version = "0.12.8"
+version = "0.12.9"
 description = "A Mithril Client"
 authors = { workspace = true }
 edition = { workspace = true }

mithril-client-cli/src/command_context.rs

@@ -1,3 +1,4 @@
+use anyhow::anyhow;
 use config::builder::DefaultState;
 use config::ConfigBuilder;
 use slog::Logger;
@@ -33,6 +34,23 @@ impl CommandContext {
         self.unstable_enabled
     }
 
+    /// Ensure that unstable commands are enabled
+    pub fn require_unstable(
+        &self,
+        sub_command: &str,
+        command_example: Option<&str>,
+    ) -> MithrilResult<()> {
+        if self.is_unstable_enabled() {
+            Ok(())
+        } else {
+            let example = command_example.map(|e| format!(" {e}")).unwrap_or_default();
+            Err(anyhow!(
+                "The \"{sub_command}\" subcommand is only accepted using the --unstable flag.\n\n\
+                ie: \"mithril-client --unstable {sub_command}{example}\""
+            ))
+        }
+    }
+
     /// Get the configured parameters
     pub fn config_parameters(&self) -> MithrilResult<ConfigParameters> {
         let config = self.config_builder.clone().build()?;
@@ -45,3 +63,36 @@ impl CommandContext {
         &self.logger
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use slog::o;
+
+    use super::*;
+
+    #[test]
+    fn require_unstable_return_ok_if_unstable_enabled() {
+        let unstable_enabled = true;
+        let context = CommandContext::new(
+            ConfigBuilder::default(),
+            unstable_enabled,
+            Logger::root(slog::Discard, o!()),
+        );
+
+        let result = context.require_unstable("test", None);
+        assert!(result.is_ok(), "Expected Ok, got {result:?}");
+    }
+
+    #[test]
+    fn require_unstable_return_err_if_unstable_disabled() {
+        let unstable_enabled = false;
+        let context = CommandContext::new(
+            ConfigBuilder::default(),
+            unstable_enabled,
+            Logger::root(slog::Discard, o!()),
+        );
+
+        let result = context.require_unstable("test", None);
+        assert!(result.is_err(), "Expected Err, got {result:?}");
+    }
+}