shardline_gc/lib.rs
1#![deny(unsafe_code)]
2#![cfg_attr(
3 test,
4 allow(
5 clippy::unwrap_used,
6 clippy::expect_used,
7 clippy::indexing_slicing,
8 clippy::shadow_unrelated,
9 clippy::let_underscore_must_use,
10 clippy::format_push_string
11 )
12)]
13
14//! Garbage collection for Shardline chunk storage.
15//!
16//! This crate provides local filesystem garbage collection including orphan
17//! chunk discovery, quarantine lifecycle management, and retention window
18//! enforcement.
19//!
20//! # Quick start
21//!
22//! GC is driven by a [`LocalGcOptions`] mode selection and reports back through
23//! [`LocalGcReport`]. The options and report types are pure and safe to build
24//! directly:
25//!
26//! ```
27//! use shardline_gc::{
28//! LocalGcDiagnostics, LocalGcOptions, LocalGcReport, MINIMUM_GC_RETENTION_SECONDS,
29//! };
30//!
31//! // Default options are a no-op dry run: nothing is marked or deleted.
32//! let options = LocalGcOptions::default();
33//! assert_eq!(options.mode_name(), "dry-run");
34//! assert!(!options.mark && !options.sweep);
35//!
36//! // A real cleanup run marks orphans and sweeps expired quarantine entries,
37//! // with a retention window that protects in-flight uploads.
38//! let options = LocalGcOptions::mark_and_sweep(MINIMUM_GC_RETENTION_SECONDS);
39//! assert_eq!(options.mode_name(), "mark-and-sweep");
40//!
41//! // Reports and diagnostics are plain data you can inspect after a run.
42//! let report = LocalGcReport::default();
43//! assert_eq!(report.deleted_chunks, 0);
44//! let diagnostics = LocalGcDiagnostics {
45//! report,
46//! retention_report: Vec::new(),
47//! orphan_inventory: Vec::new(),
48//! };
49//! assert!(diagnostics.orphan_inventory.is_empty());
50//! ```
51//!
52//! To run GC against real storage, drive [`run_gc_with_stores`] with explicit
53//! record, index, and object-store adapters (the `shardline-server` crate wires
54//! this up from its own configuration).
55
56// ---------------------------------------------------------------------------
57// Submodules
58// ---------------------------------------------------------------------------
59
60mod dispatch;
61mod error;
62mod oci_tombstones;
63mod quarantine;
64mod reachability;
65mod remote_delete;
66mod runner;
67mod types;
68
69#[cfg(test)]
70mod native_gc_tests;
71#[cfg(test)]
72mod tests;
73
74// ---------------------------------------------------------------------------
75// Re-exports
76// ---------------------------------------------------------------------------
77
78pub use error::GcError;
79#[doc(hidden)]
80pub use oci_tombstones::OciRecordReclaimer;
81pub use runner::{
82 quarantine_record_path, quarantine_root, run_gc_with_oci_tombstones, run_gc_with_stores,
83 run_local_gc, run_local_gc_diagnostics, run_postgres_gc_with_remote_delete_protection,
84};
85pub use shardline_server_core::server_frontend::{
86 ServerFrontend, ServerFrontend as ServerFrontendKind, ServerFrontendParseError,
87};
88pub use types::DEFAULT_LOCAL_GC_RETENTION_SECONDS;
89pub use types::{
90 GcOrphanInventoryEntry, GcOrphanQuarantineState, GcRetentionReportEntry, LocalGcDiagnostics,
91 LocalGcOptions, LocalGcReport, LocalRecordStore, MINIMUM_GC_RETENTION_SECONDS,
92};