Skip to main content

git_xet_filter/
callbacks.rs

1//! C callback implementations for libgit2 filter
2//!
3//! Implements a streaming filter using git_writestream.
4//! Data flows: source -> our writestream -> process -> next writestream
5
6#[cfg(feature = "xet-storage")]
7use dashmap::DashMap;
8
9#[cfg(feature = "xet-storage")]
10use once_cell::sync::Lazy;
11
12#[cfg(feature = "xet-storage")]
13use std::sync::Arc;
14
15#[cfg(feature = "xet-storage")]
16use std::ffi::CStr;
17
18#[cfg(feature = "xet-storage")]
19use libc::{c_char, c_int, size_t};
20
21#[cfg(feature = "xet-storage")]
22use crate::ffi::*;
23
24#[cfg(feature = "xet-storage")]
25use crate::filter::XetFilterPayload;
26
27#[cfg(feature = "xet-storage")]
28use crate::error::{XetError, XetErrorKind};
29
30/// Global payload registry
31///
32/// Maps filter instance pointer -> payload. Used because libgit2 doesn't provide
33/// a way to pass user data to all callbacks. Using instance address instead of
34/// name allows multiple filter instances with different configurations.
35#[cfg(feature = "xet-storage")]
36pub(crate) static PAYLOAD_REGISTRY: Lazy<DashMap<usize, Arc<XetFilterPayload>>> =
37    Lazy::new(DashMap::new);
38
39/// Register payload for a filter instance
40#[cfg(feature = "xet-storage")]
41pub(crate) fn register_payload(filter_ptr: *const OpaqueGitFilter, payload: XetFilterPayload) {
42    let key = filter_ptr as usize;
43    PAYLOAD_REGISTRY.insert(key, Arc::new(payload));
44    tracing::debug!("Registered payload for filter instance {:x}", key);
45}
46
47/// Unregister and return payload
48///
49/// Returns None if the payload was not found (e.g., double-unregister or corrupted registry)
50#[cfg(feature = "xet-storage")]
51pub(crate) fn unregister_payload(
52    filter_ptr: *const OpaqueGitFilter,
53) -> Option<Arc<XetFilterPayload>> {
54    let key = filter_ptr as usize;
55    tracing::debug!("Unregistering payload for filter instance {:x}", key);
56    PAYLOAD_REGISTRY.remove(&key).map(|(_, p)| p)
57}
58
59/// Get payload by filter instance
60#[cfg(feature = "xet-storage")]
61fn get_payload(filter_ptr: *const OpaqueGitFilter) -> Option<Arc<XetFilterPayload>> {
62    let key = filter_ptr as usize;
63    PAYLOAD_REGISTRY
64        .get(&key)
65        .map(|entry| entry.value().clone())
66}
67
68/// Initialize callback (called once when filter is first used)
69#[cfg(feature = "xet-storage")]
70pub extern "C" fn xet_filter_initialize(_filter: *mut OpaqueGitFilter) -> c_int {
71    tracing::debug!("XET filter initialized");
72    0
73}
74
75/// Shutdown callback (called when filter is unregistered)
76#[cfg(feature = "xet-storage")]
77pub extern "C" fn xet_filter_shutdown(_filter: *mut OpaqueGitFilter) {
78    tracing::debug!("XET filter shutdown");
79}
80
81/// Check callback (determines if filter should apply)
82///
83/// # Safety
84/// This function is called by libgit2 with valid pointers. The `source` pointer
85/// must be valid for the duration of this call. This is guaranteed by libgit2's
86/// callback contract. The raw pointer dereferences are safe within this context.
87#[allow(clippy::not_unsafe_ptr_arg_deref)]
88#[cfg(feature = "xet-storage")]
89pub extern "C" fn xet_filter_check(
90    _filter: *mut OpaqueGitFilter,
91    _payload_out: *mut *mut libc::c_void,
92    source: *const OpaqueGitFilterSource,
93    _attr_values: *const *const libc::c_char,
94) -> c_int {
95    // SAFETY: libgit2 guarantees source is valid for this callback
96    let mode = unsafe { git_filter_source_mode(source) };
97
98    // CRITICAL: During clone/checkout, libgit2 should ONLY call SMUDGE (ODB → workdir)
99    // NEVER CLEAN (workdir → ODB). If CLEAN is being called during checkout, something
100    // is wrong with how libgit2 is invoking the filter.
101    //
102    // Refuse to CLEAN during checkout to prevent uploading files during clone.
103    if mode == GIT_FILTER_CLEAN {
104        // Check if this is a checkout operation (TO_WORKDIR flag)
105        // SAFETY: libgit2 guarantees source is valid for this callback
106        let flags = unsafe { git_filter_source_flags(source) };
107
108        if (flags & GIT_FILTER_TO_WORKTREE) != 0 {
109            tracing::warn!(
110                "XET filter: Refusing CLEAN during checkout (this indicates a libgit2 bug)"
111            );
112            // Return GIT_PASSTHROUGH to skip this filter
113            return GIT_PASSTHROUGH;
114        }
115    }
116
117    // Apply filter if libgit2 matched our attributes
118    0
119}
120
121// ============================================================================
122// Custom Writestream Implementation
123// ============================================================================
124
125/// XET writestream - buffers data and processes on close
126#[cfg(feature = "xet-storage")]
127#[repr(C)]
128struct XetWriteStream {
129    /// Base writestream (must be first field for C compatibility)
130    base: GitWriteStreamBase,
131    /// Buffered input data
132    buffer: Vec<u8>,
133    /// Next stream to write to
134    next: *mut OpaqueGitWriteStream,
135    /// Filter mode (clean or smudge)
136    mode: c_int,
137    /// File path being filtered
138    path: String,
139    /// Payload with storage backend
140    payload: Arc<XetFilterPayload>,
141}
142
143/// Write callback - buffers incoming data
144#[cfg(feature = "xet-storage")]
145extern "C" fn xet_stream_write(
146    stream: *mut GitWriteStreamBase,
147    buffer: *const c_char,
148    len: size_t,
149) -> c_int {
150    // SAFETY: This function is a C callback invoked by libgit2.
151    // - `stream` points to our XetWriteStream (first field is GitWriteStreamBase for C compat)
152    // - `buffer` is valid for `len` bytes per libgit2's writestream contract
153    // - The XetWriteStream lifetime is managed by xet_filter_stream (alloc) and xet_stream_free (dealloc)
154    // - We check for null before dereferencing
155    unsafe {
156        let xet_stream = stream as *mut XetWriteStream;
157        if xet_stream.is_null() {
158            return -1;
159        }
160
161        let data = std::slice::from_raw_parts(buffer.cast::<u8>(), len);
162        (*xet_stream).buffer.extend_from_slice(data);
163    }
164    0
165}
166
167/// Close callback - processes buffered data and writes to next stream
168#[cfg(feature = "xet-storage")]
169extern "C" fn xet_stream_close(stream: *mut GitWriteStreamBase) -> c_int {
170    // SAFETY: This function is a C callback invoked by libgit2.
171    // - `stream` points to our XetWriteStream allocated in xet_filter_stream
172    // - libgit2 guarantees close() is called exactly once before free()
173    // - The mutable reference is exclusive because libgit2 serializes callbacks
174    // - We check for null before dereferencing
175    let result = unsafe {
176        let xet_stream = stream as *mut XetWriteStream;
177        if xet_stream.is_null() {
178            return -1;
179        }
180
181        let stream_ref = &mut *xet_stream;
182        process_and_write(stream_ref)
183    };
184
185    match result {
186        Ok(()) => 0,
187        Err(e) => {
188            tracing::error!("XET stream close error: {}", e);
189            -1
190        }
191    }
192}
193
194/// Process buffered data and write to next stream
195#[cfg(feature = "xet-storage")]
196fn process_and_write(stream: &mut XetWriteStream) -> Result<(), XetError> {
197    let input = &stream.buffer;
198
199    // Process based on mode
200    let output = if stream.mode == GIT_FILTER_SMUDGE {
201        // Smudge: XET pointer -> file content
202        smudge_data(&stream.payload, input, &stream.path)?
203    } else {
204        // Clean: file content -> XET pointer
205        clean_data(&stream.payload, input, &stream.path)?
206    };
207
208    // Write output to next stream
209    write_to_next(stream.next, &output)?;
210
211    // Close next stream
212    close_next(stream.next)?;
213
214    Ok(())
215}
216
217/// Smudge: convert XET pointer to file content
218#[cfg(feature = "xet-storage")]
219fn smudge_data(payload: &XetFilterPayload, input: &[u8], path: &str) -> Result<Vec<u8>, XetError> {
220    // Convert to string to check if it's a pointer
221    let pointer_str = match std::str::from_utf8(input) {
222        Ok(s) => s,
223        Err(_) => {
224            // Not valid UTF-8, pass through as-is
225            tracing::debug!("XET smudge {}: not UTF-8, passing through", path);
226            return Ok(input.to_vec());
227        }
228    };
229
230    // Check if it's actually a pointer
231    if !payload.storage.is_pointer(pointer_str) {
232        // Not a pointer, pass through as-is
233        tracing::debug!("XET smudge {}: not a pointer, passing through", path);
234        return Ok(input.to_vec());
235    }
236
237    // Download from XET CAS
238    let content = payload
239        .runtime
240        .block_on(payload.storage.smudge_bytes(pointer_str))
241        .map_err(|e| XetError::new(XetErrorKind::RuntimeError, format!("Runtime error: {e}")))?
242        .map_err(|e| {
243            XetError::new(
244                XetErrorKind::DownloadFailed,
245                format!("Download failed: {e}"),
246            )
247        })?;
248
249    tracing::debug!("XET smudge {}: pointer -> {} bytes", path, content.len());
250    crate::notify_smudge_progress(path);
251    Ok(content)
252}
253
254/// Clean: convert file content to XET pointer
255#[cfg(feature = "xet-storage")]
256fn clean_data(payload: &XetFilterPayload, input: &[u8], path: &str) -> Result<Vec<u8>, XetError> {
257    if input.is_empty() {
258        // Empty file - pass through
259        return Ok(Vec::new());
260    }
261
262    // Write to temporary file for upload
263    let temp_file = tempfile::NamedTempFile::new().map_err(|e| {
264        XetError::new(
265            XetErrorKind::IoError,
266            format!("Failed to create temp file: {e}"),
267        )
268    })?;
269
270    std::fs::write(temp_file.path(), input).map_err(|e| {
271        XetError::new(
272            XetErrorKind::IoError,
273            format!("Failed to write temp file: {e}"),
274        )
275    })?;
276
277    // Upload to XET CAS
278    let pointer = payload
279        .runtime
280        .block_on(payload.storage.clean_file(temp_file.path()))
281        .map_err(|e| XetError::new(XetErrorKind::RuntimeError, format!("Runtime error: {e}")))?
282        .map_err(|e| XetError::new(XetErrorKind::UploadFailed, format!("Upload failed: {e}")))?;
283
284    tracing::debug!("XET clean {}: {} bytes -> pointer", path, input.len());
285    Ok(pointer.into_bytes())
286}
287
288/// Write data to next stream using the writestream vtable
289#[cfg(feature = "xet-storage")]
290fn write_to_next(next: *mut OpaqueGitWriteStream, data: &[u8]) -> Result<(), XetError> {
291    if next.is_null() || data.is_empty() {
292        return Ok(());
293    }
294
295    // SAFETY: `next` is a git_writestream provided by libgit2 in xet_filter_stream.
296    // - The pointer is valid for the duration of our stream operation
297    // - GitWriteStreamBase is the first field of git_writestream (C struct layout)
298    // - The write function pointer is initialized by libgit2
299    // - We check for null before this point
300    unsafe {
301        let ws = next as *mut GitWriteStreamBase;
302        let write_fn = (*ws).write;
303        let result = write_fn(ws, data.as_ptr().cast::<c_char>(), data.len());
304        if result < 0 {
305            return Err(XetError::new(
306                XetErrorKind::IoError,
307                "Write to next stream failed",
308            ));
309        }
310    }
311    Ok(())
312}
313
314/// Close the next stream
315#[cfg(feature = "xet-storage")]
316fn close_next(next: *mut OpaqueGitWriteStream) -> Result<(), XetError> {
317    if next.is_null() {
318        return Ok(());
319    }
320
321    // SAFETY: `next` is a git_writestream provided by libgit2 in xet_filter_stream.
322    // - The pointer remains valid until after close() returns
323    // - GitWriteStreamBase is the first field of git_writestream (C struct layout)
324    // - The close function pointer is initialized by libgit2
325    // - We check for null before this point
326    unsafe {
327        let ws = next as *mut GitWriteStreamBase;
328        let close_fn = (*ws).close;
329        let result = close_fn(ws);
330        if result < 0 {
331            return Err(XetError::new(
332                XetErrorKind::IoError,
333                "Close next stream failed",
334            ));
335        }
336    }
337    Ok(())
338}
339
340/// Free callback - deallocates the stream
341#[cfg(feature = "xet-storage")]
342extern "C" fn xet_stream_free(stream: *mut GitWriteStreamBase) {
343    if stream.is_null() {
344        return;
345    }
346
347    // SAFETY: This function is a C callback invoked by libgit2.
348    // - `stream` was allocated by Box::into_raw in xet_filter_stream
349    // - libgit2 guarantees free() is called exactly once after close()
350    // - After this call, the memory is deallocated and the pointer is invalid
351    // - We check for null before dereferencing
352    unsafe {
353        let xet_stream = stream as *mut XetWriteStream;
354        drop(Box::from_raw(xet_stream));
355    }
356}
357
358/// Stream callback (creates our custom writestream)
359///
360/// # Safety
361/// This function is called by libgit2 with valid pointers. All pointer parameters
362/// must be valid for the duration of this call. This is guaranteed by libgit2's
363/// callback contract. The raw pointer dereferences are safe within this context.
364#[allow(clippy::not_unsafe_ptr_arg_deref)]
365#[cfg(feature = "xet-storage")]
366pub extern "C" fn xet_filter_stream(
367    out: *mut *mut OpaqueGitWriteStream,
368    filter: *mut OpaqueGitFilter,
369    _payload_ptr: *mut *mut libc::c_void,
370    source: *const OpaqueGitFilterSource,
371    next: *mut OpaqueGitWriteStream,
372) -> c_int {
373    // SAFETY: libgit2 guarantees source is valid for this callback
374    let mode = unsafe { git_filter_source_mode(source) };
375
376    // Get file path for logging
377    // SAFETY: libgit2 guarantees source is valid for this callback
378    let path = unsafe {
379        let path_ptr = git_filter_source_path(source);
380        if path_ptr.is_null() {
381            tracing::error!("XET filter: null path");
382            return -1;
383        }
384        match CStr::from_ptr(path_ptr).to_str() {
385            Ok(s) => s.to_owned(),
386            Err(_) => {
387                tracing::error!("XET filter: invalid UTF-8 in path");
388                return -1;
389            }
390        }
391    };
392
393    // Get payload using filter instance pointer
394    let payload = match get_payload(filter) {
395        Some(p) => p,
396        None => {
397            tracing::error!("XET storage not initialized for filter {:p}", filter);
398            return -1;
399        }
400    };
401
402    tracing::debug!(
403        "XET filter stream: mode={}, path={}",
404        if mode == GIT_FILTER_SMUDGE {
405            "smudge"
406        } else {
407            "clean"
408        },
409        path
410    );
411
412    // Create our custom writestream
413    let xet_stream = Box::new(XetWriteStream {
414        base: GitWriteStreamBase {
415            write: xet_stream_write,
416            close: xet_stream_close,
417            free: xet_stream_free,
418        },
419        buffer: Vec::new(),
420        next,
421        mode,
422        path,
423        payload,
424    });
425
426    // Convert to raw pointer and return
427    // SAFETY: Box::into_raw creates a stable pointer
428    // libgit2 will call free() when done
429    unsafe {
430        *out = Box::into_raw(xet_stream) as *mut OpaqueGitWriteStream;
431    }
432
433    0
434}
435
436/// Cleanup callback (releases per-source resources)
437#[cfg(feature = "xet-storage")]
438pub extern "C" fn xet_filter_cleanup(_filter: *mut OpaqueGitFilter, _payload: *mut libc::c_void) {
439    // Currently we don't use per-source payload
440}