wire types: WireTime newtype for timestamps instead of adaptor-annotated i64

hive-sh4re/src/wire_time.rs

@@ -11,13 +11,63 @@
 //! safe (an old peer emitting epoch ints into a new reader) and lets
 //! previously persisted JSON blobs re-load unchanged.
 //!
-//! Usage: `#[serde(with = "crate::wire_time::iso")]` on `i64` fields,
-//! `#[serde(with = "crate::wire_time::iso_opt")]` on `Option<i64>`
-//! (keep the usual `default` + `skip_serializing_if` attributes).
+//! Usage: type timestamp fields as [`WireTime`] / `Option<WireTime>`
+//! (keep the usual `default` + `skip_serializing_if` attributes on the
+//! optional form). The type IS the adaptor — no `#[serde(with = …)]`
+//! needed.
 
 use chrono::{DateTime, SecondsFormat, Utc};
 use serde::Deserialize;
 
+/// A timestamp on the wire: unix-epoch seconds in Rust, RFC 3339 UTC
+/// string in JSON. Carries "this is a timestamp" in the type system
+/// instead of a bare `i64` — the module docs above describe the wire
+/// behaviour (ISO out, lenient epoch-or-ISO in).
+///
+/// The inner value is public: arithmetic like `now + delay` stays
+/// plain integer math (`WireTime(now_secs + delay)`), no chrono types
+/// leak into call sites.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct WireTime(pub i64);
+
+impl WireTime {
+    /// The wrapped unix-epoch seconds.
+    #[must_use]
+    pub fn secs(self) -> i64 {
+        self.0
+    }
+
+    /// RFC 3339 UTC `Z` string form (same as the serialized shape).
+    #[must_use]
+    pub fn to_iso(self) -> String {
+        to_iso(self.0)
+    }
+}
+
+impl From<i64> for WireTime {
+    fn from(secs: i64) -> Self {
+        Self(secs)
+    }
+}
+
+impl std::fmt::Display for WireTime {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&to_iso(self.0))
+    }
+}
+
+impl serde::Serialize for WireTime {
+    fn serialize<S: serde::Serializer>(&self, ser: S) -> Result<S::Ok, S::Error> {
+        ser.serialize_str(&to_iso(self.0))
+    }
+}
+
+impl<'de> Deserialize<'de> for WireTime {
+    fn deserialize<D: serde::Deserializer<'de>>(de: D) -> Result<Self, D::Error> {
+        EpochOrIso::deserialize(de)?.into_secs().map(Self)
+    }
+}
+
 /// Format unix-epoch seconds as an RFC 3339 UTC string with a `Z`
 /// suffix. Out-of-range values (never produced by our clocks) clamp to
 /// the epoch rather than erroring — serialization must not fail.
@@ -52,61 +102,23 @@ impl EpochOrIso {
     }
 }
 
-/// Adaptor for required `i64` timestamp fields.
-pub mod iso {
-    use serde::{Deserializer, Serializer};
-
-    use super::{Deserialize, EpochOrIso};
-
-    pub fn serialize<S: Serializer>(secs: &i64, ser: S) -> Result<S::Ok, S::Error> {
-        ser.serialize_str(&super::to_iso(*secs))
-    }
-
-    pub fn deserialize<'de, D: Deserializer<'de>>(de: D) -> Result<i64, D::Error> {
-        EpochOrIso::deserialize(de)?.into_secs()
-    }
-}
-
-/// Adaptor for `Option<i64>` timestamp fields.
-pub mod iso_opt {
-    use serde::{Deserializer, Serializer};
-
-    use super::{Deserialize, EpochOrIso};
-
-    pub fn serialize<S: Serializer>(secs: &Option<i64>, ser: S) -> Result<S::Ok, S::Error> {
-        match secs {
-            Some(secs) => ser.serialize_str(&super::to_iso(*secs)),
-            None => ser.serialize_none(),
-        }
-    }
-
-    pub fn deserialize<'de, D: Deserializer<'de>>(de: D) -> Result<Option<i64>, D::Error> {
-        Option::<EpochOrIso>::deserialize(de)?
-            .map(EpochOrIso::into_secs)
-            .transpose()
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use serde::{Deserialize, Serialize};
 
+    use super::WireTime;
+
     #[derive(Serialize, Deserialize, PartialEq, Debug)]
     struct Row {
-        #[serde(with = "crate::wire_time::iso")]
-        at: i64,
-        #[serde(
-            default,
-            skip_serializing_if = "Option::is_none",
-            with = "crate::wire_time::iso_opt"
-        )]
-        maybe_at: Option<i64>,
+        at: WireTime,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        maybe_at: Option<WireTime>,
     }
 
     #[test]
     fn serializes_epoch_as_rfc3339_z() {
         let json = serde_json::to_string(&Row {
-            at: 1_751_480_000,
+            at: WireTime(1_751_480_000),
             maybe_at: None,
         })
         .unwrap();
@@ -116,8 +128,8 @@ mod tests {
     #[test]
     fn round_trips_and_serializes_some() {
         let row = Row {
-            at: 0,
-            maybe_at: Some(1_751_480_000),
+            at: WireTime(0),
+            maybe_at: Some(WireTime(1_751_480_000)),
         };
         let json = serde_json::to_string(&row).unwrap();
         assert_eq!(
@@ -132,13 +144,13 @@ mod tests {
         // Rolling-deploy skew: an old writer still emits bare epoch
         // integers — the lenient reader must accept them.
         let row: Row = serde_json::from_str(r#"{"at":1751480000,"maybe_at":1751480000}"#).unwrap();
-        assert_eq!(row.at, 1_751_480_000);
-        assert_eq!(row.maybe_at, Some(1_751_480_000));
+        assert_eq!(row.at, WireTime(1_751_480_000));
+        assert_eq!(row.maybe_at, Some(WireTime(1_751_480_000)));
     }
 
     #[test]
     fn deserializes_offset_form_normalized_to_utc() {
         let row: Row = serde_json::from_str(r#"{"at":"2025-07-02T20:13:20+02:00"}"#).unwrap();
-        assert_eq!(row.at, 1_751_480_000);
+        assert_eq!(row.at, WireTime(1_751_480_000));
     }
 }