use std::cmp::Ordering;
use serde::{Deserialize, Serialize};
use thiserror::Error;
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
pub enum TemporalAxis {
ProcessingPosition,
Timestamp,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TemporalPoint {
axis: TemporalAxis,
magnitude: i64,
clock: Option<String>,
}
impl TemporalPoint {
#[must_use]
pub fn position(position: i64) -> Self {
Self {
axis: TemporalAxis::ProcessingPosition,
magnitude: position,
clock: None,
}
}
#[must_use]
pub fn timestamp_ticks(ticks: i64) -> Self {
Self {
axis: TemporalAxis::Timestamp,
magnitude: ticks,
clock: None,
}
}
#[must_use]
pub fn timestamp_ticks_with_clock(ticks: i64, clock: impl Into<String>) -> Self {
Self {
axis: TemporalAxis::Timestamp,
magnitude: ticks,
clock: Some(clock.into()),
}
}
#[must_use]
pub const fn axis(&self) -> TemporalAxis {
self.axis
}
#[must_use]
pub const fn magnitude(&self) -> i64 {
self.magnitude
}
#[must_use]
pub fn clock(&self) -> Option<&str> {
self.clock.as_deref()
}
#[must_use]
pub fn is_compatible_with(&self, other: &Self) -> bool {
self.axis == other.axis
&& (self.axis != TemporalAxis::Timestamp || self.clock == other.clock)
}
pub fn try_cmp(&self, other: &Self) -> Result<Ordering, TemporalPointError> {
if self.axis != other.axis {
return Err(TemporalPointError::AxisMismatch {
left: self.axis,
right: other.axis,
});
}
if self.axis == TemporalAxis::Timestamp && self.clock != other.clock {
return Err(TemporalPointError::ClockMismatch {
left: self.clock.clone(),
right: other.clock.clone(),
});
}
Ok(self.magnitude.cmp(&other.magnitude))
}
}
#[derive(Clone, Debug, Eq, PartialEq, Error)]
pub enum TemporalPointError {
#[error("temporal point axis mismatch: left={left:?}, right={right:?}")]
AxisMismatch {
left: TemporalAxis,
right: TemporalAxis,
},
#[error("temporal point clock mismatch: left={left:?}, right={right:?}")]
ClockMismatch {
left: Option<String>,
right: Option<String>,
},
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct TemporalRange {
start: TemporalPoint,
end: TemporalPoint,
}
impl TemporalRange {
pub fn new(start: TemporalPoint, end: TemporalPoint) -> Result<Self, TemporalRangeError> {
if start.axis() != end.axis() {
return Err(TemporalRangeError::AxisMismatch {
start: start.axis(),
end: end.axis(),
});
}
if start.axis() == TemporalAxis::Timestamp && start.clock != end.clock {
return Err(TemporalRangeError::ClockMismatch {
start: start.clock.clone(),
end: end.clock.clone(),
});
}
if start.magnitude > end.magnitude {
return Err(TemporalRangeError::EndBeforeStart { start, end });
}
if end.magnitude.checked_sub(start.magnitude).is_none() {
return Err(TemporalRangeError::MagnitudeOverflow { start, end });
}
Ok(Self { start, end })
}
pub fn positions(start: i64, end: i64) -> Result<Self, TemporalRangeError> {
Self::new(TemporalPoint::position(start), TemporalPoint::position(end))
}
#[must_use]
pub fn start(&self) -> TemporalPoint {
self.start.clone()
}
pub(crate) fn start_ref(&self) -> &TemporalPoint {
&self.start
}
#[must_use]
pub fn end(&self) -> TemporalPoint {
self.end.clone()
}
pub(crate) fn end_ref(&self) -> &TemporalPoint {
&self.end
}
#[must_use]
pub fn magnitude(&self) -> i64 {
self.end
.magnitude
.checked_sub(self.start.magnitude)
.expect("validated temporal range magnitude")
}
}
impl<'de> Deserialize<'de> for TemporalRange {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct RawRange {
start: TemporalPoint,
end: TemporalPoint,
}
let raw = RawRange::deserialize(deserializer)?;
Self::new(raw.start, raw.end).map_err(serde::de::Error::custom)
}
}
#[derive(Clone, Debug, Error, Eq, PartialEq)]
pub enum TemporalRangeError {
#[error("temporal range axis mismatch: start={start:?}, end={end:?}")]
AxisMismatch {
start: TemporalAxis,
end: TemporalAxis,
},
#[error("temporal range clock mismatch: start={start:?}, end={end:?}")]
ClockMismatch {
start: Option<String>,
end: Option<String>,
},
#[error("temporal range end is before start: start={start:?}, end={end:?}")]
EndBeforeStart {
start: TemporalPoint,
end: TemporalPoint,
},
#[error("temporal range magnitude overflows i64: start={start:?}, end={end:?}")]
MagnitudeOverflow {
start: TemporalPoint,
end: TemporalPoint,
},
}
#[cfg(test)]
mod tests {
use super::*;
use proptest::prelude::*;
#[test]
fn position_ranges_are_half_open_and_have_magnitude() {
let range = TemporalRange::positions(10, 14).expect("valid range");
assert_eq!(range.start(), TemporalPoint::position(10));
assert_eq!(range.end(), TemporalPoint::position(14));
assert_eq!(range.magnitude(), 4);
}
#[test]
fn timestamp_points_can_carry_clock_identity() {
let point = TemporalPoint::timestamp_ticks_with_clock(10, "provider");
assert_eq!(point.axis(), TemporalAxis::Timestamp);
assert_eq!(point.magnitude(), 10);
assert_eq!(point.clock(), Some("provider"));
}
#[test]
fn ranges_reject_mixed_axes() {
let error = TemporalRange::new(
TemporalPoint::position(1),
TemporalPoint::timestamp_ticks(2),
)
.expect_err("mixed axes should fail");
assert!(matches!(error, TemporalRangeError::AxisMismatch { .. }));
}
#[test]
fn ranges_reject_mixed_clocks_and_overflowing_magnitude() {
let error = TemporalRange::new(
TemporalPoint::timestamp_ticks_with_clock(1, "provider-a"),
TemporalPoint::timestamp_ticks_with_clock(2, "provider-b"),
)
.expect_err("mixed clocks should fail");
assert!(matches!(error, TemporalRangeError::ClockMismatch { .. }));
let error = TemporalRange::new(
TemporalPoint::position(i64::MIN),
TemporalPoint::position(i64::MAX),
)
.expect_err("overflowing magnitude should fail");
assert!(matches!(
error,
TemporalRangeError::MagnitudeOverflow { .. }
));
}
#[test]
fn points_do_not_order_across_domains() {
assert!(matches!(
TemporalPoint::position(1).try_cmp(&TemporalPoint::timestamp_ticks(1)),
Err(TemporalPointError::AxisMismatch { .. })
));
assert!(matches!(
TemporalPoint::timestamp_ticks_with_clock(1, "a")
.try_cmp(&TemporalPoint::timestamp_ticks_with_clock(1, "b")),
Err(TemporalPointError::ClockMismatch { .. })
));
}
proptest! {
#[test]
fn range_constructor_never_accepts_backwards_positions(start in any::<i64>(), end in any::<i64>()) {
let result = TemporalRange::new(TemporalPoint::position(start), TemporalPoint::position(end));
if start > end {
prop_assert!(matches!(result, Err(TemporalRangeError::EndBeforeStart { .. })), "backwards range accepted");
} else if end.checked_sub(start).is_none() {
prop_assert!(matches!(result, Err(TemporalRangeError::MagnitudeOverflow { .. })), "overflowing range accepted");
} else {
prop_assert!(result.is_ok());
}
}
#[test]
fn compatible_points_compare_by_magnitude(left in any::<i64>(), right in any::<i64>()) {
let ordering = TemporalPoint::position(left).try_cmp(&TemporalPoint::position(right)).expect("same domain");
prop_assert_eq!(ordering, left.cmp(&right));
}
}
}