Skip to main content

git2db/
transport_registry.rs

1//! Thread-safe transport registry for custom git transports
2//!
3//! This module provides a thread-safe wrapper around libgit2's transport
4//! registration system with proper synchronization and lifecycle management.
5//!
6//! # Safety
7//!
8//! This module uses `unsafe` code to call `git2::transport::register()`.
9//! Safety is ensured through:
10//! - Thread-safe factory storage using `Arc<Mutex<HashMap>>`
11//! - Per-scheme registration locks to prevent concurrent registration
12//! - Reference counting to prevent duplicate registrations
13//! - Factory trait bounds requiring `Send + Sync`
14//!
15//! # Examples
16//!
17//! ```rust
18//! use git2db::transport_registry::TransportRegistry;
19//! use std::sync::Arc;
20//!
21//! let registry = TransportRegistry::new();
22//!
23//! // Register a custom transport
24//! // let factory = Arc::new(MyTransportFactory::new());
25//! // registry.register_transport("mycustom".to_owned(), factory).unwrap();
26//! ```
27
28use crate::errors::Git2DBError;
29use crate::transport::{BoxedSubtransport, TransportFactory};
30use git2::transport::Transport;
31use once_cell::sync::Lazy;
32use parking_lot::Mutex;
33use std::collections::HashMap;
34use std::sync::Arc;
35use tracing::{debug, info, warn};
36
37/// Process-wide mutex serializing all calls to `git2::transport::register`.
38///
39/// libgit2's transport list is a global linked list with no internal lock —
40/// concurrent registration from different schemes (each holding only their
41/// own per-scheme lock) causes heap corruption. This mutex ensures only one
42/// thread calls `git2::transport::register` at a time.
43static GIT2_TRANSPORT_REGISTER_LOCK: Lazy<Mutex<()>> = Lazy::new(|| Mutex::new(()));
44
45/// Thread-safe transport registry with proper lifecycle management
46pub struct TransportRegistry {
47    /// Registered transport factories by scheme
48    transports: Arc<Mutex<HashMap<String, Arc<dyn TransportFactory>>>>,
49    /// Registration synchronization per scheme
50    registration_locks: Arc<Mutex<HashMap<String, Arc<Mutex<()>>>>>,
51    /// Global transport registration state
52    global_registry: Arc<Mutex<GlobalRegistryState>>,
53}
54
55/// Global registry state to track which schemes are registered
56#[derive(Debug, Default)]
57struct GlobalRegistryState {
58    registered_schemes: HashMap<String, usize>, // scheme -> reference count
59}
60
61impl TransportRegistry {
62    /// Create a new transport registry
63    pub fn new() -> Self {
64        Self {
65            transports: Arc::new(Mutex::new(HashMap::new())),
66            registration_locks: Arc::new(Mutex::new(HashMap::new())),
67            global_registry: Arc::new(Mutex::new(GlobalRegistryState::default())),
68        }
69    }
70
71    /// Register a transport factory for a URL scheme
72    ///
73    /// This method is thread-safe and ensures proper synchronization.
74    /// Multiple registrations for the same scheme are reference counted.
75    pub fn register_transport(
76        &self,
77        scheme: String,
78        factory: Arc<dyn TransportFactory>,
79    ) -> Result<(), Git2DBError> {
80        if scheme.is_empty() {
81            return Err(Git2DBError::configuration(
82                "Transport scheme cannot be empty",
83            ));
84        }
85
86        // Validate scheme format
87        if !Self::is_valid_scheme(&scheme) {
88            return Err(Git2DBError::configuration(format!(
89                "Invalid transport scheme: '{scheme}'. Schemes must contain only alphanumeric characters, hyphens, and underscores"
90            )));
91        }
92
93        debug!("Registering transport for scheme: {}", scheme);
94
95        // Add to local registry
96        {
97            let mut transports = self.transports.lock();
98            transports.insert(scheme.clone(), factory);
99        }
100
101        // Get or create registration lock for this scheme
102        let registration_lock = {
103            let mut locks = self.registration_locks.lock();
104            locks
105                .entry(scheme.clone())
106                .or_insert_with(|| Arc::new(Mutex::new(())))
107                .clone()
108        };
109
110        // Acquire registration lock to ensure thread safety
111        let _lock = registration_lock.lock();
112
113        // Check if already globally registered and increment ref count atomically
114        let should_register = {
115            let mut global_state = self.global_registry.lock();
116            let ref_count = global_state
117                .registered_schemes
118                .entry(scheme.clone())
119                .or_insert(0);
120            let should_register = *ref_count == 0;
121            if should_register {
122                *ref_count = 1; // Increment immediately to prevent other threads
123            }
124            should_register
125        };
126
127        if should_register {
128            // Actually register with git2
129            if let Err(e) = self.register_with_git2(&scheme) {
130                // Registration failed, decrement ref count
131                let mut global_state = self.global_registry.lock();
132                if let Some(ref_count) = global_state.registered_schemes.get_mut(&scheme) {
133                    *ref_count = 0;
134                }
135                return Err(e);
136            }
137
138            debug!(
139                "Successfully registered transport with git2 for scheme: {}",
140                scheme
141            );
142        } else {
143            debug!("Transport already registered for scheme: {}", scheme);
144        }
145
146        Ok(())
147    }
148
149    /// Unregister a transport factory
150    ///
151    /// This method is thread-safe and uses reference counting.
152    /// The transport is only unregistered from git2 when the last factory is removed.
153    pub fn unregister_transport(&self, scheme: &str) -> Option<Arc<dyn TransportFactory>> {
154        if scheme.is_empty() {
155            return None;
156        }
157
158        debug!("Unregistering transport for scheme: {}", scheme);
159
160        // Remove from local registry
161        let factory = {
162            let mut transports = self.transports.lock();
163            transports.remove(scheme)
164        };
165
166        if factory.is_some() {
167            // Get registration lock
168            let registration_lock = {
169                let locks = self.registration_locks.lock();
170                locks.get(scheme).cloned()
171            };
172
173            if let Some(lock) = registration_lock {
174                let _lock_guard = lock.lock();
175
176                // Decrement reference count and unregister if zero
177                let should_unregister = {
178                    let mut global_state = self.global_registry.lock();
179                    if let Some(ref_count) = global_state.registered_schemes.get_mut(scheme) {
180                        *ref_count = ref_count.saturating_sub(1);
181                        *ref_count == 0
182                    } else {
183                        false
184                    }
185                };
186
187                if should_unregister {
188                    if let Err(e) = self.unregister_from_git2(scheme) {
189                        warn!(
190                            "Failed to unregister transport from git2 for scheme '{}': {}",
191                            scheme, e
192                        );
193                        // Don't return error - this is cleanup code
194                    } else {
195                        debug!(
196                            "Successfully unregistered transport from git2 for scheme: {}",
197                            scheme
198                        );
199                    }
200
201                    // Clean up registration lock
202                    {
203                        let mut locks = self.registration_locks.lock();
204                        locks.remove(scheme);
205                    }
206                }
207            }
208        }
209
210        factory
211    }
212
213    /// Get a transport factory for a scheme
214    pub fn get_transport(&self, scheme: &str) -> Option<Arc<dyn TransportFactory>> {
215        let transports = self.transports.lock();
216        transports.get(scheme).cloned()
217    }
218
219    /// Check if a transport is registered for a scheme
220    pub fn has_transport(&self, scheme: &str) -> bool {
221        let transports = self.transports.lock();
222        transports.contains_key(scheme)
223    }
224
225    /// Get all registered transport schemes
226    pub fn registered_schemes(&self) -> Vec<String> {
227        let transports = self.transports.lock();
228        transports.keys().cloned().collect()
229    }
230
231    /// Validate transport scheme format
232    fn is_valid_scheme(scheme: &str) -> bool {
233        if scheme.is_empty() || scheme.len() > 64 {
234            return false;
235        }
236
237        // Only allow alphanumeric characters, hyphens, and underscores
238        scheme
239            .chars()
240            .all(|c| c.is_alphanumeric() || c == '-' || c == '_')
241    }
242
243    /// Register transport with git2 using unsafe git2::transport::register
244    ///
245    /// # Safety
246    ///
247    /// This function is safe to call because:
248    /// - The factory is stored in an Arc<Mutex> ensuring thread-safe access
249    /// - The factory trait is `Send + Sync + 'static`
250    /// - We use per-scheme locks to prevent concurrent registration
251    /// - git2::transport::register requires external synchronization, which we provide
252    fn register_with_git2(&self, scheme: &str) -> Result<(), Git2DBError> {
253        let factory = self.get_transport(scheme).ok_or_else(|| {
254            Git2DBError::configuration(format!("No factory for scheme '{scheme}'"))
255        })?;
256
257        info!(
258            "Registering custom transport for scheme '{}' with libgit2",
259            scheme
260        );
261
262        // SAFETY:
263        // - factory is Arc<dyn TransportFactory> which is Send + Sync + 'static
264        // - GIT2_TRANSPORT_REGISTER_LOCK serializes all calls globally (per-scheme lock
265        //   alone is insufficient because two different schemes hold different locks)
266        // - The closure captures factory in an Arc, ensuring proper lifetime
267        // - git2::transport::register is unsafe due to global state, but we synchronize access
268        let _global_guard = GIT2_TRANSPORT_REGISTER_LOCK.lock();
269        unsafe {
270            git2::transport::register(scheme, move |remote| {
271                let url = remote.url().unwrap_or("");
272                debug!("Creating transport for URL: {}", url);
273
274                // Create the transport
275                let transport = factory.create_transport(url).map_err(|e| {
276                    git2::Error::from_str(&format!("Failed to create transport: {e}"))
277                })?;
278
279                // Wrap in BoxedSubtransport and create smart transport
280                Transport::smart(remote, true, BoxedSubtransport(transport))
281            })
282            .map_err(|e| {
283                Git2DBError::internal(format!("Failed to register transport with git2: {e}"))
284            })?;
285        }
286
287        info!("Successfully registered transport for scheme '{}'", scheme);
288        Ok(())
289    }
290
291    /// Unregister transport from git2
292    ///
293    /// Note: libgit2 does not provide a way to unregister transports once registered.
294    /// The transport will remain registered for the lifetime of the process.
295    /// This is a limitation of libgit2's API.
296    fn unregister_from_git2(&self, scheme: &str) -> Result<(), Git2DBError> {
297        debug!(
298            "Transport '{}' remains registered with git2 (libgit2 limitation)",
299            scheme
300        );
301        Ok(())
302    }
303
304    /// Get registry statistics
305    pub fn stats(&self) -> RegistryStats {
306        let transports = self.transports.lock();
307        let global_state = self.global_registry.lock();
308        let locks = self.registration_locks.lock();
309
310        RegistryStats {
311            registered_factories: transports.len(),
312            globally_registered_schemes: global_state.registered_schemes.len(),
313            active_registration_locks: locks.len(),
314            schemes: transports.keys().cloned().collect(),
315        }
316    }
317}
318
319impl Clone for TransportRegistry {
320    fn clone(&self) -> Self {
321        Self {
322            transports: Arc::clone(&self.transports),
323            registration_locks: Arc::clone(&self.registration_locks),
324            global_registry: Arc::clone(&self.global_registry),
325        }
326    }
327}
328
329impl Default for TransportRegistry {
330    fn default() -> Self {
331        Self::new()
332    }
333}
334
335/// Registry statistics
336#[derive(Debug, Clone)]
337pub struct RegistryStats {
338    pub registered_factories: usize,
339    pub globally_registered_schemes: usize,
340    pub active_registration_locks: usize,
341    pub schemes: Vec<String>,
342}
343
344/// Drop guard for automatic transport cleanup
345pub struct TransportGuard {
346    registry: TransportRegistry,
347    scheme: String,
348}
349
350impl TransportGuard {
351    /// Create a new transport guard
352    pub fn new(registry: TransportRegistry, scheme: String) -> Self {
353        Self { registry, scheme }
354    }
355
356    /// Get the scheme
357    pub fn scheme(&self) -> &str {
358        &self.scheme
359    }
360}
361
362impl Drop for TransportGuard {
363    fn drop(&mut self) {
364        debug!("Auto-unregistering transport for scheme: {}", self.scheme);
365        if let Some(_factory) = self.registry.unregister_transport(&self.scheme) {
366            debug!("Successfully auto-unregistered transport");
367        }
368    }
369}
370
371#[cfg(test)]
372mod tests {
373    use super::*;
374    use crate::transport::MockTransportFactory;
375
376    #[test]
377    fn test_transport_registry_thread_safety() {
378        use std::sync::atomic::{AtomicU64, Ordering};
379        static TEST_COUNTER: AtomicU64 = AtomicU64::new(0);
380
381        // Use a unique scheme name to avoid conflicts with other tests
382        let test_id = TEST_COUNTER.fetch_add(1, Ordering::SeqCst);
383        let scheme = format!("test-thread-{test_id}");
384
385        let registry = Arc::new(TransportRegistry::new());
386        let factory: Arc<dyn TransportFactory> = Arc::new(MockTransportFactory);
387
388        // Test concurrent registration
389        let handles: Vec<_> = (0..10)
390            .map(|_| {
391                let registry = Arc::clone(&registry);
392                let factory = Arc::clone(&factory);
393                let scheme = scheme.clone();
394                std::thread::spawn(move || {
395                    registry.register_transport(scheme, Arc::clone(&factory))
396                })
397            })
398            .collect();
399
400        // All should succeed - only first thread registers with git2, others skip
401        for handle in handles {
402            if let Ok(result) = handle.join() {
403                assert!(result.is_ok());
404            }
405        }
406
407        // Should have exactly one factory registered
408        let stats = registry.stats();
409        assert_eq!(stats.registered_factories, 1);
410        assert_eq!(stats.globally_registered_schemes, 1);
411
412        // Cleanup
413        let _ = registry.unregister_transport(&scheme);
414    }
415
416    #[test]
417    fn test_scheme_validation() {
418        use std::sync::atomic::{AtomicU64, Ordering};
419        static TEST_COUNTER: AtomicU64 = AtomicU64::new(0);
420        let test_id = TEST_COUNTER.fetch_add(1, Ordering::SeqCst);
421
422        let registry = TransportRegistry::new();
423        let factory: Arc<dyn TransportFactory> = Arc::new(MockTransportFactory);
424
425        // Valid schemes
426        assert!(registry
427            .register_transport(format!("valid1-{test_id}"), Arc::clone(&factory))
428            .is_ok());
429        assert!(registry
430            .register_transport(format!("valid2-{test_id}"), Arc::clone(&factory))
431            .is_ok());
432        assert!(registry
433            .register_transport(format!("my-transport-{test_id}"), Arc::clone(&factory))
434            .is_ok());
435        assert!(registry
436            .register_transport(format!("my_transport_{test_id}"), Arc::clone(&factory))
437            .is_ok());
438
439        // Invalid schemes
440        assert!(registry
441            .register_transport("".to_owned(), Arc::clone(&factory))
442            .is_err());
443        assert!(registry
444            .register_transport("http://".to_owned(), Arc::clone(&factory))
445            .is_err());
446        assert!(registry
447            .register_transport("http://invalid".to_owned(), Arc::clone(&factory))
448            .is_err());
449        assert!(registry
450            .register_transport("transport with spaces".to_owned(), Arc::clone(&factory))
451            .is_err());
452    }
453
454    #[test]
455    fn test_reference_counting() {
456        use std::sync::atomic::{AtomicU64, Ordering};
457        static TEST_COUNTER: AtomicU64 = AtomicU64::new(0);
458        let test_id = TEST_COUNTER.fetch_add(1, Ordering::SeqCst);
459        let scheme = format!("refcount-{test_id}");
460
461        let registry = TransportRegistry::new();
462        let factory1 = Arc::new(MockTransportFactory);
463        let factory2 = Arc::new(MockTransportFactory);
464
465        // Register first factory
466        assert!(registry
467            .register_transport(scheme.clone(), factory1)
468            .is_ok());
469        let stats = registry.stats();
470        assert_eq!(stats.registered_factories, 1);
471
472        // Register second factory (replaces first)
473        assert!(registry
474            .register_transport(scheme.clone(), factory2)
475            .is_ok());
476        let stats = registry.stats();
477        assert_eq!(stats.registered_factories, 1);
478
479        // Unregister
480        let _ = registry.unregister_transport(&scheme);
481        let stats = registry.stats();
482        assert_eq!(stats.registered_factories, 0);
483    }
484
485    #[test]
486    fn test_transport_guard_cleanup() {
487        use std::sync::atomic::{AtomicU64, Ordering};
488        static TEST_COUNTER: AtomicU64 = AtomicU64::new(0);
489        let test_id = TEST_COUNTER.fetch_add(1, Ordering::SeqCst);
490        let scheme = format!("guarded-{test_id}");
491
492        let registry = TransportRegistry::new();
493        let factory: Arc<dyn TransportFactory> = Arc::new(MockTransportFactory);
494
495        {
496            let _guard = TransportGuard::new(registry.clone(), scheme.clone());
497            let result = registry.register_transport(scheme.clone(), Arc::clone(&factory));
498            assert!(result.is_ok());
499            assert!(registry.has_transport(&scheme));
500        } // Guard goes out of scope
501
502        // Transport should be unregistered
503        assert!(!registry.has_transport(&scheme));
504    }
505}