fix: windows migration panic with platform-specific atomic operations

implements platform-specific atomic file operations to handle Windows
file locking during migrations.

key changes:
- read config into memory before atomic operations to avoid file locks
- use simple write for backup (not atomic) since it's a new file
- add sync and retry logic with exponential backoff on Windows
- use MoveFileEx with MOVEFILE_REPLACE_EXISTING for atomic renames
- fix TestRepoDir to set USERPROFILE on Windows (not just HOME)

fixes the "panic: error can't be dealt with transactionally: Access
is denied" error during repo migration from v17 to v18 on Windows.

Author: lidel

docs/changelogs/v0.38.md

@@ -5,6 +5,7 @@
 This release was brought to you by the [Shipyard](https://ipshipyard.com/) team.
 
 - [v0.38.0](#v0380)
+- [v0.38.1](#v0381)
 
 ## v0.38.0
 
@@ -290,3 +291,26 @@ The new [`Internal.MFSNoFlushLimit`](https://github.com/ipfs/kubo/blob/master/do
 | Jakub Sztandera | 1 | +67/-15 | 3 |
 | Masih H. Derkani | 1 | +1/-2 | 2 |
 | Dominic Della Valle | 1 | +2/-1 | 1 |
+
+## v0.38.1
+
+This patch release fixes a critical issue on Windows where repository migrations from version 17 to 18 would fail with "panic: error can't be dealt with transactionally: Access is denied."
+
+The issue was caused by Windows file locking semantics preventing atomic file operations during the migration. This release implements platform-specific file handling with retry logic to work around Windows file system limitations.
+
+### Changelog
+
+<details>
+<summary>Full Changelog</summary>
+
+- github.com/ipfs/kubo:
+  - fix: windows migration panic with platform-specific atomic file operations
+  - fix: add sync and retry logic for Windows file operations to handle transient locks
+
+</details>
+
+### 👨‍👩‍👧‍👦 Contributors
+
+| Contributor | Commits | Lines ± | Files Changed |
+|-------------|---------|---------|---------------|
+| TBD | | | |

…repo/migrations/atomicfile/atomicfile.go …grations/atomicfile/atomicfile_common.gorepo/fsrepo/migrations/atomicfile/atomicfile.go renamed to repo/fsrepo/migrations/atomicfile/atomicfile_common.go repo/fsrepo/migrations/atomicfile/atomicfile.go renamed to repo/fsrepo/migrations/atomicfile/atomicfile_common.go

@@ -32,21 +32,6 @@ func New(path string, mode os.FileMode) (*File, error) {
 	}, nil
 }
 
-// Close atomically replaces the target file with the temporary file
-func (f *File) Close() error {
-	if err := f.File.Close(); err != nil {
-		os.Remove(f.File.Name())
-		return err
-	}
-
-	if err := os.Rename(f.File.Name(), f.path); err != nil {
-		os.Remove(f.File.Name())
-		return err
-	}
-
-	return nil
-}
-
 // Abort removes the temporary file without replacing the target
 func (f *File) Abort() error {
 	f.File.Close()

repo/fsrepo/migrations/atomicfile/atomicfile_test.go

@@ -0,0 +1,88 @@
+package atomicfile
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestAtomicFile(t *testing.T) {
+	tempDir := t.TempDir()
+	targetPath := filepath.Join(tempDir, "target.txt")
+
+	// Test creating a new file atomically
+	af, err := New(targetPath, 0600)
+	if err != nil {
+		t.Fatalf("failed to create atomic file: %v", err)
+	}
+
+	testContent := "test content"
+	if _, err := af.Write([]byte(testContent)); err != nil {
+		t.Fatalf("failed to write to atomic file: %v", err)
+	}
+
+	// Close should rename the temp file to target
+	if err := af.Close(); err != nil {
+		t.Fatalf("failed to close atomic file: %v", err)
+	}
+
+	// Verify target file exists with correct content
+	content, err := os.ReadFile(targetPath)
+	if err != nil {
+		t.Fatalf("failed to read target file: %v", err)
+	}
+	if string(content) != testContent {
+		t.Errorf("content mismatch: got %q, want %q", string(content), testContent)
+	}
+
+	// Test replacing an existing file
+	af2, err := New(targetPath, 0600)
+	if err != nil {
+		t.Fatalf("failed to create second atomic file: %v", err)
+	}
+
+	newContent := "new content"
+	if _, err := af2.Write([]byte(newContent)); err != nil {
+		t.Fatalf("failed to write to second atomic file: %v", err)
+	}
+
+	// This should replace the existing file
+	if err := af2.Close(); err != nil {
+		t.Fatalf("failed to close second atomic file: %v", err)
+	}
+
+	// Verify file was replaced
+	content, err = os.ReadFile(targetPath)
+	if err != nil {
+		t.Fatalf("failed to read replaced file: %v", err)
+	}
+	if string(content) != newContent {
+		t.Errorf("content not replaced: got %q, want %q", string(content), newContent)
+	}
+}
+
+func TestAtomicFileAbort(t *testing.T) {
+	tempDir := t.TempDir()
+	targetPath := filepath.Join(tempDir, "target.txt")
+
+	// Create an atomic file
+	af, err := New(targetPath, 0600)
+	if err != nil {
+		t.Fatalf("failed to create atomic file: %v", err)
+	}
+
+	// Write some content
+	if _, err := af.Write([]byte("should be aborted")); err != nil {
+		t.Fatalf("failed to write to atomic file: %v", err)
+	}
+
+	// Abort should remove temp file without creating target
+	if err := af.Abort(); err != nil {
+		t.Fatalf("failed to abort atomic file: %v", err)
+	}
+
+	// Verify target file doesn't exist
+	if _, err := os.Stat(targetPath); !os.IsNotExist(err) {
+		t.Errorf("target file should not exist after abort")
+	}
+}

repo/fsrepo/migrations/atomicfile/atomicfile_unix.go

@@ -0,0 +1,24 @@
+//go:build !windows
+// +build !windows
+
+package atomicfile
+
+import (
+	"os"
+)
+
+// Close atomically replaces the target file with the temporary file on Unix-like systems
+func (f *File) Close() error {
+	if err := f.File.Close(); err != nil {
+		os.Remove(f.File.Name())
+		return err
+	}
+
+	// On Unix-like systems, os.Rename is atomic and can replace existing files
+	if err := os.Rename(f.File.Name(), f.path); err != nil {
+		os.Remove(f.File.Name())
+		return err
+	}
+
+	return nil
+}

repo/fsrepo/migrations/atomicfile/atomicfile_windows.go

@@ -0,0 +1,83 @@
+//go:build windows
+// +build windows
+
+package atomicfile
+
+import (
+	"os"
+	"time"
+
+	"golang.org/x/sys/windows"
+)
+
+// Close atomically replaces the target file with the temporary file on Windows
+func (f *File) Close() error {
+	// Sync to ensure all data is written to disk before closing
+	// This is important on Windows to avoid file locking issues
+	if err := f.File.Sync(); err != nil {
+		// Sync error is non-fatal, continue with close
+		_ = err
+	}
+
+	// Close the file handle first
+	if err := f.File.Close(); err != nil {
+		os.Remove(f.File.Name())
+		return err
+	}
+
+	// On Windows, always use MoveFileEx for atomic operations
+	// os.Rename fails when files are locked or in use, which is common on Windows
+
+	// First attempt with standard rename to see if it works
+	// This is faster when there are no locks
+	err := os.Rename(f.File.Name(), f.path)
+	if err == nil {
+		return nil
+	}
+
+	// If rename failed, wait a bit for file handles to be released
+	// Windows sometimes holds file handles briefly after close
+	time.Sleep(time.Millisecond * 10)
+
+	// Retry logic to handle transient locks from antivirus/indexing
+	const maxRetries = 5
+	var lastErr error
+	for i := 0; i < maxRetries; i++ {
+		if i > 0 {
+			// Exponential backoff with longer delays
+			time.Sleep(time.Millisecond * 100 * time.Duration(i))
+		}
+
+		// Convert paths to UTF16 for Windows API
+		from, err := windows.UTF16PtrFromString(f.File.Name())
+		if err != nil {
+			lastErr = err
+			continue
+		}
+
+		to, err := windows.UTF16PtrFromString(f.path)
+		if err != nil {
+			lastErr = err
+			continue
+		}
+
+		// Use MoveFileEx with MOVEFILE_REPLACE_EXISTING to atomically replace the file
+		// MOVEFILE_WRITE_THROUGH ensures the file is flushed to disk
+		err = windows.MoveFileEx(from, to,
+			windows.MOVEFILE_REPLACE_EXISTING|windows.MOVEFILE_WRITE_THROUGH)
+
+		if err == nil {
+			return nil
+		}
+
+		lastErr = err
+		// Check if it's a retryable error
+		if err != windows.ERROR_SHARING_VIOLATION && err != windows.ERROR_LOCK_VIOLATION && err != windows.ERROR_ACCESS_DENIED {
+			break
+		}
+	}
+
+	// Clean up temp file on failure
+	os.Remove(f.File.Name())
+	return lastErr
+}

repo/fsrepo/migrations/common/utils.go

@@ -1,6 +1,7 @@
 package common
 
 import (
+	"bytes"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -40,47 +41,42 @@ func Must(err error) {
 
 // WithBackup performs a config file operation with automatic backup and rollback on error
 func WithBackup(configPath string, backupSuffix string, fn func(in io.ReadSeeker, out io.Writer) error) error {
-	in, err := os.Open(configPath)
+	// Read the entire file into memory first
+	// This allows us to close the file before doing atomic operations,
+	// which is necessary on Windows where open files can't be renamed
+	data, err := os.ReadFile(configPath)
 	if err != nil {
 		return err
 	}
-	defer in.Close()
 
-	// Create backup
-	backup, err := atomicfile.New(configPath+backupSuffix, 0600)
-	if err != nil {
-		return err
-	}
-
-	// Copy to backup
-	if _, err := backup.ReadFrom(in); err != nil {
-		Must(backup.Abort())
-		return err
-	}
+	// Create an in-memory reader for the data
+	in := bytes.NewReader(data)
 
-	// Reset input for reading
-	if _, err := in.Seek(0, io.SeekStart); err != nil {
-		Must(backup.Abort())
+	// Create backup using direct write (not atomic, since backup doesn't need to be atomic)
+	backupPath := configPath + backupSuffix
+	if err := os.WriteFile(backupPath, data, 0600); err != nil {
 		return err
 	}
 
-	// Create output file
+	// Create output file atomically
 	out, err := atomicfile.New(configPath, 0600)
 	if err != nil {
-		Must(backup.Abort())
+		// Clean up backup on error
+		os.Remove(backupPath)
 		return err
 	}
 
 	// Run the conversion function
 	if err := fn(in, out); err != nil {
 		Must(out.Abort())
-		Must(backup.Abort())
+		// Clean up backup on error
+		os.Remove(backupPath)
 		return err
 	}
 
-	// Close everything on success
+	// Close the output file atomically
 	Must(out.Close())
-	Must(backup.Close())
+	// Backup remains for potential revert
 
 	return nil
 }