Add replaceFile

[zlonast]

haskell/cabal#10938

haskell/win32#240

[Bodigrim]

It would be nice to elaborate explicitly how replaceFile is different from renameFile.

[zlonast]

Added more description

[noughtmare]

I think the documentation would help me much more if you add something like: "In constrast to renameFile, replaceFile ... (is atomic?) You should use this when ... For example, consider this program ..."

In other words, the current explanation raises these questions with me:

• What do renamePath and ReplaceFileW do? (Perhaps this is just meant for people who are familiar with those functions and I should just ignore that sentence.)
• What can go wrong if I use renameFile? Why is it important that it is atomic?

[zlonast]

On Windows now renameFile is MoveFileEx and replaceFile is ReplaceFileW

Atomic Operation in ReplaceFile:

1. Creates a temporary backup of the original file (backup)
2. Moves the new file to the original file's location
3. Deletes the backup

On failure at step 2:

• Original file remains in backup
• New file stays in its original location

System preserves both versions!

For Comparison: MoveFileEx Behavior:

1. Deletes the target file
2. Moves the new file to target location

On failure at step 2:

• Target file is already deleted
• New file remains in its original location

Data is lost!

[Bodigrim]

I think the convention is to provide the same set of functions both from System.Directory and from System.Directory.OsPath.

[zlonast]

Done

[Rufflewind]

• Could you add a unit test?
• We'll have to wait until the upstream change is released to Hackage: Add ReplaceFileW win32#240

[noughtmare]

As an outsider, it seems that replaceFile should always be preferred over renameFile, because it is guaranteed to be atomic on all platforms. Would it make sense to eventually replace the implementation of renameFile with this new replaceFile function? Would that be a backwards compatible change?

[Bodigrim]

* We'll have to wait until the upstream change is released to Hackage: [Add ReplaceFileW win32#240](https://github.com/haskell/win32/pull/240)

I think it's merged and released now, in Win32-2.14.2.0.

[zlonast]

@Rufflewind
I'm not really sure if it's worth adding this to the tests, but I'll describe the behavior that will be used in other places

Blocking the target name:

HANDLE hLock = CreateFile(
    L"C:\\target.exe", 
    GENERIC_READ,
    FILE_SHARE_READ, // We prohibit exclusive access
    NULL,
    CREATE_ALWAYS,
    FILE_ATTRIBUTE_NORMAL,
    NULL
);

ReplaceFile(
    L"C:\\target.exe", 
    L"C:\\new_version.exe",
    NULL, 
    0, 
    NULL, 
    NULL
); // Return ERROR_UNABLE_TO_MOVE_REPLACEMENT

CloseHandle(hLock);

Access rights violation:

// Set read-only permissions for the target directory:
icacls C:\ /deny Everyone:(WD)

ReplaceFile(L"C:\\app.exe", L"C:\\update.tmp", NULL, 0, NULL, NULL);
// Return ERROR_UNABLE_TO_MOVE_REPLACEMENT

Recovery in case of failure

if (!ReplaceFile(L"app.exe", L"update.tmp", NULL, 0, NULL, NULL)) {
    DWORD err = GetLastError();
    
    if (err == ERROR_UNABLE_TO_MOVE_REPLACEMENT) {
        // 1. Find .RXXXX file
        // 2. Try to restore manually:
        MoveFile(L"app.exe.R4987", L"app.exe");
        
        // 3. Notify user
        MessageBox(NULL, L"Update error. Previous version restored.", L"Error", MB_OK);
    }
}

[noughtmare]

Is there any reason to ever use renameFile over replaceFile? Can't we just fix the windows implementation of renameFile instead of introducing a whole new function?

If we are going to have two functions it should be very clear from the documentation what the differences are and when you should use one over the other. You described (part of?) it in this comment, but that is not really reflected in the documentation.

[Bodigrim]

AFAIU from reading StackOverflow on Windows:

• renameFile old new (aka MoveFileEx) retains the identity of old file such as attributes, ownership, etc. and only replaces its name with new,
• replaceFile old new is vice versa: it retains the identity of new file, but replaces its contents with the contents of old.

@zlonast could you confirm that my understanding is correct?

What I don't know is how to achieve the semantics of Windows replaceFile on Unix. Is there a call to preserve the identity of the old file and replace contents only?

[zlonast]

@noughtmare @Bodigrim

Is there any reason to ever use renameFile over replaceFile? Can't we just fix the windows implementation of renameFile instead of introducing a whole new function?

I think these are different functions, as a result they produce different attributes.

Do you think it's normal for a general package to have some useless features for a particular platform? If you think it's not, let me know.

If we are going to have two functions it should be very clear from the documentation what the differences are and when you should use one over the other. You described (part of?) it in #200 (comment), but that is not really reflected in the documentation.

Yes, I think you're right, I'll fix it.

@zlonast could you confirm that my understanding is correct?

Yes

What I don't know is how to achieve the semantics of Windows replaceFile on Unix. Is there a call to preserve the identity of the old file and replace contents only?

As I understand it, it doesn't make sense.

From what I understand, I need rename on unix and replaceFile on windows to implement atomicReplaceFile and atomicWriteFile. (I think it's worth continuing in file-io)

[Bodigrim]

@zlonast I don't quite follow all the details, but if the goal is to implement something in file-io then contributing it into directory will be of little help: somewhat awkwardly it's directory who depends on file-io, not vice versa.

[Rufflewind]

To make the tests pass, try updating the Win32 version number in .github/workflows/build.yml:

directory/.github/workflows/build.yml

Lines 25 to 27 in 6442a3c

	- { os: windows-latest, stack: lts-15.3, stack-extra-deps: "bytestring-0.11.3.0, file-io-0.1.4, filepath-1.4.100.0, time-1.9.3, Win32-2.14.1.0", overrides: "before_prepare() { sed -i.bak -e /CreateSymbolicLinkW/d -e /GetFinalPathNameByHandleW/d configure.ac; }" }
	- { os: windows-latest, stack: lts-17.5, stack-extra-deps: "bytestring-0.11.3.0, file-io-0.1.4, filepath-1.4.100.0, time-1.9.3, Win32-2.14.1.0" }
	- { os: windows-latest, stack: lts-22.7, stack-extra-deps: "bytestring-0.11.5.3, file-io-0.1.4, filepath-1.5.2.0, os-string-2.0.2, time-1.14, Win32-2.14.1.0", stack-package-flags: "{directory: {os-string: true}, file-io: {os-string: true}, Win32: {os-string: true}}", ghc-flags: -Werror=deprecations }

[Rufflewind]

To my understanding, the Haskell Win32 library does not expose the underlying Win32 API error code in the IOException object, so the information here isn't really usable to users. It should really be rephrased as IOErrorTypes instead, and preferably merged with the Unix section if possible to reduce the platform-specific content for users. It's probably not worth documenting every single error case either, just the most commonly encountered ones.

[Rufflewind]

replaceFileInternal = renamePathInternal