NIOFileSystem: provide a function that copies or replaces a file/dir

[weissi]

Usually, when copying a file, I don't hugely mind if it already exists. If it does, I want to overwrite it.

NIO FS currently provides copyItem (fails if dest already exists) and replaceItem (fails if dest does not already exist). This makes for pretty awkward code if you want to do it correctly.

[Lukasa]

Agreed, this is a useful extension.

[stepan-ulyanin]

@Lukasa surely these would have to be new functions? Reading through the source at the moment.

[stepan-ulyanin]

Ok, I am going to pick this one up, working on it

[stepan-ulyanin]

Some notes on implementation here.

Looks like we can use COPYFILE_UNLINK with Libc.copyfile to atomically unlink and copy on Darwin systems. But similar functionality doesn't exist (?) on Linux.

A couple of options on Linux are:

1. We unlink and copy from user space, but we lose atomicity.
2. We truncate the destination on copy, but it will affect all hard-linked files as well - which is bad. Unless SwiftNIO's users can't create hard-links for some reason?
3. We copy the file into a temp location in the same directory as dest and then rename it. The rename docs mention that the rename is atomic. However, I imagine that this temporarily consumes more disk space and requires to do some cleanup.

Looking at some other logic in the FileSystem.swift I think we have some non-atomic calls from the user space, for example

swift-nio/Sources/_NIOFileSystem/FileSystem.swift

Lines 521 to 522 in 767ea9e

	try await self.copyItem(at: sourcePath, to: destinationPath)
	try await self.removeItem(at: sourcePath, strategy: .platformDefault)

@Lukasa am I missing anything? Which one is more important in our case, atomicity or disk space utilization, or perhaps a simple unlink - copy should be good for our use case here?

[Lukasa]

We should do this atomically, I think: behaving differently on the different platforms will cause surprises.

[stepan-ulyanin]

Sorry for the delay guys, here is the PR for copying regular files and symbolic links with overwriting: #3470

Not entirely sure what to do with directory trees - I don't think there is an atomic way to copy directories overwriting existing non-empty ones in Posix systems - happy to take a stab at a non-atomic implementation in a follow up PR?