Add ability to overwrite regular files and symbolic links in NIO FileSystem

Sources/NIOFS/FileSystemProtocol.swift

@@ -175,7 +175,7 @@ public protocol FileSystemProtocol: Sendable {
     /// The following error codes may be thrown:
     /// - ``FileSystemError/Code-swift.struct/notFound`` if the item at `sourcePath` does not exist,
     /// - ``FileSystemError/Code-swift.struct/invalidArgument`` if an item at `destinationPath`
-    ///   exists prior to the copy or its parent directory does not exist.
+    ///   exists prior to the copy (when `overwriting` is `false`) or its parent directory does not exist.
     ///
     /// Note that other errors may also be thrown.
     ///
@@ -186,6 +186,7 @@ public protocol FileSystemProtocol: Sendable {
     ///   - sourcePath: The path to the item to copy.
     ///   - destinationPath: The path at which to place the copy.
     ///   - copyStrategy: How to deal with concurrent aspects of the copy, only relevant to directories.
+    ///   - overwriting: Whether to overwrite an existing file or symlink at `destinationPath`.
     ///   - shouldProceedAfterError: A closure which is executed to determine whether to continue
     ///       copying files if an error is encountered during the operation. See Errors section for full details.
     ///   - shouldCopyItem: A closure which is executed before each copy to determine whether each
@@ -195,7 +196,7 @@ public protocol FileSystemProtocol: Sendable {
     ///
     /// No errors should be throw by implementors without first calling `shouldProceedAfterError`,
     /// if that returns without throwing this is taken as permission to continue and the error is swallowed.
-    /// If instead the closure throws then ``copyItem(at:to:strategy:shouldProceedAfterError:shouldCopyItem:)``
+    /// If instead the closure throws then ``copyItem(at:to:strategy:overwriting:shouldProceedAfterError:shouldCopyItem:)``
     ///  will throw and copying will stop, though the precise semantics of this can depend on the `strategy`.
     ///
     /// if using ``CopyStrategy/parallel(maxDescriptors:)``
@@ -236,6 +237,7 @@ public protocol FileSystemProtocol: Sendable {
         at sourcePath: NIOFilePath,
         to destinationPath: NIOFilePath,
         strategy copyStrategy: CopyStrategy,
+        overwriting: Bool,
         shouldProceedAfterError:
             @escaping @Sendable (
                 _ source: DirectoryEntry,
@@ -472,7 +474,7 @@ extension FileSystemProtocol {
     ///
     /// Note that other errors may also be thrown. If any error is encountered during the copy
     /// then the copy is aborted. You can modify the behaviour with the `shouldProceedAfterError`
-    /// parameter of ``FileSystemProtocol/copyItem(at:to:strategy:shouldProceedAfterError:shouldCopyItem:)``.
+    /// parameter of ``FileSystemProtocol/copyItem(at:to:strategy:overwriting:shouldProceedAfterError:shouldCopyItem:)``.
     ///
     /// If the file at `sourcePath` is a symbolic link then only the link is copied to the new path.
     ///
@@ -485,11 +487,18 @@ extension FileSystemProtocol {
         to destinationPath: NIOFilePath,
         strategy copyStrategy: CopyStrategy = .platformDefault
     ) async throws {
-        try await self.copyItem(at: sourcePath, to: destinationPath, strategy: copyStrategy) { path, error in
-            throw error
-        } shouldCopyItem: { source, destination in
-            true
-        }
+        try await self.copyItem(
+            at: sourcePath,
+            to: destinationPath,
+            strategy: copyStrategy,
+            overwriting: false,
+            shouldProceedAfterError: { path, error in
+                throw error
+            },
+            shouldCopyItem: { source, destination in
+                true
+            }
+        )
     }
 
     /// Copies the item at the specified path to a new location.
@@ -516,7 +525,7 @@ extension FileSystemProtocol {
     ///
     /// This overload uses ``CopyStrategy/platformDefault`` which is likely to result in multiple concurrency domains being used
     /// in the event of copying a directory.
-    /// See the detailed description on ``copyItem(at:to:strategy:shouldProceedAfterError:shouldCopyItem:)``
+    /// See the detailed description on ``copyItem(at:to:strategy:overwriting:shouldProceedAfterError:shouldCopyItem:)``
     /// for the implications of this with respect to the `shouldProceedAfterError` and `shouldCopyItem` callbacks
     public func copyItem(
         at sourcePath: NIOFilePath,
@@ -536,6 +545,7 @@ extension FileSystemProtocol {
             at: sourcePath,
             to: destinationPath,
             strategy: .platformDefault,
+            overwriting: false,
             shouldProceedAfterError: shouldProceedAfterError,
             shouldCopyItem: shouldCopyItem
         )

Sources/NIOFS/IOStrategy.swift

@@ -56,7 +56,7 @@ enum IOStrategy: Hashable, Sendable {
 }
 
 /// How to perform copies. Currently only relevant to directory level copies when using
-/// ``FileSystemProtocol/copyItem(at:to:strategy:shouldProceedAfterError:shouldCopyItem:)`` or other
+/// ``FileSystemProtocol/copyItem(at:to:strategy:overwriting:shouldProceedAfterError:shouldCopyItem:)`` or other
 /// overloads that use the default behaviour.
 public struct CopyStrategy: Hashable, Sendable {
     internal let wrapped: IOStrategy

Sources/NIOFS/Internal/System Calls/Syscall.swift

@@ -106,6 +106,29 @@ public enum Syscall: Sendable {
             Self(rawValue: UInt32(bitPattern: RENAME_SWAP))
         }
     }
+
+    @_spi(Testing)
+    public static func rename(
+        from old: FilePath,
+        relativeTo oldFD: FileDescriptor,
+        to new: FilePath,
+        relativeTo newFD: FileDescriptor,
+        options: RenameOptions
+    ) -> Result<Void, Errno> {
+        nothingOrErrno(retryOnInterrupt: false) {
+            old.withPlatformString { oldPath in
+                new.withPlatformString { newPath in
+                    system_renameatx_np(
+                        oldFD.rawValue,
+                        oldPath,
+                        newFD.rawValue,
+                        newPath,
+                        options.rawValue
+                    )
+                }
+            }
+        }
+    }
     #endif
 
     #if canImport(Glibc) || canImport(Musl) || canImport(Bionic)
@@ -219,6 +242,19 @@ public enum Syscall: Sendable {
         }
     }
 
+    @_spi(Testing)
+    public static func unlinkat(
+        path: FilePath,
+        relativeTo directoryDescriptor: FileDescriptor,
+        flags: CInt = 0
+    ) -> Result<Void, Errno> {
+        nothingOrErrno(retryOnInterrupt: false) {
+            path.withPlatformString { ptr in
+                system_unlinkat(directoryDescriptor.rawValue, ptr, flags)
+            }
+        }
+    }
+
     @_spi(Testing)
     public static func symlink(
         to destination: FilePath,
@@ -233,6 +269,21 @@ public enum Syscall: Sendable {
         }
     }
 
+    @_spi(Testing)
+    public static func symlinkat(
+        to destination: FilePath,
+        in directoryDescriptor: FileDescriptor,
+        from source: FilePath
+    ) -> Result<Void, Errno> {
+        nothingOrErrno(retryOnInterrupt: false) {
+            source.withPlatformString { src in
+                destination.withPlatformString { dst in
+                    system_symlinkat(dst, directoryDescriptor.rawValue, src)
+                }
+            }
+        }
+    }
+
     @_spi(Testing)
     public static func readlink(at path: FilePath) -> Result<FilePath, Errno> {
         do {

Sources/NIOFS/Internal/System Calls/Syscalls.swift

@@ -149,6 +149,20 @@ internal func system_symlink(
     return symlink(destination, source)
 }
 
+/// symlinkat(2): Make symbolic link to a file relative to directory file descriptor
+internal func system_symlinkat(
+    _ destination: UnsafePointer<CInterop.PlatformChar>,
+    _ dirfd: FileDescriptor.RawValue,
+    _ source: UnsafePointer<CInterop.PlatformChar>
+) -> CInt {
+    #if ENABLE_MOCKING
+    if mockingEnabled {
+        return mock(destination, dirfd, source)
+    }
+    #endif
+    return symlinkat(destination, dirfd, source)
+}
+
 /// readlink(2): Read value of a symolic link
 internal func system_readlink(
     _ path: UnsafePointer<CInterop.PlatformChar>,
@@ -271,6 +285,21 @@ internal func system_renamex_np(
     #endif
     return renamex_np(old, new, flags)
 }
+
+internal func system_renameatx_np(
+    _ oldFD: FileDescriptor.RawValue,
+    _ old: UnsafePointer<CInterop.PlatformChar>,
+    _ newFD: FileDescriptor.RawValue,
+    _ new: UnsafePointer<CInterop.PlatformChar>,
+    _ flags: CUnsignedInt
+) -> CInt {
+    #if ENABLE_MOCKING
+    if mockingEnabled {
+        return mock(oldFD, old, newFD, new, flags)
+    }
+    #endif
+    return renameatx_np(oldFD, old, newFD, new, flags)
+}
 #endif
 
 #if canImport(Glibc) || canImport(Musl) || canImport(Android)
@@ -333,6 +362,20 @@ internal func system_unlink(
     return unlink(path)
 }
 
+/// unlinkat(2): Remove a directory entry relative to a directory file descriptor.
+internal func system_unlinkat(
+    _ fd: FileDescriptor.RawValue,
+    _ path: UnsafePointer<CInterop.PlatformChar>,
+    _ flags: CInt
+) -> CInt {
+    #if ENABLE_MOCKING
+    if mockingEnabled {
+        return mock(fd, path, flags)
+    }
+    #endif
+    return unlinkat(fd, path, flags)
+}
+
 #if canImport(Glibc) || canImport(Musl) || canImport(Android)
 /// sendfile(2): Transfer data between descriptors
 internal func system_sendfile(

Sources/_NIOFileSystem/Docs.docc/Extensions/FileSystemProtocol.md

@@ -33,7 +33,7 @@ closing it to avoid leaking resources.
 
 ### Managing files
 
-- ``copyItem(at:to:strategy:shouldProceedAfterError:shouldCopyItem:)``
+- ``copyItem(at:to:strategy:overwriting:shouldProceedAfterError:shouldCopyItem:)``
 - ``removeItem(at:)``
 - ``moveItem(at:to:)``
 - ``replaceItem(at:withItemAt:)``