Skip to main content

git_xet_filter/
filter.rs

1//! XET filter implementation with type state pattern
2
3use std::ffi::{CStr, CString};
4
5#[cfg(feature = "xet-storage")]
6use std::marker::PhantomData;
7
8#[cfg(feature = "xet-storage")]
9use std::pin::Pin;
10
11#[cfg(feature = "xet-storage")]
12use std::sync::Arc;
13
14#[cfg(feature = "xet-storage")]
15use libc::c_char;
16
17#[cfg(feature = "xet-storage")]
18use crate::ffi::GitFilter;
19
20#[cfg(feature = "xet-storage")]
21use crate::storage::{StorageBackend, XetStorage};
22
23#[cfg(feature = "xet-storage")]
24use crate::runtime::XetRuntime;
25
26#[cfg(feature = "xet-storage")]
27use crate::error::{Result, XetError, XetErrorKind};
28
29// Type state markers
30#[cfg(feature = "xet-storage")]
31pub struct Unregistered;
32
33#[cfg(feature = "xet-storage")]
34pub struct Registered;
35
36/// XET filter with type state
37#[cfg(feature = "xet-storage")]
38pub struct XetFilter<State = Unregistered> {
39    inner: Pin<Box<GitFilter>>,
40    payload: Option<Box<XetFilterPayload>>,
41    name: String,
42    attributes_cstr: Option<CString>,
43    _state: PhantomData<State>,
44}
45
46/// Filter payload stored in libgit2's filter->payload field
47#[cfg(feature = "xet-storage")]
48#[derive(Clone)]
49pub struct XetFilterPayload {
50    pub storage: Arc<dyn StorageBackend>,
51    pub runtime: Arc<XetRuntime>,
52}
53
54#[cfg(feature = "xet-storage")]
55impl XetFilter<Unregistered> {
56    /// Create a new unregistered filter
57    pub async fn new(config: crate::config::XetConfig) -> Result<Self> {
58        // Create runtime in a separate thread to avoid nested runtime errors
59        // We use std::thread::spawn instead of tokio::spawn_blocking because
60        // tokio's blocking thread pool has access to the runtime handle
61        let (runtime, storage) = std::thread::spawn(move || {
62            let runtime = XetRuntime::new()?;
63            let storage = runtime.block_on_unchecked(async { XetStorage::new(&config).await })?;
64            Ok::<_, XetError>((
65                Arc::new(runtime),
66                Arc::new(storage) as Arc<dyn StorageBackend>,
67            ))
68        })
69        .join()
70        .map_err(|e| {
71            XetError::new(
72                XetErrorKind::RuntimeError,
73                format!("Thread join error: {e:?}"),
74            )
75        })??;
76
77        // Create payload
78        let payload = Box::new(XetFilterPayload { storage, runtime });
79
80        // Creating a CString for attributes
81        // Format: "filter=xet" matches .gitattributes entries like "*.safetensors filter=xet"
82        // SAFETY: "filter=xet" is a static literal with no null bytes
83        let attributes_cstr = CString::new("filter=xet")
84            .map_err(|_| XetError::new(XetErrorKind::RuntimeError, "Invalid attributes string"))?;
85        let attributes_ptr = attributes_cstr.as_ptr() as *const c_char;
86
87        // Create filter structure
88        let filter = Box::pin(GitFilter {
89            version: crate::ffi::GIT_FILTER_VERSION,
90            attributes: attributes_ptr,
91            initialize: Some(crate::callbacks::xet_filter_initialize),
92            shutdown: Some(crate::callbacks::xet_filter_shutdown),
93            check: Some(crate::callbacks::xet_filter_check),
94            reserved: std::ptr::null_mut(),
95            stream: Some(crate::callbacks::xet_filter_stream),
96            cleanup: Some(crate::callbacks::xet_filter_cleanup),
97        });
98
99        Ok(Self {
100            inner: filter,
101            payload: Some(payload),
102            name: "xet".to_owned(),
103            attributes_cstr: Some(attributes_cstr),
104            _state: PhantomData,
105        })
106    }
107
108    /// Register this filter with libgit2
109    ///
110    /// Transitions to Registered state on success
111    pub fn register(mut self, priority: i32) -> Result<XetFilter<Registered>> {
112        // Ensure libgit2 is fully initialized
113        // Calling any git2 function triggers initialization
114        unsafe { git2::opts::set_mwindow_size(crate::ffi::LIBGIT2_MWINDOW_SIZE).ok() };
115
116        let name_cstr = CString::new(self.name.as_str())
117            .map_err(|_| XetError::new(XetErrorKind::RuntimeError, "Invalid filter name"))?;
118
119        // SAFETY: We're passing a stable pointer to a Pin<Box<GitFilter>>
120        // which will not move. The payload is also boxed and won't move.
121        unsafe {
122            // Try to unregister first in case it's already registered
123            let unregister_result = crate::ffi::git_filter_unregister(name_cstr.as_ptr());
124            if unregister_result == 0 {
125                tracing::debug!(
126                    "Unregistered existing '{}' filter before re-registering",
127                    self.name
128                );
129            }
130
131            let filter_ptr = Pin::as_mut(&mut self.inner).get_unchecked_mut() as *mut GitFilter;
132
133            // Initialize the filter structure with libgit2's expected defaults
134            let init_result =
135                crate::ffi::git_filter_init(filter_ptr, crate::ffi::GIT_FILTER_VERSION);
136            if init_result < 0 {
137                tracing::warn!(
138                    "git_filter_init returned {} (continuing anyway)",
139                    init_result
140                );
141            }
142
143            // Restore our callbacks after git_filter_init (it may have cleared them)
144            (*filter_ptr).attributes = self
145                .attributes_cstr
146                .as_ref()
147                .ok_or_else(|| {
148                    XetError::new(XetErrorKind::RuntimeError, "attributes_cstr not set")
149                })?
150                .as_ptr();
151            (*filter_ptr).initialize = Some(crate::callbacks::xet_filter_initialize);
152            (*filter_ptr).shutdown = Some(crate::callbacks::xet_filter_shutdown);
153            (*filter_ptr).check = Some(crate::callbacks::xet_filter_check);
154            (*filter_ptr).stream = Some(crate::callbacks::xet_filter_stream);
155            (*filter_ptr).cleanup = Some(crate::callbacks::xet_filter_cleanup);
156
157            // Store payload in global registry using filter instance pointer
158            // Cast to OpaqueGitFilter for the registry
159            let payload = self
160                .payload
161                .take()
162                .ok_or_else(|| XetError::new(XetErrorKind::RuntimeError, "payload not set"))?;
163            crate::callbacks::register_payload(
164                filter_ptr as *const crate::ffi::OpaqueGitFilter,
165                *payload,
166            );
167
168            let result = crate::ffi::git_filter_register(name_cstr.as_ptr(), filter_ptr, priority);
169
170            if result < 0 {
171                // Get detailed error from libgit2
172                let git_error = git2::Error::last_error(result);
173
174                // Check if it's GIT_EEXISTS (-4) which means filter already registered
175                // In that case, we'll consider it a success
176                const GIT_EEXISTS: i32 = -4;
177                if result == GIT_EEXISTS {
178                    tracing::warn!("XET filter was already registered, continuing anyway");
179                    // Don't clean up payload - keep it registered
180                } else {
181                    // Clean up payload on other failures
182                    let _ = crate::callbacks::unregister_payload(
183                        filter_ptr as *const crate::ffi::OpaqueGitFilter,
184                    );
185
186                    // Log for debugging
187                    tracing::error!(
188                        "git_filter_register failed: result={}, error={:?}, version={}, attributes={:?}",
189                        result,
190                        git_error,
191                        (*filter_ptr).version,
192                        CStr::from_ptr((*filter_ptr).attributes)
193                    );
194
195                    return Err(XetError::new(
196                        XetErrorKind::RuntimeError,
197                        format!("git_filter_register failed (code {result}): {git_error:?}"),
198                    ));
199                }
200            }
201        }
202
203        // Transition to Registered state
204        Ok(XetFilter {
205            inner: self.inner,
206            payload: None, // Ownership transferred to global registry
207            name: self.name,
208            attributes_cstr: self.attributes_cstr,
209            _state: PhantomData,
210        })
211    }
212}
213
214#[cfg(feature = "xet-storage")]
215impl XetFilter<Registered> {
216    /// Unregister this filter
217    ///
218    /// Transitions back to Unregistered state
219    pub fn unregister(mut self) -> Result<XetFilter<Unregistered>> {
220        let name_cstr = CString::new(self.name.as_str())
221            .map_err(|_| XetError::new(XetErrorKind::RuntimeError, "Invalid filter name"))?;
222
223        unsafe {
224            let filter_ptr = Pin::as_mut(&mut self.inner).get_unchecked_mut() as *mut GitFilter;
225
226            let result = crate::ffi::git_filter_unregister(name_cstr.as_ptr());
227
228            if result < 0 {
229                return Err(XetError::new(
230                    XetErrorKind::RuntimeError,
231                    "git_filter_unregister failed",
232                ));
233            }
234
235            // Retrieve payload from global registry using filter instance pointer
236            // Cast to OpaqueGitFilter for the registry
237            let payload = crate::callbacks::unregister_payload(
238                filter_ptr as *const crate::ffi::OpaqueGitFilter,
239            )
240            .ok_or_else(|| {
241                XetError::new(
242                    XetErrorKind::RuntimeError,
243                    "Payload not found in registry - filter may have been double-unregistered",
244                )
245            })?;
246
247            // Convert Arc back to Box for ownership transfer
248            let payload_box = Box::new((*payload).clone());
249
250            Ok(XetFilter {
251                inner: self.inner,
252                payload: Some(payload_box),
253                name: self.name,
254                attributes_cstr: self.attributes_cstr,
255                _state: PhantomData,
256            })
257        }
258    }
259}
260
261// Safety: Filter can be sent across threads when unregistered
262#[cfg(feature = "xet-storage")]
263unsafe impl Send for XetFilter<Unregistered> {}
264
265#[cfg(feature = "xet-storage")]
266unsafe impl Sync for XetFilter<Unregistered> {}
267
268// Safety: Registered filter is stored in static and never accessed directly
269// across threads. The actual filter operations are handled by libgit2's C API.
270#[cfg(feature = "xet-storage")]
271unsafe impl Send for XetFilter<Registered> {}
272
273#[cfg(feature = "xet-storage")]
274unsafe impl Sync for XetFilter<Registered> {}
275
276// Note: No Drop implementation for XetFilter<Registered>
277//
278// We intentionally do NOT implement Drop for the Registered state because:
279//
280// 1. **C Library Integration Safety**: libgit2 may still have references to the
281//    filter structure. Auto-unregistering on drop could cause use-after-free.
282//
283// 2. **Explicit Lifecycle**: Users must explicitly call `unregister()` to get back
284//    the Unregistered state. This makes the lifecycle predictable and intentional.
285//
286// 3. **Global Registration**: The filter is registered globally with libgit2, not
287//    scoped to this Rust object. Automatic cleanup on drop would be surprising.
288//
289// 4. **Payload Cleanup**: The payload remains in PAYLOAD_REGISTRY until explicit
290//    unregister. If the XetFilter is dropped without unregister, the payload leaks
291//    (intentionally) rather than causing a crash.
292//
293// Users should follow this pattern:
294// ```rust
295// let filter = XetFilter::new(config).await?;
296// let registered = filter.register(100)?;
297// // ... use filter ...
298// let unregistered = registered.unregister()?; // Explicit cleanup
299// ```