Skip to main content

git_xet_filter/
lib.rs

1//! XET large file storage filter for git2db
2//!
3//! Provides transparent integration with XET repositories via libgit2 filters.
4//!
5//! This crate can be used standalone or as part of git2db.
6//!
7//! # Feature Flags
8//!
9//! - **`xet-storage`** (disabled by default): Enables actual XET CAS integration.
10//!   Without this feature, only configuration types and error handling are available.
11//!
12//! ## Available without `xet-storage`:
13//! - [`XetConfig`] - Configuration for XET endpoints
14//! - [`XetError`], [`XetErrorKind`], [`Result`] - Error types for handling XET failures
15//!
16//! ## Available with `xet-storage`:
17//! - [`initialize()`] - Register the XET filter with libgit2
18//! - [`is_initialized()`] - Check if filter is registered
19//! - Filter storage and runtime modules
20
21pub mod config;
22pub mod error;
23
24#[cfg(feature = "xet-storage")]
25pub mod ffi;
26
27#[cfg(feature = "xet-storage")]
28pub mod filter;
29
30#[cfg(feature = "xet-storage")]
31pub mod storage;
32
33#[cfg(feature = "xet-storage")]
34pub mod runtime;
35
36#[cfg(feature = "xet-storage")]
37pub mod callbacks;
38
39#[cfg(feature = "ssh-transport")]
40pub mod ssh_client;
41
42#[cfg(feature = "gittorrent-transport")]
43pub mod gittorrent_storage;
44
45#[cfg(feature = "xet-storage")]
46use tokio::sync::OnceCell;
47
48use std::cell::{Cell, RefCell};
49use std::sync::Arc;
50
51/// Callback invoked on each smudge (download) operation during checkout.
52///
53/// Arguments: `(files_completed, file_path)`
54/// Called from libgit2 filter callbacks (sync context, inside `spawn_blocking`).
55pub type SmudgeProgressCallback = dyn Fn(usize, &str) + Send + Sync;
56
57thread_local! {
58    /// Per-thread smudge progress hook — set before worktree checkout, cleared after.
59    /// Thread-local ensures concurrent checkouts on different `spawn_blocking` threads
60    /// don't interfere with each other.
61    static SMUDGE_HOOK: RefCell<Option<Arc<SmudgeProgressCallback>>> = const { RefCell::new(None) };
62
63    /// Per-thread counter of smudge operations completed (reset on set_smudge_progress).
64    static SMUDGE_COUNT: Cell<usize> = const { Cell::new(0) };
65}
66
67/// Set a callback to receive per-file smudge progress during checkout.
68/// Resets the internal counter to 0.
69///
70/// Uses thread-local storage, so each `spawn_blocking` thread gets its own
71/// independent hook. Safe for concurrent checkouts.
72pub fn set_smudge_progress(callback: Arc<SmudgeProgressCallback>) {
73    SMUDGE_COUNT.with(|c| c.set(0));
74    SMUDGE_HOOK.with(|h| *h.borrow_mut() = Some(callback));
75}
76
77/// Clear the smudge progress callback for the current thread.
78pub fn clear_smudge_progress() {
79    SMUDGE_HOOK.with(|h| *h.borrow_mut() = None);
80}
81
82/// Called internally after each successful smudge operation.
83pub(crate) fn notify_smudge_progress(path: &str) {
84    SMUDGE_COUNT.with(|c| {
85        let count = c.get() + 1;
86        c.set(count);
87        SMUDGE_HOOK.with(|h| {
88            if let Some(ref cb) = *h.borrow() {
89                cb(count, path);
90            }
91        });
92    });
93}
94
95pub use config::{XetConfig, HUGGINGFACE_XET_ENDPOINT};
96pub use error::{Result, XetError, XetErrorKind};
97
98/// Global filter instance (initialized once)
99#[cfg(feature = "xet-storage")]
100static FILTER_INSTANCE: OnceCell<Arc<filter::XetFilter<filter::Registered>>> =
101    OnceCell::const_new();
102
103/// Config used during initialization (stored for later retrieval)
104#[cfg(feature = "xet-storage")]
105static FILTER_CONFIG: OnceCell<XetConfig> = OnceCell::const_new();
106
107/// Initialize XET filter support
108///
109/// This function is idempotent - calling it multiple times with the same
110/// config is safe and will return success without re-registering.
111///
112/// # Errors
113///
114/// Returns error if:
115/// - XET storage initialization fails
116/// - Filter registration with libgit2 fails
117/// - Called with different config after already initialized
118#[cfg(feature = "xet-storage")]
119pub async fn initialize(config: XetConfig) -> Result<()> {
120    // Check if already initialized with different config
121    if let Some(existing) = FILTER_CONFIG.get() {
122        if existing.endpoint != config.endpoint {
123            tracing::warn!(
124                "XET already initialized with endpoint '{}', ignoring new endpoint '{}'",
125                existing.endpoint,
126                config.endpoint
127            );
128        }
129    } else {
130        // Store config for later retrieval (first call wins)
131        let _ = FILTER_CONFIG.set(config.clone());
132    }
133
134    FILTER_INSTANCE
135        .get_or_try_init(|| async {
136            tracing::info!("Initializing XET filter...");
137
138            // Create unregistered filter
139            let filter = filter::XetFilter::new(config).await?;
140
141            // Register with libgit2 (priority 100, same as git-lfs)
142            let registered = filter.register(100)?;
143
144            tracing::info!("XET filter registered successfully");
145            Ok::<_, XetError>(Arc::new(registered))
146        })
147        .await?;
148
149    Ok(())
150}
151
152/// Get the XET config used during initialization
153///
154/// Returns `None` if the filter hasn't been initialized yet.
155#[cfg(feature = "xet-storage")]
156pub fn get_config() -> Option<XetConfig> {
157    FILTER_CONFIG.get().cloned()
158}
159
160/// Check if XET filter is initialized
161#[cfg(feature = "xet-storage")]
162pub fn is_initialized() -> bool {
163    FILTER_INSTANCE.get().is_some()
164}
165
166/// Get the last XET filter error from this thread
167///
168/// When a git operation fails and XET filter was involved, this function
169/// can provide detailed error information that wouldn't be available through
170/// git2's error handling.
171///
172/// # Example
173/// ```ignore
174/// use git2::Repository;
175/// use git2db::xet_filter;
176///
177/// let repo = Repository::open("path/to/repo")?;
178/// if let Err(e) = repo.checkout_head(None) {
179///     // Git operation failed - check if XET filter has details
180///     if let Some(xet_error) = xet_filter::last_error() {
181///         eprintln!("XET filter error: {:?}", xet_error);
182///         eprintln!("Error kind: {:?}", xet_error.kind());
183///         eprintln!("Message: {}", xet_error.message());
184///     }
185/// }
186/// ```
187///
188/// # Thread-Local Storage
189/// This function uses thread-local storage, so it only returns errors from
190/// git operations performed on the current thread.
191pub fn last_error() -> Option<XetError> {
192    error::get_last_error()
193}
194
195/// Clear the last XET filter error for this thread
196///
197/// This can be useful to prevent stale errors from previous operations
198/// from being mistaken for new errors.
199pub fn clear_last_error() {
200    error::clear_last_error();
201}
202
203#[cfg(all(test, feature = "xet-storage"))]
204mod tests {
205    use super::*;
206
207    #[tokio::test]
208    async fn test_initialize_idempotent() -> std::result::Result<(), XetError> {
209        let config = XetConfig {
210            endpoint: "https://cas.xet.dev".to_owned(),
211            token: Some("test".to_owned()),
212            compression: None,
213        };
214
215        // First call
216        initialize(config.clone()).await?;
217        assert!(is_initialized());
218
219        // Second call (should succeed)
220        initialize(config).await?;
221        Ok(())
222    }
223}