fix cross-device error for temp file - fixed #122 (#320)

* fix cross-device error for temp file - fixed #122

* add changelog

* address pr comments

Author: funkyshu

CHANGELOG.md

@@ -6,6 +6,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `backend/os.WithTempDir` option to specify a custom directory for intermediate temporary files during OS write operations, providing a reliable way to resolve cross-device rename issues (#122).
+
+### Fixed
+- OS backend now selects temporary file locations on the same device/volume as the target file by default, preventing cross-device rename errors (#122).
+- Fixed OS backend handling of Windows drive letters in URIs: the drive letter (e.g. `C:`) is now correctly part of the path (`file:///C:/...`) rather than the authority, conforming to RFC 8089.
+
 ## [v7.15.0] - 2026-03-06
 ### Added
 - Added AGENTS.md with comprehensive guidelines for AI agents, including development standards, testing requirements, CHANGELOG/PR process, Go version policy, GitHub Actions maintenance, and module management.

backend/os/doc.go

@@ -3,27 +3,47 @@ Package os - built-in os lib VFS implementation.
 
 # Usage
 
-Rely on github.com/c2fo/vfs/v7/backend
+The OS backend interacts directly with the local operating system's file system.
+
+It can be initialized using the backend registry:
 
 	import(
 	    "github.com/c2fo/vfs/v7/backend"
-	    "github.com/c2fo/vfs/v7/backend/os"
+	    _ "github.com/c2fo/vfs/v7/backend/os"
 	)
 
 	func UseFs() error {
-	    fs := backend.Backend(os.Scheme)
+	    fs, err := backend.NewFileSystem(os.Scheme)
+	    if err != nil {
+	        return err
+	    }
+	    // Use fs
 	    ...
 	}
 
-Or call directly:
+Or by calling directly:
 
 	import _os "github.com/c2fo/vfs/v7/backend/os"
 
 	func DoSomething() {
-	    fs := &_os.NewFileSystem()
+	    fs := _os.NewFileSystem()
+
+	    // Or with a custom temporary directory
+	    fsWithOpts := _os.NewFileSystem(
+	        _os.WithTempDir{TempDir: "/path/to/my/temp"},
+	    )
 	    ...
 	}
 
+# Options
+
+The OS backend supports the following options for NewFileSystem:
+
+  - WithTempDir: Specifies a custom directory path for temporary files used
+    during write operations. If not provided, the backend uses the system
+    temp directory when it's on the same device as the target file, or falls
+    back to the target file's parent directory.
+
 # See Also
 
 See: https://golang.org/pkg/os/

backend/os/file.go

@@ -32,6 +32,7 @@ type File struct {
 	fileOpener  opener
 	seekCalled  bool
 	readCalled  bool
+	tempDir     string
 }
 
 // Delete unlinks the file returning any error or nil.
@@ -461,30 +462,45 @@ func (f *File) getInternalFile() (*os.File, error) {
 }
 
 func (f *File) copyToLocalTempReader() (*os.File, error) {
-	tmpFile, err := os.CreateTemp("", fmt.Sprintf("%s.%d", f.Name(), time.Now().UnixNano()))
+	filePath := osFilePath(f)
+
+	tempDir, err := f.selectTempDir(filePath)
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("failed to select temp directory for %s: %w", filePath, err)
 	}
 
-	exists, err := f.Exists()
+	tmpFile, err := os.CreateTemp(tempDir, ".vfs-*.tmp")
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("failed to create temp file for %s: %w", filePath, err)
 	}
 
+	// Clean up temp file on any error after this point
+	ok := false
+	defer func() {
+		if !ok {
+			_ = tmpFile.Close()
+			_ = os.Remove(tmpFile.Name())
+		}
+	}()
+
 	// If file exists AND we've called Seek or Read first, any subsequent writes should edit the file (temp),
 	// so we copy the original file to the temp file then set the cursor position on the temp file to the current position.
 	// If we're opening because Write is called first, we always overwrite the file, so no need to copy the original contents.
 	//
 	// So imagine we have a file with content "hello world" and we call Seek(6, 0) and then Write([]byte("there")), the
 	// temp file should have "hello there" and not "there".  Then finally when Close is called, the temp file is renamed
 	// to the original file.  This code ensures that scenario works as expected.
+	exists, err := f.Exists()
+	if err != nil {
+		return nil, err
+	}
 	if exists && (f.seekCalled || f.readCalled) {
 		openFunc := openOSFile
 		if f.fileOpener != nil {
 			openFunc = f.fileOpener
 		}
 
-		actualFile, err := openFunc(osFilePath(f))
+		actualFile, err := openFunc(filePath)
 		if err != nil {
 			return nil, err
 		}
@@ -494,19 +510,71 @@ func (f *File) copyToLocalTempReader() (*os.File, error) {
 		}
 
 		if f.cursorPos > 0 {
-			// match cursor position in tmep file
 			if _, err := tmpFile.Seek(f.cursorPos, 0); err != nil {
 				return nil, err
 			}
 		}
 	}
 
+	ok = true
 	return tmpFile, nil
 }
 
