Skip to main content

git_xet_filter/
ffi.rs

1//! Safe FFI bindings to libgit2's filter system
2//!
3//! Provides type-safe wrappers around git2/sys/filter.h
4
5use libc::{c_char, c_int, c_uint, c_void, size_t};
6use std::marker::PhantomData;
7
8// Opaque types for type safety (not just c_void)
9// Note: These are intentionally zero-sized for compile-time type safety.
10// The FFI-safety warnings are expected and suppressed below.
11#[repr(transparent)]
12pub struct OpaqueGitFilter {
13    _private: [u8; 0],
14    _phantom: PhantomData<*mut c_void>,
15}
16
17#[repr(transparent)]
18pub struct OpaqueGitFilterSource {
19    _private: [u8; 0],
20    _phantom: PhantomData<*mut c_void>,
21}
22
23#[repr(transparent)]
24pub struct OpaqueGitWriteStream {
25    _private: [u8; 0],
26    _phantom: PhantomData<*mut c_void>,
27}
28
29// Filter mode constants
30/// Filter mode for cleaning (workdir → ODB)
31pub const GIT_FILTER_CLEAN: c_int = 0;
32/// Filter mode for smudging (ODB → workdir)
33pub const GIT_FILTER_SMUDGE: c_int = 1;
34
35// Filter source flags
36/// Flag indicating operation is towards worktree (checkout operation)
37pub const GIT_FILTER_TO_WORKTREE: u32 = 1 << 0;
38
39// Filter return codes
40/// Filter passthrough - filter declines to process this file
41pub const GIT_PASSTHROUGH: c_int = -30;
42
43// Filter version
44/// Current filter structure version for ABI compatibility
45pub const GIT_FILTER_VERSION: c_uint = 1;
46
47// libgit2 configuration
48/// Memory window size for large file operations (8 MB)
49pub const LIBGIT2_MWINDOW_SIZE: usize = 8 * 1024 * 1024;
50
51// Callback function types
52pub type FilterInitializeFn = extern "C" fn(*mut OpaqueGitFilter) -> c_int;
53pub type FilterShutdownFn = extern "C" fn(*mut OpaqueGitFilter);
54pub type FilterCheckFn = extern "C" fn(
55    *mut OpaqueGitFilter,
56    *mut *mut c_void,
57    *const OpaqueGitFilterSource,
58    *const *const c_char,
59) -> c_int;
60pub type FilterStreamFn = extern "C" fn(
61    *mut *mut OpaqueGitWriteStream, // out (pointer to pointer)
62    *mut OpaqueGitFilter,           // self
63    *mut *mut c_void,               // payload
64    *const OpaqueGitFilterSource,   // src
65    *mut OpaqueGitWriteStream,      // next
66) -> c_int;
67pub type FilterCleanupFn = extern "C" fn(*mut OpaqueGitFilter, *mut c_void);
68
69/// Writestream callback types
70pub type WriteStreamWriteFn =
71    extern "C" fn(stream: *mut GitWriteStreamBase, buffer: *const c_char, len: size_t) -> c_int;
72
73pub type WriteStreamCloseFn = extern "C" fn(stream: *mut GitWriteStreamBase) -> c_int;
74
75pub type WriteStreamFreeFn = extern "C" fn(stream: *mut GitWriteStreamBase);
76
77/// Base writestream structure (matches libgit2's git_writestream)
78/// Custom writestreams should embed this at the start of their struct
79#[repr(C)]
80pub struct GitWriteStreamBase {
81    pub write: WriteStreamWriteFn,
82    pub close: WriteStreamCloseFn,
83    pub free: WriteStreamFreeFn,
84}
85
86/// Filter structure (must match libgit2's git_filter)
87#[repr(C)]
88pub struct GitFilter {
89    pub version: c_uint,
90    pub attributes: *const c_char,
91    pub initialize: Option<FilterInitializeFn>,
92    pub shutdown: Option<FilterShutdownFn>,
93    pub check: Option<FilterCheckFn>,
94    /// Reserved field (or apply callback in older versions)
95    /// This field exists for ABI compatibility with libgit2
96    pub reserved: *mut c_void,
97    pub stream: Option<FilterStreamFn>,
98    pub cleanup: Option<FilterCleanupFn>,
99}
100
101// Safety: GitFilter has no interior pointers and matches C layout
102unsafe impl Send for GitFilter {}
103unsafe impl Sync for GitFilter {}
104
105// These functions are part of libgit2's filter API
106// They're available via libgit2-sys's vendored libgit2
107#[allow(improper_ctypes)] // Opaque types are intentionally zero-sized for type safety
108extern "C" {
109    /// Initialize the global filter registry (internal libgit2 function)
110    pub fn git_filter_global_init() -> c_int;
111
112    /// Initialize a git_filter with default values
113    pub fn git_filter_init(filter: *mut GitFilter, version: c_uint) -> c_int;
114
115    /// Register a filter with libgit2
116    pub fn git_filter_register(
117        name: *const c_char,
118        filter: *mut GitFilter,
119        priority: c_int,
120    ) -> c_int;
121
122    /// Unregister a filter
123    pub fn git_filter_unregister(name: *const c_char) -> c_int;
124
125    /// Get filter source mode (clean or smudge)
126    pub fn git_filter_source_mode(src: *const OpaqueGitFilterSource) -> c_int;
127
128    /// Get filter source flags (e.g., GIT_FILTER_TO_WORKTREE)
129    pub fn git_filter_source_flags(src: *const OpaqueGitFilterSource) -> u32;
130
131    /// Get filter source repo
132    pub fn git_filter_source_repo(src: *const OpaqueGitFilterSource) -> *mut c_void;
133
134    /// Get filter source path
135    pub fn git_filter_source_path(src: *const OpaqueGitFilterSource) -> *const c_char;
136
137}
138
139// Safety: GitWriteStreamBase is a simple C struct with function pointers
140unsafe impl Send for GitWriteStreamBase {}
141unsafe impl Sync for GitWriteStreamBase {}