git2db/transport.rs
1//! Custom git transport support for git2db
2//!
3//! This module provides trait-based extension points for registering custom
4//! git transports. This enables integration with P2P systems (GitTorrent),
5//! content-addressable storage (IPFS), cloud storage (S3), and other backends.
6
7use git2::transport::{SmartSubtransport, SmartSubtransportStream};
8use std::sync::Arc;
9
10/// Wrapper to make Box<dyn SmartSubtransport> implement SmartSubtransport
11///
12/// This is needed because trait objects don't automatically implement their trait.
13/// We use this wrapper to pass boxed transports to git2::Transport::smart().
14pub struct BoxedSubtransport(pub Box<dyn SmartSubtransport>);
15
16impl SmartSubtransport for BoxedSubtransport {
17 fn action(
18 &self,
19 url: &str,
20 action: git2::transport::Service,
21 ) -> Result<Box<dyn SmartSubtransportStream>, git2::Error> {
22 self.0.action(url, action)
23 }
24
25 fn close(&self) -> Result<(), git2::Error> {
26 self.0.close()
27 }
28}
29
30/// Factory trait for creating custom git transports
31///
32/// Implementations of this trait can be registered with GitManager to handle
33/// custom URL schemes like `gittorrent://`, `ipfs://`, `s3://`, etc.
34///
35/// # Example
36///
37/// ```ignore
38/// use git2db::transport::TransportFactory;
39/// use git2::transport::SmartSubtransport;
40///
41/// struct MyTransportFactory {
42/// config: MyConfig,
43/// }
44///
45/// impl TransportFactory for MyTransportFactory {
46/// fn create_transport(&self, url: &str) -> anyhow::Result<Box<dyn SmartSubtransport>> {
47/// Ok(Box::new(MyTransport::new(url, &self.config)?))
48/// }
49///
50/// fn supports_url(&self, url: &str) -> bool {
51/// url.starts_with("mytransport://")
52/// }
53/// }
54/// ```
55pub trait TransportFactory: Send + Sync {
56 /// Create a new transport instance for the given URL
57 ///
58 /// This method is called by git2 when a remote operation (clone, fetch, push)
59 /// needs to communicate with a repository at the given URL.
60 ///
61 /// # Arguments
62 ///
63 /// * `url` - The repository URL (e.g., "gittorrent://abc123/repo")
64 ///
65 /// # Returns
66 ///
67 /// A boxed `SmartSubtransport` implementation that handles git protocol operations
68 fn create_transport(&self, url: &str) -> anyhow::Result<Box<dyn SmartSubtransport>>;
69
70 /// Check if this factory can handle the given URL
71 ///
72 /// This is checked before calling `create_transport` to ensure the factory
73 /// is appropriate for the URL scheme.
74 ///
75 /// # Arguments
76 ///
77 /// * `url` - The repository URL to check
78 ///
79 /// # Returns
80 ///
81 /// `true` if this factory can create transports for this URL, `false` otherwise
82 fn supports_url(&self, url: &str) -> bool;
83}
84
85/// Helper trait for cloning TransportFactory trait objects
86///
87/// This is a workaround for the fact that `Clone` cannot be made into a trait object.
88/// Implementations should return a boxed clone of themselves.
89pub trait TransportFactoryClone {
90 fn clone_box(&self) -> Box<dyn TransportFactory>;
91}
92
93impl<T> TransportFactoryClone for T
94where
95 T: TransportFactory + Clone + 'static,
96{
97 fn clone_box(&self) -> Box<dyn TransportFactory> {
98 Box::new(self.clone())
99 }
100}
101
102/// Extension trait to add Clone support to Arc<dyn TransportFactory>
103///
104/// This allows us to clone transport factories wrapped in Arc when needed
105/// for passing to multiple callbacks or storing in collections.
106pub trait TransportFactoryExt {
107 fn clone_arc(&self) -> Arc<dyn TransportFactory>;
108}
109
110impl TransportFactoryExt for Arc<dyn TransportFactory> {
111 fn clone_arc(&self) -> Arc<dyn TransportFactory> {
112 Arc::clone(self)
113 }
114}
115
116/// Mock transport for testing
117///
118/// This transport always fails with a predefined error, useful for testing
119/// transport registration and error handling without real network operations.
120pub struct MockTransport;
121
122impl MockTransport {
123 pub fn new(_url: &str) -> Self {
124 Self
125 }
126}
127
128impl SmartSubtransport for MockTransport {
129 fn action(
130 &self,
131 _url: &str,
132 _action: git2::transport::Service,
133 ) -> Result<Box<dyn SmartSubtransportStream>, git2::Error> {
134 Err(git2::Error::from_str("Mock transport: not implemented"))
135 }
136
137 fn close(&self) -> Result<(), git2::Error> {
138 Ok(())
139 }
140}
141
142/// Mock transport factory for testing
143#[cfg(test)]
144#[derive(Clone)]
145pub struct MockTransportFactory;
146
147#[cfg(test)]
148impl TransportFactory for MockTransportFactory {
149 fn create_transport(&self, url: &str) -> anyhow::Result<Box<dyn SmartSubtransport>> {
150 Ok(Box::new(MockTransport::new(url)))
151 }
152
153 fn supports_url(&self, url: &str) -> bool {
154 url.starts_with("mock://")
155 }
156}
157
158#[cfg(test)]
159mod tests {
160 use super::*;
161
162 #[test]
163 fn test_mock_transport_factory() -> crate::Git2DBResult<()> {
164 let factory = MockTransportFactory;
165 assert!(factory.supports_url("mock://test/repo"));
166 assert!(!factory.supports_url("https://example.com/repo"));
167
168 let transport = factory.create_transport("mock://test/repo")?;
169 assert!(transport
170 .action("mock://test/repo", git2::transport::Service::UploadPackLs)
171 .is_err());
172 Ok(())
173 }
174
175 #[test]
176 fn test_transport_factory_clone() {
177 let factory = MockTransportFactory;
178 let boxed: Box<dyn TransportFactory> = factory.clone_box();
179 assert!(boxed.supports_url("mock://test/repo"));
180 }
181}