refactor: move parsing logic of epoch/latest[offset] to Epoch type

Alenar · Alenar · commit 70e5b8beb79f · 2025-10-21T15:19:22.000+02:00
So it can be re-used accross crates.

- `EpochSpecifier` enum to represents the cases between &lt;{uint}, 'latest',
  latest-{uint}&gt;
- add `Epoch::parse_specifier`
- impl `FromStr` to epoch to avoid having downstream code specifying the
  inner type of the epoch when parsing from str
- update aggregator `ExpandedEpoch` logic
diff --git a/mithril-aggregator/src/http_server/parameters.rs b/mithril-aggregator/src/http_server/parameters.rs
@@ -1,10 +1,9 @@
 //! Helpers when working with parameters from either the query string or the path of an HTTP request
 
-use anyhow::Context;
 use std::ops::Deref;
 
 use mithril_common::StdResult;
-use mithril_common::entities::Epoch;
+use mithril_common::entities::{Epoch, EpochSpecifier};
 
 use crate::dependency_injection::EpochServiceWrapper;
 
@@ -61,26 +60,18 @@ pub async fn expand_epoch(
     epoch_service: EpochServiceWrapper,
 ) -> StdResult<ExpandedEpoch> {
     let epoch_str = epoch_str.to_lowercase();
-    if epoch_str == "latest" {
-        epoch_service
+    match Epoch::parse_specifier(&epoch_str)? {
+        EpochSpecifier::Number(epoch) => Ok(ExpandedEpoch::Parsed(epoch)),
+        EpochSpecifier::Latest => epoch_service
             .read()
             .await
             .epoch_of_current_data()
-            .map(ExpandedEpoch::Latest)
-    } else if epoch_str.starts_with("latest-") {
-        let (_, offset_str) = epoch_str.split_at("latest-".len());
-        let offset = offset_str
-            .parse::<u64>()
-            .with_context(|| "Invalid epoch offset: must be a number")?;
-
-        epoch_service.read().await.epoch_of_current_data().map(|epoch| {
-            ExpandedEpoch::LatestMinusOffset(Epoch(epoch.saturating_sub(offset)), offset)
-        })
-    } else {
-        epoch_str
-            .parse::<u64>()
-            .map(|epoch| ExpandedEpoch::Parsed(Epoch(epoch)))
-            .with_context(|| "Invalid epoch: must be a number or 'latest'")
+            .map(ExpandedEpoch::Latest),
+        EpochSpecifier::LatestMinusOffset(offset) => {
+            epoch_service.read().await.epoch_of_current_data().map(|epoch| {
+                ExpandedEpoch::LatestMinusOffset(Epoch(epoch.saturating_sub(offset)), offset)
+            })
+        }
     }
 }
 
diff --git a/mithril-client/src/type_alias.rs b/mithril-client/src/type_alias.rs
@@ -69,10 +69,10 @@ pub mod common {
     pub use mithril_common::crypto_helper::MKProof;
     pub use mithril_common::entities::{
         AncillaryLocation, BlockHash, BlockNumber, CardanoDbBeacon, CardanoNetwork, ChainPoint,
-        CompressionAlgorithm, DigestLocation, Epoch, ImmutableFileNumber, ImmutablesLocation,
-        MagicId, MultiFilesUri, ProtocolMessage, ProtocolMessagePartKey, ProtocolParameters,
-        SignedEntityType, SlotNumber, StakeDistribution, SupportedEra, TemplateUri,
-        TransactionHash,
+        CompressionAlgorithm, DigestLocation, Epoch, EpochSpecifier, ImmutableFileNumber,
+        ImmutablesLocation, MagicId, MultiFilesUri, ProtocolMessage, ProtocolMessagePartKey,
+        ProtocolParameters, SignedEntityType, SlotNumber, StakeDistribution, SupportedEra,
+        TemplateUri, TransactionHash,
     };
     pub use mithril_common::messages::{
         AncillaryMessagePart, DigestsMessagePart, ImmutablesMessagePart,
diff --git a/mithril-common/src/entities/epoch.rs b/mithril-common/src/entities/epoch.rs
@@ -1,14 +1,20 @@
 use std::fmt::{Display, Formatter};
 use std::num::TryFromIntError;
 use std::ops::{Deref, DerefMut};
+use std::str::FromStr;
 
+use anyhow::Context;
 use serde::{Deserialize, Serialize};
 use thiserror::Error;
 
+use crate::StdResult;
 use crate::entities::arithmetic_operation_wrapper::{
     impl_add_to_wrapper, impl_partial_eq_to_wrapper, impl_sub_to_wrapper,
 };
 
+const INVALID_EPOCH_SPECIFIER_ERROR: &str =
+    "Invalid epoch: expected 'X', 'latest' or 'latest-X' where X is a positive 64-bit integer";
+
 /// Epoch represents a Cardano epoch
 #[derive(
     Debug, Copy, Clone, Default, PartialEq, Serialize, Deserialize, Hash, Eq, PartialOrd, Ord,
@@ -100,6 +106,32 @@ impl Epoch {
     pub fn has_gap_with(&self, other: &Epoch) -> bool {
         self.0.abs_diff(other.0) > 1
     }
+
+    /// Parses the given epoch string into an `EpochSpecifier`.
+    ///
+    /// Accepted values are:
+    /// - a `u64` number
+    /// - `latest`
+    /// - `latest-{offset}` where `{offset}` is a `u64` number
+    pub fn parse_specifier(epoch_str: &str) -> StdResult<EpochSpecifier> {
+        if epoch_str == "latest" {
+            Ok(EpochSpecifier::Latest)
+        } else if let Some(offset_str) = epoch_str.strip_prefix("latest-") {
+            if offset_str.is_empty() {
+                anyhow::bail!("Invalid epoch '{epoch_str}': offset cannot be empty");
+            }
+            let offset = offset_str.parse::<u64>().with_context(|| {
+                format!("Invalid epoch '{epoch_str}': offset must be a positive 64-bit integer")
+            })?;
+
+            Ok(EpochSpecifier::LatestMinusOffset(offset))
+        } else {
+            epoch_str
+                .parse::<Epoch>()
+                .map(EpochSpecifier::Number)
+                .with_context(|| INVALID_EPOCH_SPECIFIER_ERROR)
+        }
+    }
 }
 
 impl Deref for Epoch {
@@ -148,6 +180,16 @@ impl From<Epoch> for f64 {
     }
 }
 
+impl FromStr for Epoch {
+    type Err = anyhow::Error;
+
+    fn from_str(epoch_str: &str) -> Result<Self, Self::Err> {
+        epoch_str.parse::<u64>().map(Epoch).with_context(|| {
+            format!("Invalid epoch '{epoch_str}': must be a positive 64-bit integer")
+        })
+    }
+}
+
 /// EpochError is an error triggered by an [Epoch]
 #[derive(Error, Debug)]
 pub enum EpochError {
@@ -156,6 +198,31 @@ pub enum EpochError {
     EpochOffset(u64, i64),
 }
 
+/// Represents the different ways to specify an epoch when querying the API.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EpochSpecifier {
+    /// Epoch was explicitly provided as a number (e.g., "123")
+    Number(Epoch),
+    /// Epoch was provided as "latest" (e.g., "latest")
+    Latest,
+    /// Epoch was provided as "latest-{offset}" (e.g., "latest-100")
+    LatestMinusOffset(u64),
+}
+
+impl Display for EpochSpecifier {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            EpochSpecifier::Number(epoch) => write!(f, "{}", epoch),
+            EpochSpecifier::Latest => {
+                write!(f, "latest")
+            }
+            EpochSpecifier::LatestMinusOffset(offset) => {
+                write!(f, "latest-{}", offset)
+            }
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use crate::entities::arithmetic_operation_wrapper::tests::test_op_assign;
@@ -262,4 +329,114 @@ mod tests {
         assert!(!Epoch(3).has_gap_with(&Epoch(2)));
         assert!(Epoch(3).has_gap_with(&Epoch(0)));
     }
+
+    #[test]
+    fn from_str() {
+        let expected_epoch = Epoch(123);
+        let from_str = Epoch::from_str("123").unwrap();
+        assert_eq!(from_str, expected_epoch);
+
+        let from_string = String::from("123").parse::<Epoch>().unwrap();
+        assert_eq!(from_string, expected_epoch);
+
+        let alternate_notation: Epoch = "123".parse().unwrap();
+        assert_eq!(alternate_notation, expected_epoch);
+
+        let invalid_epoch_err = Epoch::from_str("123.456").unwrap_err();
+        assert!(
+            invalid_epoch_err
+                .to_string()
+                .contains("Invalid epoch '123.456': must be a positive 64-bit integer")
+        );
+
+        let overflow_err = format!("1{}", u64::MAX).parse::<Epoch>().unwrap_err();
+        assert!(
+            overflow_err.to_string().contains(
+                "Invalid epoch '118446744073709551615': must be a positive 64-bit integer"
+            )
+        );
+    }
+
+    #[test]
+    fn display_epoch_specifier() {
+        assert_eq!(format!("{}", EpochSpecifier::Number(Epoch(123))), "123");
+        assert_eq!(format!("{}", EpochSpecifier::Latest), "latest");
+        assert_eq!(
+            format!("{}", EpochSpecifier::LatestMinusOffset(123)),
+            "latest-123"
+        );
+    }
+
+    mod parse_specifier {
+        use super::*;
+
+        #[test]
+        fn parse_epoch_number() {
+            let parsed_value = Epoch::parse_specifier("5").unwrap();
+            assert_eq!(EpochSpecifier::Number(Epoch(5)), parsed_value);
+        }
+
+        #[test]
+        fn parse_latest_epoch() {
+            let parsed_value = Epoch::parse_specifier("latest").unwrap();
+            assert_eq!(EpochSpecifier::Latest, parsed_value);
+        }
+
+        #[test]
+        fn parse_latest_epoch_with_offset() {
+            let parsed_value = Epoch::parse_specifier("latest-43").unwrap();
+            assert_eq!(EpochSpecifier::LatestMinusOffset(43), parsed_value);
+        }
+
+        #[test]
+        fn parse_invalid_str_yield_error() {
+            let error = Epoch::parse_specifier("invalid_string").unwrap_err();
+            assert!(error.to_string().contains(INVALID_EPOCH_SPECIFIER_ERROR));
+        }
+
+        #[test]
+        fn parse_too_big_epoch_number_yield_error() {
+            let error = Epoch::parse_specifier(&format!("9{}", u64::MAX)).unwrap_err();
+            assert!(error.to_string().contains(INVALID_EPOCH_SPECIFIER_ERROR));
+            println!("{:?}", error);
+        }
+
+        #[test]
+        fn parse_latest_epoch_with_invalid_offset_yield_error() {
+            let error = Epoch::parse_specifier("latest-invalid").unwrap_err();
+            assert!(error.to_string().contains(
+                "Invalid epoch 'latest-invalid': offset must be a positive 64-bit integer"
+            ));
+        }
+
+        #[test]
+        fn parse_latest_epoch_with_empty_offset_yield_error() {
+            let error = Epoch::parse_specifier("latest-").unwrap_err();
+            assert!(
+                error
+                    .to_string()
+                    .contains("Invalid epoch 'latest-': offset cannot be empty")
+            );
+        }
+
+        #[test]
+        fn parse_latest_epoch_with_too_big_offset_yield_error() {
+            let error = Epoch::parse_specifier(&format!("latest-9{}", u64::MAX)).unwrap_err();
+            assert!(error.to_string().contains(
+                "Invalid epoch 'latest-918446744073709551615': offset must be a positive 64-bit integer"
+            ))
+        }
+
+        #[test]
+        fn specifier_to_string_can_be_parsed_back() {
+            for specifier in [
+                EpochSpecifier::Number(Epoch(121)),
+                EpochSpecifier::Latest,
+                EpochSpecifier::LatestMinusOffset(121),
+            ] {
+                let value = Epoch::parse_specifier(&specifier.to_string()).unwrap();
+                assert_eq!(value, specifier);
+            }
+        }
+    }
 }
diff --git a/mithril-common/src/entities/mod.rs b/mithril-common/src/entities/mod.rs
@@ -48,7 +48,7 @@ pub use cardano_transactions_snapshot::CardanoTransactionsSnapshot;
 pub use certificate::{Certificate, CertificateSignature};
 pub use certificate_metadata::{CertificateMetadata, StakeDistributionParty};
 pub use compression_algorithm::*;
-pub use epoch::{Epoch, EpochError};
+pub use epoch::{Epoch, EpochError, EpochSpecifier};
 pub use file_uri::{FileUri, MultiFilesUri, TemplateUri};
 pub use http_server_error::{ClientError, ServerError};
 pub use mithril_stake_distribution::MithrilStakeDistribution;
