Skip to main content

datum_persistence/projection/
cursor.rs

1//! Provider-complete durable projection cursors.
2
3use 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/// Durable identity of a source provider and its cursor semantics.
12///
13/// A manifest is a persisted protocol identifier, not a Rust type name. Once
14/// deployed, changing it makes existing cursors incompatible and must be
15/// handled as an explicit migration. Loading a cursor under a different
16/// manifest is a fatal [`ProjectionError::ProviderManifestMismatch`].
17#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
18pub struct ProviderManifest(String);
19
20impl ProviderManifest {
21    /// Creates a non-blank provider manifest.
22    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    /// Returns the durable manifest text.
34    #[must_use]
35    pub fn as_str(&self) -> &str {
36        &self.0
37    }
38
39    /// Consumes the manifest and returns its durable text.
40    #[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/// Provider-defined stable resume position.
53///
54/// The projection core treats this text as opaque. A source provider owns its
55/// meaning and must keep its encoding stable for the lifetime of the provider
56/// manifest.
57#[derive(Debug, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
58pub struct CursorPosition(String);
59
60impl CursorPosition {
61    /// Creates an opaque provider position.
62    #[must_use]
63    pub fn new(value: impl Into<String>) -> Self {
64        Self(value.into())
65    }
66
67    /// Returns the stable provider position text.
68    #[must_use]
69    pub fn as_str(&self) -> &str {
70        &self.0
71    }
72
73    /// Consumes the position and returns its stable text.
74    #[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/// One event already consumed at a cursor's inclusive resume boundary.
99///
100/// The pair, rather than sequence number alone, is required because sequence
101/// numbers are scoped to a persistence id.
102#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
103pub struct BoundaryEvent {
104    persistence_id: PersistenceId,
105    sequence_nr: SequenceNr,
106}
107
108impl BoundaryEvent {
109    /// Creates a consumed boundary event identity.
110    #[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    /// Returns the persistent entity at the boundary.
119    #[must_use]
120    pub fn persistence_id(&self) -> &PersistenceId {
121        &self.persistence_id
122    }
123
124    /// Returns the entity-local event sequence number.
125    #[must_use]
126    pub const fn sequence_nr(&self) -> SequenceNr {
127        self.sequence_nr
128    }
129}
130
131/// Resume boundary plus every event consumed at that exact position.
132///
133/// Inclusive-resume providers use [`Self::contains`] to drop an event that is
134/// re-emitted at the saved position. Events at later positions remain eligible.
135/// Providers whose positions are complete still persist an empty set, keeping
136/// one cursor shape across backends.
137#[derive(Debug, Clone, PartialEq, Eq)]
138pub struct DeduplicationBoundary {
139    position: CursorPosition,
140    consumed: BTreeSet<BoundaryEvent>,
141}
142
143impl DeduplicationBoundary {
144    /// Creates a boundary with no consumed event identities.
145    #[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    /// Creates a boundary with a complete consumed-event set.
154    #[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    /// Returns the provider-defined boundary position.
166    #[must_use]
167    pub fn position(&self) -> &CursorPosition {
168        &self.position
169    }
170
171    /// Returns consumed identities in stable persistence-id/sequence order.
172    pub fn consumed(&self) -> impl ExactSizeIterator<Item = &BoundaryEvent> {
173        self.consumed.iter()
174    }
175
176    /// Records an event consumed at this exact position.
177    ///
178    /// Returns `true` when the identity was not already present.
179    pub fn record(&mut self, event: BoundaryEvent) -> bool {
180        self.consumed.insert(event)
181    }
182
183    /// Returns whether an event was already consumed at this exact position.
184    #[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/// Provider-tagged, provider-complete durable projection cursor.
192///
193/// The cursor owns the opaque source position and the deduplication set needed
194/// by inclusive-resume providers. [`Self::encode`] and [`Self::decode`] form the
195/// stable store-independent string codec used by durable backends.
196#[derive(Debug, Clone, PartialEq, Eq)]
197pub struct ProjectionCursor {
198    provider_manifest: ProviderManifest,
199    boundary: DeduplicationBoundary,
200}
201
202impl ProjectionCursor {
203    /// Creates a provider-complete cursor.
204    #[must_use]
205    pub fn new(provider_manifest: ProviderManifest, boundary: DeduplicationBoundary) -> Self {
206        Self {
207            provider_manifest,
208            boundary,
209        }
210    }
211
212    /// Creates a cursor with an empty deduplication set.
213    #[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    /// Returns the durable source-provider manifest.
222    #[must_use]
223    pub fn provider_manifest(&self) -> &ProviderManifest {
224        &self.provider_manifest
225    }
226
227    /// Returns the provider-defined resume position.
228    #[must_use]
229    pub fn position(&self) -> &CursorPosition {
230        self.boundary.position()
231    }
232
233    /// Returns the complete inclusive-resume deduplication boundary.
234    #[must_use]
235    pub fn boundary(&self) -> &DeduplicationBoundary {
236        &self.boundary
237    }
238
239    /// Verifies that this cursor belongs to the configured source provider.
240    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    /// Encodes this cursor using Datum's stable versioned string format.
251    ///
252    /// Strings are UTF-8 encoded as lowercase hexadecimal and boundary events
253    /// are ordered by persistence id then sequence number, so equal cursors
254    /// always produce byte-for-byte equal output.
255    #[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    /// Decodes and validates Datum's stable versioned string format.
278    ///
279    /// Malformed, duplicate, out-of-order, or non-canonical data is a fatal
280    /// cursor-codec error and must not enter projection restart backoff.
281    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}