use std::{collections::BTreeSet, fmt};
use crate::{PersistenceId, SequenceNr};
use super::{ProjectionError, ProjectionResult};
const CURSOR_FORMAT_VERSION: &str = "datum-projection-cursor-v1";
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ProviderManifest(String);
impl ProviderManifest {
pub fn new(value: impl Into<String>) -> ProjectionResult<Self> {
let value = value.into();
if value.trim().is_empty() {
return Err(ProjectionError::invalid_config(
"provider_manifest",
"provider manifest must not be blank",
));
}
Ok(Self(value))
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
#[must_use]
pub fn into_inner(self) -> String {
self.0
}
}
impl fmt::Display for ProviderManifest {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(self.as_str())
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct CursorPosition(String);
impl CursorPosition {
#[must_use]
pub fn new(value: impl Into<String>) -> Self {
Self(value.into())
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
#[must_use]
pub fn into_inner(self) -> String {
self.0
}
}
impl fmt::Display for CursorPosition {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(self.as_str())
}
}
impl From<String> for CursorPosition {
fn from(value: String) -> Self {
Self::new(value)
}
}
impl From<&str> for CursorPosition {
fn from(value: &str) -> Self {
Self::new(value)
}
}
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct BoundaryEvent {
persistence_id: PersistenceId,
sequence_nr: SequenceNr,
}
impl BoundaryEvent {
#[must_use]
pub fn new(persistence_id: PersistenceId, sequence_nr: SequenceNr) -> Self {
Self {
persistence_id,
sequence_nr,
}
}
#[must_use]
pub fn persistence_id(&self) -> &PersistenceId {
&self.persistence_id
}
#[must_use]
pub const fn sequence_nr(&self) -> SequenceNr {
self.sequence_nr
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DeduplicationBoundary {
position: CursorPosition,
consumed: BTreeSet<BoundaryEvent>,
}
impl DeduplicationBoundary {
#[must_use]
pub fn new(position: impl Into<CursorPosition>) -> Self {
Self {
position: position.into(),
consumed: BTreeSet::new(),
}
}
#[must_use]
pub fn with_consumed(
position: impl Into<CursorPosition>,
consumed: impl IntoIterator<Item = BoundaryEvent>,
) -> Self {
Self {
position: position.into(),
consumed: consumed.into_iter().collect(),
}
}
#[must_use]
pub fn position(&self) -> &CursorPosition {
&self.position
}
pub fn consumed(&self) -> impl ExactSizeIterator<Item = &BoundaryEvent> {
self.consumed.iter()
}
pub fn record(&mut self, event: BoundaryEvent) -> bool {
self.consumed.insert(event)
}
#[must_use]
pub fn contains(&self, persistence_id: &PersistenceId, sequence_nr: SequenceNr) -> bool {
self.consumed
.contains(&BoundaryEvent::new(persistence_id.clone(), sequence_nr))
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProjectionCursor {
provider_manifest: ProviderManifest,
boundary: DeduplicationBoundary,
}
impl ProjectionCursor {
#[must_use]
pub fn new(provider_manifest: ProviderManifest, boundary: DeduplicationBoundary) -> Self {
Self {
provider_manifest,
boundary,
}
}
#[must_use]
pub fn from_position(
provider_manifest: ProviderManifest,
position: impl Into<CursorPosition>,
) -> Self {
Self::new(provider_manifest, DeduplicationBoundary::new(position))
}
#[must_use]
pub fn provider_manifest(&self) -> &ProviderManifest {
&self.provider_manifest
}
#[must_use]
pub fn position(&self) -> &CursorPosition {
self.boundary.position()
}
#[must_use]
pub fn boundary(&self) -> &DeduplicationBoundary {
&self.boundary
}
pub fn ensure_manifest(&self, expected: &ProviderManifest) -> ProjectionResult<()> {
if &self.provider_manifest != expected {
return Err(ProjectionError::ProviderManifestMismatch {
expected: expected.as_str().to_owned(),
actual: self.provider_manifest.as_str().to_owned(),
});
}
Ok(())
}
#[must_use]
pub fn encode(&self) -> String {
let consumed = self
.boundary
.consumed()
.map(|event| {
format!(
"{}:{}",
encode_hex(event.persistence_id().id()),
event.sequence_nr().as_u64()
)
})
.collect::<Vec<_>>()
.join(",");
format!(
"{CURSOR_FORMAT_VERSION}|{}|{}|{}|{consumed}",
encode_hex(self.provider_manifest.as_str()),
encode_hex(self.position().as_str()),
self.boundary.consumed().len(),
)
}
pub fn decode(encoded: &str) -> ProjectionResult<Self> {
let mut fields = encoded.splitn(5, '|');
let version = required_field(&mut fields, "format version")?;
let manifest = required_field(&mut fields, "provider manifest")?;
let position = required_field(&mut fields, "cursor position")?;
let count = required_field(&mut fields, "boundary count")?;
let consumed = required_field(&mut fields, "boundary events")?;
if version != CURSOR_FORMAT_VERSION {
return Err(codec_error(format!(
"unsupported format version {version:?}"
)));
}
let provider_manifest = ProviderManifest::new(decode_hex(manifest, "provider manifest")?)
.map_err(|error| codec_error(error.to_string()))?;
let position = CursorPosition::new(decode_hex(position, "cursor position")?);
let expected_count = count
.parse::<usize>()
.map_err(|_| codec_error(format!("invalid boundary count {count:?}")))?;
let mut boundary_events = BTreeSet::new();
if !consumed.is_empty() {
for item in consumed.split(',') {
let (persistence_id, sequence_nr) = item
.split_once(':')
.ok_or_else(|| codec_error(format!("invalid boundary event {item:?}")))?;
let persistence_id =
PersistenceId::from_unique(decode_hex(persistence_id, "persistence id")?)
.map_err(|error| codec_error(error.to_string()))?;
let sequence_nr = sequence_nr.parse::<u64>().map_err(|_| {
codec_error(format!("invalid boundary sequence number {sequence_nr:?}"))
})?;
if !boundary_events.insert(BoundaryEvent::new(
persistence_id,
SequenceNr::new(sequence_nr),
)) {
return Err(codec_error("duplicate boundary event"));
}
}
}
if boundary_events.len() != expected_count {
return Err(codec_error(format!(
"boundary count declares {expected_count}, decoded {}",
boundary_events.len()
)));
}
let cursor = Self::new(
provider_manifest,
DeduplicationBoundary::with_consumed(position, boundary_events),
);
if cursor.encode() != encoded {
return Err(codec_error("cursor encoding is not canonical"));
}
Ok(cursor)
}
}
fn required_field<'a>(
fields: &mut impl Iterator<Item = &'a str>,
name: &str,
) -> ProjectionResult<&'a str> {
fields
.next()
.ok_or_else(|| codec_error(format!("missing {name}")))
}
fn encode_hex(value: &str) -> String {
const HEX: &[u8; 16] = b"0123456789abcdef";
let bytes = value.as_bytes();
let mut encoded = String::with_capacity(bytes.len().saturating_mul(2));
for byte in bytes {
encoded.push(char::from(HEX[usize::from(byte >> 4)]));
encoded.push(char::from(HEX[usize::from(byte & 0x0f)]));
}
encoded
}
fn decode_hex(value: &str, name: &str) -> ProjectionResult<String> {
if !value.len().is_multiple_of(2) {
return Err(codec_error(format!("{name} has odd-length hexadecimal")));
}
let mut decoded = Vec::with_capacity(value.len() / 2);
for pair in value.as_bytes().chunks_exact(2) {
let high = hex_nibble(pair[0])
.ok_or_else(|| codec_error(format!("{name} contains non-hexadecimal data")))?;
let low = hex_nibble(pair[1])
.ok_or_else(|| codec_error(format!("{name} contains non-hexadecimal data")))?;
decoded.push((high << 4) | low);
}
String::from_utf8(decoded).map_err(|_| codec_error(format!("{name} is not valid UTF-8")))
}
const fn hex_nibble(byte: u8) -> Option<u8> {
match byte {
b'0'..=b'9' => Some(byte - b'0'),
b'a'..=b'f' => Some(byte - b'a' + 10),
_ => None,
}
}
fn codec_error(reason: impl Into<String>) -> ProjectionError {
ProjectionError::CursorCodec(reason.into())
}
#[cfg(test)]
mod tests {
use super::*;
fn test_manifest() -> ProviderManifest {
ProviderManifest::new("datum-test-provider/timestamp-v1")
.expect("test provider manifest is valid")
}
#[test]
fn stable_codec_round_trips_unicode_and_delimiters() {
let events = [
BoundaryEvent::new(
PersistenceId::from_unique("account|a:b,c|δ")
.expect("test persistence id is valid"),
SequenceNr::new(7),
),
BoundaryEvent::new(
PersistenceId::from_unique("account|z").expect("test persistence id is valid"),
SequenceNr::new(u64::MAX),
),
];
let cursor = ProjectionCursor::new(
test_manifest(),
DeduplicationBoundary::with_consumed("ts|1:2,3/λ", events),
);
let encoded = cursor.encode();
assert_eq!(ProjectionCursor::decode(&encoded).unwrap(), cursor);
assert_eq!(
ProjectionCursor::decode(&encoded).unwrap().encode(),
encoded
);
}
#[test]
fn malformed_and_mismatched_cursors_are_fatal() {
let malformed =
ProjectionCursor::decode("not-a-cursor").expect_err("malformed durable data must fail");
assert!(malformed.is_fatal());
let cursor = ProjectionCursor::from_position(test_manifest(), "42");
let other = ProviderManifest::new("datum-test-provider/sequence-v1").unwrap();
let mismatch = cursor
.ensure_manifest(&other)
.expect_err("provider identity must be checked");
assert!(matches!(
mismatch,
ProjectionError::ProviderManifestMismatch { .. }
));
assert!(mismatch.is_fatal());
}
}