surreal_sync_core/checkpoint/
phase.rs

1//! Sync phase enumeration for checkpoint tracking.
2
3use serde::{Deserialize, Serialize};
4
5/// Represents different phases of the synchronization process.
6///
7/// Checkpoints are emitted at specific phases during sync operations
8/// to enable:
9/// - Resumable synchronization (start from last known position)
10/// - Incremental sync coordination (use t1/t2 checkpoints)
11#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
12#[serde(rename_all = "snake_case")]
13pub enum SyncPhase {
14    /// Checkpoint emitted before full sync begins (t1).
15    ///
16    /// This checkpoint captures the database state at the moment
17    /// before data migration starts. It is used to:
18    /// - Resume incremental sync from this point
19    /// - Replay changes that occurred during full sync
20    FullSyncStart,
21
22    /// Checkpoint emitted after full sync completes (t2).
23    ///
24    /// This checkpoint captures the database state at the moment
25    /// after data migration completes. It marks the point where
26    /// incremental sync should stop replaying and switch to live mode.
27    FullSyncEnd,
28
29    /// Checkpoint emitted per chunk while a watermark snapshot is in progress.
30    ///
31    /// This captures the current stream position together with per-table
32    /// progress (the last primary key copied and whether the table is done),
33    /// enabling a snapshot to resume mid-way after a crash without re-copying
34    /// already-copied chunks.
35    SnapshotProgress,
36
37    /// Checkpoint emitted when a watermark snapshot completes.
38    ///
39    /// This records the final stream position the snapshot reached. Downstream
40    /// incremental/live processing continues from exactly this position.
41    SnapshotHandoff,
42
43    /// Catch-up progress for binlog sync: stream position plus table coverage.
44    ///
45    /// Updated during incremental sync (position only) and when snapshot batches
46    /// complete (position plus covered tables). [`FullSyncEnd`] remains the
47    /// immutable t2 boundary written once at snapshot handoff completion.
48    CatchUpProgress,
49}
50
51impl SyncPhase {
52    /// Get the string representation of this phase.
53    ///
54    /// Used for:
55    /// - Checkpoint file naming (e.g., `checkpoint_full_sync_start_2024-01-01.json`)
56    /// - Logging and debugging output
57    pub fn as_str(&self) -> &str {
58        match self {
59            SyncPhase::FullSyncStart => "full_sync_start",
60            SyncPhase::FullSyncEnd => "full_sync_end",
61            SyncPhase::SnapshotProgress => "snapshot_progress",
62            SyncPhase::SnapshotHandoff => "snapshot_handoff",
63            SyncPhase::CatchUpProgress => "catch_up_progress",
64        }
65    }
66}
67
68impl std::fmt::Display for SyncPhase {
69    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
70        f.write_str(self.as_str())
71    }
72}
surreal_sync_core/checkpoint/phase.rs

surreal_sync_core/checkpoint/
phase.rs
