Skip to main content

git2db/storage/
overlay2.rs

1//! Overlay2 driver (Linux overlayfs)
2#[cfg(all(target_os = "linux", feature = "overlayfs"))]
3use super::driver::DriverFactory;
4use super::driver::{Driver, DriverOpts, WorktreeHandle};
5use crate::errors::{Git2DBError, Git2DBResult};
6use async_trait::async_trait;
7use std::path::Path;
8#[cfg(all(target_os = "linux", feature = "overlayfs"))]
9use tokio::process::Command;
10#[cfg(all(target_os = "linux", feature = "overlayfs"))]
11use tracing::{debug, info, warn};
12
13#[cfg(all(target_os = "linux", feature = "overlayfs"))]
14inventory::submit!(DriverFactory::new("overlay2", || Box::new(Overlay2Driver)));
15
16/// Overlay2 storage driver (Linux overlayfs)
17///
18/// Automatically tries mount methods in order: kernel → userns → fuse.
19///
20/// # Role in the writable union (#394)
21///
22/// This driver mounts the per-worktree overlay whose **upper** directory is
23/// the node-local, append-only writable layer of the union namespace. The
24/// union copy-up primitive lives in `hyprstream_vfs::Namespace` (above this
25/// driver): a write to a path that exists only in the read-only `/oid` floor
26/// is redirected to the writable upper, which the kernel overlayfs presents as
27/// a regular filesystem. Promote (`hyprstream::git::promote`) snapshots the
28/// upper via `stageAll` + `commit`, draining it into an immutable
29/// content-addressed registry commit; after promote the upper is empty and the
30/// floor advances to the new commit.
31#[allow(dead_code)] // Constructed via inventory::submit! when overlayfs feature enabled
32pub struct Overlay2Driver;
33
34#[async_trait]
35impl Driver for Overlay2Driver {
36    fn name(&self) -> &'static str {
37        "overlay2"
38    }
39
40    fn is_available(&self) -> bool {
41        #[cfg(all(target_os = "linux", feature = "overlayfs"))]
42        {
43            // Check if overlay filesystem is supported by kernel
44            if let Ok(filesystems) = std::fs::read_to_string("/proc/filesystems") {
45                filesystems.contains("overlay")
46            } else {
47                false
48            }
49        }
50
51        #[cfg(not(all(target_os = "linux", feature = "overlayfs")))]
52        false
53    }
54
55    #[cfg(feature = "overlayfs")]
56    async fn create_worktree(&self, opts: &DriverOpts) -> Git2DBResult<WorktreeHandle> {
57        // Strict: worktree path must not exist
58        if opts.worktree_path.exists() {
59            return Err(Git2DBError::worktree_exists(&opts.worktree_path));
60        }
61
62        // Validate inputs
63        if !opts.base_repo.exists() {
64            return Err(Git2DBError::invalid_path(
65                opts.base_repo.clone(),
66                "Base repository does not exist",
67            ));
68        }
69
70        // Generate unique ID
71        let id = format!("git2db-{}", uuid::Uuid::new_v4());
72
73        // Create overlay directories in a separate location
74        let overlay_base = opts
75            .worktree_path
76            .parent()
77            .ok_or_else(|| {
78                Git2DBError::invalid_path(
79                    opts.worktree_path.clone(),
80                    "Worktree path has no parent directory",
81                )
82            })?
83            .join(".git2db-overlay")
84            .join(&id);
85
86        let upper_dir = overlay_base.join("upper");
87        let work_dir = overlay_base.join("work");
88        let mount_dir = overlay_base.join("mount");
89
90        tokio::fs::create_dir_all(&upper_dir)
91            .await
92            .map_err(|e| Git2DBError::internal(format!("Failed to create upper directory: {e}")))?;
93        tokio::fs::create_dir_all(&work_dir)
94            .await
95            .map_err(|e| Git2DBError::internal(format!("Failed to create work directory: {e}")))?;
96        tokio::fs::create_dir_all(&mount_dir)
97            .await
98            .map_err(|e| Git2DBError::internal(format!("Failed to create mount point: {e}")))?;
99
100        info!(
101            "Creating overlay2 worktree: id={}, lower={}, mount={}",
102            id,
103            opts.base_repo.display(),
104            mount_dir.display()
105        );
106
107        // Try mounting with fallback strategy
108        let mount_method = self
109            .try_mount_overlayfs(&opts.base_repo, &upper_dir, &work_dir, &mount_dir)
110            .await?;
111
112        info!("Successfully mounted using {}", mount_method);
113
114        // Create git worktree at the desired path
115        self.create_git_worktree(
116            &opts.base_repo,
117            &opts.worktree_path,
118            &opts.ref_spec,
119            opts.progress.clone(),
120        )
121        .await?;
122
123        // Apply pathspec filter if requested
124        if let Some(ref paths) = opts.checkout_paths {
125            super::vfs::apply_pathspec_filter(&opts.worktree_path, paths)?;
126        }
127
128        // Create handle with cleanup
129        let mount_point = mount_dir.clone();
130        let upper = upper_dir.clone();
131        let work = work_dir.clone();
132        let id_clone = id.clone();
133
134        let cleanup = move || async move {
135            let mount_point = mount_point.clone();
136            let upper = upper.clone();
137            let work = work.clone();
138            let id = id_clone.clone();
139
140            info!("Cleaning up overlay2 worktree {}", id);
141
142            // Unmount (try fusermount first, then umount)
143            if let Err(e) = Self::unmount_overlayfs(&mount_point).await {
144                warn!(
145                    "Failed to unmount {} in cleanup: {}",
146                    mount_point.display(),
147                    e
148                );
149            }
150
151            // Remove overlay directories
152            if let Err(e) = tokio::fs::remove_dir_all(&upper).await {
153                warn!("Failed to remove upper dir {}: {}", upper.display(), e);
154            }
155            if let Err(e) = tokio::fs::remove_dir_all(&work).await {
156                warn!("Failed to remove work dir {}: {}", work.display(), e);
157            }
158            if let Err(e) = tokio::fs::remove_dir_all(&mount_point).await {
159                warn!(
160                    "Failed to remove mount point {}: {}",
161                    mount_point.display(),
162                    e
163                );
164            }
165
166            Ok(())
167        };
168
169        Ok(WorktreeHandle::with_cleanup(
170            opts.worktree_path.clone(),
171            format!("overlay2-{mount_method}"),
172            cleanup,
173        ))
174    }
175
176    #[cfg(not(feature = "overlayfs"))]
177    async fn create_worktree(&self, _opts: &DriverOpts) -> Git2DBResult<WorktreeHandle> {
178        Err(Git2DBError::internal(
179            "overlay2 driver requires 'overlayfs' feature to be enabled",
180        ))
181    }
182
183    #[cfg(feature = "overlayfs")]
184    async fn get_worktrees(&self, base_repo: &Path) -> Git2DBResult<Vec<WorktreeHandle>> {
185        let worktrees_dir = base_repo
186            .parent()
187            .ok_or_else(|| {
188                Git2DBError::invalid_path(base_repo.to_path_buf(), "Invalid base repository path")
189            })?
190            .join("worktrees");
191
192        let mut worktrees = Vec::new();
193
194        if !worktrees_dir.exists() {
195            return Ok(worktrees);
196        }
197
198        // Read worktrees directory
199        for entry in std::fs::read_dir(&worktrees_dir)? {
200            let entry = entry?;
201            let worktree_path = entry.path();
202
203            // Skip non-directories and git's internal directories
204            if !worktree_path.is_dir()
205                || worktree_path
206                    .file_name()
207                    .is_some_and(|name| name.to_string_lossy().starts_with(".git"))
208            {
209                continue;
210            }
211
212            // Check if this is an overlay2 worktree by looking for overlay signatures
213            if self.is_overlay2_worktree(&worktree_path) {
214                worktrees.push(WorktreeHandle::new(worktree_path, "overlay2".to_owned()));
215            }
216        }
217
218        Ok(worktrees)
219    }
220
221    #[cfg(feature = "overlayfs")]
222    async fn get_worktree(
223        &self,
224        base_repo: &Path,
225        branch: &str,
226    ) -> Git2DBResult<Option<WorktreeHandle>> {
227        let worktrees_dir = base_repo
228            .parent()
229            .ok_or_else(|| {
230                Git2DBError::invalid_path(base_repo.to_path_buf(), "Invalid base repository path")
231            })?
232            .join("worktrees");
233        let worktree_path = hyprstream_containedfs::contained_join(&worktrees_dir, branch)
234            .map_err(|e| {
235                Git2DBError::invalid_path(worktrees_dir, format!("Path containment: {e}"))
236            })?;
237
238        if worktree_path.exists() && self.is_overlay2_worktree(&worktree_path) {
239            Ok(Some(WorktreeHandle::new(
240                worktree_path,
241                "overlay2".to_owned(),
242            )))
243        } else {
244            Ok(None)
245        }
246    }
247
248    #[cfg(not(feature = "overlayfs"))]
249    async fn get_worktrees(&self, _base_repo: &Path) -> Git2DBResult<Vec<WorktreeHandle>> {
250        Err(Git2DBError::internal(
251            "overlay2 driver requires 'overlayfs' feature to be enabled",
252        ))
253    }
254
255    #[cfg(not(feature = "overlayfs"))]
256    async fn get_worktree(
257        &self,
258        _base_repo: &Path,
259        _branch: &str,
260    ) -> Git2DBResult<Option<WorktreeHandle>> {
261        Err(Git2DBError::internal(
262            "overlay2 driver requires 'overlayfs' feature to be enabled",
263        ))
264    }
265}
266
267#[cfg(all(target_os = "linux", feature = "overlayfs"))]
268impl Overlay2Driver {
269    /// Try mounting overlayfs with automatic fallback strategy
270    ///
271    /// Attempts methods in order of preference:
272    /// 1. Kernel overlayfs (fastest, requires CAP_SYS_ADMIN or user namespace)
273    /// 2. User namespace overlayfs (good perf, unprivileged, requires kernel support)
274    /// 3. FUSE overlayfs (slow but compatible, requires fuse-overlayfs binary)
275    async fn try_mount_overlayfs(
276        &self,
277        lower: &Path,
278        upper: &Path,
279        work: &Path,
280        target: &Path,
281    ) -> Git2DBResult<String> {
282        // S1 fix: Validate paths don't contain characters that could inject mount options
283        for (name, path) in &[
284            ("lower", lower),
285            ("upper", upper),
286            ("work", work),
287            ("target", target),
288        ] {
289            if let Some(s) = path.to_str() {
290                if s.contains(',') || s.contains('=') || s.contains('\n') || s.contains('\0') {
291                    return Err(Git2DBError::internal(format!(
292                        "{} path contains characters unsafe for mount options: {:?}",
293                        name, path
294                    )));
295                }
296            } else {
297                return Err(Git2DBError::internal(format!(
298                    "{} path is not valid UTF-8: {:?}",
299                    name, path
300                )));
301            }
302        }
303
304        // Build common mount options
305        let mount_opts = format!(
306            "lowerdir={},upperdir={},workdir={}",
307            lower.display(),
308            upper.display(),
309            work.display()
310        );
311
312        // Try 1: Kernel overlayfs (fastest)
313        if let Ok(filesystems) = std::fs::read_to_string("/proc/filesystems") {
314            if filesystems.contains("overlay") {
315                debug!("Attempting kernel overlayfs mount");
316                match Self::mount_kernel(target, &mount_opts).await {
317                    Ok(()) => {
318                        return Ok("kernel".to_owned());
319                    }
320                    Err(e) => {
321                        debug!("Kernel overlayfs failed, trying next method: {}", e);
322                    }
323                }
324            }
325        }
326
327        // Try 2: User namespace overlayfs (unprivileged)
328        if Self::can_use_userns().await {
329            debug!("Attempting user namespace overlayfs mount");
330            match Self::mount_userns(lower, upper, work, target).await {
331                Ok(()) => {
332                    return Ok("userns".to_owned());
333                }
334                Err(e) => {
335                    debug!("User namespace mount failed, trying next method: {}", e);
336                }
337            }
338        }
339
340        // Try 3: FUSE overlayfs (most compatible)
341        debug!("Attempting FUSE overlayfs mount");
342        match Self::mount_fuse(target, &mount_opts).await {
343            Ok(()) => {
344                return Ok("fuse".to_owned());
345            }
346            Err(e) => {
347                debug!("FUSE overlayfs failed: {}", e);
348            }
349        }
350
351        // All methods failed
352        Err(Git2DBError::internal(
353            "All overlayfs mount methods failed. Ensure one of: \
354             1) Kernel overlayfs + CAP_SYS_ADMIN capability, \
355             2) User namespace support (unprivileged_userns_clone=1), \
356             3) fuse-overlayfs binary installed and available"
357                .to_owned(),
358        ))
359    }
360
361    /// Mount using kernel overlayfs syscall
362    #[cfg(all(target_os = "linux", feature = "overlayfs"))]
363    async fn mount_kernel(target: &Path, mount_opts: &str) -> Git2DBResult<()> {
364        use nix::mount::{mount, MsFlags};
365
366        mount(
367            Some("overlay"),
368            target,
369            Some("overlay"),
370            MsFlags::empty(),
371            Some(mount_opts),
372        )
373        .map_err(|e| Git2DBError::internal(format!("Failed to mount kernel overlayfs: {e}")))
374    }
375
376    /// Check if user namespaces are available
377    async fn can_use_userns() -> bool {
378        // Check sysctl setting
379        if let Ok(content) = std::fs::read_to_string("/proc/sys/kernel/unprivileged_userns_clone") {
380            return content.trim() == "1";
381        }
382
383        // Try to create a test namespace
384        use nix::sched::{unshare, CloneFlags};
385        unshare(CloneFlags::CLONE_NEWUSER).is_ok()
386    }
387
388    /// Mount using user namespace
389    async fn mount_userns(
390        lower: &Path,
391        upper: &Path,
392        work: &Path,
393        target: &Path,
394    ) -> Git2DBResult<()> {
395        let mount_opts = format!(
396            "lowerdir={},upperdir={},workdir={},userxattr",
397            lower.display(),
398            upper.display(),
399            work.display()
400        );
401
402        let output = Command::new("unshare")
403            .arg("--user")
404            .arg("--map-root-user")
405            .arg("--mount")
406            .arg("mount")
407            .arg("-t")
408            .arg("overlay")
409            .arg("overlay")
410            .arg("-o")
411            .arg(&mount_opts)
412            .arg(target)
413            .output()
414            .await
415            .map_err(|e| Git2DBError::internal(format!("Failed to execute unshare: {e}")))?;
416
417        if !output.status.success() {
418            let stderr = String::from_utf8_lossy(&output.stderr);
419            return Err(Git2DBError::internal(format!(
420                "User namespace mount failed: {stderr}"
421            )));
422        }
423
424        Ok(())
425    }
426
427    /// Mount using FUSE overlayfs
428    async fn mount_fuse(target: &Path, mount_opts: &str) -> Git2DBResult<()> {
429        let output = Command::new("fuse-overlayfs")
430            .arg("-o")
431            .arg(mount_opts)
432            .arg(target)
433            .output()
434            .await
435            .map_err(|e| Git2DBError::internal(format!("Failed to execute fuse-overlayfs: {e}")))?;
436
437        if !output.status.success() {
438            let stderr = String::from_utf8_lossy(&output.stderr);
439            return Err(Git2DBError::internal(format!(
440                "FUSE overlayfs failed: {stderr}"
441            )));
442        }
443
444        Ok(())
445    }
446
447    /// Unmount overlayfs (try fusermount first, then umount)
448    async fn unmount_overlayfs(target: &Path) -> Git2DBResult<()> {
449        // Try fusermount first (for FUSE mounts)
450        let fusermount_output = Command::new("fusermount")
451            .arg("-u")
452            .arg(target)
453            .output()
454            .await;
455
456        if let Ok(output) = fusermount_output {
457            if output.status.success() {
458                return Ok(());
459            }
460        }
461
462        // Fallback to umount
463        let output = Command::new("umount")
464            .arg(target)
465            .output()
466            .await
467            .map_err(|e| Git2DBError::internal(format!("Failed to execute umount: {e}")))?;
468
469        if !output.status.success() {
470            // Try lazy unmount as last resort
471            let _ = Command::new("umount").arg("-l").arg(target).output().await;
472        }
473
474        Ok(())
475    }
476}
477
478#[cfg(feature = "overlayfs")]
479impl Overlay2Driver {
480    /// Create git worktree using libgit2 with unified ref support
481    ///
482    /// Note: The overlay is already mounted by the driver.
483    /// We just need to create the git worktree structure on top of it.
484    async fn create_git_worktree(
485        &self,
486        base_repo: &Path,
487        worktree_path: &Path,
488        ref_spec: &str,
489        progress: Option<std::sync::Arc<dyn crate::callback_config::ProgressReporter>>,
490    ) -> Git2DBResult<()> {
491        let base_repo = base_repo.to_path_buf();
492        let worktree_path = worktree_path.to_path_buf();
493        let ref_spec = ref_spec.to_owned();
494
495        tokio::task::spawn_blocking(move || {
496            // Set up smudge progress hook if progress reporter is available
497            if let Some(ref reporter) = progress {
498                let r = std::sync::Arc::clone(reporter);
499                git_xet_filter::set_smudge_progress(std::sync::Arc::new(move |count, _path| {
500                    r.report("smudge", count, 0);
501                }));
502            }
503
504            let result = (|| -> Git2DBResult<()> {
505                let repo = git2::Repository::open(&base_repo).map_err(|e| {
506                    Git2DBError::internal(format!("Failed to open repository: {e}"))
507                })?;
508
509                let object = repo.revparse_single(&ref_spec).map_err(|e| {
510                    Git2DBError::internal(format!("Failed to resolve ref '{ref_spec}': {e}"))
511                })?;
512
513                let commit = object.peel_to_commit().map_err(|e| {
514                    Git2DBError::internal(format!(
515                        "Ref '{ref_spec}' does not point to a commit: {e}"
516                    ))
517                })?;
518
519                let branch_ref_name = format!("refs/heads/{ref_spec}");
520                let is_branch = repo.find_reference(&branch_ref_name).is_ok();
521
522                let worktree_name = worktree_path
523                    .file_name()
524                    .and_then(|n| n.to_str())
525                    .ok_or_else(|| {
526                        Git2DBError::invalid_path(worktree_path.clone(), "Invalid worktree path")
527                    })?;
528
529                if is_branch {
530                    let reference = repo.find_reference(&branch_ref_name)?;
531                    repo.worktree(
532                        worktree_name,
533                        &worktree_path,
534                        Some(git2::WorktreeAddOptions::new().reference(Some(&reference))),
535                    )
536                    .map_err(|e| {
537                        Git2DBError::internal(format!("Failed to create worktree: {e}"))
538                    })?;
539
540                    info!(
541                        "Created overlay2 worktree at {} for branch '{}' (commit: {})",
542                        worktree_path.display(),
543                        ref_spec,
544                        commit.id()
545                    );
546                } else {
547                    repo.worktree(worktree_name, &worktree_path, None)
548                        .map_err(|e| {
549                            Git2DBError::internal(format!("Failed to create worktree: {e}"))
550                        })?;
551
552                    let wt_repo = git2::Repository::open(&worktree_path)?;
553                    wt_repo.set_head_detached(commit.id())?;
554                    wt_repo.checkout_head(Some(git2::build::CheckoutBuilder::default().force()))?;
555
556                    info!(
557                        "Created overlay2 worktree at {} for ref '{}' (detached HEAD at {})",
558                        worktree_path.display(),
559                        ref_spec,
560                        commit.id()
561                    );
562                }
563
564                Ok(())
565            })();
566
567            // Always clear smudge progress hook
568            git_xet_filter::clear_smudge_progress();
569
570            result
571        })
572        .await
573        .map_err(|e| Git2DBError::internal(format!("Task join error: {e}")))?
574    }
575
576    /// Check if a worktree is managed by overlay2 driver
577    fn is_overlay2_worktree(&self, worktree_path: &Path) -> bool {
578        // Check for overlay2 signatures
579        let overlay_path = worktree_path.join(".overlay");
580        let git_overlay_path = worktree_path.join(".git").join("overlay");
581
582        // Also check for overlayfs mount signatures
583        let has_overlay_sig = overlay_path.exists() || git_overlay_path.exists();
584
585        // Additional check: look for overlay mount points in /proc/mounts
586        if has_overlay_sig {
587            if let Ok(mounts) = std::fs::read_to_string("/proc/mounts") {
588                let worktree_str = worktree_path.to_string_lossy();
589                if mounts.contains(&*worktree_str) {
590                    return true;
591                }
592            }
593        }
594
595        has_overlay_sig
596    }
597}
598
599#[cfg(test)]
600#[allow(clippy::print_stdout)]
601mod tests {
602    use super::*;
603
604    #[test]
605    fn test_driver_name() {
606        assert_eq!(Overlay2Driver.name(), "overlay2");
607    }
608
609    #[test]
610    #[cfg(all(feature = "overlayfs", target_os = "linux"))]
611    fn test_availability() {
612        // May or may not be available depending on system
613        println!("Overlay2 available: {}", Overlay2Driver.is_available());
614    }
615}