Skip to main content

git2db/storage/
vfs.rs

1//! VFS driver (plain directories)
2//!
3//! The vfs driver is Docker's universal fallback - it uses plain directories
4//! with no optimization. This driver always works on all platforms.
5//!
6//! In our case, it creates standard git worktrees using libgit2 without
7//! any storage optimization layers underneath.
8
9use super::driver::{Driver, DriverFactory, DriverOpts, WorktreeHandle};
10use crate::errors::{Git2DBError, Git2DBResult};
11use async_trait::async_trait;
12use std::path::Path;
13use tracing::{info, warn};
14
15inventory::submit!(DriverFactory::new("vfs", || Box::new(VfsDriver)));
16
17/// VFS storage driver (plain git worktree, no optimization)
18///
19/// This is the universal fallback that always works. It creates standard
20/// git worktrees using libgit2 without any CoW or space-saving features.
21pub struct VfsDriver;
22
23#[async_trait]
24impl Driver for VfsDriver {
25    fn name(&self) -> &'static str {
26        "vfs"
27    }
28
29    fn is_available(&self) -> bool {
30        // VFS is always available (it's just plain directories)
31        true
32    }
33
34    async fn create_worktree(&self, opts: &DriverOpts) -> Git2DBResult<WorktreeHandle> {
35        // Strict: worktree path must not exist
36        if opts.worktree_path.exists() {
37            return Err(Git2DBError::worktree_exists(&opts.worktree_path));
38        }
39
40        // Validate inputs
41        if !opts.base_repo.exists() {
42            return Err(Git2DBError::invalid_path(
43                opts.base_repo.clone(),
44                "Base repository does not exist",
45            ));
46        }
47
48        // Ensure parent directory exists
49        if let Some(parent) = opts.worktree_path.parent() {
50            tokio::fs::create_dir_all(parent).await.map_err(|e| {
51                Git2DBError::internal(format!("Failed to create parent directory: {e}"))
52            })?;
53        }
54
55        info!(
56            "Creating vfs worktree: base={}, path={}, ref={}",
57            opts.base_repo.display(),
58            opts.worktree_path.display(),
59            opts.ref_spec
60        );
61
62        // Create git worktree using libgit2
63        self.create_git_worktree(opts).await?;
64
65        // Return handle (no special cleanup needed for plain directories)
66        Ok(WorktreeHandle::new(
67            opts.worktree_path.clone(),
68            "vfs".to_owned(),
69        ))
70    }
71
72    async fn get_worktrees(&self, base_repo: &Path) -> Git2DBResult<Vec<WorktreeHandle>> {
73        let worktrees_dir = base_repo
74            .parent()
75            .ok_or_else(|| {
76                Git2DBError::invalid_path(base_repo.to_path_buf(), "Invalid base repository path")
77            })?
78            .join("worktrees");
79
80        let mut worktrees = Vec::new();
81
82        if !worktrees_dir.exists() {
83            return Ok(worktrees);
84        }
85
86        // Read worktrees directory
87        for entry in std::fs::read_dir(&worktrees_dir)? {
88            let entry = entry?;
89            let worktree_path = entry.path();
90
91            // Skip non-directories and git's internal directories
92            if !worktree_path.is_dir()
93                || worktree_path
94                    .file_name()
95                    .is_some_and(|name| name.to_string_lossy().starts_with(".git"))
96            {
97                continue;
98            }
99
100            // For VFS driver, any directory with a .git inside is a valid worktree
101            if worktree_path.join(".git").exists() {
102                worktrees.push(WorktreeHandle::new(worktree_path, "vfs".to_owned()));
103            }
104        }
105
106        Ok(worktrees)
107    }
108
109    async fn get_worktree(
110        &self,
111        base_repo: &Path,
112        branch: &str,
113    ) -> Git2DBResult<Option<WorktreeHandle>> {
114        let worktrees_dir = base_repo
115            .parent()
116            .ok_or_else(|| {
117                Git2DBError::invalid_path(base_repo.to_path_buf(), "Invalid base repository path")
118            })?
119            .join("worktrees");
120        let worktree_path = hyprstream_containedfs::contained_join(&worktrees_dir, branch)
121            .map_err(|e| {
122                Git2DBError::invalid_path(worktrees_dir, format!("Path containment: {e}"))
123            })?;
124
125        if worktree_path.exists() && worktree_path.join(".git").exists() {
126            Ok(Some(WorktreeHandle::new(worktree_path, "vfs".to_owned())))
127        } else {
128            Ok(None)
129        }
130    }
131}
132
133/// Skip-worktree flag in git index extended flags.
134///
135/// When set on an index entry, `checkout_head()` will not overwrite the
136/// (absent) working-tree file, preventing re-materialization of filtered-out
137/// paths on subsequent checkouts.
138pub(crate) const GIT_INDEX_ENTRY_SKIP_WORKTREE: u16 = 0x4000;
139
140/// Check whether `path` matches any of the `keep_paths` with proper path-boundary semantics.
141///
142/// A keep_path ending with `/` is a directory prefix: `backends/cuda130/` matches
143/// `backends/cuda130/lib.so` but NOT `backends/cuda130_old/lib.so`.
144/// A keep_path without `/` suffix requires exact match or a `/`-separated prefix:
145/// `manifest.toml` matches `manifest.toml` but NOT `manifest.toml.bak`.
146fn path_matches_keep(path: &str, keep: &str) -> bool {
147    if keep.ends_with('/') {
148        path.starts_with(keep)
149    } else {
150        path == keep || path.starts_with(&format!("{keep}/"))
151    }
152}
153
154/// Apply pathspec filtering to a worktree after creation.
155///
156/// 1. Re-checkout with only the matching paths materialized
157/// 2. Remove working-tree files that don't match
158/// 3. Set skip-worktree bits on excluded index entries
159///
160/// Shared by VFS and overlay2 drivers.
161pub(crate) fn apply_pathspec_filter(
162    worktree_path: &std::path::Path,
163    keep_paths: &[String],
164) -> Git2DBResult<()> {
165    let wt_repo = git2::Repository::open(worktree_path)
166        .map_err(|e| Git2DBError::internal(format!("Failed to open worktree: {e}")))?;
167
168    info!(
169        "Applying pathspec filter to worktree at {}: {:?}",
170        worktree_path.display(),
171        keep_paths
172    );
173
174    // Step 1: Remove working-tree files that don't match keep_paths
175    {
176        let index = wt_repo
177            .index()
178            .map_err(|e| Git2DBError::internal(format!("Failed to open index: {e}")))?;
179        for i in 0..index.len() {
180            let entry = match index.get(i) {
181                Some(e) => e,
182                None => continue,
183            };
184            let path = String::from_utf8_lossy(&entry.path).to_string();
185            let keep = keep_paths.iter().any(|p| path_matches_keep(&path, p));
186            if !keep {
187                let full_path = worktree_path.join(&path);
188                if full_path.exists() {
189                    if let Err(e) = std::fs::remove_file(&full_path) {
190                        warn!(
191                            "Could not remove filtered path {}: {e}",
192                            full_path.display()
193                        );
194                    }
195                }
196            }
197        }
198        // Clean up empty directories left behind
199        remove_empty_dirs(worktree_path);
200    }
201
202    // Step 2: Set skip-worktree bits on excluded index entries
203    mark_skip_worktree(&wt_repo, keep_paths)?;
204
205    let index = wt_repo
206        .index()
207        .map_err(|e| Git2DBError::internal(format!("Failed to open index: {e}")))?;
208    let total = index.len();
209    let skipped = (0..total)
210        .filter(|i| {
211            index
212                .get(*i)
213                .map(|e| e.flags_extended & GIT_INDEX_ENTRY_SKIP_WORKTREE != 0)
214                .unwrap_or(false)
215        })
216        .count();
217
218    info!(
219        "Pathspec filter applied: {}/{} entries materialized, {} skipped",
220        total - skipped,
221        total,
222        skipped
223    );
224
225    Ok(())
226}
227
228/// Set `GIT_INDEX_ENTRY_SKIP_WORKTREE` on index entries that don't match
229/// the keep_paths prefixes. This prevents `checkout_head()` from
230/// re-materializing them on subsequent operations.
231pub(crate) fn mark_skip_worktree(
232    repo: &git2::Repository,
233    keep_paths: &[String],
234) -> Git2DBResult<()> {
235    let mut index = repo
236        .index()
237        .map_err(|e| Git2DBError::internal(format!("Failed to open index: {e}")))?;
238
239    for i in 0..index.len() {
240        let entry = match index.get(i) {
241            Some(e) => e,
242            None => continue,
243        };
244        let path = String::from_utf8_lossy(&entry.path).to_string();
245        let dominated = keep_paths.iter().any(|p| path_matches_keep(&path, p));
246        if !dominated {
247            let mut modified = entry;
248            modified.flags_extended |= GIT_INDEX_ENTRY_SKIP_WORKTREE;
249            index.add(&modified).map_err(|e| {
250                Git2DBError::internal(format!("Failed to set skip-worktree on '{}': {e}", path))
251            })?;
252        }
253    }
254
255    index
256        .write()
257        .map_err(|e| Git2DBError::internal(format!("Failed to write index: {e}")))?;
258
259    Ok(())
260}
261
262/// Recursively remove empty directories under `root`, ignoring `.git`.
263fn remove_empty_dirs(root: &std::path::Path) {
264    fn walk(dir: &std::path::Path) -> bool {
265        let Ok(entries) = std::fs::read_dir(dir) else {
266            return false;
267        };
268        let mut has_files = false;
269        for entry in entries.flatten() {
270            let path = entry.path();
271            let name = entry.file_name();
272            if name == ".git" {
273                has_files = true;
274                continue;
275            }
276            if path.is_dir() {
277                if walk(&path) {
278                    has_files = true;
279                } else {
280                    let _ = std::fs::remove_dir(&path);
281                }
282            } else {
283                has_files = true;
284            }
285        }
286        has_files
287    }
288    walk(root);
289}
290
291impl VfsDriver {
292    /// Create git worktree using libgit2 with unified ref support
293    ///
294    /// Supports any git ref: branches, commits, tags, symbolic refs (HEAD~3), etc.
295    /// When `opts.checkout_paths` is set, only matching files are materialized
296    /// and excluded entries get skip-worktree bits.
297    async fn create_git_worktree(&self, opts: &DriverOpts) -> Git2DBResult<()> {
298        let base_repo = opts.base_repo.clone();
299        let worktree_path = opts.worktree_path.clone();
300        let ref_spec = opts.ref_spec.clone();
301        let progress = opts.progress.clone();
302
303        tokio::task::spawn_blocking(move || {
304            // Set up smudge progress hook if progress reporter is available
305            if let Some(ref reporter) = progress {
306                let r = std::sync::Arc::clone(reporter);
307                git_xet_filter::set_smudge_progress(std::sync::Arc::new(move |count, _path| {
308                    r.report("smudge", count, 0);
309                }));
310            }
311
312            let result = (|| -> Git2DBResult<()> {
313                let repo = git2::Repository::open(&base_repo).map_err(|e| {
314                    Git2DBError::internal(format!("Failed to open repository: {e}"))
315                })?;
316
317                let object = repo.revparse_single(&ref_spec).map_err(|e| {
318                    Git2DBError::internal(format!("Failed to resolve ref '{}': {}", ref_spec, e))
319                })?;
320
321                let commit = object.peel_to_commit().map_err(|e| {
322                    Git2DBError::internal(format!(
323                        "Ref '{}' does not point to a commit: {}",
324                        ref_spec, e
325                    ))
326                })?;
327
328                let branch_ref_name = format!("refs/heads/{}", ref_spec);
329                let is_branch = repo.find_reference(&branch_ref_name).is_ok();
330
331                let worktree_name = worktree_path
332                    .file_name()
333                    .and_then(|n| n.to_str())
334                    .ok_or_else(|| {
335                        Git2DBError::invalid_path(worktree_path.clone(), "Invalid worktree path")
336                    })?;
337
338                if is_branch {
339                    let reference = repo.find_reference(&branch_ref_name)?;
340                    repo.worktree(
341                        worktree_name,
342                        &worktree_path,
343                        Some(git2::WorktreeAddOptions::new().reference(Some(&reference))),
344                    )
345                    .map_err(|e| {
346                        Git2DBError::internal(format!("Failed to create worktree: {e}"))
347                    })?;
348
349                    info!(
350                        "Created git worktree at {} for branch '{}' (commit: {})",
351                        worktree_path.display(),
352                        ref_spec,
353                        commit.id()
354                    );
355                } else {
356                    repo.worktree(worktree_name, &worktree_path, None)
357                        .map_err(|e| {
358                            Git2DBError::internal(format!("Failed to create worktree: {e}"))
359                        })?;
360
361                    let wt_repo = git2::Repository::open(&worktree_path)?;
362                    wt_repo.set_head_detached(commit.id()).map_err(|e| {
363                        Git2DBError::internal(format!("Failed to set detached HEAD: {e}"))
364                    })?;
365
366                    wt_repo
367                        .checkout_head(Some(git2::build::CheckoutBuilder::default().force()))
368                        .map_err(|e| {
369                            Git2DBError::internal(format!("Failed to checkout HEAD: {e}"))
370                        })?;
371
372                    info!(
373                        "Created git worktree at {} for ref '{}' (detached HEAD at {})",
374                        worktree_path.display(),
375                        ref_spec,
376                        commit.id()
377                    );
378                }
379
380                Ok(())
381            })();
382
383            // Always clear smudge progress hook
384            git_xet_filter::clear_smudge_progress();
385
386            result
387        })
388        .await
389        .map_err(|e| Git2DBError::internal(format!("Task join error: {e}")))??;
390
391        // Apply pathspec filter if requested
392        if let Some(ref paths) = opts.checkout_paths {
393            apply_pathspec_filter(&opts.worktree_path, paths)?;
394        }
395
396        Ok(())
397    }
398}
399
400#[cfg(test)]
401mod tests {
402    use super::*;
403
404    #[test]
405    fn test_driver_name() {
406        let driver = VfsDriver;
407        assert_eq!(driver.name(), "vfs");
408    }
409
410    #[test]
411    fn test_always_available() {
412        let driver = VfsDriver;
413        assert!(driver.is_available());
414    }
415
416    /// #427: `create_git_worktree` must propagate the real libgit2 failure
417    /// instead of discarding it. Previously the inner `Git2DBResult<()>` was
418    /// thrown away via `let _ = spawn_blocking(...).await...?` — only the
419    /// *join* error was checked, so any failure inside the closure (e.g. a
420    /// ref that doesn't resolve, or a worktree-add failure) was silently
421    /// swallowed and `create_git_worktree` returned `Ok(())` regardless.
422    #[tokio::test]
423    async fn create_git_worktree_propagates_inner_error() -> Result<(), Box<dyn std::error::Error>>
424    {
425        // A repo with no commits at all: `ref_spec` cannot resolve to
426        // anything, so libgit2's `revparse_single` fails inside the
427        // spawn_blocking closure — exactly the kind of failure that used to
428        // be discarded.
429        let base_dir = tempfile::tempdir()?;
430        let repo_path = base_dir.path().join("repo");
431        std::fs::create_dir_all(&repo_path)?;
432        git2::Repository::init(&repo_path)?;
433
434        let opts = DriverOpts {
435            base_repo: repo_path.clone(),
436            worktree_path: base_dir.path().join("worktree"),
437            ref_spec: "does-not-exist".to_owned(),
438            progress: None,
439            checkout_paths: None,
440        };
441
442        let driver = VfsDriver;
443        match driver.create_git_worktree(&opts).await {
444            Ok(()) => panic!(
445                "create_git_worktree must fail when ref_spec cannot be resolved, not silently succeed"
446            ),
447            Err(e) => {
448                let msg = e.to_string();
449                assert!(
450                    msg.contains("Failed to resolve ref") || msg.contains("does-not-exist"),
451                    "error must surface the real libgit2 failure, got: {msg}"
452                );
453            }
454        }
455        Ok(())
456    }
457}