datum_persistence/projection/
cursor.rs1use std::{collections::BTreeSet, fmt};
4
5use crate::{PersistenceId, SequenceNr};
6
7use super::{ProjectionError, ProjectionResult};
8
9const CURSOR_FORMAT_VERSION: &str = "datum-projection-cursor-v1";
10
11#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
18pub struct ProviderManifest(String);
19
20impl ProviderManifest {
21 pub fn new(value: impl Into<String>) -> ProjectionResult<Self> {
23 let value = value.into();
24 if value.trim().is_empty() {
25 return Err(ProjectionError::invalid_config(
26 "provider_manifest",
27 "provider manifest must not be blank",
28 ));
29 }
30 Ok(Self(value))
31 }
32
33 #[must_use]
35 pub fn as_str(&self) -> &str {
36 &self.0
37 }
38
39 #[must_use]
41 pub fn into_inner(self) -> String {
42 self.0
43 }
44}
45
46impl fmt::Display for ProviderManifest {
47 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
48 formatter.write_str(self.as_str())
49 }
50}
51
52#[derive(Debug, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
58pub struct CursorPosition(String);
59
60impl CursorPosition {
61 #[must_use]
63 pub fn new(value: impl Into<String>) -> Self {
64 Self(value.into())
65 }
66
67 #[must_use]
69 pub fn as_str(&self) -> &str {
70 &self.0
71 }
72
73 #[must_use]
75 pub fn into_inner(self) -> String {
76 self.0
77 }
78}
79
80impl fmt::Display for CursorPosition {
81 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
82 formatter.write_str(self.as_str())
83 }
84}
85
86impl From<String> for CursorPosition {
87 fn from(value: String) -> Self {
88 Self::new(value)
89 }
90}
91
92impl From<&str> for CursorPosition {
93 fn from(value: &str) -> Self {
94 Self::new(value)
95 }
96}
97
98#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
103pub struct BoundaryEvent {
104 persistence_id: PersistenceId,
105 sequence_nr: SequenceNr,
106}
107
108impl BoundaryEvent {
109 #[must_use]
111 pub fn new(persistence_id: PersistenceId, sequence_nr: SequenceNr) -> Self {
112 Self {
113 persistence_id,
114 sequence_nr,
115 }
116 }
117
118 #[must_use]
120 pub fn persistence_id(&self) -> &PersistenceId {
121 &self.persistence_id
122 }
123
124 #[must_use]
126 pub const fn sequence_nr(&self) -> SequenceNr {
127 self.sequence_nr
128 }
129}
130
131#[derive(Debug, Clone, PartialEq, Eq)]
138pub struct DeduplicationBoundary {
139 position: CursorPosition,
140 consumed: BTreeSet<BoundaryEvent>,
141}
142
143impl DeduplicationBoundary {
144 #[must_use]
146 pub fn new(position: impl Into<CursorPosition>) -> Self {
147 Self {
148 position: position.into(),
149 consumed: BTreeSet::new(),
150 }
151 }
152
153 #[must_use]
155 pub fn with_consumed(
156 position: impl Into<CursorPosition>,
157 consumed: impl IntoIterator<Item = BoundaryEvent>,
158 ) -> Self {
159 Self {
160 position: position.into(),
161 consumed: consumed.into_iter().collect(),
162 }
163 }
164
165 #[must_use]
167 pub fn position(&self) -> &CursorPosition {
168 &self.position
169 }
170
171 pub fn consumed(&self) -> impl ExactSizeIterator<Item = &BoundaryEvent> {
173 self.consumed.iter()
174 }
175
176 pub fn record(&mut self, event: BoundaryEvent) -> bool {
180 self.consumed.insert(event)
181 }
182
183 #[must_use]
185 pub fn contains(&self, persistence_id: &PersistenceId, sequence_nr: SequenceNr) -> bool {
186 self.consumed
187 .contains(&BoundaryEvent::new(persistence_id.clone(), sequence_nr))
188 }
189}
190
191#[derive(Debug, Clone, PartialEq, Eq)]
197pub struct ProjectionCursor {
198 provider_manifest: ProviderManifest,
199 boundary: DeduplicationBoundary,
200}
201
202impl ProjectionCursor {
203 #[must_use]
205 pub fn new(provider_manifest: ProviderManifest, boundary: DeduplicationBoundary) -> Self {
206 Self {
207 provider_manifest,
208 boundary,
209 }
210 }
211
212 #[must_use]
214 pub fn from_position(
215 provider_manifest: ProviderManifest,
216 position: impl Into<CursorPosition>,
217 ) -> Self {
218 Self::new(provider_manifest, DeduplicationBoundary::new(position))
219 }
220
221 #[must_use]
223 pub fn provider_manifest(&self) -> &ProviderManifest {
224 &self.provider_manifest
225 }
226
227 #[must_use]
229 pub fn position(&self) -> &CursorPosition {
230 self.boundary.position()
231 }
232
233 #[must_use]
235 pub fn boundary(&self) -> &DeduplicationBoundary {
236 &self.boundary
237 }
238
239 pub fn ensure_manifest(&self, expected: &ProviderManifest) -> ProjectionResult<()> {
241 if &self.provider_manifest != expected {
242 return Err(ProjectionError::ProviderManifestMismatch {
243 expected: expected.as_str().to_owned(),
244 actual: self.provider_manifest.as_str().to_owned(),
245 });
246 }
247 Ok(())
248 }
249
250 #[must_use]
256 pub fn encode(&self) -> String {
257 let consumed = self
258 .boundary
259 .consumed()
260 .map(|event| {
261 format!(
262 "{}:{}",
263 encode_hex(event.persistence_id().id()),
264 event.sequence_nr().as_u64()
265 )
266 })
267 .collect::<Vec<_>>()
268 .join(",");
269 format!(
270 "{CURSOR_FORMAT_VERSION}|{}|{}|{}|{consumed}",
271 encode_hex(self.provider_manifest.as_str()),
272 encode_hex(self.position().as_str()),
273 self.boundary.consumed().len(),
274 )
275 }
276
277 pub fn decode(encoded: &str) -> ProjectionResult<Self> {
282 let mut fields = encoded.splitn(5, '|');
283 let version = required_field(&mut fields, "format version")?;
284 let manifest = required_field(&mut fields, "provider manifest")?;
285 let position = required_field(&mut fields, "cursor position")?;
286 let count = required_field(&mut fields, "boundary count")?;
287 let consumed = required_field(&mut fields, "boundary events")?;
288
289 if version != CURSOR_FORMAT_VERSION {
290 return Err(codec_error(format!(
291 "unsupported format version {version:?}"
292 )));
293 }
294
295 let provider_manifest = ProviderManifest::new(decode_hex(manifest, "provider manifest")?)
296 .map_err(|error| codec_error(error.to_string()))?;
297 let position = CursorPosition::new(decode_hex(position, "cursor position")?);
298 let expected_count = count
299 .parse::<usize>()
300 .map_err(|_| codec_error(format!("invalid boundary count {count:?}")))?;
301
302 let mut boundary_events = BTreeSet::new();
303 if !consumed.is_empty() {
304 for item in consumed.split(',') {
305 let (persistence_id, sequence_nr) = item
306 .split_once(':')
307 .ok_or_else(|| codec_error(format!("invalid boundary event {item:?}")))?;
308 let persistence_id =
309 PersistenceId::from_unique(decode_hex(persistence_id, "persistence id")?)
310 .map_err(|error| codec_error(error.to_string()))?;
311 let sequence_nr = sequence_nr.parse::<u64>().map_err(|_| {
312 codec_error(format!("invalid boundary sequence number {sequence_nr:?}"))
313 })?;
314 if !boundary_events.insert(BoundaryEvent::new(
315 persistence_id,
316 SequenceNr::new(sequence_nr),
317 )) {
318 return Err(codec_error("duplicate boundary event"));
319 }
320 }
321 }
322
323 if boundary_events.len() != expected_count {
324 return Err(codec_error(format!(
325 "boundary count declares {expected_count}, decoded {}",
326 boundary_events.len()
327 )));
328 }
329
330 let cursor = Self::new(
331 provider_manifest,
332 DeduplicationBoundary::with_consumed(position, boundary_events),
333 );
334 if cursor.encode() != encoded {
335 return Err(codec_error("cursor encoding is not canonical"));
336 }
337 Ok(cursor)
338 }
339}
340
341fn required_field<'a>(
342 fields: &mut impl Iterator<Item = &'a str>,
343 name: &str,
344) -> ProjectionResult<&'a str> {
345 fields
346 .next()
347 .ok_or_else(|| codec_error(format!("missing {name}")))
348}
349
350fn encode_hex(value: &str) -> String {
351 const HEX: &[u8; 16] = b"0123456789abcdef";
352 let bytes = value.as_bytes();
353 let mut encoded = String::with_capacity(bytes.len().saturating_mul(2));
354 for byte in bytes {
355 encoded.push(char::from(HEX[usize::from(byte >> 4)]));
356 encoded.push(char::from(HEX[usize::from(byte & 0x0f)]));
357 }
358 encoded
359}
360
361fn decode_hex(value: &str, name: &str) -> ProjectionResult<String> {
362 if !value.len().is_multiple_of(2) {
363 return Err(codec_error(format!("{name} has odd-length hexadecimal")));
364 }
365 let mut decoded = Vec::with_capacity(value.len() / 2);
366 for pair in value.as_bytes().chunks_exact(2) {
367 let high = hex_nibble(pair[0])
368 .ok_or_else(|| codec_error(format!("{name} contains non-hexadecimal data")))?;
369 let low = hex_nibble(pair[1])
370 .ok_or_else(|| codec_error(format!("{name} contains non-hexadecimal data")))?;
371 decoded.push((high << 4) | low);
372 }
373 String::from_utf8(decoded).map_err(|_| codec_error(format!("{name} is not valid UTF-8")))
374}
375
376const fn hex_nibble(byte: u8) -> Option<u8> {
377 match byte {
378 b'0'..=b'9' => Some(byte - b'0'),
379 b'a'..=b'f' => Some(byte - b'a' + 10),
380 _ => None,
381 }
382}
383
384fn codec_error(reason: impl Into<String>) -> ProjectionError {
385 ProjectionError::CursorCodec(reason.into())
386}
387
388#[cfg(test)]
389mod tests {
390 use super::*;
391
392 fn test_manifest() -> ProviderManifest {
393 ProviderManifest::new("datum-test-provider/timestamp-v1")
394 .expect("test provider manifest is valid")
395 }
396
397 #[test]
398 fn stable_codec_round_trips_unicode_and_delimiters() {
399 let events = [
400 BoundaryEvent::new(
401 PersistenceId::from_unique("account|a:b,c|δ")
402 .expect("test persistence id is valid"),
403 SequenceNr::new(7),
404 ),
405 BoundaryEvent::new(
406 PersistenceId::from_unique("account|z").expect("test persistence id is valid"),
407 SequenceNr::new(u64::MAX),
408 ),
409 ];
410 let cursor = ProjectionCursor::new(
411 test_manifest(),
412 DeduplicationBoundary::with_consumed("ts|1:2,3/λ", events),
413 );
414 let encoded = cursor.encode();
415 assert_eq!(ProjectionCursor::decode(&encoded).unwrap(), cursor);
416 assert_eq!(
417 ProjectionCursor::decode(&encoded).unwrap().encode(),
418 encoded
419 );
420 }
421
422 #[test]
423 fn malformed_and_mismatched_cursors_are_fatal() {
424 let malformed =
425 ProjectionCursor::decode("not-a-cursor").expect_err("malformed durable data must fail");
426 assert!(malformed.is_fatal());
427
428 let cursor = ProjectionCursor::from_position(test_manifest(), "42");
429 let other = ProviderManifest::new("datum-test-provider/sequence-v1").unwrap();
430 let mismatch = cursor
431 .ensure_manifest(&other)
432 .expect_err("provider identity must be checked");
433 assert!(matches!(
434 mismatch,
435 ProjectionError::ProviderManifestMismatch { .. }
436 ));
437 assert!(mismatch.is_fatal());
438 }
439}