A continuation of HomeBox the inventory and organization system built for the Home User
fix: #1424 migrate legacy flat-encoded windows attachment paths
Matthew Kilgore836cae83c89d
diff --git a/backend/app/api/main.go b/backend/app/api/main.goindex 5ad36ff8..0c8de911 100644--- a/backend/app/api/main.go+++ b/backend/app/api/main.go@@ -5,6 +5,7 @@ import ("errors""fmt""net/http"+ "runtime""strings""time"@@ -213,6 +214,16 @@ func run(cfg *config.Config) error {app.bus = eventbus.New()app.db = capp.repos = repo.New(c, app.bus, cfg.Storage, cfg.Database.PubSubConnString, cfg.Thumbnail)++ // Attachment-key escaping in fileblob only flattens paths on Windows+ // (where os.PathSeparator is "\"), so the legacy-path rename is a Windows-+ // only concern; skip the disk scan everywhere else.+ if runtime.GOOS == "windows" {+ if err := app.repos.Attachments.MigrateLegacyFlatPaths(); err != nil {+ log.Error().Err(err).Msg("failed to migrate legacy attachment file paths")+ }+ }+app.services = services.New(app.repos,services.WithAutoIncrementAssetID(cfg.Options.AutoIncrementAssetID),diff --git a/backend/internal/data/repo/repo_item_attachments.go b/backend/internal/data/repo/repo_item_attachments.goindex 704dc169..6efd2df9 100644--- a/backend/internal/data/repo/repo_item_attachments.go+++ b/backend/internal/data/repo/repo_item_attachments.go@@ -9,6 +9,7 @@ import ("io""io/fs""net/http"+ "os""path/filepath""runtime""strings"@@ -104,6 +105,111 @@ func normalizePath(path string) string {return strings.Trim(path, "/")}+// legacyFlatPathToken is the gocloud fileblob escape sequence for a backslash+// (0x5c). On Windows, pre-v0.22.1 attachment keys built with filepath.Join used+// "\" as the path separator; fileblob escaped that to this token, so files were+// stored as flat names at the bucket root. v0.22.1+ uses "/" so files now live+// in real subdirectories.+const legacyFlatPathToken = "__0x5c__"++// bucketLocalDir returns the absolute on-disk directory backing the fileblob+// bucket, or "" if the storage backend is not a file:// URL.+func (r *AttachmentRepo) bucketLocalDir() (string, error) {+ cs := r.storage.ConnString+ if !strings.HasPrefix(cs, "file://") {+ return "", nil+ }+ // Homebox-specific shortcut for "relative to cwd".+ if strings.HasPrefix(cs, "file:///./") {+ return filepath.Abs(strings.TrimPrefix(cs, "file:///./"))+ }+ raw := strings.TrimPrefix(cs, "file://")+ if i := strings.IndexAny(raw, "?#"); i >= 0 {+ raw = raw[:i]+ }+ // On Windows a file URL looks like file:///C:/foo, so strip the empty-host+ // leading slash before treating the rest as a native path.+ if runtime.GOOS == "windows" && len(raw) >= 3 && raw[0] == '/' && raw[2] == ':' {+ raw = raw[1:]+ }+ return filepath.Abs(raw)+}++// MigrateLegacyFlatPaths renames attachment files written by older homebox+// versions on Windows from a flat-escaped layout into a real subdirectory+// layout. It is a no-op when the storage backend is not file:// or when no+// matching files are found, so it is safe to run on every startup. Callers+// should gate invocation on runtime.GOOS == "windows" since no other platform+// can produce these files.+func (r *AttachmentRepo) MigrateLegacyFlatPaths() error {+ root, err := r.bucketLocalDir()+ if err != nil {+ return err+ }+ if root == "" {+ return nil+ }+ info, err := os.Stat(root)+ if err != nil {+ if os.IsNotExist(err) {+ return nil+ }+ return err+ }+ if !info.IsDir() {+ return nil+ }++ entries, err := os.ReadDir(root)+ if err != nil {+ return fmt.Errorf("read bucket root %s: %w", root, err)+ }++ moved, skipped := 0, 0+ for _, entry := range entries {+ if entry.IsDir() {+ continue+ }+ name := entry.Name()+ if !strings.Contains(name, legacyFlatPathToken) {+ continue+ }++ decoded := strings.ReplaceAll(name, legacyFlatPathToken, string(filepath.Separator))+ oldPath := filepath.Join(root, name)+ newPath := filepath.Join(root, decoded)++ if _, statErr := os.Stat(newPath); statErr == nil {+ log.Warn().Str("source", oldPath).Str("target", newPath).+ Msg("legacy attachment migration: target already exists, leaving source in place")+ skipped+++ continue+ } else if !os.IsNotExist(statErr) {+ log.Err(statErr).Str("target", newPath).Msg("legacy attachment migration: failed to stat target")+ skipped+++ continue+ }++ if err := os.MkdirAll(filepath.Dir(newPath), 0o755); err != nil {+ log.Err(err).Str("dir", filepath.Dir(newPath)).Msg("legacy attachment migration: failed to create parent directory")+ skipped+++ continue+ }+ if err := os.Rename(oldPath, newPath); err != nil {+ log.Err(err).Str("source", oldPath).Str("target", newPath).Msg("legacy attachment migration: failed to rename file")+ skipped+++ continue+ }+ moved+++ }++ if moved > 0 || skipped > 0 {+ log.Info().Int("moved", moved).Int("skipped", skipped).+ Msg("migrated legacy flat-encoded attachment files")+ }+ return nil+}+func (r *AttachmentRepo) path(gid uuid.UUID, hash string) string {// Always use forward slashes for consistency across platforms// This ensures paths are stored in the database with forward slashesdiff --git a/backend/internal/data/repo/repo_item_attachments_test.go b/backend/internal/data/repo/repo_item_attachments_test.goindex ff1d9cae..c3f238b9 100644--- a/backend/internal/data/repo/repo_item_attachments_test.go+++ b/backend/internal/data/repo/repo_item_attachments_test.go@@ -2,6 +2,8 @@ package repoimport ("context"+ "os"+ "path/filepath""strings""testing"@@ -331,3 +333,65 @@ func TestAttachmentRepo_PathNormalization(t *testing.T) {assert.Equal(t, "eb6bf410-a1a8-478d-a803-ca3948368a0c/documents/f295eb01-18a9-4631-a797-70bd9623edd4.png", fullPathSlashPrefix)assert.NotContains(t, fullPathSlashPrefix, "//", "fullPath() should not have double slashes")}++func TestAttachmentRepo_MigrateLegacyFlatPaths(t *testing.T) {+ root := t.TempDir()++ // Legacy flat-encoded files written by pre-v0.22.1 homebox on Windows.+ legacy1 := ".data__0x5c__eb6bf410-a1a8-478d-a803-ca3948368a0c__0x5c__documents__0x5c__hash1.png"+ legacy2 := ".data__0x5c__eb6bf410-a1a8-478d-a803-ca3948368a0c__0x5c__documents__0x5c__hash2.png"+ require.NoError(t, os.WriteFile(filepath.Join(root, legacy1), []byte("one"), 0o644))+ require.NoError(t, os.WriteFile(filepath.Join(root, legacy2), []byte("two"), 0o644))++ // Unrelated file at the bucket root must be left alone.+ other := filepath.Join(root, "homebox.db")+ require.NoError(t, os.WriteFile(other, []byte("db"), 0o644))++ r := &AttachmentRepo{storage: config.Storage{ConnString: "file://" + root, PrefixPath: ".data"}}++ require.NoError(t, r.MigrateLegacyFlatPaths())++ for _, name := range []string{legacy1, legacy2} {+ _, err := os.Stat(filepath.Join(root, name))+ assert.True(t, os.IsNotExist(err), "legacy file %s should have been moved", name)+ }+ for _, hash := range []string{"hash1.png", "hash2.png"} {+ want := filepath.Join(root, ".data", "eb6bf410-a1a8-478d-a803-ca3948368a0c", "documents", hash)+ _, err := os.Stat(want)+ assert.NoError(t, err, "expected migrated file at %s", want)+ }+ _, err := os.Stat(other)+ assert.NoError(t, err, "unrelated files at the bucket root should be left in place")++ // Idempotent: running again should be a no-op and not error.+ require.NoError(t, r.MigrateLegacyFlatPaths())+}++func TestAttachmentRepo_MigrateLegacyFlatPaths_NoOpForCloudBackend(t *testing.T) {+ r := &AttachmentRepo{storage: config.Storage{ConnString: "s3://my-bucket"}}+ require.NoError(t, r.MigrateLegacyFlatPaths())+}++func TestAttachmentRepo_MigrateLegacyFlatPaths_TargetExistsKeepsSource(t *testing.T) {+ root := t.TempDir()++ legacy := "uuid__0x5c__documents__0x5c__hash.png"+ require.NoError(t, os.WriteFile(filepath.Join(root, legacy), []byte("legacy"), 0o644))++ // Pre-existing target — migration should leave the source in place rather+ // than overwrite the (presumably-correct) target.+ target := filepath.Join(root, "uuid", "documents", "hash.png")+ require.NoError(t, os.MkdirAll(filepath.Dir(target), 0o755))+ require.NoError(t, os.WriteFile(target, []byte("new"), 0o644))++ r := &AttachmentRepo{storage: config.Storage{ConnString: "file://" + root}}+ require.NoError(t, r.MigrateLegacyFlatPaths())++ src, err := os.ReadFile(filepath.Join(root, legacy))+ require.NoError(t, err)+ assert.Equal(t, "legacy", string(src), "source file should remain untouched when target exists")++ dst, err := os.ReadFile(target)+ require.NoError(t, err)+ assert.Equal(t, "new", string(dst), "target file should not be overwritten")+}