Add a TypedEvent conversion trait for ABCI events.

.changelog/unreleased/improvements/1288-typedevent-trait.md

@@ -0,0 +1,2 @@
+- [`tendermint`] Adds a new `TypedEvent` for encoding structured data in ABCI events
+  ([\#1288](https://github.com/informalsystems/tendermint-rs/pull/1288)).

tendermint/src/abci/event.rs

@@ -12,7 +12,7 @@ use crate::prelude::*;
 /// be queried using these events.
 ///
 /// [ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#events)
-#[derive(Clone, PartialEq, Eq, Debug, Serialize)]
+#[derive(Clone, PartialEq, Eq, Debug, Serialize, Hash)]
 pub struct Event {
     /// The kind of event.
     ///
@@ -34,14 +34,13 @@ impl Event {
     ///
     /// let event = Event::new(
     ///     "app",
-    ///     vec![
+    ///     [
     ///         ("key1", "value1").index(),
     ///         ("key2", "value2").index(),
     ///         ("key3", "value3").no_index(), // will not be indexed
     ///     ],
     /// );
     /// ```
-    // XXX(hdevalence): remove vec! from example after https://github.com/rust-lang/rust/pull/65819
     pub fn new<K, I>(kind: K, attributes: I) -> Self
     where
         K: Into<String>,
@@ -53,6 +52,61 @@ impl Event {
             attributes: attributes.into_iter().map(Into::into).collect(),
         }
     }
+
+    /// Checks whether `&self` is equal to `other`, ignoring the `index` field on any attributes.
+    pub fn eq_ignoring_index(&self, other: &Self) -> bool {
+        self.kind == other.kind
+            // IMPORTANT! We need to check the lengths before calling zip,
+            // in order to not drop any attributes.
+            && self.attributes.len() == other.attributes.len()
+            && self
+                .attributes
+                .iter()
+                .zip(other.attributes.iter())
+                .all(|(a, b)| a.eq_ignoring_index(b))
+    }
+
+    /// A variant of [`core::hash::Hash::hash`] that ignores the `index` field on any attributes.
+    pub fn hash_ignoring_index<H: core::hash::Hasher>(&self, state: &mut H) {
+        use core::hash::Hash;
+        self.kind.hash(state);
+        // We can't forward to the slice impl here, because we need to call `hash_ignoring_index`
+        // on each attribute, so we need to do our own length prefixing.
+        state.write_usize(self.attributes.len());
+        for attr in &self.attributes {
+            attr.hash_ignoring_index(state);
+        }
+    }
+}
+
+/// A marker trait for types that can be converted to and from [`Event`]s.
+///
+/// This trait doesn't make any assumptions about how the conversion is
+/// performed, or how the type's data is encoded in event attributes.  Instead,
+/// it just declares the conversion methods used to serialize the type to an
+/// [`Event`] and to deserialize it from an [`Event`], allowing downstream users
+/// to declare a single source of truth about how event data is structured.
+///
+/// # Contract
+///
+/// If `T: TypedEvent`, then:
+///
+/// - `T::try_from(e) == Ok(t)` for all `t: T, e: Event` where `Event::from(t).eq_ignoring_index(e)
+///   == true`.
+/// - `Event::from(T::try_from(e).unwrap()).eq_ignoring_index(e) == true` for all `e: Event` where
+///   `T::try_from(e)` returns `Ok(_)`.
+///
+/// In other words, the conversion methods should round-trip on the attributes,
+/// but are not required to preserve the (nondeterministic) index information.
+pub trait TypedEvent
+where
+    Self: TryFrom<Event>,
+    Event: From<Self>,
+{
+    /// Convenience wrapper around `Into::into` that doesn't require type inference.
+    fn into_event(self) -> Event {
+        self.into()
+    }
 }
 
 /// A key-value pair describing an [`Event`].
@@ -61,7 +115,7 @@ impl Event {
 /// [`Event::new`] for details.
 ///
 /// [ABCI documentation](https://docs.tendermint.com/master/spec/abci/abci.html#events)
-#[derive(Clone, PartialEq, Eq, Debug, Serialize)]
+#[derive(Clone, PartialEq, Eq, Debug, Serialize, Hash)]
 pub struct EventAttribute {
     /// The event key.
     pub key: String,
@@ -73,6 +127,20 @@ pub struct EventAttribute {
     pub index: bool,
 }
 
+impl EventAttribute {
+    /// Checks whether `&self` is equal to `other`, ignoring the `index` field.
+    pub fn eq_ignoring_index(&self, other: &Self) -> bool {
+        self.key == other.key && self.value == other.value
+    }
+
+    /// A variant of [`core::hash::Hash::hash`] that ignores the `index` field.
+    pub fn hash_ignoring_index<H: core::hash::Hasher>(&self, state: &mut H) {
+        use core::hash::Hash;
+        // Call the `Hash` impl on the (k,v) tuple to avoid prefix collision issues.
+        (&self.key, &self.value).hash(state);
+    }
+}
+
 impl<K: Into<String>, V: Into<String>> From<(K, V, bool)> for EventAttribute {
     fn from((key, value, index): (K, V, bool)) -> Self {
         EventAttribute {
@@ -250,3 +318,110 @@ mod v0_37 {
 
     impl Protobuf<pb::Event> for Event {}
 }
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::bool_assert_comparison)]
+    #![allow(clippy::redundant_clone)]
+
+    use serde::Deserialize;
+
+    use super::*;
+
+    #[test]
+    fn event_eq_ignoring_index_ignores_index() {
+        let event_a = Event::new("test", [("foo", "bar").index()]);
+        let event_b = Event::new("test", [("foo", "bar").no_index()]);
+        let event_c = Event::new("test", [("foo", "baz").index()]);
+
+        assert_eq!(event_a.eq_ignoring_index(&event_b), true);
+        assert_eq!(event_a.eq_ignoring_index(&event_c), false);
+    }
+
+    #[test]
+    fn exercise_typed_event() {
+        #[derive(Clone, Serialize, Deserialize, Debug, PartialEq, Eq)]
+        struct Payload {
+            x: u32,
+            y: u32,
+        }
+
+        #[derive(Clone, Debug, PartialEq, Eq)]
+        struct MyEvent {
+            a: Payload,
+            b: Payload,
+        }
+
+        impl From<MyEvent> for Event {
+            fn from(event: MyEvent) -> Self {
+                Event::new(
+                    "my_event",
+                    vec![
+                        ("a", serde_json::to_string(&event.a).unwrap()).index(),
+                        ("b", serde_json::to_string(&event.b).unwrap()).index(),
+                    ],
+                )
+            }
+        }
+
+        impl TryFrom<Event> for MyEvent {
+            type Error = (); // Avoid depending on a specific error library in test code
+
+            fn try_from(event: Event) -> Result<Self, Self::Error> {
+                if event.kind != "my_event" {
+                    return Err(());
+                }
+
+                let a = event
+                    .attributes
+                    .iter()
+                    .find(|attr| attr.key == "a")
+                    .ok_or(())
+                    .and_then(|attr| serde_json::from_str(&attr.value).map_err(|_| ()))?;
+                let b = event
+                    .attributes
+                    .iter()
+                    .find(|attr| attr.key == "b")
+                    .ok_or(())
+                    .and_then(|attr| serde_json::from_str(&attr.value).map_err(|_| ()))?;
+
+                Ok(MyEvent { a, b })
+            }
+        }
+
+        impl TypedEvent for MyEvent {}
+
+        let t = MyEvent {
+            a: Payload { x: 1, y: 2 },
+            b: Payload { x: 3, y: 4 },
+        };
+
+        let e1 = Event::from(t.clone());
+        // e2 is like e1 but with different indexing.
+        let e2 = {
+            let mut e = e1.clone();
+            e.attributes[0].index = false;
+            e.attributes[1].index = false;
+            e
+        };
+
+        // Contract:
+
+        // - `T::try_from(e) == Ok(t)` for all `t: T, e: Event` where
+        //   `Event::from(t).eq_ignoring_index(e) == true`.
+        assert_eq!(e1.eq_ignoring_index(&e2), true);
+        assert_eq!(MyEvent::try_from(e1.clone()), Ok(t.clone()));
+        assert_eq!(MyEvent::try_from(e2.clone()), Ok(t.clone()));
+
+        // - `Event::from(T::try_from(e).unwrap()).eq_ignoring_index(e) == true` for all `e: Event`
+        //   where `T::try_from(e)` returns `Ok(_)`.
+        assert_eq!(
+            Event::from(MyEvent::try_from(e1.clone()).unwrap()).eq_ignoring_index(&e1),
+            true
+        );
+        assert_eq!(
+            Event::from(MyEvent::try_from(e2.clone()).unwrap()).eq_ignoring_index(&e2),
+            true
+        );
+    }
+}