Skip to main content

git2db/
clone_builder.rs

1//! Fluent builder API for cloning repositories
2//!
3//! Provides a git-native interface for cloning with multiple configuration options.
4//!
5//! [`CloneBuilder`] takes ownership of an `Arc<RwLock<Git2DB>>` and manages locks
6//! internally for optimal performance - releasing the lock during network I/O.
7
8use crate::callback_config::CallbackConfig;
9use crate::errors::{Git2DBError, Git2DBResult};
10use crate::references::GitRef;
11use crate::registry::{Git2DB, RemoteConfig, RepoId};
12use crate::storage::Driver;
13use std::path::PathBuf;
14use std::sync::Arc;
15use tokio::sync::RwLock;
16
17/// Fast-path flag: set after a successful XET initialization so concurrent
18/// callers skip redundant work without entering `initialize()`.
19///
20/// `xet_filter::initialize()` is internally idempotent (uses
21/// `tokio::sync::OnceCell::get_or_try_init`), so concurrent callers that race
22/// past the fast path won't crash, but they will do redundant work. This OnceLock
23/// avoids the extra overhead.
24#[cfg(feature = "xet-storage")]
25static XET_INITIALIZED: std::sync::OnceLock<()> = std::sync::OnceLock::new();
26
27/// Automatically initialize XET for URLs that have XET support
28///
29/// XET endpoint resolution:
30/// 1. Environment variable (XETHUB_ENDPOINT/GIT2DB_XET_ENDPOINT) - always takes priority
31/// 2. URL pattern matching for known providers (e.g., huggingface.co, hf.co)
32/// 3. None - XET disabled, will use git-lfs
33#[cfg(feature = "xet-storage")]
34async fn maybe_init_xet_for_url(url: &str) -> Git2DBResult<()> {
35    // Fast path: a previous call already succeeded.
36    if XET_INITIALIZED.get().is_some() {
37        return Ok(());
38    }
39
40    // Check if XET is already initialized (e.g. initialized by caller before clone).
41    if crate::xet_filter::is_initialized() {
42        tracing::debug!(url = %url, "XET filter already initialized");
43        let _ = XET_INITIALIZED.set(());
44        return Ok(());
45    }
46
47    // Get XET config for this URL (if any)
48    let Some(config) = crate::xet_filter::XetConfig::for_url(url) else {
49        tracing::debug!(url = %url, "No XET endpoint configured for URL");
50        return Ok(());
51    };
52
53    // Token is optional for public repos, but log a hint for private repos
54    if config.token.is_none() {
55        tracing::info!(
56            url = %url,
57            "No XET token found. Public repos will work, private repos require authentication. \
58             Set XETHUB_TOKEN or HF_TOKEN environment variable."
59        );
60    }
61
62    // Initialize XET - failures are non-fatal (fallback to Git LFS).
63    // Concurrent callers may all reach here; initialize() is non-fatal on re-entry.
64    tracing::info!(url = %url, "Auto-initializing XET filter");
65
66    match crate::xet_filter::initialize(config).await {
67        Ok(()) => {
68            let _ = XET_INITIALIZED.set(());
69            tracing::info!(url = %url, "XET filter initialized successfully");
70            Ok(())
71        }
72        Err(e) => {
73            // Non-fatal: fallback to Git LFS
74            tracing::warn!(url = %url, error = %e, "XET init failed, falling back to Git LFS");
75            Ok(())
76        }
77    }
78}
79
80#[cfg(not(feature = "xet-storage"))]
81async fn maybe_init_xet_for_url(_url: &str) -> Git2DBResult<()> {
82    Ok(())
83}
84
85/// Builder for cloning repositories with fluent configuration.
86///
87/// Manages locks internally for minimal lock duration:
88/// - Brief read lock for configuration (base_dir, existing repo check)
89/// - No lock during network clone (the slow part)
90/// - Brief write lock for final registration
91///
92/// # Examples
93///
94/// ```rust,no_run
95/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
96/// use git2db::Git2DB;
97/// use std::sync::Arc;
98/// use tokio::sync::RwLock;
99///
100/// let registry = Arc::new(RwLock::new(Git2DB::open("/models").await?));
101///
102/// // Basic clone
103/// let id = git2db::CloneBuilder::new(Arc::clone(&registry), "https://github.com/user/repo.git")
104///     .exec()
105///     .await?;
106///
107/// // Clone with configuration
108/// let id = git2db::CloneBuilder::new(Arc::clone(&registry), "https://github.com/user/repo.git")
109///     .name("my-repo")
110///     .branch("develop")
111///     .depth(1)
112///     .exec()
113///     .await?;
114/// # Ok(())
115/// # }
116/// ```
117pub struct CloneBuilder {
118    registry: Arc<RwLock<Git2DB>>,
119    url: String,
120    name: Option<String>,
121    reference: GitRef,
122    depth: Option<u32>,
123    remotes: Vec<(String, String)>,
124    callback_config: Option<CallbackConfig>,
125}
126
127impl CloneBuilder {
128    /// Create a new clone builder.
129    pub fn new(registry: Arc<RwLock<Git2DB>>, url: impl Into<String>) -> Self {
130        Self {
131            registry,
132            url: url.into(),
133            name: None,
134            reference: GitRef::DefaultBranch,
135            depth: None,
136            remotes: Vec::new(),
137            callback_config: None,
138        }
139    }
140
141    /// Set a custom name for the repository
142    ///
143    /// If not specified, a UUID will be used.
144    pub fn name(mut self, name: impl Into<String>) -> Self {
145        self.name = Some(name.into());
146        self
147    }
148
149    /// Checkout a specific branch
150    ///
151    /// Similar to `git clone --branch <name>`
152    pub fn branch(mut self, branch: impl Into<String>) -> Self {
153        self.reference = GitRef::Branch(branch.into());
154        self
155    }
156
157    /// Checkout a specific tag
158    ///
159    /// Similar to `git clone --branch <tag>`
160    pub fn tag(mut self, tag: impl Into<String>) -> Self {
161        self.reference = GitRef::Tag(tag.into());
162        self
163    }
164
165    /// Checkout a specific commit
166    pub fn commit(mut self, oid: git2::Oid) -> Self {
167        self.reference = GitRef::Commit(oid);
168        self
169    }
170
171    /// Checkout a specific revspec
172    ///
173    /// Can be branch, tag, commit hash, or complex expressions like `HEAD~3`
174    pub fn revspec(mut self, spec: impl Into<String>) -> Self {
175        self.reference = GitRef::Revspec(spec.into());
176        self
177    }
178
179    /// Add an additional remote
180    ///
181    /// The primary URL becomes "origin". Additional remotes are configured
182    /// after cloning. Supports gittorrent:// URLs.
183    ///
184    /// # Examples
185    ///
186    /// ```rust,ignore
187    /// CloneBuilder::new(Arc::clone(&registry), "https://github.com/user/repo.git")
188    ///     .remote("backup", "https://backup.com/repo.git")
189    ///     .remote("p2p", "gittorrent://peer/repo")
190    ///     .exec()
191    ///     .await?;
192    /// ```
193    pub fn remote(mut self, name: impl Into<String>, url: impl Into<String>) -> Self {
194        self.remotes.push((name.into(), url.into()));
195        self
196    }
197
198    /// Create a shallow clone with specific depth
199    ///
200    /// Similar to `git clone --depth <n>`
201    pub fn depth(mut self, depth: u32) -> Self {
202        self.depth = Some(depth);
203        self
204    }
205
206    /// Set callback configuration for progress reporting and authentication
207    ///
208    /// This allows custom progress callbacks during clone operations.
209    ///
210    /// # Example
211    ///
212    /// ```rust,ignore
213    /// use git2db::callback_config::{CallbackConfig, ProgressConfig, ProgressReporter};
214    /// use std::sync::Arc;
215    ///
216    /// struct MyReporter;
217    /// impl ProgressReporter for MyReporter {
218    ///     fn report(&self, stage: &str, current: usize, total: usize) {
219    ///         println!("{}: {}/{}", stage, current, total);
220    ///     }
221    /// }
222    ///
223    /// let config = CallbackConfig::new()
224    ///     .with_progress(ProgressConfig::Channel(Arc::new(MyReporter)));
225    ///
226    /// CloneBuilder::new(Arc::clone(&registry), "https://github.com/user/repo.git")
227    ///     .callback_config(config)
228    ///     .exec()
229    ///     .await?;
230    /// ```
231    pub fn callback_config(mut self, config: CallbackConfig) -> Self {
232        self.callback_config = Some(config);
233        self
234    }
235
236    /// Execute the clone operation with minimal lock duration.
237    ///
238    /// Lock strategy:
239    /// 1. Read lock: Get config (base_dir, check existing, storage driver)
240    /// 2. No lock: Perform network clone (the slow part)
241    /// 3. Write lock: Register repository
242    pub async fn exec(mut self) -> Git2DBResult<RepoId> {
243        // Auto-initialize XET for URLs with XET support
244        maybe_init_xet_for_url(&self.url).await?;
245
246        // Generate repository ID
247        let repo_id = RepoId::new();
248
249        // Determine repository name
250        let repo_name = self.name.clone().unwrap_or_else(|| repo_id.to_string());
251        validate_repo_name(&repo_name)?;
252
253        // ===== Phase 1: Read lock for configuration =====
254        let (models_dir, driver): (PathBuf, Arc<dyn Driver>) = {
255            let registry = self.registry.read().await;
256
257            // Check if already registered (idempotent return)
258            if let Some(tracked) = registry.get_by_name(&repo_name) {
259                tracing::info!(
260                    "Repository '{}' already registered with ID {}",
261                    repo_name,
262                    tracked.id
263                );
264                return Ok(tracked.id.clone());
265            }
266
267            (
268                registry.base_dir().to_path_buf(),
269                registry.storage_driver().clone(),
270            )
271        }; // Read lock released
272
273        // Build paths
274        let repo_dir = hyprstream_containedfs::contained_join(&models_dir, &repo_name)
275            .map_err(|e| Git2DBError::configuration(format!("Invalid repository name: {e}")))?;
276        let bare_repo_name = format!("{}.git", repo_name);
277        let bare_repo_path = repo_dir.join(&bare_repo_name);
278        let worktrees_dir = repo_dir.join("worktrees");
279
280        // Check for existing bare repo (resume case)
281        let existing_valid = if repo_dir.exists() {
282            let bp = bare_repo_path.clone();
283            let rd = repo_dir.clone();
284            tokio::task::spawn_blocking(move || -> Git2DBResult<bool> {
285                if git2::Repository::open_bare(&bp).is_ok() {
286                    tracing::info!("Resuming clone: valid bare repo found at {:?}", bp);
287                    Ok(true)
288                } else {
289                    tracing::warn!("Removing incomplete/corrupted clone at {:?}", rd);
290                    std::fs::remove_dir_all(&rd).map_err(|e| {
291                        Git2DBError::repository(
292                            &rd,
293                            format!("Failed to cleanup incomplete clone: {e}"),
294                        )
295                    })?;
296                    Ok(false)
297                }
298            })
299            .await
300            .map_err(|e| Git2DBError::internal(format!("Task join error: {e}")))??
301        } else {
302            false
303        };
304
305        // Create directory structure if fresh clone
306        if !existing_valid {
307            std::fs::create_dir_all(&repo_dir).map_err(|e| {
308                Git2DBError::repository(&repo_dir, format!("Failed to create repo directory: {e}"))
309            })?;
310            std::fs::create_dir_all(&worktrees_dir).map_err(|e| {
311                Git2DBError::repository(
312                    &worktrees_dir,
313                    format!("Failed to create worktrees directory: {e}"),
314                )
315            })?;
316        }
317
318        // ===== Phase 2: No lock - perform network clone =====
319        // Extract progress reporter before callback_config is consumed by clone options
320        let progress_reporter = self
321            .callback_config
322            .as_ref()
323            .and_then(crate::callback_config::CallbackConfig::progress_reporter);
324
325        if !existing_valid {
326            tracing::info!(
327                "Cloning repository '{}' as bare to {:?}",
328                repo_name,
329                bare_repo_path
330            );
331
332            let clone_options = if let Some(config) = self.callback_config.take() {
333                crate::clone_options::CloneOptions::with_callback_config(config)
334            } else {
335                crate::manager::GitManager::global().default_clone_options()
336            };
337
338            let url_clone = self.url.clone();
339            let bare_path_clone = bare_repo_path.clone();
340
341            // This is the slow network operation - no lock held!
342            // We discard the returned Repository (it's !Send) and re-open below.
343            tokio::task::spawn_blocking(move || -> Git2DBResult<()> {
344                let mut git2_options = clone_options.to_git2_options();
345                let mut builder = git2::build::RepoBuilder::new();
346                builder.bare(true);
347                builder.fetch_options(git2_options.create_fetch_options().map_err(|e| {
348                    Git2DBError::internal(format!("Failed to create fetch options: {e}"))
349                })?);
350
351                builder.clone(&url_clone, &bare_path_clone).map_err(|e| {
352                    Git2DBError::repository(
353                        &bare_path_clone,
354                        format!("Failed to clone bare repository: {e}"),
355                    )
356                })?;
357                Ok(())
358            })
359            .await
360            .map_err(|e| Git2DBError::internal(format!("Task join error: {e}")))??;
361        }
362
363        // Post-clone git2 operations: add remotes + detect default branch.
364        // Re-open the bare repo inside spawn_blocking (git2::Repository is !Send).
365        let remotes_clone = self.remotes.clone();
366        let bp = bare_repo_path.clone();
367        let default_branch = tokio::task::spawn_blocking(move || -> Git2DBResult<String> {
368            let repo = git2::Repository::open_bare(&bp).map_err(|e| {
369                Git2DBError::repository(&bp, format!("Failed to open bare repo: {e}"))
370            })?;
371            for (remote_name, remote_url) in &remotes_clone {
372                // Use remote_set_url: creates the remote if missing, updates if it exists.
373                // This is idempotent for the resume path where remotes may already exist.
374                repo.remote_set_url(remote_name, remote_url).map_err(|e| {
375                    Git2DBError::configuration(format!("Failed to set remote '{remote_name}': {e}"))
376                })?;
377            }
378            get_default_branch(&repo)
379        })
380        .await
381        .map_err(|e| Git2DBError::internal(format!("Task join error: {e}")))??;
382        tracing::debug!("Default branch detected: {}", default_branch);
383
384        // Validate branch name for path safety (C2 fix)
385        hyprstream_containedfs::validate_ref_name(&default_branch)
386            .map_err(|e| Git2DBError::configuration(format!("Unsafe default branch name: {e}")))?;
387
388        let initial_worktree =
389            hyprstream_containedfs::contained_join(&worktrees_dir, &default_branch)
390                .map_err(|e| Git2DBError::configuration(format!("Invalid worktree path: {e}")))?;
391        if let Some(parent) = initial_worktree.parent() {
392            if parent != worktrees_dir {
393                std::fs::create_dir_all(parent).map_err(|e| {
394                    Git2DBError::configuration(format!(
395                        "Failed to create worktree parent directories: {e}"
396                    ))
397                })?;
398            }
399        }
400
401        tracing::info!(
402            "Creating default worktree '{}' at {:?}",
403            default_branch,
404            initial_worktree
405        );
406        create_worktree(
407            &driver,
408            &bare_repo_path,
409            &initial_worktree,
410            &default_branch,
411            progress_reporter.clone(),
412        )
413        .await?;
414
415        // Create additional worktree if requested ref differs from default
416        let checkout_ref = match &self.reference {
417            GitRef::DefaultBranch => default_branch.clone(),
418            GitRef::Branch(b) => b.clone(),
419            GitRef::Tag(t) => t.clone(),
420            GitRef::Commit(oid) => oid.to_string(),
421            GitRef::Revspec(spec) => spec.clone(),
422        };
423
424        if checkout_ref != default_branch && !matches!(self.reference, GitRef::DefaultBranch) {
425            // Validate checkout ref for path safety (C2 fix)
426            hyprstream_containedfs::validate_ref_name(&checkout_ref).map_err(|e| {
427                Git2DBError::configuration(format!("Unsafe checkout ref name: {e}"))
428            })?;
429            let ref_worktree_path =
430                hyprstream_containedfs::contained_join(&worktrees_dir, &checkout_ref).map_err(
431                    |e| Git2DBError::configuration(format!("Invalid worktree path: {e}")),
432                )?;
433            if let Some(parent) = ref_worktree_path.parent() {
434                std::fs::create_dir_all(parent).map_err(|e| {
435                    Git2DBError::configuration(format!(
436                        "Failed to create worktree parent directories: {e}"
437                    ))
438                })?;
439            }
440            tracing::info!("Creating worktree for ref '{}'", checkout_ref);
441            create_worktree(
442                &driver,
443                &bare_repo_path,
444                &ref_worktree_path,
445                &checkout_ref,
446                progress_reporter.clone(),
447            )
448            .await?;
449        }
450
451        // Build remote configs
452        let mut remote_configs = vec![RemoteConfig {
453            name: "origin".to_owned(),
454            url: self.url.clone(),
455            fetch_refs: vec!["+refs/heads/*:refs/remotes/origin/*".to_owned()],
456        }];
457        for (name, url) in self.remotes {
458            remote_configs.push(RemoteConfig {
459                name: name.clone(),
460                url,
461                fetch_refs: vec![format!("+refs/heads/*:refs/remotes/{}/*", name)],
462            });
463        }
464
465        // ===== Phase 3: Write lock for registration =====
466        {
467            let mut registry = self.registry.write().await;
468            registry
469                .register_repository_internal(
470                    repo_id.clone(),
471                    self.name.clone(),
472                    self.url,
473                    bare_repo_path,
474                    self.reference,
475                    remote_configs,
476                    std::collections::HashMap::new(),
477                )
478                .await?;
479        } // Write lock released
480
481        Ok(repo_id)
482    }
483}
484
485/// Validate repository name to prevent path traversal
486fn validate_repo_name(name: &str) -> Git2DBResult<()> {
487    // Check for empty name
488    if name.is_empty() {
489        return Err(Git2DBError::configuration(
490            "Repository name cannot be empty",
491        ));
492    }
493
494    // Check for path separators and parent directory references
495    if name.contains('/') || name.contains("..") {
496        return Err(Git2DBError::configuration(
497            "Repository name cannot contain path separators or parent references",
498        ));
499    }
500
501    Ok(())
502}
503
504/// Get the default branch from a bare repository
505fn get_default_branch(repo: &git2::Repository) -> Git2DBResult<String> {
506    // Try to get from HEAD
507    if let Ok(head) = repo.head() {
508        if let Some(name) = head.shorthand() {
509            return Ok(name.to_owned());
510        }
511    }
512
513    // Try to get from remote HEAD
514    if let Ok(remote) = repo.find_remote("origin") {
515        if let Ok(buf) = remote.default_branch() {
516            if let Some(s) = buf.as_str() {
517                // Remove refs/heads/ prefix
518                let branch = s.strip_prefix("refs/heads/").unwrap_or(s);
519                return Ok(branch.to_owned());
520            }
521        }
522    }
523
524    // Fallback to common defaults
525    for default in &["main", "master"] {
526        if repo.find_branch(default, git2::BranchType::Local).is_ok() {
527            return Ok((*default).to_owned());
528        }
529    }
530
531    // Last resort
532    Ok("main".to_owned())
533}
534
535/// Create a worktree from a bare repository using the storage driver
536async fn create_worktree(
537    driver: &std::sync::Arc<dyn crate::storage::Driver>,
538    bare_repo_path: &std::path::Path,
539    worktree_path: &std::path::Path,
540    branch: &str,
541    progress: Option<std::sync::Arc<dyn crate::callback_config::ProgressReporter>>,
542) -> Git2DBResult<()> {
543    // Ensure parent exists
544    if let Some(parent) = worktree_path.parent() {
545        std::fs::create_dir_all(parent).map_err(|e| {
546            Git2DBError::configuration(format!("Failed to create worktree parent directories: {e}"))
547        })?;
548    }
549
550    // Use storage driver (strict: errors if path exists)
551    let opts = crate::storage::DriverOpts {
552        base_repo: bare_repo_path.to_path_buf(),
553        worktree_path: worktree_path.to_path_buf(),
554        ref_spec: branch.to_owned(),
555        progress: progress.clone(),
556        checkout_paths: None,
557    };
558
559    match driver.create_worktree(&opts).await {
560        Ok(_) => {
561            // LFS fetch (idempotent) with progress reporting
562            crate::repository_handle::RepositoryHandle::fetch_lfs_files_with_progress(
563                worktree_path,
564                progress,
565            )
566            .await?;
567            tracing::info!(
568                "Created worktree at {:?} for branch '{}'",
569                worktree_path,
570                branch
571            );
572            Ok(())
573        }
574        Err(e) if e.is_worktree_exists() => {
575            // Clone resume: worktree already exists, just fetch LFS
576            tracing::info!(
577                "Worktree already exists at {:?}, fetching LFS files",
578                worktree_path
579            );
580            crate::repository_handle::RepositoryHandle::fetch_lfs_files_with_progress(
581                worktree_path,
582                progress,
583            )
584            .await?;
585            Ok(())
586        }
587        Err(e) => Err(Git2DBError::repository(
588            worktree_path,
589            format!("Failed to create worktree for branch '{branch}': {e}"),
590        )),
591    }
592}
593
594#[cfg(test)]
595mod tests {
596    use super::*;
597
598    #[tokio::test]
599    async fn named_clone_and_registration_share_unique_name_insertion() -> anyhow::Result<()> {
600        use git2::Signature;
601
602        let source_dir = tempfile::tempdir()?;
603        let source = git2::Repository::init(source_dir.path())?;
604        std::fs::write(source_dir.path().join("README.md"), "canary\n")?;
605        let mut index = source.index()?;
606        index.add_path(std::path::Path::new("README.md"))?;
607        index.write()?;
608        let tree = source.find_tree(index.write_tree()?)?;
609        let author = Signature::now("Canary", "canary@example.invalid")?;
610        let oid = source.commit(Some("HEAD"), &author, &author, "canary", &tree, &[])?;
611
612        let base = tempfile::tempdir()?;
613        let registry = Arc::new(RwLock::new(Git2DB::open(base.path()).await?));
614        let source_url = format!("file://{}", source_dir.path().display());
615        let oid_hex = oid.to_string();
616        let id = CloneBuilder::new(Arc::clone(&registry), source_url.clone())
617            .name("canary")
618            .callback_config(CallbackConfig::new())
619            .exec()
620            .await?;
621        let tracked = registry
622            .read()
623            .await
624            .get_by_name("canary")
625            .cloned()
626            .ok_or_else(|| anyhow::anyhow!("named clone was not registered"))?;
627        assert_eq!(tracked.id, id);
628        assert_eq!(tracked.current_oid.as_deref(), Some(oid_hex.as_str()));
629
630        let other = base.path().join("other");
631        git2::Repository::init(&other)?;
632        let duplicate = registry
633            .write()
634            .await
635            .register(RepoId::new())
636            .name("canary")
637            .url(format!("file://{}", other.display()))
638            .worktree_path(other)
639            .exec()
640            .await;
641        assert!(duplicate.is_err());
642        let repeated = CloneBuilder::new(Arc::clone(&registry), source_url)
643            .name("canary")
644            .exec()
645            .await?;
646        assert_eq!(repeated, id);
647        assert_eq!(
648            registry
649                .read()
650                .await
651                .list()
652                .filter(|repo| repo.name.as_deref() == Some("canary"))
653                .count(),
654            1
655        );
656        Ok(())
657    }
658
659    #[test]
660    fn test_builder_fluent_api() {
661        // This test just validates the fluent API compiles correctly
662        fn _example(registry: Arc<RwLock<Git2DB>>) {
663            let _builder =
664                CloneBuilder::new(Arc::clone(&registry), "https://github.com/user/repo.git")
665                    .name("my-repo")
666                    .branch("main")
667                    .remote("backup", "https://backup.com/repo.git")
668                    .depth(1);
669        }
670    }
671
672    #[test]
673    fn test_validate_repo_name() {
674        // Valid names
675        assert!(validate_repo_name("my-repo").is_ok());
676        assert!(validate_repo_name("repo_123").is_ok());
677        assert!(validate_repo_name("MyRepo").is_ok());
678        assert!(validate_repo_name(".hidden").is_ok()); // Hidden files are fine on Linux
679
680        // Invalid names - only path traversal concerns
681        assert!(validate_repo_name("").is_err());
682        assert!(validate_repo_name("my/repo").is_err());
683        assert!(validate_repo_name("../etc").is_err());
684        assert!(validate_repo_name("repo..name").is_err());
685    }
686}