Skip to content

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.go
index 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 = c
app.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.go
index 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 slashes
diff --git a/backend/internal/data/repo/repo_item_attachments_test.go b/backend/internal/data/repo/repo_item_attachments_test.go
index 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 repo
import (
"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")
+}