Skip to content

Modern Docker Management, Designed for Everyone

fix: scope project update backup to changed files and lazy-load file tree (#3158)

Kyle Mendell1cb5ed204fe0
diff --git a/backend/api/handlers/projects.go b/backend/api/handlers/projects.go
index 0c8ac2269..d2304d2fc 100644
--- a/backend/api/handlers/projects.go
+++ b/backend/api/handlers/projects.go
@@ -965,7 +965,18 @@ func (h *ProjectHandler) UpdateProject(ctx context.Context, input *UpdateProject
return nil, huma.Error400BadRequest((&common.ProjectUpdateError{Err: err}).Error())
}
- details, err := h.projectService.GetProjectDetails(runtimeCtx, input.ProjectID, project.AllDetails())
+ // Skip the recursive directory walks on save: the file tree is only
+ // re-read when the save actually staged file changes (fresh revision),
+ // and the frontend fetches /files lazily otherwise.
+ details, err := h.projectService.GetProjectDetails(runtimeCtx, input.ProjectID, project.DetailsOptions{
+ IncludeComposeContent: true,
+ IncludeEnvState: true,
+ IncludeIncludeFiles: true,
+ IncludeServiceConfigs: true,
+ IncludeProjectFiles: len(input.Body.FileChanges) > 0,
+ IncludeRuntimeServices: true,
+ IncludeUpdateInfo: true,
+ })
if err != nil {
return nil, huma.Error500InternalServerError((&common.ProjectDetailsError{Err: err}).Error())
}
@@ -1017,7 +1028,14 @@ func (h *ProjectHandler) UpdateProjectInclude(ctx context.Context, input *Update
return nil, huma.Error400BadRequest((&common.ProjectUpdateError{Err: err}).Error())
}
- details, err := h.projectService.GetProjectDetails(runtimeCtx, input.ProjectID, project.AllDetails())
+ details, err := h.projectService.GetProjectDetails(runtimeCtx, input.ProjectID, project.DetailsOptions{
+ IncludeComposeContent: true,
+ IncludeEnvState: true,
+ IncludeIncludeFiles: true,
+ IncludeServiceConfigs: true,
+ IncludeRuntimeServices: true,
+ IncludeUpdateInfo: true,
+ })
if err != nil {
return nil, huma.Error500InternalServerError((&common.ProjectDetailsError{Err: err}).Error())
}
diff --git a/backend/internal/services/gitops_sync_service.go b/backend/internal/services/gitops_sync_service.go
index 2ba74b79e..1ce520862 100644
--- a/backend/internal/services/gitops_sync_service.go
+++ b/backend/internal/services/gitops_sync_service.go
@@ -1149,7 +1149,7 @@ func (s *GitOpsSyncService) performSwarmStackSyncInternal(ctx context.Context, s
// *common.RedeployAfterSyncFailedError when the redeploy itself fails; callers
// surface that on the sync row's LastSyncError.
func (s *GitOpsSyncService) redeployIfRunningAfterSync(ctx context.Context, project *models.Project, actor models.User, syncMode string) error {
- details, err := s.projectService.GetProjectDetails(ctx, project.ID, projecttypes.AllDetails())
+ details, err := s.projectService.GetProjectDetails(ctx, project.ID, projecttypes.DetailsOptions{})
if err != nil {
return nil //nolint:nilerr // best-effort: skip post-sync redeploy when project state can't be determined
}
@@ -1562,7 +1562,7 @@ func (s *GitOpsSyncService) updateProjectForSyncInternal(ctx context.Context, sy
// is bubbled up as a *common.RedeployAfterSyncFailedError so the parent flow
// can reflect it on the sync row's LastSyncError.
if contentChanged {
- details, err := s.projectService.GetProjectDetails(ctx, project.ID, projecttypes.AllDetails())
+ details, err := s.projectService.GetProjectDetails(ctx, project.ID, projecttypes.DetailsOptions{})
if err == nil && (details.Status == string(models.ProjectStatusRunning) || details.Status == string(models.ProjectStatusPartiallyRunning)) {
slog.InfoContext(ctx, "Redeploying project due to content change from Git sync", "projectName", project.Name, "projectId", project.ID)
if err := s.projectService.RedeployProject(ctx, project.ID, actor, nil); err != nil {
diff --git a/backend/internal/services/gitops_sync_service_test.go b/backend/internal/services/gitops_sync_service_test.go
index 7a3613775..4195582bb 100644
--- a/backend/internal/services/gitops_sync_service_test.go
+++ b/backend/internal/services/gitops_sync_service_test.go
@@ -1397,15 +1397,6 @@ func setupLifecycleValidationService(t *testing.T) (*GitOpsSyncService, context.
return svc, ctx
}
-//go:fix inline
-func strPtr(s string) *string { return new(s) }
-
-//go:fix inline
-func intPtr(i int) *int { return new(i) }
-
-//go:fix inline
-func boolPtr(b bool) *bool { return new(b) }
-
func TestValidateLifecycleConfig_AllNilNoError(t *testing.T) {
svc, ctx := setupLifecycleValidationService(t)
require.NoError(t, svc.validateLifecycleConfigInternal(ctx, nil, lifecycleConfigInputInternal{}))
diff --git a/backend/internal/services/project_service.go b/backend/internal/services/project_service.go
index 2dd20b9c3..dfe60700a 100644
--- a/backend/internal/services/project_service.go
+++ b/backend/internal/services/project_service.go
@@ -10,7 +10,9 @@ import (
"log/slog"
"maps"
"os"
+ "path"
"path/filepath"
+ "slices"
"strings"
"sync"
"time"
@@ -1448,7 +1450,7 @@ func (s *ProjectService) enrichWithProjectFiles(ctx context.Context, projectPath
return
}
- files, revision, err := projects.ReadProjectFileTree(projectPath, s.config.ProjectFileTreeMaxDepth, s.config.ProjectScanSkipDirs, composeFileName)
+ files, revision, truncated, err := projects.ReadProjectFileTree(projectPath, s.config.ProjectFileTreeMaxDepth, s.config.ProjectScanSkipDirs, composeFileName, projects.DefaultProjectFileTreeMaxEntries)
if err != nil {
slog.WarnContext(ctx, "Failed to scan project file tree", "error", err, "path", projectPath)
return
@@ -1456,6 +1458,7 @@ func (s *ProjectService) enrichWithProjectFiles(ctx context.Context, projectPath
resp.ProjectFiles = files
resp.FileTreeRevision = revision
+ resp.FileTreeTruncated = truncated
}
func (s *ProjectService) enrichWithGitOpsInfo(ctx context.Context, proj *models.Project, resp *project.Details) {
@@ -1706,6 +1709,14 @@ func (s *ProjectService) cleanupDBProjectsInternal(ctx context.Context, seen map
tempDeletions = append(tempDeletions, projectCleanupDecision{project: p, reason: "removed internal Arcane scratch record (project-update/gitops temp dir)"})
continue
}
+ // Projects inside filesystem snapshot/trash directories (e.g. BTRFS
+ // #snapshot) are point-in-time copies mistakenly registered by earlier
+ // discovery passes. The decision is name-based, not missing-path-based,
+ // so it bypasses the mass-wipe guard like the scratch records above.
+ if rel := s.getProjectRelativePathInternal(projectsDir, p.Path); rel != "" && projects.PathContainsSnapshotDirectory(rel) {
+ tempDeletions = append(tempDeletions, projectCleanupDecision{project: p, reason: "removed project inside a filesystem snapshot/trash directory"})
+ continue
+ }
candidates++
if decision, remove := s.evaluateProjectCleanupInternal(ctx, p, followProjectSymlinks, projectsDir, maxDepth); remove {
pendingDeletions = append(pendingDeletions, decision)
@@ -2880,7 +2891,7 @@ func (s *ProjectService) UpdateProject(ctx context.Context, projectID string, na
renameJournal := s.prepareProjectRenameJournalInternal(&proj, name, projectsDirectory, volumeMigration)
- backupPath, backupSkipped, cleanupBackup, err := s.prepareProjectUpdateBackupInternal(ctx, projectsDirectory, proj.Path, composeContent, envContent, fileChanges)
+ backup, cleanupBackup, err := s.prepareProjectUpdateBackupInternal(ctx, projectsDirectory, proj.Path, composeContent, envContent, fileChanges)
if err != nil {
return nil, err
}
@@ -2895,7 +2906,7 @@ func (s *ProjectService) UpdateProject(ctx context.Context, projectID string, na
if err := s.withProjectRenameRollback(ctx, &proj, &projectStateCommitted, func() error {
return s.applyProjectUpdateWithRenameJournalInternal(ctx, &proj, name, projectsDirectory, composeContent, envContent, fileTreeRevision, fileChanges, volumeMigration, renameJournal, &journalActive, &projectStateCommitted)
}); err != nil {
- err = s.handleProjectUpdateFailureInternal(ctx, projectID, projectsDirectory, &proj, backupPath, backupSkipped, &journalActive, projectStateCommitted, err)
+ err = s.handleProjectUpdateFailureInternal(ctx, projectID, projectsDirectory, &proj, backup, &journalActive, projectStateCommitted, err)
return nil, err
}
@@ -2927,17 +2938,22 @@ func resolveAuthoritativeProjectNameInternal(proj *models.Project, name *string,
return name
}
-func (s *ProjectService) prepareProjectUpdateBackupInternal(ctx context.Context, projectsDirectory, projectPath string, composeContent, envContent *string, fileChanges []project.ProjectFileChange) (string, []string, func(), error) {
+func (s *ProjectService) prepareProjectUpdateBackupInternal(ctx context.Context, projectsDirectory, projectPath string, composeContent, envContent *string, fileChanges []project.ProjectFileChange) (*projects.ProjectUpdateBackup, func(), error) {
if composeContent == nil && envContent == nil && len(fileChanges) == 0 {
- return "", nil, func() {}, nil
+ return nil, func() {}, nil
}
- backupPath, skipped, err := s.backupProjectDirectoryInternal(ctx, projectsDirectory, projectPath)
+ scope := projectUpdateBackupScopeInternal(projectPath, composeContent, envContent, fileChanges)
+ if scope.IsEmpty() {
+ return nil, func() {}, nil
+ }
+
+ backup, err := s.backupProjectDirectoryInternal(ctx, projectsDirectory, projectPath, scope)
if err != nil {
- return "", nil, nil, err
+ return nil, nil, err
}
- return backupPath, skipped, func() { _ = os.RemoveAll(backupPath) }, nil
+ return backup, func() { _ = os.RemoveAll(backup.BackupDir) }, nil
}
func (s *ProjectService) startProjectRenameJournalInternal(ctx context.Context, journal *projectRenameJournalInternal) (bool, error) {
@@ -3053,13 +3069,13 @@ func (s *ProjectService) completeProjectRenameJournalForUpdateInternal(ctx conte
*journalActive = false
}
-func (s *ProjectService) handleProjectUpdateFailureInternal(ctx context.Context, projectID, projectsDirectory string, proj *models.Project, backupPath string, backupSkipped []string, journalActive *bool, projectStateCommitted bool, err error) error {
+func (s *ProjectService) handleProjectUpdateFailureInternal(ctx context.Context, projectID, projectsDirectory string, proj *models.Project, backup *projects.ProjectUpdateBackup, journalActive *bool, projectStateCommitted bool, err error) error {
if projectStateCommitted {
return err
}
- if backupPath != "" {
- if restoreErr := s.restoreProjectDirectoryBackupInternal(ctx, projectsDirectory, proj.Path, backupPath, backupSkipped); restoreErr != nil {
+ if backup != nil {
+ if restoreErr := s.restoreProjectDirectoryBackupInternal(ctx, projectsDirectory, proj.Path, backup); restoreErr != nil {
err = errors.Join(err, fmt.Errorf("failed to restore project files after update failure: %w", restoreErr))
}
}
@@ -3308,6 +3324,7 @@ func (s *ProjectService) projectFileApplyOptionsInternal(ctx context.Context, pr
return projects.ProjectFileApplyOptions{
ExpectedRevision: strings.TrimSpace(expectedRevision),
MaxDepth: s.config.ProjectFileTreeMaxDepth,
+ MaxEntries: projects.DefaultProjectFileTreeMaxEntries,
SkipDirectories: s.config.ProjectScanSkipDirs,
ComposeFileName: composeFileName,
}
@@ -3328,41 +3345,124 @@ func wrapProjectFileErrorInternal(err error) error {
}
}
-func (s *ProjectService) backupProjectDirectoryInternal(ctx context.Context, projectsDirectory, projectPath string) (string, []string, error) {
+// projectUpdateBackupScopeInternal derives the exact set of paths an update
+// can mutate so the backup never copies out-of-scope data directories.
+// Changes that fail normalization are skipped: the apply step rejects them
+// before mutating anything, so there is nothing to roll back for them.
+func projectUpdateBackupScopeInternal(projectPath string, composeContent, envContent *string, fileChanges []project.ProjectFileChange) projects.ProjectUpdateBackupScope {
+ scope := projects.ProjectUpdateBackupScope{
+ TopLevelFiles: composeContent != nil || envContent != nil,
+ }
+
+ for _, change := range fileChanges {
+ rel, err := projects.NormalizeProjectRelativePath(change.RelativePath)
+ if err != nil {
+ continue
+ }
+
+ var dest string
+ switch change.Operation {
+ case project.FileOpRename:
+ newName, nameErr := projects.ValidateProjectFileName(change.NewName)
+ if nameErr != nil {
+ continue
+ }
+ dest = path.Join(path.Dir(rel), newName)
+ case project.FileOpMove:
+ parent := strings.TrimSpace(change.NewParentPath)
+ if parent != "" {
+ normalizedParent, parentErr := projects.NormalizeProjectRelativePath(parent)
+ if parentErr != nil {
+ continue
+ }
+ parent = normalizedParent
+ }
+ dest = path.Join(parent, path.Base(rel))
+ default:
+ scope.Paths = append(scope.Paths, rel)
+ continue
+ }
+
+ // Rename/move of an existing directory rolls back via an inverse
+ // rename — never a copy of a potentially huge tree.
+ if info, statErr := os.Lstat(filepath.Join(projectPath, filepath.FromSlash(rel))); statErr == nil && info.IsDir() {
+ scope.RenamedDirs = append(scope.RenamedDirs, [2]string{rel, dest})
+ } else {
+ scope.Paths = append(scope.Paths, rel, dest)
+ }
+ }
+
+ demoteInterferingRenamedDirsInternal(&scope)
+ return scope
+}
+
+// demoteInterferingRenamedDirsInternal downgrades a directory rename to a full
+// copy when another change in the same batch touches its source or destination
+// subtree (e.g. rename a -> b then delete b, or update_file b/x). The inverse
+// rename alone cannot roll those back: the destination may be mutated or gone
+// by the time the batch fails, so the original directory must be backed up.
+func demoteInterferingRenamedDirsInternal(scope *projects.ProjectUpdateBackupScope) {
+ overlaps := func(a, b string) bool {
+ return a == b || strings.HasPrefix(a, b+"/") || strings.HasPrefix(b, a+"/")
+ }
+ touchesPair := func(p string, pair [2]string) bool {
+ return overlaps(p, pair[0]) || overlaps(p, pair[1])
+ }
+
+ for i := 0; i < len(scope.RenamedDirs); i++ {
+ pair := scope.RenamedDirs[i]
+ conflict := slices.ContainsFunc(scope.Paths, func(p string) bool { return touchesPair(p, pair) })
+ if !conflict {
+ for j, other := range scope.RenamedDirs {
+ if j != i && (touchesPair(other[0], pair) || touchesPair(other[1], pair)) {
+ conflict = true
+ break
+ }
+ }
+ }
+ if conflict {
+ scope.Paths = append(scope.Paths, pair[0], pair[1])
+ scope.RenamedDirs = slices.Delete(scope.RenamedDirs, i, i+1)
+ i--
+ }
+ }
+}
+
+func (s *ProjectService) backupProjectDirectoryInternal(ctx context.Context, projectsDirectory, projectPath string, scope projects.ProjectUpdateBackupScope) (*projects.ProjectUpdateBackup, error) {
projectAbs, err := filepath.Abs(projectPath)
if err != nil {
- return "", nil, fmt.Errorf("failed to resolve project path: %w", err)
+ return nil, fmt.Errorf("failed to resolve project path: %w", err)
}
projectAbs = filepath.Clean(projectAbs)
rootAbs, err := filepath.Abs(projectsDirectory)
if err != nil {
- return "", nil, fmt.Errorf("failed to resolve projects directory: %w", err)
+ return nil, fmt.Errorf("failed to resolve projects directory: %w", err)
}
rootAbs = filepath.Clean(rootAbs)
if !projects.IsSafeSubdirectory(rootAbs, projectAbs) || projectAbs == rootAbs {
- return "", nil, errors.New("project path is outside projects directory")
+ return nil, errors.New("project path is outside projects directory")
}
backupPath, err := os.MkdirTemp(projectsDirectory, ".project-update-backup-*")
if err != nil {
- return "", nil, fmt.Errorf("failed to create project backup directory: %w", err)
+ return nil, fmt.Errorf("failed to create project backup directory: %w", err)
}
// Tolerate files Arcane cannot read (e.g. foreign-owned secrets): skip them
// in the backup so an unrelated unreadable file can't block the whole save.
- // The skipped paths are returned so the rollback restore can preserve them.
- skipped, err := projects.CopyDirectoryContentsTolerant(projectAbs, backupPath)
+ // The skipped paths are recorded so the rollback restore can preserve them.
+ backup, err := projects.BackupProjectUpdateScope(projectAbs, backupPath, scope)
if err != nil {
_ = os.RemoveAll(backupPath)
- return "", nil, fmt.Errorf("failed to backup project files: %w", err)
+ return nil, fmt.Errorf("failed to backup project files: %w", err)
}
- if len(skipped) > 0 {
- slog.WarnContext(ctx, "skipped unreadable files while backing up project; they will be left untouched on rollback", "projectPath", projectAbs, "skipped", skipped)
+ if len(backup.Skipped) > 0 {
+ slog.WarnContext(ctx, "skipped unreadable files while backing up project; they will be left untouched on rollback", "projectPath", projectAbs, "skipped", backup.Skipped)
}
- return backupPath, skipped, nil
+ return backup, nil
}
-func (s *ProjectService) restoreProjectDirectoryBackupInternal(ctx context.Context, projectsDirectory, projectPath, backupPath string, skipped []string) error {
+func (s *ProjectService) restoreProjectDirectoryBackupInternal(ctx context.Context, projectsDirectory, projectPath string, backup *projects.ProjectUpdateBackup) error {
projectAbs, err := filepath.Abs(projectPath)
if err != nil {
return fmt.Errorf("failed to resolve project path: %w", err)
@@ -3378,14 +3478,14 @@ func (s *ProjectService) restoreProjectDirectoryBackupInternal(ctx context.Conte
return errors.New("project path is outside projects directory")
}
- slog.DebugContext(ctx, "restoring project directory backup", "path", projectAbs, "backup", backupPath)
+ slog.DebugContext(ctx, "restoring project directory backup", "path", projectAbs, "backup", backup.BackupDir)
if err := os.MkdirAll(projectAbs, common.DirPerm); err != nil {
return fmt.Errorf("failed to recreate project directory: %w", err)
}
- // Mirror the backup back over the live directory rather than wiping it: files
+ // Restore only the paths the update could have mutated, in place: files
// that were skipped during backup (unreadable, e.g. foreign-owned secrets)
- // are absent from the backup and must be preserved, not deleted.
- if err := projects.MirrorDirectoryContentsPreserving(backupPath, projectAbs, skipped); err != nil {
+ // are preserved, and out-of-scope files are never touched.
+ if err := projects.RestoreProjectUpdateBackup(projectAbs, backup); err != nil {
return fmt.Errorf("failed to restore project backup: %w", err)
}
return nil
diff --git a/backend/internal/services/project_service_test.go b/backend/internal/services/project_service_test.go
index 4d4ede6a0..85e5193c8 100644
--- a/backend/internal/services/project_service_test.go
+++ b/backend/internal/services/project_service_test.go
@@ -2178,7 +2178,7 @@ func TestProjectService_GetProjectDetails_UsesFileTreeMaxDepthForProjectFiles(t
assert.DirExists(t, filepath.Join(project.Path, filepath.FromSlash(deepFolder)))
- filesAtScanDepth, _, err := projects.ReadProjectFileTree(project.Path, cfg.ProjectScanMaxDepth, cfg.ProjectScanSkipDirs, "compose.yaml")
+ filesAtScanDepth, _, _, err := projects.ReadProjectFileTree(project.Path, cfg.ProjectScanMaxDepth, cfg.ProjectScanSkipDirs, "compose.yaml", 0)
require.NoError(t, err)
scanDepthRelativePaths := make([]string, 0, len(filesAtScanDepth))
for _, file := range filesAtScanDepth {
@@ -2215,7 +2215,7 @@ func TestProjectService_UpdateProject_AppliesStagedProjectFileChanges(t *testing
})
require.NoError(t, err)
- _, revision, err := projects.ReadProjectFileTree(project.Path, config.Load().ProjectScanMaxDepth, config.Load().ProjectScanSkipDirs, "compose.yaml")
+ _, revision, _, err := projects.ReadProjectFileTree(project.Path, config.Load().ProjectScanMaxDepth, config.Load().ProjectScanSkipDirs, "compose.yaml", 0)
require.NoError(t, err)
updated := "updated\n"
@@ -2257,7 +2257,7 @@ func TestProjectService_UpdateProject_RejectsStaleProjectFileRevision(t *testing
})
require.NoError(t, err)
- _, revision, err := projects.ReadProjectFileTree(project.Path, config.Load().ProjectScanMaxDepth, config.Load().ProjectScanSkipDirs, "compose.yaml")
+ _, revision, _, err := projects.ReadProjectFileTree(project.Path, config.Load().ProjectScanMaxDepth, config.Load().ProjectScanSkipDirs, "compose.yaml", 0)
require.NoError(t, err)
require.NoError(t, os.WriteFile(filepath.Join(project.Path, "external.txt"), []byte("external\n"), 0o644))
@@ -5166,7 +5166,7 @@ func TestProjectService_UpdateProject_RenameRollsBackWhenFileRevisionIsStale(t *
}
require.NoError(t, db.Create(project).Error)
- _, revision, err := projects.ReadProjectFileTree(project.Path, config.Load().ProjectFileTreeMaxDepth, config.Load().ProjectScanSkipDirs, "compose.yaml")
+ _, revision, _, err := projects.ReadProjectFileTree(project.Path, config.Load().ProjectFileTreeMaxDepth, config.Load().ProjectScanSkipDirs, "compose.yaml", 0)
require.NoError(t, err)
require.NoError(t, os.WriteFile(filepath.Join(project.Path, "external.txt"), []byte("external\n"), 0o644))
@@ -6906,3 +6906,115 @@ func TestProjectService_RecoverProjectRenameJournals_ClearsJournalWhenTargetPres
require.FileExists(t, filepath.Join(oldPath, "compose.yaml"))
require.NoDirExists(t, newPath)
}
+
+func TestProjectUpdateBackup_ScopedBackupAndRestore(t *testing.T) {
+ projectsDir := t.TempDir()
+ projectPath := createComposeProjectDir(t, projectsDir, "scoped")
+ require.NoError(t, os.WriteFile(filepath.Join(projectPath, ".env"), []byte("A=1\n"), 0o644))
+ require.NoError(t, os.MkdirAll(filepath.Join(projectPath, "data"), 0o755))
+ require.NoError(t, os.WriteFile(filepath.Join(projectPath, "data", "keep.bin"), []byte("keep"), 0o644))
+
+ compose := "services: {}\n"
+ scope := projectUpdateBackupScopeInternal(projectPath, &compose, nil, []projecttypes.ProjectFileChange{
+ {Operation: projecttypes.FileOpCreateFile, RelativePath: "notes.txt", Content: ptr("notes\n")},
+ })
+
+ backupDir := t.TempDir()
+ backup, err := projects.BackupProjectUpdateScope(projectPath, backupDir, scope)
+ require.NoError(t, err)
+ require.FileExists(t, filepath.Join(backupDir, "compose.yaml"))
+ require.FileExists(t, filepath.Join(backupDir, ".env"))
+ require.NoDirExists(t, filepath.Join(backupDir, "data"))
+ require.Equal(t, []string{"notes.txt"}, backup.AbsentEntries)
+
+ // Simulate a failed update: compose overwritten, notes.txt created, and an
+ // out-of-scope file written into data/ by a running container.
+ require.NoError(t, os.WriteFile(filepath.Join(projectPath, "compose.yaml"), []byte("broken\n"), 0o644))
+ require.NoError(t, os.WriteFile(filepath.Join(projectPath, "notes.txt"), []byte("notes\n"), 0o644))
+ require.NoError(t, os.WriteFile(filepath.Join(projectPath, "data", "new.bin"), []byte("new"), 0o644))
+
+ require.NoError(t, projects.RestoreProjectUpdateBackup(projectPath, backup))
+
+ restored, err := os.ReadFile(filepath.Join(projectPath, "compose.yaml"))
+ require.NoError(t, err)
+ require.Equal(t, "services:\n app:\n image: nginx:alpine\n", string(restored))
+ require.NoFileExists(t, filepath.Join(projectPath, "notes.txt"))
+ require.FileExists(t, filepath.Join(projectPath, "data", "keep.bin"))
+ require.FileExists(t, filepath.Join(projectPath, "data", "new.bin"))
+}
+
+func TestProjectService_UpdateProject_FileChangeFailureRollsBackScoped(t *testing.T) {
+ db := setupProjectTestDB(t)
+ ctx := context.Background()
+
+ projectsDir := t.TempDir()
+ t.Setenv("PROJECTS_DIRECTORY", projectsDir)
+
+ settingsService, err := NewSettingsService(ctx, db)
+ require.NoError(t, err)
+ require.NoError(t, settingsService.SetStringSetting(ctx, "projectsDirectory", projectsDir))
+
+ eventService := NewEventService(db, nil, nil)
+ svc := NewProjectService(db, settingsService, eventService, nil, nil, nil, nil, nil, config.Load())
+ configureProjectRuntimeDockerInternal(t, nil)
+
+ dirName := "rollback"
+ projectPath := createComposeProjectDir(t, projectsDir, dirName)
+ require.NoError(t, os.MkdirAll(filepath.Join(projectPath, "data"), 0o755))
+ require.NoError(t, os.WriteFile(filepath.Join(projectPath, "data", "keep.bin"), []byte("keep"), 0o644))
+
+ project := &models.Project{
+ BaseModel: models.BaseModel{ID: "proj-scoped-rollback"},
+ Name: "rollback",
+ DirName: &dirName,
+ Path: projectPath,
+ Status: models.ProjectStatusStopped,
+ }
+ require.NoError(t, db.Create(project).Error)
+
+ _, revision, _, err := projects.ReadProjectFileTree(project.Path, config.Load().ProjectFileTreeMaxDepth, config.Load().ProjectScanSkipDirs, "compose.yaml", 0)
+ require.NoError(t, err)
+
+ // The second change fails after the first has mutated the directory.
+ _, err = svc.UpdateProject(ctx, project.ID, nil, nil, nil, &revision, []projecttypes.ProjectFileChange{
+ {Operation: projecttypes.FileOpCreateFile, RelativePath: "notes.txt", Content: ptr("notes\n")},
+ {Operation: projecttypes.FileOpUpdateFile, RelativePath: "missing.txt", Content: ptr("nope\n")},
+ }, models.User{BaseModel: models.BaseModel{ID: "u1"}, Username: "tester"})
+
+ require.Error(t, err)
+ require.NoFileExists(t, filepath.Join(projectPath, "notes.txt"))
+ require.FileExists(t, filepath.Join(projectPath, "compose.yaml"))
+ require.FileExists(t, filepath.Join(projectPath, "data", "keep.bin"))
+
+ entries, err := os.ReadDir(projectsDir)
+ require.NoError(t, err)
+ for _, entry := range entries {
+ require.False(t, strings.HasPrefix(entry.Name(), ".project-update-backup-"), "leftover backup dir: %s", entry.Name())
+ }
+}
+
+func TestProjectUpdateBackup_RenamedDirDemotedToCopyWhenBatchTouchesIt(t *testing.T) {
+ projectsDir := t.TempDir()
+ projectPath := createComposeProjectDir(t, projectsDir, "demote")
+ require.NoError(t, os.MkdirAll(filepath.Join(projectPath, "a"), 0o755))
+ require.NoError(t, os.WriteFile(filepath.Join(projectPath, "a", "keep.txt"), []byte("keep\n"), 0o644))
+
+ // Batch: rename a -> b, then delete b — the inverse rename cannot roll
+ // this back, so the rename must be demoted to a full copy of a.
+ scope := projectUpdateBackupScopeInternal(projectPath, nil, nil, []projecttypes.ProjectFileChange{
+ {Operation: projecttypes.FileOpRename, RelativePath: "a", NewName: "b"},
+ {Operation: projecttypes.FileOpDelete, RelativePath: "b", Recursive: true},
+ })
+ require.Empty(t, scope.RenamedDirs)
+
+ backup, err := projects.BackupProjectUpdateScope(projectPath, t.TempDir(), scope)
+ require.NoError(t, err)
+
+ // Simulate the batch running, then failing on a later change.
+ require.NoError(t, os.Rename(filepath.Join(projectPath, "a"), filepath.Join(projectPath, "b")))
+ require.NoError(t, os.RemoveAll(filepath.Join(projectPath, "b")))
+
+ require.NoError(t, projects.RestoreProjectUpdateBackup(projectPath, backup))
+ require.FileExists(t, filepath.Join(projectPath, "a", "keep.txt"))
+ require.NoDirExists(t, filepath.Join(projectPath, "b"))
+}
diff --git a/backend/pkg/projects/discovery.go b/backend/pkg/projects/discovery.go
index 29f7fbfd8..bfef14378 100644
--- a/backend/pkg/projects/discovery.go
+++ b/backend/pkg/projects/discovery.go
@@ -89,8 +89,11 @@ func DiscoverProjectDirectories(root string, followSymlinks bool, maxDepth int)
}
func walkProjectDirectoriesInternal(path string, isRoot bool, currentDepth int, maxDepth int, followSymlinks bool, ancestors map[string]struct{}, discovered *[]DiscoveredProjectDir) error {
- if !isRoot && IsInternalScratchDirName(filepath.Base(path)) {
- return nil
+ if !isRoot {
+ name := filepath.Base(path)
+ if IsInternalScratchDirName(name) || IsFilesystemSnapshotDirName(name) {
+ return nil
+ }
}
identity, err := ResolveDirectoryIdentityInternal(path)
@@ -177,6 +180,37 @@ func IsGitOpsScratchDirName(name string) bool {
return gitOpsScratchEmbeddedNameRe.MatchString(name)
}
+// filesystemSnapshotDirNames are directory names used by filesystems and NAS
+// appliances for read-only snapshots or trash. They contain point-in-time
+// copies of real project directories and must never be discovered as projects:
+// #snapshot/#recycle (Synology BTRFS), .snapshot (NetApp), .snapshots
+// (snapper/btrbk), .zfs (ZFS snapdir).
+var filesystemSnapshotDirNames = map[string]bool{
+ "#snapshot": true,
+ "#recycle": true,
+ ".snapshot": true,
+ ".snapshots": true,
+ ".zfs": true,
+}
+
+// IsFilesystemSnapshotDirName reports whether name is a well-known filesystem
+// snapshot/trash directory (see filesystemSnapshotDirNames).
+func IsFilesystemSnapshotDirName(name string) bool {
+ return filesystemSnapshotDirNames[strings.ToLower(strings.TrimSpace(name))]
+}
+
+// PathContainsSnapshotDirectory reports whether any segment of relPath is a
+// filesystem snapshot/trash directory name, i.e. the path points into a
+// point-in-time copy rather than a live project directory.
+func PathContainsSnapshotDirectory(relPath string) bool {
+ for segment := range strings.SplitSeq(filepath.ToSlash(relPath), "/") {
+ if IsFilesystemSnapshotDirName(segment) {
+ return true
+ }
+ }
+ return false
+}
+
// ArcaneTrashPrefix is the prefix Arcane uses when quarantining (soft-deleting) a
// project's files, e.g. ".arcane-trash-<name>-<unix>". Trash directories are
// Arcane-managed and must never be discovered or imported as user projects.
diff --git a/backend/pkg/projects/discovery_test.go b/backend/pkg/projects/discovery_test.go
index 595ea345e..ba30e8a07 100644
--- a/backend/pkg/projects/discovery_test.go
+++ b/backend/pkg/projects/discovery_test.go
@@ -241,3 +241,20 @@ func TestDiscoverProjectDirectories_SkipsUnreadableNestedSibling(t *testing.T) {
// tolerating a failure at the very end of the scan.
assert.Equal(t, []string{"project1"}, discoveredNamesInternal(discovered))
}
+
+// TestDiscoverProjectDirectories_SkipsFilesystemSnapshotDirs verifies that
+// point-in-time copies inside filesystem snapshot/trash directories (e.g.
+// Synology BTRFS #snapshot) are never discovered as projects.
+func TestDiscoverProjectDirectories_SkipsFilesystemSnapshotDirs(t *testing.T) {
+ t.Parallel()
+
+ root := t.TempDir()
+ writeComposeFileInternal(t, filepath.Join(root, "arcane"))
+ writeComposeFileInternal(t, filepath.Join(root, "#snapshot", "GMT+10-2026.07.04-03.30.01", "arcane"))
+ writeComposeFileInternal(t, filepath.Join(root, "#recycle", "arcane"))
+ writeComposeFileInternal(t, filepath.Join(root, ".snapshots", "1", "arcane"))
+
+ discovered, err := DiscoverProjectDirectories(root, false, 0)
+ require.NoError(t, err)
+ assert.Equal(t, []string{"arcane"}, discoveredNamesInternal(discovered))
+}
diff --git a/backend/pkg/projects/fs_backup.go b/backend/pkg/projects/fs_backup.go
new file mode 100644
index 000000000..5fd226765
--- /dev/null
+++ b/backend/pkg/projects/fs_backup.go
@@ -0,0 +1,394 @@
+package projects
+
+import (
+ "errors"
+ "fmt"
+ "os"
+ "path"
+ "path/filepath"
+ "slices"
+ "strings"
+
+ "go.getarcane.app/sys/atomic"
+)
+
+// ProjectUpdateBackupScope describes exactly what a project update can mutate,
+// so the pre-update backup copies only those paths instead of the whole
+// project directory (which may contain huge container data directories).
+type ProjectUpdateBackupScope struct {
+ // TopLevelFiles backs up every top-level regular file in the project
+ // directory. Compose/env persistence only ever writes top-level files.
+ TopLevelFiles bool
+ // Paths are normalized project-relative paths a file change can create,
+ // overwrite or delete.
+ Paths []string
+ // RenamedDirs holds {src, dest} pairs for a rename/move of an existing
+ // directory. These are rolled back with an inverse rename instead of a
+ // copy, so a huge directory move never triggers a full copy.
+ RenamedDirs [][2]string
+}
+
+func (s ProjectUpdateBackupScope) IsEmpty() bool {
+ return !s.TopLevelFiles && len(s.Paths) == 0 && len(s.RenamedDirs) == 0
+}
+
+// ProjectUpdateBackup records what BackupProjectUpdateScope copied so
+// RestoreProjectUpdateBackup can put the project directory back without
+// touching anything outside the update's scope.
+type ProjectUpdateBackup struct {
+ BackupDir string
+ TopLevelFiles bool
+ FileEntries []string // regular files copied into BackupDir
+ DirEntries []string // directories copied recursively
+ AbsentEntries []string // did not exist at backup time -> removed on restore
+ RenamedDirs [][2]string // undone via inverse rename on restore
+ Skipped []string // unreadable, skipped; preserved on restore
+}
+
+// BackupProjectUpdateScope copies the parts of projectDir named by scope into
+// backupDir. Unreadable files are skipped (recorded in Skipped) so an
+// unrelated foreign-owned file cannot block a save, matching the tolerant
+// semantics of the old whole-directory backup.
+func BackupProjectUpdateScope(projectDir, backupDir string, scope ProjectUpdateBackupScope) (*ProjectUpdateBackup, error) {
+ projRoot, err := os.OpenRoot(projectDir)
+ if err != nil {
+ return nil, fmt.Errorf("open project directory: %w", err)
+ }
+ defer func() { _ = projRoot.Close() }()
+
+ backupRoot, err := os.OpenRoot(backupDir)
+ if err != nil {
+ return nil, fmt.Errorf("open backup directory: %w", err)
+ }
+ defer func() { _ = backupRoot.Close() }()
+
+ backup := &ProjectUpdateBackup{
+ BackupDir: backupDir,
+ TopLevelFiles: scope.TopLevelFiles,
+ RenamedDirs: scope.RenamedDirs,
+ }
+
+ if scope.TopLevelFiles {
+ if err := backupTopLevelFilesInternal(projRoot, backupRoot, backup); err != nil {
+ return nil, err
+ }
+ }
+
+ for _, rel := range normalizeScopePathsInternal(scope.Paths) {
+ if err := backupScopePathInternal(projRoot, backupRoot, projectDir, backupDir, rel, backup); err != nil {
+ return nil, err
+ }
+ }
+
+ dedupeCoveredBackupEntriesInternal(backup)
+ slices.Sort(backup.Skipped)
+ return backup, nil
+}
+
+func normalizeScopePathsInternal(paths []string) []string {
+ normalized := make([]string, 0, len(paths))
+ for _, p := range paths {
+ cleaned := path.Clean(filepath.ToSlash(p))
+ if cleaned == "." || cleaned == "" || cleaned == ".." || strings.HasPrefix(cleaned, "../") {
+ continue
+ }
+ normalized = append(normalized, cleaned)
+ }
+ slices.Sort(normalized)
+ return slices.Compact(normalized)
+}
+
+func backupTopLevelFilesInternal(projRoot, backupRoot *os.Root, backup *ProjectUpdateBackup) error {
+ entries, err := os.ReadDir(projRoot.Name())
+ if err != nil {
+ return fmt.Errorf("read project directory: %w", err)
+ }
+ for _, entry := range entries {
+ if !entry.Type().IsRegular() {
+ continue
+ }
+ name := entry.Name()
+ if err := copyBackupFileInternal(projRoot, backupRoot, name, backup); err != nil {
+ return err
+ }
+ }
+ return nil
+}
+
+func backupScopePathInternal(projRoot, backupRoot *os.Root, projectDir, backupDir, rel string, backup *ProjectUpdateBackup) error {
+ info, err := projRoot.Lstat(rel)
+ if errors.Is(err, os.ErrNotExist) {
+ // Record the shallowest nonexistent ancestor so MkdirAll debris from a
+ // failed create is removed on restore too.
+ absent, absentErr := shallowestAbsentAncestorInternal(projRoot, rel)
+ if absentErr != nil {
+ return absentErr
+ }
+ backup.AbsentEntries = append(backup.AbsentEntries, absent)
+ return nil
+ }
+ if err != nil {
+ return fmt.Errorf("inspect project path %s: %w", rel, err)
+ }
+
+ switch {
+ case info.IsDir():
+ destDir := filepath.Join(backupDir, filepath.FromSlash(rel))
+ if err := os.MkdirAll(destDir, 0o755); err != nil {
+ return fmt.Errorf("create backup directory: %w", err)
+ }
+ skipped, err := CopyDirectoryContentsTolerant(filepath.Join(projectDir, filepath.FromSlash(rel)), destDir)
+ if err != nil {
+ return fmt.Errorf("backup project directory %s: %w", rel, err)
+ }
+ for _, sub := range skipped {
+ backup.Skipped = append(backup.Skipped, path.Join(rel, filepath.ToSlash(sub)))
+ }
+ backup.DirEntries = append(backup.DirEntries, rel)
+ case info.Mode().IsRegular():
+ if err := copyBackupFileInternal(projRoot, backupRoot, rel, backup); err != nil {
+ return err
+ }
+ default:
+ // Symlinks and other special files: the apply operations reject them
+ // before mutating anything, so there is nothing to back up.
+ }
+ return nil
+}
+
+func shallowestAbsentAncestorInternal(projRoot *os.Root, rel string) (string, error) {
+ current := ""
+ for segment := range strings.SplitSeq(rel, "/") {
+ current = path.Join(current, segment)
+ if _, err := projRoot.Lstat(current); err != nil {
+ if errors.Is(err, os.ErrNotExist) {
+ return current, nil
+ }
+ return "", fmt.Errorf("inspect project path %s: %w", current, err)
+ }
+ }
+ return rel, nil
+}
+
+func copyBackupFileInternal(projRoot, backupRoot *os.Root, rel string, backup *ProjectUpdateBackup) error {
+ info, err := projRoot.Lstat(rel)
+ if err != nil {
+ return fmt.Errorf("inspect project file %s: %w", rel, err)
+ }
+ content, err := projRoot.ReadFile(rel)
+ if err != nil {
+ if errors.Is(err, os.ErrPermission) {
+ backup.Skipped = append(backup.Skipped, rel)
+ return nil
+ }
+ return fmt.Errorf("read project file %s: %w", rel, err)
+ }
+ if dir := path.Dir(rel); dir != "." {
+ if err := backupRoot.MkdirAll(dir, 0o755); err != nil {
+ return fmt.Errorf("create backup directory: %w", err)
+ }
+ }
+ if err := atomic.WriteFile(filepath.Join(backupRoot.Name(), filepath.FromSlash(rel)), content, info.Mode().Perm()); err != nil {
+ return fmt.Errorf("write backup file %s: %w", rel, err)
+ }
+ backup.FileEntries = append(backup.FileEntries, rel)
+ return nil
+}
+
+// dedupeCoveredBackupEntriesInternal drops entries that live under a directory
+// already covered by DirEntries or AbsentEntries (e.g. a file change inside a
+// folder that is also being deleted recursively).
+func dedupeCoveredBackupEntriesInternal(backup *ProjectUpdateBackup) {
+ covered := append(append([]string{}, backup.DirEntries...), backup.AbsentEntries...)
+ hasCoveredAncestor := func(rel string) bool {
+ for _, dir := range covered {
+ if rel != dir && strings.HasPrefix(rel, dir+"/") {
+ return true
+ }
+ }
+ return false
+ }
+ backup.FileEntries = slices.DeleteFunc(backup.FileEntries, hasCoveredAncestor)
+ backup.DirEntries = slices.DeleteFunc(backup.DirEntries, hasCoveredAncestor)
+ backup.AbsentEntries = slices.DeleteFunc(backup.AbsentEntries, hasCoveredAncestor)
+}
+
+// RestoreProjectUpdateBackup rolls the scoped parts of projectDir back to the
+// state captured in backup. Files are restored in place (preserving inodes so
+// container bind mounts stay valid) and out-of-scope files are never touched.
+func RestoreProjectUpdateBackup(projectDir string, backup *ProjectUpdateBackup) error {
+ projRoot, err := os.OpenRoot(projectDir)
+ if err != nil {
+ return fmt.Errorf("open project directory: %w", err)
+ }
+ defer func() { _ = projRoot.Close() }()
+
+ // 1. Undo directory renames, then 2. remove debris the failed update
+ // created at paths that did not exist.
+ if err := undoRenamedDirsAndDebrisInternal(projRoot, backup); err != nil {
+ return err
+ }
+
+ // 3. Mirror backed-up directories back in place.
+ for _, rel := range backup.DirEntries {
+ if err := projRoot.MkdirAll(rel, 0o755); err != nil {
+ return fmt.Errorf("recreate project directory %s: %w", rel, err)
+ }
+ preserve := skippedUnderInternal(backup.Skipped, rel)
+ src := filepath.Join(backup.BackupDir, filepath.FromSlash(rel))
+ dest := filepath.Join(projectDir, filepath.FromSlash(rel))
+ if err := MirrorDirectoryContentsPreserving(src, dest, preserve); err != nil {
+ return fmt.Errorf("restore project directory %s: %w", rel, err)
+ }
+ }
+
+ backupRoot, err := os.OpenRoot(backup.BackupDir)
+ if err != nil {
+ return fmt.Errorf("open backup directory: %w", err)
+ }
+ defer func() { _ = backupRoot.Close() }()
+
+ // 4. Restore individual files in place.
+ for _, rel := range backup.FileEntries {
+ if err := restoreBackupFileInternal(backupRoot, projRoot, rel); err != nil {
+ return err
+ }
+ }
+
+ // 5. Depth-1 mini-mirror of top-level regular files: prune live top-level
+ // regular files absent from the backup (and not skipped as unreadable),
+ // then copy every top-level backup file back. Top-level directories and
+ // symlinks are never touched.
+ if backup.TopLevelFiles {
+ if err := restoreTopLevelFilesInternal(backupRoot, projRoot, backup.Skipped); err != nil {
+ return err
+ }
+ }
+
+ return nil
+}
+
+// undoRenamedDirsAndDebrisInternal reverses directory renames with an inverse
+// rename (no copy involved), then removes debris the failed update created at
+// paths that were absent at backup time.
+func undoRenamedDirsAndDebrisInternal(projRoot *os.Root, backup *ProjectUpdateBackup) error {
+ handledAbsent := make(map[string]bool)
+ for _, pair := range backup.RenamedDirs {
+ src, dest := pair[0], pair[1]
+ if _, err := projRoot.Lstat(dest); err != nil {
+ continue
+ }
+ if _, err := projRoot.Lstat(src); err == nil {
+ // The failed batch recreated something at src (e.g. rename a -> b
+ // then create_folder a). Clear it only when the backup covers src —
+ // debris at an absent path or a directory we hold a full copy of —
+ // so the renamed directory always moves back; an out-of-scope
+ // occupant is left alone.
+ if !slices.Contains(backup.DirEntries, src) && !slices.Contains(backup.AbsentEntries, src) {
+ continue
+ }
+ if err := projRoot.RemoveAll(src); err != nil {
+ return fmt.Errorf("remove recreated path %s: %w", src, err)
+ }
+ handledAbsent[src] = true
+ }
+ if err := projRoot.Rename(dest, src); err != nil {
+ return fmt.Errorf("undo rename of %s: %w", src, err)
+ }
+ }
+
+ for _, rel := range backup.AbsentEntries {
+ if handledAbsent[rel] {
+ // Already cleared above, and the inverse rename has since restored
+ // the original directory at this path — do not delete it again.
+ continue
+ }
+ if err := projRoot.RemoveAll(rel); err != nil {
+ return fmt.Errorf("remove created path %s: %w", rel, err)
+ }
+ }
+ return nil
+}
+
+func skippedUnderInternal(skipped []string, rel string) []string {
+ prefix := rel + "/"
+ var under []string
+ for _, s := range skipped {
+ if rest, ok := strings.CutPrefix(s, prefix); ok {
+ under = append(under, filepath.FromSlash(rest))
+ }
+ }
+ return under
+}
+
+func restoreBackupFileInternal(backupRoot, projRoot *os.Root, rel string) error {
+ info, err := backupRoot.Lstat(rel)
+ if err != nil {
+ return fmt.Errorf("inspect backup file %s: %w", rel, err)
+ }
+ content, err := backupRoot.ReadFile(rel)
+ if err != nil {
+ return fmt.Errorf("read backup file %s: %w", rel, err)
+ }
+ if live, err := projRoot.Lstat(rel); err == nil && live.IsDir() {
+ if err := projRoot.RemoveAll(rel); err != nil {
+ return fmt.Errorf("remove conflicting directory %s: %w", rel, err)
+ }
+ }
+ if dir := path.Dir(rel); dir != "." {
+ if err := projRoot.MkdirAll(dir, 0o755); err != nil {
+ return fmt.Errorf("recreate parent directory of %s: %w", rel, err)
+ }
+ }
+ // Atomic write: a crash mid-restore leaves either the failed-update
+ // content or the fully restored file, never a torn write.
+ if err := atomic.WriteFile(filepath.Join(projRoot.Name(), filepath.FromSlash(rel)), content, info.Mode().Perm()); err != nil {
+ return fmt.Errorf("restore project file %s: %w", rel, err)
+ }
+ return nil
+}
+
+func restoreTopLevelFilesInternal(backupRoot, projRoot *os.Root, skipped []string) error {
+ backupEntries, err := os.ReadDir(backupRoot.Name())
+ if err != nil {
+ return fmt.Errorf("read backup directory: %w", err)
+ }
+ inBackup := make(map[string]bool, len(backupEntries))
+ for _, entry := range backupEntries {
+ if entry.Type().IsRegular() {
+ inBackup[entry.Name()] = true
+ }
+ }
+ skippedTopLevel := make(map[string]bool)
+ for _, s := range skipped {
+ if !strings.Contains(s, "/") {
+ skippedTopLevel[s] = true
+ }
+ }
+
+ liveEntries, err := os.ReadDir(projRoot.Name())
+ if err != nil {
+ return fmt.Errorf("read project directory: %w", err)
+ }
+ for _, entry := range liveEntries {
+ name := entry.Name()
+ if !entry.Type().IsRegular() || inBackup[name] || skippedTopLevel[name] {
+ continue
+ }
+ if err := projRoot.Remove(name); err != nil {
+ return fmt.Errorf("prune created file %s: %w", name, err)
+ }
+ }
+
+ // backupEntries is sorted by os.ReadDir, so restoration order is
+ // deterministic and mirrors the backup order.
+ for _, entry := range backupEntries {
+ if !entry.Type().IsRegular() {
+ continue
+ }
+ if err := restoreBackupFileInternal(backupRoot, projRoot, entry.Name()); err != nil {
+ return err
+ }
+ }
+ return nil
+}
diff --git a/backend/pkg/projects/fs_backup_test.go b/backend/pkg/projects/fs_backup_test.go
new file mode 100644
index 000000000..4a82447cd
--- /dev/null
+++ b/backend/pkg/projects/fs_backup_test.go
@@ -0,0 +1,33 @@
+package projects
+
+import (
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestRestoreProjectUpdateBackup_UndoesRenameWhenSourceWasRecreated(t *testing.T) {
+ t.Parallel()
+
+ projectDir := t.TempDir()
+ require.NoError(t, os.MkdirAll(filepath.Join(projectDir, "a"), 0o755))
+ require.NoError(t, os.WriteFile(filepath.Join(projectDir, "a", "keep.txt"), []byte("keep\n"), 0o644))
+
+ // Batch: rename a -> b, create_folder a, then a later change fails.
+ scope := ProjectUpdateBackupScope{
+ Paths: []string{"a"},
+ RenamedDirs: [][2]string{{"a", "b"}},
+ }
+ backup, err := BackupProjectUpdateScope(projectDir, t.TempDir(), scope)
+ require.NoError(t, err)
+
+ require.NoError(t, os.Rename(filepath.Join(projectDir, "a"), filepath.Join(projectDir, "b")))
+ require.NoError(t, os.MkdirAll(filepath.Join(projectDir, "a"), 0o755))
+
+ require.NoError(t, RestoreProjectUpdateBackup(projectDir, backup))
+
+ require.NoDirExists(t, filepath.Join(projectDir, "b"))
+ require.FileExists(t, filepath.Join(projectDir, "a", "keep.txt"))
+}
diff --git a/backend/pkg/projects/project_files.go b/backend/pkg/projects/project_files.go
index 7c00d78e3..291bfe484 100644
--- a/backend/pkg/projects/project_files.go
+++ b/backend/pkg/projects/project_files.go
@@ -24,6 +24,10 @@ import (
const (
MaxManagedProjectFileBytes = 1024 * 1024
ProjectFileTreeUseScanDepth = -1
+ // DefaultProjectFileTreeMaxEntries bounds the file-tree walk so a project
+ // with a huge data directory cannot stall the details load. Not a user
+ // setting; pass 0 to use it.
+ DefaultProjectFileTreeMaxEntries = 2000
)
var (
@@ -36,100 +40,131 @@ var (
type ProjectFileApplyOptions struct {
ExpectedRevision string
MaxDepth int
+ MaxEntries int
SkipDirectories string
ComposeFileName string
}
-func ReadProjectFileTree(projectPath string, maxDepth int, skipDirectories, composeFileName string) ([]project.ProjectFile, string, error) {
+func ReadProjectFileTree(projectPath string, maxDepth int, skipDirectories, composeFileName string, maxEntries int) ([]project.ProjectFile, string, bool, error) {
if maxDepth == ProjectFileTreeUseScanDepth {
maxDepth = config.LoadProjectFilesConfig().ProjectFileTreeMaxDepth
}
+ if maxEntries <= 0 {
+ maxEntries = DefaultProjectFileTreeMaxEntries
+ }
projectAbs, err := filepath.Abs(projectPath)
if err != nil {
- return nil, "", fmt.Errorf("resolve project path: %w", err)
+ return nil, "", false, fmt.Errorf("resolve project path: %w", err)
}
projectAbs = filepath.Clean(projectAbs)
root, err := os.OpenRoot(projectAbs)
if err != nil {
- return nil, "", fmt.Errorf("open project directory: %w", err)
+ return nil, "", false, fmt.Errorf("open project directory: %w", err)
}
defer func() { _ = root.Close() }()
- protected := ProtectedProjectFilePaths(composeFileName)
- skipDirs := projectScanSkipDirectorySetInternal(skipDirectories)
- files := []project.ProjectFile{}
- revisionHash := sha256.New()
+ walker := &projectFileTreeWalkerInternal{
+ projectAbs: projectAbs,
+ maxDepth: maxDepth,
+ maxEntries: maxEntries,
+ protected: ProtectedProjectFilePaths(composeFileName),
+ skipDirs: projectScanSkipDirectorySetInternal(skipDirectories),
+ files: []project.ProjectFile{},
+ revisionHash: sha256.New(),
+ }
- err = fs.WalkDir(root.FS(), ".", func(rel string, entry fs.DirEntry, walkErr error) error {
- if walkErr != nil {
- return walkErr
- }
- if rel == "." {
- return nil
- }
+ if err := fs.WalkDir(root.FS(), ".", walker.visit); err != nil {
+ return nil, "", false, err
+ }
- depth := strings.Count(rel, "/") + 1
- if depth > maxDepth {
- if entry.IsDir() {
- return fs.SkipDir
+ slices.SortFunc(walker.files, func(a, b project.ProjectFile) int {
+ if a.IsDirectory != b.IsDirectory {
+ if a.IsDirectory {
+ return -1
}
- return nil
+ return 1
}
+ return strings.Compare(a.RelativePath, b.RelativePath)
+ })
- if entry.Type()&fs.ModeSymlink != 0 {
- return nil
- }
- if entry.IsDir() && skipDirs[entry.Name()] {
- return fs.SkipDir
- }
+ return walker.files, hex.EncodeToString(walker.revisionHash.Sum(nil)), walker.truncated, nil
+}
- info, err := entry.Info()
- if err != nil {
- return fmt.Errorf("inspect project file: %w", err)
- }
+type projectFileTreeWalkerInternal struct {
+ projectAbs string
+ maxDepth int
+ maxEntries int
+ protected map[string]bool
+ skipDirs map[string]bool
+ files []project.ProjectFile
+ revisionHash hash.Hash
+ entryCount int
+ truncated bool
+}
- // fs.WalkDir visits entries in deterministic lexical order, so hashing
- // in visit order yields a stable revision.
- isProtected := protected[rel]
- writeProjectFileRevisionEntryInternal(revisionHash, rel, info, entry.IsDir(), isProtected)
+func (w *projectFileTreeWalkerInternal) visit(rel string, entry fs.DirEntry, walkErr error) error {
+ if walkErr != nil {
+ return walkErr
+ }
+ if rel == "." {
+ return nil
+ }
- if isProtected {
- return nil
- }
+ // The walk visits entries in deterministic lexical order, so cutting
+ // off after maxEntries still yields a stable revision as long as the
+ // concurrency compare walk uses the same cap.
+ if w.entryCount >= w.maxEntries {
+ w.truncated = true
+ return fs.SkipAll
+ }
- size := info.Size()
+ depth := strings.Count(rel, "/") + 1
+ if depth > w.maxDepth {
if entry.IsDir() {
- size = 0
+ return fs.SkipDir
}
- files = append(files, project.ProjectFile{
- Path: filepath.Join(projectAbs, filepath.FromSlash(rel)),
- RelativePath: rel,
- Name: entry.Name(),
- IsDirectory: entry.IsDir(),
- Size: size,
- ModTime: info.ModTime(),
- Protected: false,
- })
+ return nil
+ }
+ if entry.Type()&fs.ModeSymlink != 0 {
return nil
- })
+ }
+ if entry.IsDir() && w.skipDirs[entry.Name()] {
+ return fs.SkipDir
+ }
+
+ info, err := entry.Info()
if err != nil {
- return nil, "", err
+ return fmt.Errorf("inspect project file: %w", err)
}
- slices.SortFunc(files, func(a, b project.ProjectFile) int {
- if a.IsDirectory != b.IsDirectory {
- if a.IsDirectory {
- return -1
- }
- return 1
- }
- return strings.Compare(a.RelativePath, b.RelativePath)
+ // fs.WalkDir visits entries in deterministic lexical order, so hashing
+ // in visit order yields a stable revision.
+ isProtected := w.protected[rel]
+ writeProjectFileRevisionEntryInternal(w.revisionHash, rel, info, entry.IsDir(), isProtected)
+ w.entryCount++
+
+ if isProtected {
+ return nil
+ }
+
+ size := info.Size()
+ if entry.IsDir() {
+ size = 0
+ }
+ w.files = append(w.files, project.ProjectFile{
+ Path: filepath.Join(w.projectAbs, filepath.FromSlash(rel)),
+ RelativePath: rel,
+ Name: entry.Name(),
+ IsDirectory: entry.IsDir(),
+ Size: size,
+ ModTime: info.ModTime(),
+ Protected: false,
})
- return files, hex.EncodeToString(revisionHash.Sum(nil)), nil
+ return nil
}
func ApplyProjectFileDrafts(projectPath string, drafts []project.ProjectFileDraft, opts ProjectFileApplyOptions) error {
@@ -163,7 +198,7 @@ func ApplyProjectFileChanges(projectPath string, changes []project.ProjectFileCh
}
if opts.ExpectedRevision != "" {
- _, currentRevision, err := ReadProjectFileTree(projectPath, opts.MaxDepth, opts.SkipDirectories, opts.ComposeFileName)
+ _, currentRevision, _, err := ReadProjectFileTree(projectPath, opts.MaxDepth, opts.SkipDirectories, opts.ComposeFileName, opts.MaxEntries)
if err != nil {
return fmt.Errorf("read project file tree revision: %w", err)
}
diff --git a/backend/pkg/projects/project_files_test.go b/backend/pkg/projects/project_files_test.go
index bb88912a7..fd4180c84 100644
--- a/backend/pkg/projects/project_files_test.go
+++ b/backend/pkg/projects/project_files_test.go
@@ -2,6 +2,7 @@ package projects
import (
"errors"
+ "fmt"
"os"
"path/filepath"
"strings"
@@ -26,7 +27,7 @@ func TestReadProjectFileTree_ExcludesProtectedFilesAndReturnsFolders(t *testing.
require.NoError(t, os.MkdirAll(filepath.Join(projectDir, ".git"), 0o755))
require.NoError(t, os.WriteFile(filepath.Join(projectDir, ".git", "config"), []byte("private"), 0o644))
- files, revision, err := ReadProjectFileTree(projectDir, 3, "", "compose.yaml")
+ files, revision, _, err := ReadProjectFileTree(projectDir, 3, "", "compose.yaml", 0)
require.NoError(t, err)
require.NotEmpty(t, revision)
@@ -46,7 +47,7 @@ func TestReadProjectFileTree_ZeroMaxDepthDisablesExpansion(t *testing.T) {
require.NoError(t, os.MkdirAll(filepath.Join(projectDir, "config"), 0o755))
require.NoError(t, os.WriteFile(filepath.Join(projectDir, "config", "app.yaml"), []byte("value: true\n"), 0o644))
- files, revision, err := ReadProjectFileTree(projectDir, 0, "", "compose.yaml")
+ files, revision, _, err := ReadProjectFileTree(projectDir, 0, "", "compose.yaml", 0)
require.NoError(t, err)
assert.NotEmpty(t, revision)
assert.Empty(t, files)
@@ -61,7 +62,7 @@ func TestReadProjectFileTree_UseScanDepthSentinelUsesFileTreeMaxDepth(t *testing
require.NoError(t, os.WriteFile(filepath.Join(projectDir, "level1", "visible.txt"), []byte("visible\n"), 0o644))
require.NoError(t, os.WriteFile(filepath.Join(projectDir, "level1", "level2", "hidden.txt"), []byte("hidden\n"), 0o644))
- files, _, err := ReadProjectFileTree(projectDir, ProjectFileTreeUseScanDepth, "", "compose.yaml")
+ files, _, _, err := ReadProjectFileTree(projectDir, ProjectFileTreeUseScanDepth, "", "compose.yaml", 0)
require.NoError(t, err)
relativePaths := make([]string, 0, len(files))
@@ -194,7 +195,7 @@ func TestApplyProjectFileChanges_UsesRevisionConflictDetection(t *testing.T) {
require.NoError(t, os.WriteFile(filepath.Join(projectDir, "compose.yaml"), []byte("services: {}\n"), 0o644))
require.NoError(t, os.WriteFile(filepath.Join(projectDir, "notes.txt"), []byte("old\n"), 0o644))
- _, revision, err := ReadProjectFileTree(projectDir, 3, "", "compose.yaml")
+ _, revision, _, err := ReadProjectFileTree(projectDir, 3, "", "compose.yaml", 0)
require.NoError(t, err)
require.NoError(t, os.WriteFile(filepath.Join(projectDir, "notes.txt"), []byte("changed elsewhere\n"), 0o644))
@@ -334,3 +335,49 @@ func TestValidateProjectFileName_RejectsPathSeparators(t *testing.T) {
_, err := ValidateProjectFileName(strings.Join([]string{"folder", "name"}, string(filepath.Separator)))
require.Error(t, err)
}
+
+func TestReadProjectFileTree_CapsEntriesWithStableRevision(t *testing.T) {
+ t.Parallel()
+
+ projectDir := t.TempDir()
+ require.NoError(t, os.WriteFile(filepath.Join(projectDir, "compose.yaml"), []byte("services: {}\n"), 0o644))
+ for i := range 5 {
+ require.NoError(t, os.WriteFile(filepath.Join(projectDir, fmt.Sprintf("file-%d.txt", i)), []byte("x\n"), 0o644))
+ }
+
+ files, revision, truncated, err := ReadProjectFileTree(projectDir, 3, "", "compose.yaml", 3)
+ require.NoError(t, err)
+ assert.True(t, truncated)
+ // compose.yaml is hashed but protected (not returned), so the cap of 3
+ // hashed entries yields 2 listed files.
+ assert.Len(t, files, 2)
+
+ _, again, truncatedAgain, err := ReadProjectFileTree(projectDir, 3, "", "compose.yaml", 3)
+ require.NoError(t, err)
+ assert.True(t, truncatedAgain)
+ assert.Equal(t, revision, again)
+}
+
+func TestApplyProjectFileChanges_SucceedsWithCappedRevision(t *testing.T) {
+ t.Parallel()
+
+ projectDir := t.TempDir()
+ require.NoError(t, os.WriteFile(filepath.Join(projectDir, "compose.yaml"), []byte("services: {}\n"), 0o644))
+ for i := range 5 {
+ require.NoError(t, os.WriteFile(filepath.Join(projectDir, fmt.Sprintf("file-%d.txt", i)), []byte("x\n"), 0o644))
+ }
+
+ _, revision, truncated, err := ReadProjectFileTree(projectDir, 3, "", "compose.yaml", 3)
+ require.NoError(t, err)
+ require.True(t, truncated)
+
+ err = ApplyProjectFileChanges(projectDir, []project.ProjectFileChange{
+ {Operation: "update_file", RelativePath: "file-0.txt", Content: new("new\n")},
+ }, ProjectFileApplyOptions{
+ ExpectedRevision: revision,
+ MaxDepth: 3,
+ MaxEntries: 3,
+ ComposeFileName: "compose.yaml",
+ })
+ require.NoError(t, err)
+}
diff --git a/frontend/src/lib/query/query-keys.ts b/frontend/src/lib/query/query-keys.ts
index 23b75d9ed..b1e553a96 100644
--- a/frontend/src/lib/query/query-keys.ts
+++ b/frontend/src/lib/query/query-keys.ts
@@ -111,7 +111,8 @@ export const queryKeys = {
detailCheckUpdates: (environmentId: string, projectId: string) =>
['project', 'check-updates', environmentId, projectId] as const,
statusCounts: (environmentId: string) => ['projects', 'status-counts', environmentId] as const,
- detail: (environmentId: string, projectId: string) => ['project', environmentId, projectId] as const
+ detail: (environmentId: string, projectId: string) => ['project', environmentId, projectId] as const,
+ files: (environmentId: string, projectId: string) => ['project', environmentId, projectId, 'files'] as const
},
networks: {
all: ['networks'] as const,
diff --git a/frontend/src/lib/services/project-service.ts b/frontend/src/lib/services/project-service.ts
index fdc2cefbe..17fdf9909 100644
--- a/frontend/src/lib/services/project-service.ts
+++ b/frontend/src/lib/services/project-service.ts
@@ -77,10 +77,11 @@ class ProjectService extends BaseAPIService {
async getProjectForEnvironment(environmentId: string, projectId: string): Promise<Project> {
const basePath = `/environments/${environmentId}/projects/${projectId}`;
- const [summary, compose, files, runtime, updates] = await Promise.all([
+ // The /files section walks the project directory recursively and can be
+ // slow on large projects, so it is fetched lazily via getProjectFiles.
+ const [summary, compose, runtime, updates] = await Promise.all([
this.getProjectSection(basePath),
this.getProjectSection(`${basePath}/compose`),
- this.getProjectSection(`${basePath}/files`),
this.getProjectSection(`${basePath}/runtime`),
this.getProjectSection(`${basePath}/updates`)
]);
@@ -88,12 +89,15 @@ class ProjectService extends BaseAPIService {
return {
...summary,
...compose,
- ...files,
...runtime,
updateInfo: updates.updateInfo ?? compose.updateInfo ?? summary.updateInfo
};
}
+ async getProjectFiles(environmentId: string, projectId: string): Promise<Project> {
+ return this.getProjectSection(`/environments/${environmentId}/projects/${projectId}/files`);
+ }
+
private async getProjectSection(path: string): Promise<Project> {
const response = await this.handleResponse<{ project?: Project; success?: boolean } | Project>(this.api.get(path));
return 'project' in response && response.project ? response.project : (response as Project);
diff --git a/frontend/src/lib/types/swarm.ts b/frontend/src/lib/types/swarm.ts
index ec4a73429..25286df1b 100644
--- a/frontend/src/lib/types/swarm.ts
+++ b/frontend/src/lib/types/swarm.ts
@@ -551,6 +551,7 @@ export interface Project {
directoryFiles?: IncludeFile[];
projectFiles?: ProjectFile[];
fileTreeRevision?: string;
+ fileTreeTruncated?: boolean;
}
export interface ProjectStatusCounts {
diff --git a/frontend/src/routes/(app)/projects/[projectId]/+page.svelte b/frontend/src/routes/(app)/projects/[projectId]/+page.svelte
index ba528ed41..921a71eb7 100644
--- a/frontend/src/routes/(app)/projects/[projectId]/+page.svelte
+++ b/frontend/src/routes/(app)/projects/[projectId]/+page.svelte
@@ -112,6 +112,13 @@
refetchOnMount: false
}));
+ // The file tree walk can be slow on large projects, so it loads lazily and
+ // never blocks navigation; +page.ts prefetches this key without awaiting.
+ const projectFilesQuery = createQuery(() => ({
+ queryKey: queryKeys.projects.files(envId, projectId),
+ queryFn: () => projectService.getProjectFiles(envId, projectId)
+ }));
+
const lifecycleSyncQuery = createQuery(() => {
const syncId = data.project?.gitOpsManagedBy;
return {
@@ -172,7 +179,11 @@
};
}
- const project = $derived.by(() => withLoadedProjectFileContent(projectDetailQuery.data ?? data.project));
+ const project = $derived.by(() => {
+ const detail = projectDetailQuery.data ?? data.project;
+ if (!detail) return null;
+ return withLoadedProjectFileContent({ ...detail, ...(projectFilesQuery.data ?? {}) });
+ });
const projectImageRefs = $derived.by(() => getProjectImageRefs(project));
const serverName = $derived(project?.name ?? '');
const serverComposeContent = $derived(project?.composeContent ?? '');
@@ -514,7 +525,28 @@
async function syncProjectQueries(updatedProject: Project) {
const currentEnvId = envId ?? (await environmentStore.getCurrentEnvironmentId());
- queryClient.setQueryData(queryKeys.projects.detail(currentEnvId, updatedProject.id), updatedProject);
+ // The save response is slim (no directory walks), so merge it into the
+ // cached detail instead of replacing it wholesale.
+ queryClient.setQueryData(
+ queryKeys.projects.detail(currentEnvId, updatedProject.id),
+ (old: Project | undefined) => ({ ...(old ?? {}), ...updatedProject }) as Project
+ );
+ if (updatedProject.projectFiles || updatedProject.fileTreeRevision) {
+ // A file-changes save returns a fresh tree + revision; sync it into the
+ // files cache so the next file save doesn't hit a revision conflict.
+ queryClient.setQueryData(
+ queryKeys.projects.files(currentEnvId, updatedProject.id),
+ (old: Project | undefined) =>
+ ({
+ ...(old ?? {}),
+ projectFiles: updatedProject.projectFiles,
+ fileTreeRevision: updatedProject.fileTreeRevision,
+ fileTreeTruncated: updatedProject.fileTreeTruncated
+ }) as Project
+ );
+ } else {
+ await queryClient.invalidateQueries({ queryKey: queryKeys.projects.files(currentEnvId, updatedProject.id) });
+ }
await Promise.all([
queryClient.invalidateQueries({ queryKey: ['projects', currentEnvId] }),
queryClient.invalidateQueries({ queryKey: queryKeys.projects.statusCounts(currentEnvId) })
@@ -556,9 +588,13 @@
if (!project?.id) return;
if (lastPrefsProjectId === project.id) return;
- lastPrefsProjectId = project.id;
const prefsStorageKey = `arcane.compose.ui:${project.id}`;
const hadStoredPrefs = sessionStorage.getItem(prefsStorageKey) !== null;
+ // The tree/classic auto-detect needs the lazily loaded file tree; without
+ // stored prefs, wait for the files query to settle before finalizing.
+ if (!hadStoredPrefs && !(projectFilesQuery.isSuccess || projectFilesQuery.isError)) return;
+
+ lastPrefsProjectId = project.id;
prefs = new PersistedState<ComposeUIPrefs>(prefsStorageKey, defaultComposeUIPrefs, {
storage: 'session',
syncTabs: false
diff --git a/frontend/src/routes/(app)/projects/[projectId]/+page.ts b/frontend/src/routes/(app)/projects/[projectId]/+page.ts
index ac91d208f..b90a51900 100644
--- a/frontend/src/routes/(app)/projects/[projectId]/+page.ts
+++ b/frontend/src/routes/(app)/projects/[projectId]/+page.ts
@@ -34,6 +34,13 @@ export const load: PageLoad = async ({ params, parent }) => {
throwPageLoadError(err, 'Failed to load project');
}
+ // Kick off the file-tree walk without awaiting it: on large projects it can
+ // take a while and must not block navigation.
+ void queryClient.prefetchQuery({
+ queryKey: queryKeys.projects.files(envId, params.projectId),
+ queryFn: () => projectService.getProjectFiles(envId, params.projectId)
+ });
+
const globalVariables = await loadGlobalVariables(queryClient);
const editorState = {
diff --git a/types/project/project.go b/types/project/project.go
index 19f4203a5..bb9bde86f 100644
--- a/types/project/project.go
+++ b/types/project/project.go
@@ -517,6 +517,12 @@ type Details struct {
// Required: false
FileTreeRevision string `json:"fileTreeRevision,omitempty"`
+ // FileTreeTruncated indicates the file tree walk hit the entry cap and
+ // ProjectFiles is only a prefix of the full tree.
+ //
+ // Required: false
+ FileTreeTruncated bool `json:"fileTreeTruncated,omitempty"`
+
// Status is the current status of the project.
//
// Required: true