use serde::{Deserialize, Serialize};
use thiserror::Error;
use std::{
cmp::Ordering,
collections::{BTreeMap, BTreeSet},
};
use crate::{
ComparisonFinality, PrimitiveValue, TemporalAxis, TemporalPoint, TemporalRange,
TemporalRangeError,
};
#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd, Hash, Serialize)]
pub struct WindowRecordId(String);
impl WindowRecordId {
pub fn new(value: impl Into<String>) -> Result<Self, WindowMetadataError> {
let value = value.into();
if value.trim().is_empty() {
return Err(WindowMetadataError::EmptyRecordId);
}
Ok(Self(value))
}
pub(crate) fn generated(value: String) -> Self {
debug_assert!(!value.trim().is_empty());
Self(value)
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
}
impl<'de> Deserialize<'de> for WindowRecordId {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
let value = String::deserialize(deserializer)?;
if value.trim().is_empty() {
return Err(serde::de::Error::custom("window record id cannot be empty"));
}
Ok(Self(value))
}
}
#[non_exhaustive]
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct WindowSegment {
pub(crate) name: String,
pub(crate) value: PrimitiveValue,
pub(crate) parent_name: Option<String>,
}
impl WindowSegment {
pub fn new(
name: impl Into<String>,
value: impl Into<PrimitiveValue>,
) -> Result<Self, WindowMetadataError> {
let name = name.into();
if name.trim().is_empty() {
return Err(WindowMetadataError::EmptySegmentName);
}
Ok(Self {
name,
value: value.into(),
parent_name: None,
})
}
pub fn with_parent(
mut self,
parent_name: impl Into<String>,
) -> Result<Self, WindowMetadataError> {
let parent_name = parent_name.into();
if parent_name.trim().is_empty() {
return Err(WindowMetadataError::EmptyParentSegmentName);
}
self.parent_name = Some(parent_name);
Ok(self)
}
#[must_use]
pub fn name(&self) -> &str {
&self.name
}
#[must_use]
pub const fn value(&self) -> &PrimitiveValue {
&self.value
}
#[must_use]
pub fn parent_name(&self) -> Option<&str> {
self.parent_name.as_deref()
}
}
impl<'de> Deserialize<'de> for WindowSegment {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct RawSegment {
name: String,
value: PrimitiveValue,
parent_name: Option<String>,
}
let raw = RawSegment::deserialize(deserializer)?;
if raw.name.trim().is_empty()
|| raw
.parent_name
.as_deref()
.is_some_and(|parent| parent.trim().is_empty())
{
return Err(serde::de::Error::custom("segment names cannot be empty"));
}
Ok(Self {
name: raw.name,
value: raw.value,
parent_name: raw.parent_name,
})
}
}
#[non_exhaustive]
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct WindowTag {
pub(crate) name: String,
pub(crate) value: PrimitiveValue,
}
impl WindowTag {
pub fn new(
name: impl Into<String>,
value: impl Into<PrimitiveValue>,
) -> Result<Self, WindowMetadataError> {
let name = name.into();
if name.trim().is_empty() {
return Err(WindowMetadataError::EmptyTagName);
}
Ok(Self {
name,
value: value.into(),
})
}
#[must_use]
pub fn name(&self) -> &str {
&self.name
}
#[must_use]
pub const fn value(&self) -> &PrimitiveValue {
&self.value
}
}
#[derive(Clone, Debug, Error, Eq, PartialEq)]
pub enum WindowMetadataError {
#[error("window record id cannot be empty")]
EmptyRecordId,
#[error("segment name cannot be empty")]
EmptySegmentName,
#[error("parent segment name cannot be empty")]
EmptyParentSegmentName,
#[error("tag name cannot be empty")]
EmptyTagName,
}
#[derive(Clone, Debug, Error, Eq, PartialEq)]
pub enum WindowHistoryFixtureError {
#[error(transparent)]
Temporal(#[from] TemporalRangeError),
#[error(transparent)]
Metadata(#[from] WindowMetadataError),
}
impl<'de> Deserialize<'de> for WindowTag {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct RawTag {
name: String,
value: PrimitiveValue,
}
let raw = RawTag::deserialize(deserializer)?;
if raw.name.trim().is_empty() {
return Err(serde::de::Error::custom("tag names cannot be empty"));
}
Ok(Self {
name: raw.name,
value: raw.value,
})
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub enum WindowBoundaryReason {
ActivePredicateEnded,
SegmentChanged,
}
#[non_exhaustive]
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct WindowBoundaryChange {
pub segment_name: String,
pub previous_value: Option<PrimitiveValue>,
pub current_value: Option<PrimitiveValue>,
}
impl<'de> Deserialize<'de> for WindowBoundaryChange {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct RawBoundaryChange {
segment_name: String,
previous_value: Option<PrimitiveValue>,
current_value: Option<PrimitiveValue>,
}
let raw = RawBoundaryChange::deserialize(deserializer)?;
if raw.segment_name.trim().is_empty() {
return Err(serde::de::Error::custom(
"boundary segment names cannot be empty",
));
}
Ok(Self {
segment_name: raw.segment_name,
previous_value: raw.previous_value,
current_value: raw.current_value,
})
}
}
#[non_exhaustive]
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct ClosedWindow {
pub id: WindowRecordId,
pub window_name: String,
pub key: String,
pub range: TemporalRange,
pub known_at: Option<TemporalPoint>,
pub source: Option<String>,
pub partition: Option<String>,
pub segments: Vec<WindowSegment>,
pub tags: Vec<WindowTag>,
pub boundary_reason: Option<WindowBoundaryReason>,
pub boundary_changes: Vec<WindowBoundaryChange>,
}
#[non_exhaustive]
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct OpenWindow {
pub id: WindowRecordId,
pub window_name: String,
pub key: String,
pub start: TemporalPoint,
pub known_at: Option<TemporalPoint>,
pub source: Option<String>,
pub partition: Option<String>,
pub segments: Vec<WindowSegment>,
pub tags: Vec<WindowTag>,
}
struct WindowPayload<'a> {
window_name: &'a str,
key: &'a str,
source: Option<&'a str>,
partition: Option<&'a str>,
start: &'a TemporalPoint,
known_at: Option<&'a TemporalPoint>,
segments: &'a [WindowSegment],
tags: &'a [WindowTag],
boundary_changes: &'a [WindowBoundaryChange],
}
fn validate_window_payload(payload: WindowPayload<'_>) -> Result<(), &'static str> {
if payload.window_name.trim().is_empty() {
return Err("window name cannot be empty");
}
if payload.key.trim().is_empty() {
return Err("window key cannot be empty");
}
if payload.source.is_some_and(|value| value.trim().is_empty()) {
return Err("source cannot be empty");
}
if payload
.partition
.is_some_and(|value| value.trim().is_empty())
{
return Err("partition cannot be empty");
}
if let Some(known_at) = payload.known_at
&& !payload.start.is_compatible_with(known_at)
{
return Err("known-at point must share the window temporal domain");
}
let mut segment_names = BTreeSet::new();
for segment in payload.segments {
if !segment_names.insert(segment.name.as_str()) {
return Err("segment names must be unique within a window");
}
if let Some(parent) = segment.parent_name.as_deref()
&& !segment_names.contains(parent)
{
return Err("segment parent must precede and reference a captured segment");
}
}
let mut tag_names = BTreeSet::new();
for tag in payload.tags {
if !tag_names.insert(tag.name.as_str()) {
return Err("tag names must be unique within a window");
}
}
if payload
.boundary_changes
.iter()
.any(|change| change.segment_name.trim().is_empty())
{
return Err("boundary segment names cannot be empty");
}
Ok(())
}
impl<'de> Deserialize<'de> for ClosedWindow {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct RawClosedWindow {
id: WindowRecordId,
window_name: String,
key: String,
range: TemporalRange,
known_at: Option<TemporalPoint>,
source: Option<String>,
partition: Option<String>,
segments: Vec<WindowSegment>,
tags: Vec<WindowTag>,
boundary_reason: Option<WindowBoundaryReason>,
boundary_changes: Vec<WindowBoundaryChange>,
}
let raw = RawClosedWindow::deserialize(deserializer)?;
let start = raw.range.start_ref();
validate_window_payload(WindowPayload {
window_name: &raw.window_name,
key: &raw.key,
source: raw.source.as_deref(),
partition: raw.partition.as_deref(),
start,
known_at: raw.known_at.as_ref(),
segments: &raw.segments,
tags: &raw.tags,
boundary_changes: &raw.boundary_changes,
})
.map_err(serde::de::Error::custom)?;
Ok(Self {
id: raw.id,
window_name: raw.window_name,
key: raw.key,
range: raw.range,
known_at: raw.known_at,
source: raw.source,
partition: raw.partition,
segments: raw.segments,
tags: raw.tags,
boundary_reason: raw.boundary_reason,
boundary_changes: raw.boundary_changes,
})
}
}
impl<'de> Deserialize<'de> for OpenWindow {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct RawOpenWindow {
id: WindowRecordId,
window_name: String,
key: String,
start: TemporalPoint,
known_at: Option<TemporalPoint>,
source: Option<String>,
partition: Option<String>,
segments: Vec<WindowSegment>,
tags: Vec<WindowTag>,
}
let raw = RawOpenWindow::deserialize(deserializer)?;
validate_window_payload(WindowPayload {
window_name: &raw.window_name,
key: &raw.key,
source: raw.source.as_deref(),
partition: raw.partition.as_deref(),
start: &raw.start,
known_at: raw.known_at.as_ref(),
segments: &raw.segments,
tags: &raw.tags,
boundary_changes: &[],
})
.map_err(serde::de::Error::custom)?;
Ok(Self {
id: raw.id,
window_name: raw.window_name,
key: raw.key,
start: raw.start,
known_at: raw.known_at,
source: raw.source,
partition: raw.partition,
segments: raw.segments,
tags: raw.tags,
})
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub enum WindowRecord {
Closed(ClosedWindow),
Open(OpenWindow),
}
impl WindowRecord {
#[must_use]
pub fn id(&self) -> &WindowRecordId {
match self {
Self::Closed(window) => &window.id,
Self::Open(window) => &window.id,
}
}
#[must_use]
pub fn window_name(&self) -> &str {
match self {
Self::Closed(window) => &window.window_name,
Self::Open(window) => &window.window_name,
}
}
#[must_use]
pub fn key(&self) -> &str {
match self {
Self::Closed(window) => &window.key,
Self::Open(window) => &window.key,
}
}
#[must_use]
pub fn source(&self) -> Option<&str> {
match self {
Self::Closed(window) => window.source.as_deref(),
Self::Open(window) => window.source.as_deref(),
}
}
#[must_use]
pub fn partition(&self) -> Option<&str> {
match self {
Self::Closed(window) => window.partition.as_deref(),
Self::Open(window) => window.partition.as_deref(),
}
}
#[must_use]
pub fn segments(&self) -> &[WindowSegment] {
match self {
Self::Closed(window) => &window.segments,
Self::Open(window) => &window.segments,
}
}
#[must_use]
pub fn tags(&self) -> &[WindowTag] {
match self {
Self::Closed(window) => &window.tags,
Self::Open(window) => &window.tags,
}
}
#[must_use]
pub const fn is_closed(&self) -> bool {
matches!(self, Self::Closed(_))
}
#[must_use]
pub fn start(&self) -> TemporalPoint {
match self {
Self::Closed(window) => window.range.start(),
Self::Open(window) => window.start.clone(),
}
}
#[must_use]
pub fn end(&self) -> Option<TemporalPoint> {
match self {
Self::Closed(window) => Some(window.range.end()),
Self::Open(_) => None,
}
}
}
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct WindowSnapshotRecord {
pub window: WindowRecord,
pub range: TemporalRange,
pub finality: ComparisonFinality,
}
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct WindowHistorySnapshot {
pub horizon: TemporalPoint,
pub records: Vec<WindowSnapshotRecord>,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub enum WindowGroupKind {
Segment,
Tag,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct WindowGroupSummary {
pub group_kind: WindowGroupKind,
pub name: String,
pub value: PrimitiveValue,
pub record_count: usize,
pub final_count: usize,
pub provisional_count: usize,
pub measured_position_count: usize,
pub total_position_length: i64,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct WindowOverlap {
pub first: ClosedWindow,
pub second: ClosedWindow,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct WindowResidualSegment {
pub window_name: String,
pub key: String,
pub source: String,
pub start_position: i64,
pub end_position: i64,
pub partition: Option<String>,
pub axis: TemporalAxis,
pub clock: Option<String>,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct WindowAnnotationTarget {
pub window_name: String,
pub key: String,
pub start_position: i64,
pub axis: TemporalAxis,
pub clock: Option<String>,
pub source: Option<String>,
pub partition: Option<String>,
}
impl WindowAnnotationTarget {
#[must_use]
pub fn from_window(window: &WindowRecord) -> Self {
Self {
window_name: window.window_name().to_owned(),
key: window.key().to_owned(),
start_position: window.start().magnitude(),
axis: window.start().axis(),
clock: window.start().clock().map(str::to_owned),
source: window.source().map(str::to_owned),
partition: window.partition().map(str::to_owned),
}
}
#[must_use]
pub fn from_closed(window: &ClosedWindow) -> Self {
Self::from_window(&WindowRecord::Closed(window.clone()))
}
#[must_use]
pub fn from_open(window: &OpenWindow) -> Self {
Self::from_window(&WindowRecord::Open(window.clone()))
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct WindowAnnotation {
pub target: WindowAnnotationTarget,
pub name: String,
pub value: PrimitiveValue,
pub known_at: Option<TemporalPoint>,
pub revision: usize,
}
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct WindowHistory {
closed: Vec<ClosedWindow>,
open: Vec<OpenWindow>,
#[serde(skip)]
open_indexes: BTreeMap<WindowRecordId, usize>,
annotations: Vec<WindowAnnotation>,
}
impl<'de> Deserialize<'de> for WindowHistory {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct RawHistory {
#[serde(default)]
closed: Vec<ClosedWindow>,
#[serde(default)]
open: Vec<OpenWindow>,
#[serde(default)]
annotations: Vec<WindowAnnotation>,
}
let raw = RawHistory::deserialize(deserializer)?;
let mut open_indexes = BTreeMap::new();
for (index, window) in raw.open.iter().enumerate() {
if open_indexes.insert(window.id.clone(), index).is_some() {
return Err(serde::de::Error::custom("duplicate open window record id"));
}
}
Ok(Self {
closed: raw.closed,
open: raw.open,
open_indexes,
annotations: raw.annotations,
})
}
}
impl WindowHistory {
#[must_use]
pub const fn new() -> Self {
Self {
closed: Vec::new(),
open: Vec::new(),
open_indexes: BTreeMap::new(),
annotations: Vec::new(),
}
}
#[must_use]
pub fn closed_windows(&self) -> &[ClosedWindow] {
&self.closed
}
#[must_use]
pub fn open_windows(&self) -> &[OpenWindow] {
&self.open
}
#[must_use]
pub fn annotations(&self) -> &[WindowAnnotation] {
&self.annotations
}
#[must_use]
pub fn windows(&self) -> Vec<WindowRecord> {
let mut windows = self
.closed
.iter()
.cloned()
.map(WindowRecord::Closed)
.chain(self.open.iter().cloned().map(WindowRecord::Open))
.collect::<Vec<_>>();
sort_window_records(&mut windows);
windows
}
#[must_use]
pub fn query(&self) -> WindowHistoryRefQuery<'_> {
WindowHistoryRefQuery::new(self)
}
#[must_use]
pub fn for_window(&self, window_name: &str) -> Vec<WindowRecord> {
self.query().where_window(window_name).windows()
}
#[must_use]
pub fn with_segment(&self, name: &str, value: impl Into<PrimitiveValue>) -> Vec<WindowRecord> {
self.query().where_segment(name, value).windows()
}
#[must_use]
pub fn with_tag(&self, name: &str, value: impl Into<PrimitiveValue>) -> Vec<WindowRecord> {
self.query().where_tag(name, value).windows()
}
pub fn snapshot_at(
&self,
horizon: TemporalPoint,
) -> Result<WindowHistorySnapshot, TemporalRangeError> {
let mut records = self
.query()
.windows()
.into_iter()
.map(|window| snapshot_record(window, horizon.clone()))
.collect::<Result<Vec<_>, _>>()?
.into_iter()
.flatten()
.collect::<Vec<_>>();
records.sort_by(|left, right| compare_window_records(&left.window, &right.window));
Ok(WindowHistorySnapshot { horizon, records })
}
#[must_use]
pub fn find_overlaps(&self) -> Vec<WindowOverlap> {
let mut overlaps = Vec::new();
for (index, first) in self.closed.iter().enumerate() {
for second in &self.closed[index + 1..] {
if same_closed_scope(first, second) && closed_windows_overlap(first, second) {
overlaps.push(WindowOverlap {
first: first.clone(),
second: second.clone(),
});
}
}
}
overlaps
}
#[must_use]
pub fn find_residuals(&self, target_source: &str) -> Vec<WindowResidualSegment> {
let mut residuals = Vec::new();
for target in &self.closed {
if target.source.as_deref() != Some(target_source) {
continue;
}
let mut segments = vec![(
target.range.start().magnitude(),
target.range.end().magnitude(),
)];
for comparison in &self.closed {
if comparison.id == target.id
|| comparison.source.as_deref() == Some(target_source)
|| !same_closed_scope(target, comparison)
|| !closed_windows_overlap(target, comparison)
{
continue;
}
segments = subtract_position_window(&segments, comparison);
}
residuals.extend(segments.into_iter().filter(|(start, end)| start < end).map(
|(start_position, end_position)| WindowResidualSegment {
window_name: target.window_name.clone(),
key: target.key.clone(),
source: target_source.to_owned(),
start_position,
end_position,
partition: target.partition.clone(),
axis: target.range.start().axis(),
clock: target.range.start().clock().map(str::to_owned),
},
));
}
residuals
}
pub fn annotate(
&mut self,
target: WindowAnnotationTarget,
name: impl Into<String>,
value: impl Into<PrimitiveValue>,
known_at: Option<TemporalPoint>,
) -> WindowAnnotation {
let name = name.into();
let revision = 1 + self
.annotations
.iter()
.filter(|annotation| annotation.target == target && annotation.name == name)
.count();
let annotation = WindowAnnotation {
target,
name,
value: value.into(),
known_at,
revision,
};
self.annotations.push(annotation.clone());
annotation
}
#[must_use]
pub fn annotations_for(&self, target: &WindowAnnotationTarget) -> Vec<WindowAnnotation> {
self.annotations
.iter()
.filter(|annotation| &annotation.target == target)
.cloned()
.collect()
}
#[must_use]
pub fn annotations_known_at(
&self,
target: &WindowAnnotationTarget,
horizon: TemporalPoint,
) -> Vec<WindowAnnotation> {
self.annotations
.iter()
.filter(|annotation| {
&annotation.target == target
&& annotation.known_at.as_ref().is_some_and(|known_at| {
known_at.axis() == horizon.axis()
&& known_at
.try_cmp(&horizon)
.is_ok_and(std::cmp::Ordering::is_le)
})
})
.cloned()
.collect()
}
#[must_use]
pub fn compare_sources(
&self,
name: &str,
window_name: &str,
sources: &[String],
) -> crate::SourceMatrixResult {
crate::compare_sources(self, name, window_name, sources)
}
#[must_use]
pub fn compare_hierarchy(
&self,
name: &str,
parent_window_name: &str,
child_window_name: &str,
) -> crate::HierarchyComparisonResult {
crate::compare_hierarchy(self, name, parent_window_name, child_window_name)
}
pub(crate) fn push_closed(&mut self, window: ClosedWindow) {
self.closed.push(window);
}
pub(crate) fn push_open(&mut self, window: OpenWindow) {
self.open_indexes.insert(window.id.clone(), self.open.len());
self.open.push(window);
}
pub(crate) fn remove_open(&mut self, id: &WindowRecordId) -> Option<OpenWindow> {
let index = self.open_indexes.remove(id)?;
let removed = self.open.swap_remove(index);
if index < self.open.len() {
self.open_indexes.insert(self.open[index].id.clone(), index);
}
Some(removed)
}
pub(crate) fn update_open_tags(&mut self, id: &WindowRecordId, tags: Vec<WindowTag>) -> bool {
let Some(index) = self.open_indexes.get(id).copied() else {
return false;
};
let Some(window) = self.open.get_mut(index) else {
return false;
};
window.tags = tags;
true
}
}
#[derive(Clone, Copy, Debug)]
enum WindowRef<'a> {
Closed(&'a ClosedWindow),
Open(&'a OpenWindow),
}
impl<'a> WindowRef<'a> {
fn owned(self) -> WindowRecord {
match self {
Self::Closed(window) => WindowRecord::Closed(window.clone()),
Self::Open(window) => WindowRecord::Open(window.clone()),
}
}
fn window_name(self) -> &'a str {
match self {
Self::Closed(window) => &window.window_name,
Self::Open(window) => &window.window_name,
}
}
fn key(self) -> &'a str {
match self {
Self::Closed(window) => &window.key,
Self::Open(window) => &window.key,
}
}
fn source(self) -> Option<&'a str> {
match self {
Self::Closed(window) => window.source.as_deref(),
Self::Open(window) => window.source.as_deref(),
}
}
fn partition(self) -> Option<&'a str> {
match self {
Self::Closed(window) => window.partition.as_deref(),
Self::Open(window) => window.partition.as_deref(),
}
}
fn segments(self) -> &'a [WindowSegment] {
match self {
Self::Closed(window) => &window.segments,
Self::Open(window) => &window.segments,
}
}
fn tags(self) -> &'a [WindowTag] {
match self {
Self::Closed(window) => &window.tags,
Self::Open(window) => &window.tags,
}
}
fn is_closed(self) -> bool {
matches!(self, Self::Closed(_))
}
fn start(self) -> &'a TemporalPoint {
match self {
Self::Closed(window) => window.range.start_ref(),
Self::Open(window) => &window.start,
}
}
fn end(self) -> Option<&'a TemporalPoint> {
match self {
Self::Closed(window) => Some(window.range.end_ref()),
Self::Open(_) => None,
}
}
fn id(self) -> &'a WindowRecordId {
match self {
Self::Closed(window) => &window.id,
Self::Open(window) => &window.id,
}
}
}
fn compare_window_refs(left: WindowRef<'_>, right: WindowRef<'_>) -> Ordering {
left.window_name()
.cmp(right.window_name())
.then_with(|| left.key().cmp(right.key()))
.then_with(|| left.source().cmp(&right.source()))
.then_with(|| left.partition().cmp(&right.partition()))
.then_with(|| left.start().magnitude().cmp(&right.start().magnitude()))
.then_with(|| {
left.end()
.map_or(i64::MAX, |point| point.magnitude())
.cmp(&right.end().map_or(i64::MAX, |point| point.magnitude()))
})
.then_with(|| left.id().cmp(right.id()))
}
#[derive(Clone, Debug)]
pub struct WindowHistoryRefQuery<'a> {
windows: Vec<WindowRef<'a>>,
}
impl<'a> WindowHistoryRefQuery<'a> {
fn new(history: &'a WindowHistory) -> Self {
let mut windows = history
.closed
.iter()
.map(WindowRef::Closed)
.chain(history.open.iter().map(WindowRef::Open))
.collect::<Vec<_>>();
windows.sort_by(|left, right| compare_window_refs(*left, *right));
Self { windows }
}
#[must_use]
pub fn where_window(mut self, window_name: &str) -> Self {
self.windows
.retain(|window| window.window_name() == window_name);
self
}
#[must_use]
pub fn where_key(mut self, key: &str) -> Self {
self.windows.retain(|window| window.key() == key);
self
}
#[must_use]
pub fn where_source(mut self, source: &str) -> Self {
self.windows
.retain(|window| window.source() == Some(source));
self
}
#[must_use]
pub fn where_partition(mut self, partition: &str) -> Self {
self.windows
.retain(|window| window.partition() == Some(partition));
self
}
#[must_use]
pub fn where_segment(mut self, name: &str, value: impl Into<PrimitiveValue>) -> Self {
let value = value.into();
self.windows.retain(|window| {
window
.segments()
.iter()
.any(|segment| segment.name == name && segment.value == value)
});
self
}
#[must_use]
pub fn where_tag(mut self, name: &str, value: impl Into<PrimitiveValue>) -> Self {
let value = value.into();
self.windows.retain(|window| {
window
.tags()
.iter()
.any(|tag| tag.name == name && tag.value == value)
});
self
}
#[must_use]
pub fn closed(mut self) -> Self {
self.windows.retain(|window| window.is_closed());
self
}
#[must_use]
pub fn open(mut self) -> Self {
self.windows.retain(|window| !window.is_closed());
self
}
#[must_use]
pub fn windows(&self) -> Vec<WindowRecord> {
self.windows.iter().copied().map(WindowRef::owned).collect()
}
#[must_use]
pub fn closed_windows(&self) -> Vec<ClosedWindow> {
self.windows
.iter()
.filter_map(|window| match window {
WindowRef::Closed(window) => Some((*window).clone()),
WindowRef::Open(_) => None,
})
.collect()
}
#[must_use]
pub fn open_windows(&self) -> Vec<OpenWindow> {
self.windows
.iter()
.filter_map(|window| match window {
WindowRef::Closed(_) => None,
WindowRef::Open(window) => Some((*window).clone()),
})
.collect()
}
#[must_use]
pub fn latest(&self) -> Option<WindowRecord> {
self.windows.last().copied().map(WindowRef::owned)
}
pub fn summarize_by_segment(
&self,
name: &str,
) -> Result<Vec<WindowGroupSummary>, SummaryError> {
summarize_by_segment(self.windows(), name)
}
pub fn summarize_by_tag(&self, name: &str) -> Result<Vec<WindowGroupSummary>, SummaryError> {
summarize_by_tag(self.windows(), name)
}
}
#[derive(Clone, Debug, PartialEq)]
pub struct WindowHistoryQuery {
windows: Vec<WindowRecord>,
}
impl WindowHistoryQuery {
#[must_use]
pub fn new(mut windows: Vec<WindowRecord>) -> Self {
sort_window_records(&mut windows);
Self { windows }
}
#[must_use]
pub fn where_window(mut self, window_name: &str) -> Self {
self.windows
.retain(|window| window.window_name() == window_name);
self
}
#[must_use]
pub fn where_key(mut self, key: &str) -> Self {
self.windows.retain(|window| window.key() == key);
self
}
#[must_use]
pub fn where_source(mut self, source: &str) -> Self {
self.windows
.retain(|window| window.source() == Some(source));
self
}
#[must_use]
pub fn where_partition(mut self, partition: &str) -> Self {
self.windows
.retain(|window| window.partition() == Some(partition));
self
}
#[must_use]
pub fn where_segment(mut self, name: &str, value: impl Into<PrimitiveValue>) -> Self {
let value = value.into();
self.windows.retain(|window| {
window
.segments()
.iter()
.any(|segment| segment.name == name && segment.value == value)
});
self
}
#[must_use]
pub fn where_tag(mut self, name: &str, value: impl Into<PrimitiveValue>) -> Self {
let value = value.into();
self.windows.retain(|window| {
window
.tags()
.iter()
.any(|tag| tag.name == name && tag.value == value)
});
self
}
#[must_use]
pub fn closed(mut self) -> Self {
self.windows.retain(WindowRecord::is_closed);
self
}
#[must_use]
pub fn open(mut self) -> Self {
self.windows.retain(|window| !window.is_closed());
self
}
#[must_use]
pub fn windows(&self) -> Vec<WindowRecord> {
self.windows.clone()
}
#[must_use]
pub fn closed_windows(&self) -> Vec<ClosedWindow> {
self.windows
.iter()
.filter_map(|window| match window {
WindowRecord::Closed(window) => Some(window.clone()),
WindowRecord::Open(_) => None,
})
.collect()
}
#[must_use]
pub fn open_windows(&self) -> Vec<OpenWindow> {
self.windows
.iter()
.filter_map(|window| match window {
WindowRecord::Closed(_) => None,
WindowRecord::Open(window) => Some(window.clone()),
})
.collect()
}
#[must_use]
pub fn latest(&self) -> Option<WindowRecord> {
self.windows.last().cloned()
}
pub fn windows_at(
&self,
horizon: TemporalPoint,
) -> Result<Vec<WindowSnapshotRecord>, TemporalRangeError> {
Ok(self.snapshot_at(horizon)?.records)
}
pub fn closed_windows_at(
&self,
horizon: TemporalPoint,
) -> Result<Vec<WindowSnapshotRecord>, TemporalRangeError> {
Ok(self.snapshot_at(horizon)?.query().closed_windows())
}
pub fn open_windows_at(
&self,
horizon: TemporalPoint,
) -> Result<Vec<WindowSnapshotRecord>, TemporalRangeError> {
Ok(self.snapshot_at(horizon)?.query().open_windows())
}
pub fn latest_window_at(
&self,
horizon: TemporalPoint,
) -> Result<Option<WindowSnapshotRecord>, TemporalRangeError> {
Ok(self.snapshot_at(horizon)?.query().latest_window())
}
pub fn summarize_by_segment(
&self,
name: &str,
) -> Result<Vec<WindowGroupSummary>, SummaryError> {
summarize_by_segment(self.windows.clone(), name)
}
pub fn summarize_by_tag(&self, name: &str) -> Result<Vec<WindowGroupSummary>, SummaryError> {
summarize_by_tag(self.windows.clone(), name)
}
fn snapshot_at(
&self,
horizon: TemporalPoint,
) -> Result<WindowHistorySnapshot, TemporalRangeError> {
let mut records = self
.windows
.iter()
.cloned()
.map(|window| snapshot_record(window, horizon.clone()))
.collect::<Result<Vec<_>, _>>()?
.into_iter()
.flatten()
.collect::<Vec<_>>();
records.sort_by(|left, right| compare_window_records(&left.window, &right.window));
Ok(WindowHistorySnapshot { horizon, records })
}
}
impl WindowHistorySnapshot {
#[must_use]
pub fn query(&self) -> WindowSnapshotQuery {
WindowSnapshotQuery::new(self.horizon.clone(), self.records.clone())
}
}
#[derive(Clone, Debug, PartialEq)]
pub struct WindowSnapshotQuery {
horizon: TemporalPoint,
records: Vec<WindowSnapshotRecord>,
}
impl WindowSnapshotQuery {
#[must_use]
pub fn new(horizon: TemporalPoint, mut records: Vec<WindowSnapshotRecord>) -> Self {
records.sort_by(|left, right| compare_window_records(&left.window, &right.window));
Self { horizon, records }
}
#[must_use]
pub fn where_window(mut self, window_name: &str) -> Self {
self.records
.retain(|record| record.window.window_name() == window_name);
self
}
#[must_use]
pub fn where_key(mut self, key: &str) -> Self {
self.records.retain(|record| record.window.key() == key);
self
}
#[must_use]
pub fn where_source(mut self, source: &str) -> Self {
self.records
.retain(|record| record.window.source() == Some(source));
self
}
#[must_use]
pub fn where_partition(mut self, partition: &str) -> Self {
self.records
.retain(|record| record.window.partition() == Some(partition));
self
}
#[must_use]
pub fn where_segment(mut self, name: &str, value: impl Into<PrimitiveValue>) -> Self {
let value = value.into();
self.records.retain(|record| {
record
.window
.segments()
.iter()
.any(|segment| segment.name == name && segment.value == value)
});
self
}
#[must_use]
pub fn where_tag(mut self, name: &str, value: impl Into<PrimitiveValue>) -> Self {
let value = value.into();
self.records.retain(|record| {
record
.window
.tags()
.iter()
.any(|tag| tag.name == name && tag.value == value)
});
self
}
#[must_use]
pub fn windows(&self) -> Vec<WindowSnapshotRecord> {
self.records.clone()
}
#[must_use]
pub fn closed_windows(&self) -> Vec<WindowSnapshotRecord> {
self.records
.iter()
.filter(|record| record.finality == ComparisonFinality::Final)
.cloned()
.collect()
}
#[must_use]
pub fn open_windows(&self) -> Vec<WindowSnapshotRecord> {
self.records
.iter()
.filter(|record| record.finality == ComparisonFinality::Provisional)
.cloned()
.collect()
}
#[must_use]
pub fn latest_window(&self) -> Option<WindowSnapshotRecord> {
self.records.last().cloned()
}
pub fn summarize_by_segment(
&self,
name: &str,
) -> Result<Vec<WindowGroupSummary>, SummaryError> {
summarize_snapshot_records(&self.records, WindowGroupKind::Segment, name)
}
pub fn summarize_by_tag(&self, name: &str) -> Result<Vec<WindowGroupSummary>, SummaryError> {
summarize_snapshot_records(&self.records, WindowGroupKind::Tag, name)
}
}
pub fn summarize_by_segment(
windows: impl IntoIterator<Item = WindowRecord>,
name: &str,
) -> Result<Vec<WindowGroupSummary>, SummaryError> {
summarize_windows(windows, WindowGroupKind::Segment, name)
}
pub fn summarize_by_tag(
windows: impl IntoIterator<Item = WindowRecord>,
name: &str,
) -> Result<Vec<WindowGroupSummary>, SummaryError> {
summarize_windows(windows, WindowGroupKind::Tag, name)
}
#[derive(Clone, Debug)]
struct SummaryAccumulator {
group_kind: WindowGroupKind,
name: String,
value: PrimitiveValue,
record_count: usize,
final_count: usize,
provisional_count: usize,
measured_position_count: usize,
total_position_length: i64,
}
impl SummaryAccumulator {
fn new(group_kind: WindowGroupKind, name: &str, value: PrimitiveValue) -> Self {
Self {
group_kind,
name: name.to_owned(),
value,
record_count: 0,
final_count: 0,
provisional_count: 0,
measured_position_count: 0,
total_position_length: 0,
}
}
fn add_window(&mut self, window: &WindowRecord) {
self.record_count += 1;
match window {
WindowRecord::Closed(closed) => {
self.final_count += 1;
if closed.range.start().axis() == TemporalAxis::ProcessingPosition {
self.measured_position_count += 1;
self.total_position_length += closed.range.magnitude();
}
}
WindowRecord::Open(_) => {
self.provisional_count += 1;
}
}
}
fn add_snapshot(&mut self, record: &WindowSnapshotRecord) {
self.record_count += 1;
match record.finality {
ComparisonFinality::Final => self.final_count += 1,
ComparisonFinality::Provisional
| ComparisonFinality::Revised
| ComparisonFinality::Retracted => self.provisional_count += 1,
}
if record.range.start().axis() == TemporalAxis::ProcessingPosition {
self.measured_position_count += 1;
self.total_position_length += record.range.magnitude();
}
}
fn into_summary(self) -> WindowGroupSummary {
WindowGroupSummary {
group_kind: self.group_kind,
name: self.name,
value: self.value,
record_count: self.record_count,
final_count: self.final_count,
provisional_count: self.provisional_count,
measured_position_count: self.measured_position_count,
total_position_length: self.total_position_length,
}
}
}
fn summarize_windows(
windows: impl IntoIterator<Item = WindowRecord>,
group_kind: WindowGroupKind,
name: &str,
) -> Result<Vec<WindowGroupSummary>, SummaryError> {
validate_summary_name(name)?;
let mut groups = BTreeMap::<String, SummaryAccumulator>::new();
for window in windows {
for value in metadata_values(&window, group_kind, name) {
groups
.entry(primitive_sort_key(&value))
.or_insert_with(|| SummaryAccumulator::new(group_kind, name, value.clone()))
.add_window(&window);
}
}
Ok(groups
.into_values()
.map(SummaryAccumulator::into_summary)
.collect())
}
fn summarize_snapshot_records(
records: &[WindowSnapshotRecord],
group_kind: WindowGroupKind,
name: &str,
) -> Result<Vec<WindowGroupSummary>, SummaryError> {
validate_summary_name(name)?;
let mut groups = BTreeMap::<String, SummaryAccumulator>::new();
for record in records {
for value in metadata_values(&record.window, group_kind, name) {
groups
.entry(primitive_sort_key(&value))
.or_insert_with(|| SummaryAccumulator::new(group_kind, name, value.clone()))
.add_snapshot(record);
}
}
Ok(groups
.into_values()
.map(SummaryAccumulator::into_summary)
.collect())
}
#[derive(Clone, Copy, Debug, Eq, thiserror::Error, PartialEq)]
pub enum SummaryError {
#[error("summary dimension name cannot be empty")]
EmptyName,
}
fn validate_summary_name(name: &str) -> Result<(), SummaryError> {
if name.trim().is_empty() {
return Err(SummaryError::EmptyName);
}
Ok(())
}
fn metadata_values(
window: &WindowRecord,
group_kind: WindowGroupKind,
name: &str,
) -> Vec<PrimitiveValue> {
let mut values = BTreeMap::<String, PrimitiveValue>::new();
match group_kind {
WindowGroupKind::Segment => {
for segment in window.segments() {
if segment.name == name {
let value = segment.value.clone();
values.entry(primitive_sort_key(&value)).or_insert(value);
}
}
}
WindowGroupKind::Tag => {
for tag in window.tags() {
if tag.name == name {
let value = tag.value.clone();
values.entry(primitive_sort_key(&value)).or_insert(value);
}
}
}
}
values.into_values().collect()
}
fn snapshot_record(
window: WindowRecord,
horizon: TemporalPoint,
) -> Result<Option<WindowSnapshotRecord>, TemporalRangeError> {
let start = window.start();
if start.axis() != horizon.axis() || matches!(start.try_cmp(&horizon), Ok(Ordering::Greater)) {
return Ok(None);
}
match window {
WindowRecord::Closed(closed) => {
if matches!(
closed.range.end().try_cmp(&horizon),
Ok(Ordering::Less | Ordering::Equal)
) {
Ok(Some(WindowSnapshotRecord {
range: closed.range.clone(),
window: WindowRecord::Closed(closed),
finality: ComparisonFinality::Final,
}))
} else {
let range = TemporalRange::new(closed.range.start(), horizon)?;
Ok(Some(WindowSnapshotRecord {
window: WindowRecord::Closed(closed),
range,
finality: ComparisonFinality::Provisional,
}))
}
}
WindowRecord::Open(open) => {
let range = TemporalRange::new(open.start.clone(), horizon.clone())?;
Ok(Some(WindowSnapshotRecord {
window: WindowRecord::Open(open),
range,
finality: ComparisonFinality::Provisional,
}))
}
}
}
fn sort_window_records(windows: &mut [WindowRecord]) {
windows.sort_by(compare_window_records);
}
fn compare_window_records(left: &WindowRecord, right: &WindowRecord) -> Ordering {
left.window_name()
.cmp(right.window_name())
.then_with(|| left.key().cmp(right.key()))
.then_with(|| left.source().cmp(&right.source()))
.then_with(|| left.partition().cmp(&right.partition()))
.then_with(|| left.start().magnitude().cmp(&right.start().magnitude()))
.then_with(|| {
left.end()
.map_or(i64::MAX, |point| point.magnitude())
.cmp(&right.end().map_or(i64::MAX, |point| point.magnitude()))
})
.then_with(|| left.id().cmp(right.id()))
}
fn primitive_sort_key(value: &PrimitiveValue) -> String {
match value {
PrimitiveValue::String(value) => format!("string:{value}"),
PrimitiveValue::Integer(value) => format!("integer:{value:020}"),
PrimitiveValue::Float(value) => format!("float:{value:?}"),
PrimitiveValue::Bool(value) => format!("bool:{value}"),
PrimitiveValue::Null => "null:".to_owned(),
}
}
fn same_closed_scope(first: &ClosedWindow, second: &ClosedWindow) -> bool {
first.window_name == second.window_name
&& first.key == second.key
&& first.partition == second.partition
&& first
.range
.start()
.is_compatible_with(&second.range.start())
}
fn closed_windows_overlap(first: &ClosedWindow, second: &ClosedWindow) -> bool {
matches!(
first.range.start().try_cmp(&second.range.end()),
Ok(Ordering::Less)
) && matches!(
second.range.start().try_cmp(&first.range.end()),
Ok(Ordering::Less)
)
}
fn subtract_position_window(segments: &[(i64, i64)], window: &ClosedWindow) -> Vec<(i64, i64)> {
let mut result = Vec::new();
let window_start = window.range.start().magnitude();
let window_end = window.range.end().magnitude();
for (start, end) in segments {
if window_end <= *start || window_start >= *end {
result.push((*start, *end));
continue;
}
if *start < window_start {
result.push((*start, window_start));
}
if window_end < *end {
result.push((window_end, *end));
}
}
result
}
#[derive(Clone, Debug, Default)]
pub struct WindowHistoryFixture {
history: WindowHistory,
next_record_id: u64,
}
impl WindowHistoryFixture {
#[must_use]
pub const fn new() -> Self {
Self {
history: WindowHistory::new(),
next_record_id: 0,
}
}
pub fn closed_window(
mut self,
window_name: impl Into<String>,
key: impl Into<String>,
start_position: i64,
end_position: i64,
configure: impl FnOnce(WindowHistoryFixtureWindow) -> WindowHistoryFixtureWindow,
) -> Result<Self, WindowHistoryFixtureError> {
let metadata = configure(WindowHistoryFixtureWindow::default());
if let Some(error) = metadata.error {
return Err(error.into());
}
let id = self.next_id();
let range = TemporalRange::positions(start_position, end_position)?;
self.history.push_closed(ClosedWindow {
id,
window_name: window_name.into(),
key: key.into(),
range,
known_at: metadata.known_at,
source: metadata.source,
partition: metadata.partition,
segments: metadata.segments,
tags: metadata.tags,
boundary_reason: None,
boundary_changes: Vec::new(),
});
Ok(self)
}
pub fn open_window(
mut self,
window_name: impl Into<String>,
key: impl Into<String>,
start_position: i64,
configure: impl FnOnce(WindowHistoryFixtureWindow) -> WindowHistoryFixtureWindow,
) -> Result<Self, WindowHistoryFixtureError> {
let metadata = configure(WindowHistoryFixtureWindow::default());
if let Some(error) = metadata.error {
return Err(error.into());
}
let id = self.next_id();
self.history.push_open(OpenWindow {
id,
window_name: window_name.into(),
key: key.into(),
start: TemporalPoint::position(start_position),
known_at: metadata.known_at,
source: metadata.source,
partition: metadata.partition,
segments: metadata.segments,
tags: metadata.tags,
});
Ok(self)
}
#[must_use]
pub fn build(self) -> WindowHistory {
self.history
}
fn next_id(&mut self) -> WindowRecordId {
let id = WindowRecordId::generated(format!("window-{:04}", self.next_record_id));
self.next_record_id += 1;
id
}
}
#[derive(Clone, Debug, Default)]
pub struct WindowHistoryFixtureWindow {
known_at: Option<TemporalPoint>,
source: Option<String>,
partition: Option<String>,
segments: Vec<WindowSegment>,
tags: Vec<WindowTag>,
error: Option<WindowMetadataError>,
}
impl WindowHistoryFixtureWindow {
#[must_use]
pub fn source(mut self, source: impl Into<String>) -> Self {
self.source = Some(source.into());
self
}
#[must_use]
pub fn known_at_position(mut self, position: i64) -> Self {
self.known_at = Some(TemporalPoint::position(position));
self
}
#[must_use]
pub fn partition(mut self, partition: impl Into<String>) -> Self {
self.partition = Some(partition.into());
self
}
#[must_use]
pub fn segment(mut self, name: impl Into<String>, value: impl Into<PrimitiveValue>) -> Self {
match WindowSegment::new(name, value) {
Ok(segment) => self.segments.push(segment),
Err(error) if self.error.is_none() => self.error = Some(error),
Err(_) => {}
}
self
}
#[must_use]
pub fn child_segment(
mut self,
name: impl Into<String>,
value: impl Into<PrimitiveValue>,
parent_name: impl Into<String>,
) -> Self {
match WindowSegment::new(name, value).and_then(|segment| segment.with_parent(parent_name)) {
Ok(segment) => self.segments.push(segment),
Err(error) if self.error.is_none() => self.error = Some(error),
Err(_) => {}
}
self
}
#[must_use]
pub fn tag(mut self, name: impl Into<String>, value: impl Into<PrimitiveValue>) -> Self {
match WindowTag::new(name, value) {
Ok(tag) => self.tags.push(tag),
Err(error) if self.error.is_none() => self.error = Some(error),
Err(_) => {}
}
self
}
}
#[cfg(test)]
#[path = "records_tests.rs"]
mod tests;