hyprstream_metrics/checkpoint/
manager.rs1use crate::checkpoint::state::{Checkpoint, CheckpointMetadata, TableCheckpoint};
4use crate::storage::duckdb::DuckDbBackend;
5use crate::storage::StorageBackend;
6use async_trait::async_trait;
7use chrono::Utc;
8use git2db::{GitManager, RepoId, TrackedRepository};
9
10#[async_trait]
15pub trait RegistryClient: Send + Sync {
16 async fn get_by_name(&self, name: &str) -> Result<Option<TrackedRepository>, RegistryError>;
18
19 async fn register(
21 &self,
22 id: &RepoId,
23 name: Option<&str>,
24 path: &std::path::Path,
25 ) -> Result<(), RegistryError>;
26}
27
28#[derive(Debug, thiserror::Error)]
30pub enum RegistryError {
31 #[error("Registry operation failed: {0}")]
32 Operation(String),
33}
34use std::path::PathBuf;
35use std::sync::Arc;
36use std::time::Duration;
37use tokio::sync::RwLock;
38use tokio::task::JoinHandle;
39use tonic::Status;
40use tracing::{debug, error, info, instrument};
41
42#[derive(Debug, Clone)]
44pub struct CheckpointConfig {
45 pub interval: Duration,
47 pub retention_count: usize,
49 pub checkpoint_on_shutdown: bool,
51 pub base_dir: PathBuf,
53}
54
55impl Default for CheckpointConfig {
56 fn default() -> Self {
57 Self {
58 interval: Duration::from_secs(5 * 60), retention_count: 10,
60 checkpoint_on_shutdown: true,
61 base_dir: PathBuf::from(".checkpoints"),
62 }
63 }
64}
65
66impl CheckpointConfig {
67 pub fn with_interval(mut self, interval: Duration) -> Self {
69 self.interval = interval;
70 self
71 }
72
73 pub fn with_retention(mut self, count: usize) -> Self {
75 self.retention_count = count;
76 self
77 }
78
79 pub fn with_base_dir(mut self, dir: impl Into<PathBuf>) -> Self {
81 self.base_dir = dir.into();
82 self
83 }
84}
85
86pub struct CheckpointManager {
88 config: CheckpointConfig,
90 client: Option<Arc<dyn RegistryClient>>,
92 repo_name: Option<String>,
94 repo_path: PathBuf,
96 checkpoints: RwLock<Vec<Checkpoint>>,
98}
99
100impl CheckpointManager {
101 #[instrument(skip(config), fields(base_dir = ?config.base_dir))]
106 pub async fn new(config: CheckpointConfig) -> Result<Self, Status> {
107 Self::create_internal(config, None, None).await
108 }
109
110 #[instrument(skip(client, config), fields(repo_name = %repo_name, base_dir = ?config.base_dir))]
120 pub async fn new_with_client(
121 client: Arc<dyn RegistryClient>,
122 repo_name: &str,
123 config: CheckpointConfig,
124 ) -> Result<Self, Status> {
125 info!("Initializing CheckpointManager with shared registry");
126
127 let existing = client
129 .get_by_name(repo_name)
130 .await
131 .map_err(|e| Status::internal(format!("Failed to query registry: {e}")))?;
132
133 if let Some(tracked) = existing {
134 let repo_path = PathBuf::from(&tracked.worktree_path);
136 info!(
137 "Using existing registered checkpoint repository at {:?}",
138 repo_path
139 );
140
141 return Ok(Self {
142 config,
143 client: Some(client),
144 repo_name: Some(repo_name.to_owned()),
145 repo_path,
146 checkpoints: RwLock::new(Vec::new()),
147 });
148 }
149
150 let manager =
152 Self::create_internal(config, Some(client.clone()), Some(repo_name.to_owned())).await?;
153
154 let repo_id = RepoId::new();
156 client
157 .register(&repo_id, Some(repo_name), &manager.repo_path)
158 .await
159 .map_err(|e| Status::internal(format!("Failed to register checkpoint repo: {e}")))?;
160
161 info!(
162 "Registered checkpoint repository '{}' in registry",
163 repo_name
164 );
165
166 Ok(manager)
167 }
168
169 async fn create_internal(
171 config: CheckpointConfig,
172 client: Option<Arc<dyn RegistryClient>>,
173 repo_name: Option<String>,
174 ) -> Result<Self, Status> {
175 info!("Initializing CheckpointManager");
176
177 std::fs::create_dir_all(&config.base_dir)
179 .map_err(|e| Status::internal(format!("Failed to create checkpoint directory: {e}")))?;
180
181 let repo_path = config.base_dir.join("repo");
183
184 if !repo_path.join(".git").exists() {
186 std::fs::create_dir_all(&repo_path).map_err(|e| {
187 Status::internal(format!("Failed to create repository directory: {e}"))
188 })?;
189
190 git2::Repository::init(&repo_path).map_err(|e| {
191 Status::internal(format!("Failed to initialize git repository: {e}"))
192 })?;
193
194 info!("Created new checkpoint repository at {:?}", repo_path);
195 } else {
196 info!("Using existing checkpoint repository at {:?}", repo_path);
197 }
198
199 Ok(Self {
200 config,
201 client,
202 repo_name,
203 repo_path,
204 checkpoints: RwLock::new(Vec::new()),
205 })
206 }
207
208 #[instrument(skip(self, storage), fields(checkpoint_name = ?name))]
210 pub async fn create_checkpoint(
211 &self,
212 storage: &DuckDbBackend,
213 name: Option<String>,
214 ) -> Result<Checkpoint, Status> {
215 info!("Creating checkpoint");
216
217 let tables = storage.list_tables().await?;
219 debug!(table_count = tables.len(), "Found tables to checkpoint");
220
221 let tables_dir = self.repo_path.join("tables");
223 std::fs::create_dir_all(&tables_dir)
224 .map_err(|e| Status::internal(format!("Failed to create tables directory: {e}")))?;
225
226 let mut table_checkpoints = Vec::new();
228 for table_name in &tables {
229 if table_name.starts_with("sqlite_") || table_name == "view_metadata" {
231 continue;
232 }
233
234 let parquet_path = tables_dir.join(format!("{table_name}.parquet"));
235 debug!(table = %table_name, path = ?parquet_path, "Exporting table");
236
237 storage.export_to_parquet(table_name, &parquet_path).await?;
238
239 let file_size = std::fs::metadata(&parquet_path)
241 .map(|m| m.len())
242 .unwrap_or(0);
243
244 let row_count = 0u64; table_checkpoints.push(TableCheckpoint::new(
249 table_name.clone(),
250 row_count,
251 file_size,
252 format!("tables/{table_name}.parquet"),
253 ));
254 }
255
256 let mut metadata = CheckpointMetadata::new(table_checkpoints);
258 if let Some(n) = name.clone() {
259 metadata = metadata.with_name(n);
260 }
261 metadata = metadata.with_metadata("created_by", "checkpoint_manager");
262
263 let metadata_path = self.repo_path.join("checkpoint.json");
265 let metadata_json = serde_json::to_string_pretty(&metadata).map_err(|e| {
266 Status::internal(format!("Failed to serialize checkpoint metadata: {e}"))
267 })?;
268 std::fs::write(&metadata_path, metadata_json)
269 .map_err(|e| Status::internal(format!("Failed to write checkpoint metadata: {e}")))?;
270
271 let commit_id = self.commit_checkpoint(&metadata, name.as_deref()).await?;
273
274 let mut final_metadata = metadata;
276 final_metadata.id = commit_id.clone();
277
278 let checkpoint = Checkpoint::new(commit_id, final_metadata);
279
280 {
282 let mut checkpoints = self.checkpoints.write().await;
283 checkpoints.push(checkpoint.clone());
284
285 if self.config.retention_count > 0 && checkpoints.len() > self.config.retention_count {
287 checkpoints.remove(0);
288 }
289 }
290
291 info!(checkpoint_id = %checkpoint.id(), "Checkpoint created successfully");
292 Ok(checkpoint)
293 }
294
295 async fn commit_checkpoint(
297 &self,
298 metadata: &CheckpointMetadata,
299 name: Option<&str>,
300 ) -> Result<String, Status> {
301 let repo_cache = GitManager::global()
303 .get_repository(&self.repo_path)
304 .map_err(|e| Status::internal(format!("Failed to get repository: {e}")))?;
305
306 let repo = repo_cache
307 .open()
308 .map_err(|e| Status::internal(format!("Failed to open repository: {e}")))?;
309
310 let mut index = repo
312 .index()
313 .map_err(|e| Status::internal(format!("Failed to get index: {e}")))?;
314 index
315 .add_all(["*"].iter(), git2::IndexAddOption::DEFAULT, None)
316 .map_err(|e| Status::internal(format!("Failed to stage files: {e}")))?;
317 index
318 .write()
319 .map_err(|e| Status::internal(format!("Failed to write index: {e}")))?;
320
321 let sig = GitManager::global()
322 .create_signature(None, None)
323 .map_err(|e| Status::internal(format!("Failed to create signature: {e}")))?;
324
325 let message = format!(
326 "Checkpoint: {}\n\nTables: {}\nTotal size: {} bytes",
327 name.unwrap_or(&metadata.created_at.to_rfc3339()),
328 metadata.tables.len(),
329 metadata.total_size
330 );
331
332 let mut index = repo
334 .index()
335 .map_err(|e| Status::internal(format!("Failed to get index: {e}")))?;
336 let tree_id = index
337 .write_tree()
338 .map_err(|e| Status::internal(format!("Failed to write tree: {e}")))?;
339 let tree = repo
340 .find_tree(tree_id)
341 .map_err(|e| Status::internal(format!("Failed to find tree: {e}")))?;
342
343 let parent = repo.head().ok().and_then(|h| h.peel_to_commit().ok());
345
346 let commit_id = if let Some(parent) = parent {
348 repo.commit(Some("HEAD"), &sig, &sig, &message, &tree, &[&parent])
349 } else {
350 repo.commit(Some("HEAD"), &sig, &sig, &message, &tree, &[])
351 }
352 .map_err(|e| Status::internal(format!("Failed to create commit: {e}")))?;
353
354 if let Some(tag_name) = name {
356 if let Ok(obj) = repo.find_object(commit_id, None) {
357 let _ = repo.tag_lightweight(tag_name, &obj, true);
358 }
359 }
360
361 Ok(commit_id.to_string())
362 }
363
364 #[instrument(skip(self, storage), fields(checkpoint_id = %checkpoint_id))]
366 pub async fn restore(
367 &self,
368 checkpoint_id: &str,
369 storage: &DuckDbBackend,
370 ) -> Result<(), Status> {
371 info!("Restoring from checkpoint");
372
373 let repo_cache = GitManager::global()
375 .get_repository(&self.repo_path)
376 .map_err(|e| Status::internal(format!("Failed to get repository: {e}")))?;
377
378 let repo = repo_cache
379 .open()
380 .map_err(|e| Status::internal(format!("Failed to open repository: {e}")))?;
381
382 let oid = git2::Oid::from_str(checkpoint_id)
383 .map_err(|e| Status::invalid_argument(format!("Invalid checkpoint ID: {e}")))?;
384
385 let commit = repo
386 .find_commit(oid)
387 .map_err(|e| Status::not_found(format!("Checkpoint not found: {e}")))?;
388
389 repo.reset(commit.as_object(), git2::ResetType::Hard, None)
391 .map_err(|e| Status::internal(format!("Failed to reset to checkpoint: {e}")))?;
392
393 let metadata_path = self.repo_path.join("checkpoint.json");
395 let metadata_json = std::fs::read_to_string(&metadata_path)
396 .map_err(|e| Status::internal(format!("Failed to read checkpoint metadata: {e}")))?;
397 let metadata: CheckpointMetadata = serde_json::from_str(&metadata_json)
398 .map_err(|e| Status::internal(format!("Failed to parse checkpoint metadata: {e}")))?;
399
400 for table in &metadata.tables {
402 let parquet_path = self.repo_path.join(&table.file_path);
403 debug!(table = %table.name, path = ?parquet_path, "Importing table");
404
405 let _ = storage.drop_table(&table.name).await;
407
408 storage
410 .import_from_parquet(&table.name, &parquet_path)
411 .await?;
412 }
413
414 info!("Checkpoint restored successfully");
415 Ok(())
416 }
417
418 pub async fn get_latest_checkpoint(&self) -> Option<Checkpoint> {
420 let checkpoints = self.checkpoints.read().await;
421 checkpoints.last().cloned()
422 }
423
424 pub async fn list_checkpoints(&self) -> Vec<Checkpoint> {
426 self.checkpoints.read().await.clone()
427 }
428
429 pub fn start_background(self: Arc<Self>, storage: Arc<DuckDbBackend>) -> JoinHandle<()> {
431 let interval = self.config.interval;
432
433 tokio::spawn(async move {
434 let mut interval_timer = tokio::time::interval(interval);
435 loop {
436 interval_timer.tick().await;
437
438 let checkpoint_name = format!("auto-{}", Utc::now().format("%Y%m%d-%H%M%S"));
439 match self
440 .create_checkpoint(&storage, Some(checkpoint_name))
441 .await
442 {
443 Ok(checkpoint) => {
444 info!(
445 checkpoint_id = %checkpoint.id(),
446 "Background checkpoint created"
447 );
448 }
449 Err(e) => {
450 error!(error = %e, "Failed to create background checkpoint");
451 }
452 }
453 }
454 })
455 }
456
457 pub fn config(&self) -> &CheckpointConfig {
459 &self.config
460 }
461
462 pub fn registry_client(&self) -> Option<&Arc<dyn RegistryClient>> {
464 self.client.as_ref()
465 }
466
467 pub fn repo_name(&self) -> Option<&str> {
469 self.repo_name.as_deref()
470 }
471
472 pub fn repo_path(&self) -> &PathBuf {
474 &self.repo_path
475 }
476}
477
478impl std::fmt::Debug for CheckpointManager {
479 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
480 f.debug_struct("CheckpointManager")
481 .field("config", &self.config)
482 .field("repo_path", &self.repo_path)
483 .finish()
484 }
485}
486
487#[cfg(test)]
488mod tests {
489 use super::*;
490
491 #[test]
492 fn test_checkpoint_config_defaults() {
493 let config = CheckpointConfig::default();
494 assert_eq!(config.interval, Duration::from_secs(300));
495 assert_eq!(config.retention_count, 10);
496 assert!(config.checkpoint_on_shutdown);
497 }
498
499 #[test]
500 fn test_checkpoint_config_builder() {
501 let config = CheckpointConfig::default()
502 .with_interval(Duration::from_secs(60))
503 .with_retention(5)
504 .with_base_dir("/tmp/checkpoints");
505
506 assert_eq!(config.interval, Duration::from_secs(60));
507 assert_eq!(config.retention_count, 5);
508 assert_eq!(config.base_dir, PathBuf::from("/tmp/checkpoints"));
509 }
510}