feldera_types/
checkpoint.rs

1use std::time::Duration;
2
3use chrono::{DateTime, Utc};
4use serde::{Deserialize, Serialize};
5use utoipa::ToSchema;
6use uuid::Uuid;
7
8use crate::suspend::TemporarySuspendError;
9
10/// Checkpoint status returned by the `/checkpoint_status` endpoint.
11#[derive(Clone, Debug, Default, Serialize, Deserialize, ToSchema)]
12pub struct CheckpointStatus {
13    /// Most recently successful checkpoint.
14    pub success: Option<u64>,
15
16    /// Most recently failed checkpoint, and the associated error.
17    ///
18    /// This tracks transient checkpoint failures (e.g. I/O errors during
19    /// writing).  A subsequent successful checkpoint will not clear this
20    /// field — it always reflects the *last* failure that occurred.
21    pub failure: Option<CheckpointFailure>,
22}
23
24/// Current checkpoint activity state.
25#[derive(Clone, Debug, Default, Serialize, Deserialize, ToSchema)]
26#[serde(tag = "status", rename_all = "snake_case")]
27pub enum CheckpointActivity {
28    /// No checkpoint is pending or in progress.
29    #[default]
30    Idle,
31
32    /// A checkpoint has been requested but is delayed for temporary reasons
33    /// (e.g. replaying, bootstrapping, transaction in progress, or input
34    /// endpoint barriers that require the coordinator to run steps).
35    Delayed {
36        /// Why the checkpoint cannot proceed yet.
37        reasons: Vec<TemporarySuspendError>,
38        /// When the delay started (serialized as ISO 8601).
39        delayed_since: DateTime<Utc>,
40    },
41
42    /// A checkpoint is currently being written to storage.
43    InProgress {
44        /// When the checkpoint write started (serialized as ISO 8601).
45        started_at: DateTime<Utc>,
46    },
47}
48
49/// Information about a failed checkpoint.
50#[derive(Clone, Debug, Default, Serialize, Deserialize, ToSchema)]
51pub struct CheckpointFailure {
52    /// Sequence number of the failed checkpoint.
53    pub sequence_number: u64,
54
55    /// Error message associated with the failure.
56    pub error: String,
57
58    /// When the failure occurred (serialized as ISO 8601).
59    pub failed_at: DateTime<Utc>,
60}
61
62/// Response to a checkpoint request.
63#[derive(Clone, Debug, Default, Serialize, Deserialize, ToSchema)]
64pub struct CheckpointResponse {
65    pub checkpoint_sequence_number: u64,
66}
67
68impl CheckpointResponse {
69    pub fn new(checkpoint_sequence_number: u64) -> Self {
70        Self {
71            checkpoint_sequence_number,
72        }
73    }
74}
75
76/// Response to a sync checkpoint request.
77#[derive(Clone, Debug, Default, Serialize, Deserialize, ToSchema)]
78pub struct CheckpointSyncResponse {
79    pub checkpoint_uuid: Uuid,
80}
81
82impl CheckpointSyncResponse {
83    pub fn new(checkpoint_uuid: Uuid) -> Self {
84        Self { checkpoint_uuid }
85    }
86}
87
88/// Checkpoint status returned by the `/checkpoint/sync_status` endpoint.
89#[derive(Clone, Debug, Default, Serialize, Deserialize, ToSchema)]
90pub struct CheckpointSyncStatus {
91    /// Most recently successful checkpoint sync.
92    pub success: Option<Uuid>,
93
94    /// Most recently failed checkpoint sync, and the associated error.
95    pub failure: Option<CheckpointSyncFailure>,
96
97    /// Most recently successful automated periodic checkpoint sync.
98    pub periodic: Option<Uuid>,
99}
100
101/// Information about a failed checkpoint sync.
102#[derive(Clone, Debug, Default, Serialize, Deserialize, ToSchema)]
103pub struct CheckpointSyncFailure {
104    /// UUID of the failed checkpoint.
105    pub uuid: Uuid,
106
107    /// Error message associated with the failure.
108    pub error: String,
109}
110
111/// Holds meta-data about a checkpoint that was taken for persistent storage
112/// and recovery of a circuit's state.
113#[derive(Debug, Clone, Default, Serialize, Deserialize, ToSchema, PartialEq, Eq)]
114pub struct CheckpointMetadata {
115    /// A unique identifier for the given checkpoint.
116    ///
117    /// This is used to identify the checkpoint in the file-system hierarchy.
118    pub uuid: Uuid,
119    /// An optional name for the checkpoint.
120    pub identifier: Option<String>,
121    /// Fingerprint of the circuit at the time of the checkpoint.
122    pub fingerprint: u64,
123    /// Total size of the checkpoint files in bytes.
124    pub size: Option<u64>,
125    /// Total number of steps made.
126    pub steps: Option<u64>,
127    /// Total number of records processed.
128    pub processed_records: Option<u64>,
129}
130
131/// Format of `pspine-batches-*.dat` in storage.
132///
133/// These files exist to be a simple format for higher-level code and outside
134/// tools to parse.  The spine itself writes them for that purpose, but it does
135/// not read them.
136#[derive(Debug, Serialize, Deserialize)]
137pub struct PSpineBatches {
138    pub files: Vec<String>,
139}
140
141#[derive(Debug)]
142pub struct CheckpointSyncMetrics {
143    pub duration: Duration,
144    pub speed: u64,
145    pub bytes: u64,
146}
feldera_types/checkpoint.rs

feldera_types/
checkpoint.rs
