Merge branch 'humanize-sns-configuration-v2-daniel-wong' into 'master'

feat: NNS1-1969: Humanize numbers in SNS configuration v2.

 

See merge request dfinity-lab/public/ic!12576

Author: daniel-wong-dfinity-org

Cargo.lock

@@ -7,9 +7,11 @@ DEPENDENCIES = [
     "@crate_index//:humantime",
     "@crate_index//:lazy_static",
     "@crate_index//:regex",
+    "@crate_index//:serde",
 ]
 
 DEV_DEPENDENCIES = DEPENDENCIES + [
+    "@crate_index//:serde_yaml",
 ]
 
 rust_library(

rs/nervous_system/humanize/BUILD.bazel

@@ -5,6 +5,10 @@ edition = "2021"
 
 [dependencies]
 humantime = "2.1.0"
+ic-nervous-system-proto = { path = "../proto" }
 lazy_static = "1.4.0"
 regex = "1.3.0"
-ic-nervous-system-proto = { path = "../proto" }
+serde = "1.0.99"
+
+[dev-dependencies]
+serde_yaml = "0.8.24"

rs/nervous_system/humanize/Cargo.toml

@@ -2,11 +2,23 @@ use core::fmt::Display;
 use ic_nervous_system_proto::pb::v1 as nervous_system_pb;
 use lazy_static::lazy_static;
 use regex::Regex;
-use std::str::FromStr;
+use std::{collections::VecDeque, str::FromStr};
+
+pub mod serde;
 
 #[cfg(test)]
 mod tests;
 
+// Normally, we would import this from ic_nervous_system_common, but we'd be
+// dragging in lots of stuff along with it. The main problem with that is that
+// any random change that requires ic_nervous_system_common to be rebuilt will
+// also trigger a rebuild here. This gives us a "fire wall" to prevent fires
+// from spreading.
+//
+// TODO(NNS1-2284): Move E8, and other such things to their own tiny library to
+// avoid triggering mass rebuilds.
+const E8: u64 = 100_000_000;
+
 /// Parses decimal strings ending in "tokens" (plural), decimal strings end in
 /// "token" (singular) , or integer strings (again, base 10) ending in "e8s". In
 /// the case of "tokens" strings, the maximum number of digits after the
@@ -16,6 +28,8 @@ mod tests;
 ///
 /// Whitespace around number is insignificant. E.g. " 42 tokens" is equivalent
 /// to "42tokens".
+///
+/// Inverse of [`format_tokens`].
 pub fn parse_tokens(s: &str) -> Result<nervous_system_pb::Tokens, String> {
     let e8s = if let Some(s) = s.strip_suffix("tokens").map(|s| s.trim()) {
         parse_fixed_point_decimal(s, /* decimal_places = */ 8)?
@@ -39,6 +53,8 @@ pub fn parse_tokens(s: &str) -> Result<nervous_system_pb::Tokens, String> {
 ///   1 week + 2 days + 3 hours
 ///       =
 ///   (1 * (7 * 24 * 60 * 60) + 2 * 24 * 60 * 60 + 3 * (60 * 60)) seconds
+///
+/// Inverse of [`format_duration`].
 pub fn parse_duration(s: &str) -> Result<nervous_system_pb::Duration, String> {
     humantime::parse_duration(s)
         .map(|d| nervous_system_pb::Duration {
@@ -49,6 +65,8 @@ pub fn parse_duration(s: &str) -> Result<nervous_system_pb::Duration, String> {
 
 /// Similar to parse_fixed_point_decimal(s, 2), except a trailing percent sign
 /// is REQUIRED (and not fed into parse_fixed_point_decimal).
+///
+/// Inverse of [`format_percentage`].
 pub fn parse_percentage(s: &str) -> Result<nervous_system_pb::Percentage, String> {
     let number = s
         .strip_suffix('%')
@@ -140,3 +158,91 @@ where
     n.checked_mul(boost)
         .ok_or_else(|| format!("Too large of a decimal shift: {} >> {}", n, count))
 }
+
+/// The inverse of [`parse_tokens`].
+///
+/// One wrinkle: if e8s is None, then this is equivalent to e8s = Some(0). This
+/// follows the same logic as Protocol Buffers. If the caller wants None to be
+/// treated differently, they must do it themselves.
+pub fn format_tokens(tokens: &nervous_system_pb::Tokens) -> String {
+    let nervous_system_pb::Tokens { e8s } = tokens;
+    let e8s = e8s.unwrap_or(0);
+
+    if 0 < e8s && e8s < 1_000_000 {
+        return format!("{} e8s", group_digits(e8s));
+    }
+
+    // TODO: format_fixed_point_decimal. parse_fixed_point_decimal seems
+    // lonesome. But seriously, it can also be used in format_percentage.
+
+    let whole = e8s / E8;
+    let fractional = e8s % E8;
+
+    let fractional = if fractional == 0 {
+        "".to_string()
+    } else {
+        // TODO: Group.
+        format!(".{:08}", fractional).trim_matches('0').to_string()
+    };
+
+    let units = if e8s == E8 { "token" } else { "tokens" };
+
+    format!("{}{} {}", group_digits(whole), fractional, units)
+}
+
+/// The inverse of [`parse_duration`].
+///
+/// One wrinkle: if seconds is None, then this is equivalent to seconds =
+/// Some(0). This follows the same logic as Protocol Buffers. If the caller
+/// wants None to be treated differently, they must do it themselves.
+pub fn format_duration(duration: &nervous_system_pb::Duration) -> String {
+    let nervous_system_pb::Duration { seconds } = duration;
+    let seconds = seconds.unwrap_or(0);
+
+    humantime::format_duration(std::time::Duration::from_secs(seconds)).to_string()
+}
+
+/// The inverse of [`parse_percentage`].
+///
+/// One wrinkle: if basis_points is None, then this is equivalent to
+/// basis_points = Some(0). This follows the same logic as Protocol Buffers. If
+/// the caller wants None to be treated differently, they must do it themselves.
+pub fn format_percentage(percentage: &nervous_system_pb::Percentage) -> String {
+    let nervous_system_pb::Percentage { basis_points } = percentage;
+    let basis_points = basis_points.unwrap_or(0);
+
+    let whole = basis_points / 100;
+    let fractional = basis_points % 100;
+
+    let fractional = if fractional == 0 {
+        "".to_string()
+    } else {
+        format!(".{:02}", fractional).trim_matches('0').to_string()
+    };
+
+    format!("{}{}%", group_digits(whole), fractional)
+}
+
+pub(crate) fn group_digits(n: u64) -> String {
+    let mut left_todo = n;
+    let mut groups = VecDeque::new();
+
+    while left_todo > 0 {
+        let group = left_todo % 1000;
+        left_todo /= 1000;
+
+        let group = if left_todo == 0 {
+            format!("{}", group)
+        } else {
+            format!("{:03}", group)
+        };
+
+        groups.push_front(group);
+    }
+
+    if groups.is_empty() {
+        return "0".to_string();
+    }
+
+    Vec::from(groups).join("_")
+}

rs/nervous_system/humanize/src/lib.rs

@@ -0,0 +1,7 @@
+//! This module exists to contain submodules that correspond to types that we
+//! know how to humanize. These submodules are suitable for use with
+//! #[serde(with = "module")].
+
+pub mod duration;
+pub mod percentage;
+pub mod tokens;

rs/nervous_system/humanize/src/serde.rs

@@ -0,0 +1,26 @@
+use crate::{format_duration, parse_duration};
+use ic_nervous_system_proto::pb::v1::Duration;
+use serde::{ser::Error, Deserialize, Deserializer, Serializer};
+
+#[cfg(test)]
+mod duration_tests;
+
+pub fn deserialize<'de, D>(deserializer: D) -> Result<Duration, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let string: String = Deserialize::deserialize(deserializer)?;
+    parse_duration(&string).map_err(serde::de::Error::custom)
+}
+
+pub fn serialize<S>(duration: &Duration, serializer: S) -> Result<S::Ok, S::Error>
+where
+    S: Serializer,
+{
+    if duration.seconds.is_none() {
+        return Err(S::Error::custom(
+            "Unable to format Duration, because seconds is blank.",
+        ));
+    }
+    serializer.serialize_str(&format_duration(duration))
+}

rs/nervous_system/humanize/src/serde/duration.rs

@@ -0,0 +1,44 @@
+use super::*;
+
+use serde::Serialize;
+
+#[test]
+fn test_round_trip() {
+    fn assert_survives_round_trip(
+        original_duration_str: &str,
+        expected_seconds: u64,
+        expected_formatted_str: &str,
+    ) {
+        #[derive(Debug, PartialEq, Eq, Deserialize, Serialize)]
+        struct T {
+            #[serde(with = "crate::serde::duration")]
+            duration: Duration,
+        }
+
+        let yaml = format!("duration: {}", original_duration_str);
+        let t: T = serde_yaml::from_str(&yaml).unwrap();
+
+        assert_eq!(
+            t,
+            T {
+                duration: Duration {
+                    seconds: Some(expected_seconds),
+                }
+            },
+            "original_duration_str = {:?}",
+            original_duration_str,
+        );
+
+        assert_eq!(
+            serde_yaml::to_string(&t).unwrap(),
+            format!("---\nduration: {}\n", expected_formatted_str),
+            "original_duration_str = {:?}",
+            original_duration_str,
+        );
+    }
+
+    assert_survives_round_trip("1 hour", 3600, "1h");
+    assert_survives_round_trip("1h 2m 3s", 3723, "1h 2m 3s");
+    assert_survives_round_trip("2 weeks", 2 * 7 * 24 * 60 * 60, "14days");
+    assert_survives_round_trip("8 years", (8 * 365 + 2) * 24 * 60 * 60, "8years");
+}

rs/nervous_system/humanize/src/serde/duration/duration_tests.rs

@@ -0,0 +1,26 @@
+use crate::{format_percentage, parse_percentage};
+use ic_nervous_system_proto::pb::v1::Percentage;
+use serde::{ser::Error, Deserialize, Deserializer, Serializer};
+
+#[cfg(test)]
+mod percentage_tests;
+
+pub fn deserialize<'de, D>(deserializer: D) -> Result<Percentage, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let string: String = Deserialize::deserialize(deserializer)?;
+    parse_percentage(&string).map_err(serde::de::Error::custom)
+}
+
+pub fn serialize<S>(percentage: &Percentage, serializer: S) -> Result<S::Ok, S::Error>
+where
+    S: Serializer,
+{
+    if percentage.basis_points.is_none() {
+        return Err(S::Error::custom(
+            "Unable to format Percentage, because basis_points is blank.",
+        ));
+    }
+    serializer.serialize_str(&format_percentage(percentage))
+}

rs/nervous_system/humanize/src/serde/percentage.rs

@@ -0,0 +1,47 @@
+use super::*;
+
+use serde::Serialize;
+
+#[test]
+fn test_round_trip() {
+    fn assert_survives_round_trip(
+        original_percentage_str: &str,
+        expected_basis_points: u64,
+        expected_formatted_str: &str,
+    ) {
+        #[derive(Debug, PartialEq, Eq, Deserialize, Serialize)]
+        struct T {
+            #[serde(with = "crate::serde::percentage")]
+            homelessness_rate: Percentage,
+        }
+
+        let yaml = format!("homelessness_rate: {}", original_percentage_str);
+        let t: T = serde_yaml::from_str(&yaml).unwrap();
+
+        assert_eq!(
+            t,
+            T {
+                homelessness_rate: Percentage {
+                    basis_points: Some(expected_basis_points),
+                }
+            },
+            "original_percentage_str = {:?}",
+            original_percentage_str,
+        );
+
+        assert_eq!(
+            serde_yaml::to_string(&t).unwrap(),
+            format!("---\nhomelessness_rate: {}\n", expected_formatted_str),
+            "original_percentage_str = {:?}",
+            original_percentage_str,
+        );
+    }
+
+    assert_survives_round_trip("0%", 0, "0%");
+    assert_survives_round_trip("0.1%", 10, "0.1%");
+    assert_survives_round_trip("0.89%", 89, "0.89%");
+    assert_survives_round_trip("1%", 100, "1%");
+    assert_survives_round_trip("2.30%", 230, "2.3%");
+    assert_survives_round_trip("57.68%", 57_68, "57.68%");
+    assert_survives_round_trip("1_234.56%", 12_34_56, "1_234.56%");
+}

rs/nervous_system/humanize/src/serde/percentage/percentage_tests.rs

@@ -0,0 +1,26 @@
+use crate::{format_tokens, parse_tokens};
+use ic_nervous_system_proto::pb::v1::Tokens;
+use serde::{ser::Error, Deserialize, Deserializer, Serializer};
+
+#[cfg(test)]
+mod tokens_tests;
+
+pub fn deserialize<'de, D>(deserializer: D) -> Result<Tokens, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let string: String = Deserialize::deserialize(deserializer)?;
+    parse_tokens(&string).map_err(serde::de::Error::custom)
+}
+
+pub fn serialize<S>(tokens: &Tokens, serializer: S) -> Result<S::Ok, S::Error>
+where
+    S: Serializer,
+{
+    if tokens.e8s.is_none() {
+        return Err(S::Error::custom(
+            "Unable to format Tokens, because e8s is blank.",
+        ));
+    }
+    serializer.serialize_str(&format_tokens(tokens))
+}