+// selectTempDir determines the best directory for creating a temporary file.
+// Priority:
+//  1. User-specified tempDir (via WithTempDir option)
+//  2. System temp dir, if on the same device/volume as the target file
+//  3. Target file's parent directory (last resort; may be visible to file watchers)
+func (f *File) selectTempDir(targetPath string) (string, error) {
+	if f.tempDir != "" {
+		if err := os.MkdirAll(f.tempDir, 0750); err != nil {
+			return "", fmt.Errorf("cannot create specified temp dir %s: %w", f.tempDir, err)
+		}
+		return f.tempDir, nil
+	}
+
+	osTempDir := os.TempDir()
+	same, err := areSameVolumeOrDevice(targetPath, osTempDir)
+	if err == nil && same {
+		return osTempDir, nil
+	}
+
+	// Fall back to target's parent directory — guaranteed same device
+	targetDir := filepath.Dir(targetPath)
+	if err := os.MkdirAll(targetDir, 0750); err != nil {
+		return "", fmt.Errorf("cannot create target directory %s: %w", targetDir, err)
+	}
+	return targetDir, nil
+}
+
+// areSameVolumeOrDevice checks if two paths reside on the same volume (Windows)
+// or device (Unix).
+func areSameVolumeOrDevice(path1, path2 string) (bool, error) {
+	vol1, err := getVolumeOrDevice(path1)
+	if err != nil {
+		return false, err
+	}
+	vol2, err := getVolumeOrDevice(path2)
+	if err != nil {
+		return false, err
+	}
+	return vol1 == vol2, nil
+}
+
+// osFilePath converts a VFS file path back to a native OS path.
+// On Windows, the internal path /C:/foo/bar.txt becomes C:\foo\bar.txt.
 func osFilePath(f vfs.File) string {
-	if runtime.GOOS == "windows" {
-		return f.Location().Authority().String() + filepath.FromSlash(f.Path())
+	return toNativeOSPath(f.Path())
+}
+
+// toNativeOSPath converts an internal forward-slash path to a native OS path.
+// On Windows, strips the leading "/" before a drive letter and converts slashes.
+func toNativeOSPath(p string) string {
+	if p == "" {
+		return ""
+	}
+	if runtime.GOOS == "windows" && len(p) >= 3 && p[0] == '/' && p[2] == ':' {
+		p = p[1:]
 	}
-	return f.Path()
+	return filepath.FromSlash(p)
 }

backend/os/fileSystem.go

@@ -3,7 +3,6 @@ package os
 import (
 	"path"
 	"path/filepath"
-	"runtime"
 
 	"github.com/c2fo/vfs/v7"
 	"github.com/c2fo/vfs/v7/backend"
@@ -17,7 +16,9 @@ const Scheme = "file"
 const name = "os"
 
 // FileSystem implements vfs.FileSystem for the OS file system.
-type FileSystem struct{}
+type FileSystem struct {
+	tempDir string
+}
 
 // NewFileSystem creates a new instance of the OS file system.
 func NewFileSystem(opts ...options.NewFileSystemOption[FileSystem]) *FileSystem {
@@ -38,14 +39,7 @@ func (fs *FileSystem) Retry() vfs.Retry {
 
 // NewFile function returns the os implementation of vfs.File.
 func (fs *FileSystem) NewFile(authorityStr, filePath string, opts ...options.NewFileOption) (vfs.File, error) {
-	if runtime.GOOS == "windows" && filepath.IsAbs(filePath) {
-		if v := filepath.VolumeName(filePath); v != "" {
-			authorityStr = v
-			filePath = filePath[len(v):]
-		}
-	}
-
-	filePath = filepath.ToSlash(filePath)
+	filePath = normalizeOSPath(filePath)
 	err := utils.ValidateAbsoluteFilePath(filePath)
 	if err != nil {
 		return nil, err
@@ -60,19 +54,13 @@ func (fs *FileSystem) NewFile(authorityStr, filePath string, opts ...options.New
 		name:     filePath,
 		location: loc.(*Location),
 		opts:     opts,
+		tempDir:  fs.tempDir,
 	}, nil
 }
 
 // NewLocation function returns the os implementation of vfs.Location.
 func (fs *FileSystem) NewLocation(authorityStr, locPath string) (vfs.Location, error) {
-	if runtime.GOOS == "windows" && filepath.IsAbs(locPath) {
-		if v := filepath.VolumeName(locPath); v != "" {
-			authorityStr = v
-			locPath = locPath[len(v):]
-		}
-	}
-
-	locPath = filepath.ToSlash(locPath)
+	locPath = normalizeOSPath(locPath)
 	err := utils.ValidateAbsoluteLocationPath(locPath)
 	if err != nil {
 		return nil, err
@@ -103,3 +91,19 @@ func (fs *FileSystem) Scheme() string {
 func init() {
 	backend.Register(Scheme, &FileSystem{})
 }
+
+// normalizeOSPath converts a native OS path to the canonical forward-slash form
+// used internally. On Windows, drive-letter paths like "C:\foo" become "/C:/foo"
+// so the drive letter stays in the path (not the URI authority).
+// UNC paths like "\\server\share\path" become "//server/share/path" via
+// filepath.ToSlash and already satisfy the leading-slash requirement.
+func normalizeOSPath(p string) string {
+	if p == "" {
+		return ""
+	}
+	p = filepath.ToSlash(p)
+	if len(p) >= 2 && p[1] == ':' && ((p[0] >= 'A' && p[0] <= 'Z') || (p[0] >= 'a' && p[0] <= 'z')) {
+		p = "/" + p
+	}
+	return p
+}

backend/os/fileSystem_test.go

@@ -74,6 +74,21 @@ func (o *osFileSystemTest) TestNewFileSystem() {
 	o.IsType((*FileSystem)(nil), fs)
 }
 
+func (o *osFileSystemTest) TestWithTempDirOption() {
+	opt := WithTempDir{TempDir: "/custom/temp"}
+
+	o.Equal("WithTempDir", opt.NewFileSystemOptionName())
+
+	fs := &FileSystem{}
+	opt.Apply(fs)
+	o.Equal("/custom/temp", fs.tempDir)
+}
+
+func (o *osFileSystemTest) TestNewFileSystemWithTempDir() {
+	fs := NewFileSystem(WithTempDir{TempDir: "/my/temp"})
+	o.Equal("/my/temp", fs.tempDir)
+}
+
 func TestOSFileSystem(t *testing.T) {
 	suite.Run(t, new(osFileSystemTest))
 }