Merge branch 'main' into fix/systemio/folder/invalid-path-in-filenotfoundexception

Author: Arlodotexe

src/Extensions/CopyAndMoveExtensions.cs

@@ -0,0 +1,88 @@
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace OwlCore.Storage;
+
+/// <summary>
+/// Extension methods for <see cref="IModifiableFolder"/>.
+/// </summary>
+public static partial class ModifiableFolderExtensions
+{
+    /// <summary>
+    /// Creates a copy of the provided file within this folder.
+    /// </summary>
+    /// <param name="destinationFolder">The folder where the copy is created.</param>
+    /// <param name="fileToCopy">The file to be copied into this folder.</param>
+    /// <param name="overwrite"><code>true</code> if any existing destination file can be overwritten; otherwise, <c>false</c>.</param>
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
+    /// <exception cref="FileAlreadyExistsException">Thrown when <paramref name="overwrite"/> is false and the resource being created already exists.</exception>
+    public static async Task<IChildFile> CreateCopyOfAsync(this IModifiableFolder destinationFolder, IFile fileToCopy, bool overwrite, CancellationToken cancellationToken = default)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+
+        // If the destination folder declares a non-fallback copy path, try that.
+        // Provide fallback in case this file is not a handled type.
+        if (destinationFolder is ICreateCopyOf fastPath)
+            return await fastPath.CreateCopyOfAsync(fileToCopy, overwrite, cancellationToken, fallback: CreateCopyOfFallbackAsync);
+
+        // Manual copy. Slower, but covers all scenarios.
+        return await CreateCopyOfFallbackAsync(destinationFolder, fileToCopy, overwrite, cancellationToken);
+    }
+
+    /// <summary>
+    /// Creates a copy of the provided file within this folder.
+    /// </summary>
+    /// <param name="destinationFolder">The folder where the copy is created.</param>
+    /// <param name="fileToCopy">The file to be copied into this folder.</param>
+    /// <param name="newName">The name to use for the created file.</param>
+    /// <param name="overwrite"><code>true</code> if any existing destination file can be overwritten; otherwise, <c>false</c>.</param>
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
+    /// <exception cref="FileAlreadyExistsException">Thrown when <paramref name="overwrite"/> is false and the resource being created already exists.</exception>
+    public static async Task<IChildFile> CreateCopyOfAsync(this IModifiableFolder destinationFolder, IFile fileToCopy, bool overwrite, string newName, CancellationToken cancellationToken = default)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+
+        // If the destination folder declares a non-fallback copy path, try that.
+        // Provide fallback in case this file is not a handled type.
+        if (destinationFolder is ICreateRenamedCopyOf fastPath)
+            return await fastPath.CreateCopyOfAsync(fileToCopy, overwrite, newName, cancellationToken, fallback: CreateCopyOfFallbackAsync);
+
+        // Manual copy. Slower, but covers all scenarios.
+        return await CreateCopyOfFallbackAsync(destinationFolder, fileToCopy, overwrite, newName, cancellationToken);
+    }
+
+    private static Task<IChildFile> CreateCopyOfFallbackAsync(IModifiableFolder destinationFolder, IFile fileToCopy, bool overwrite, CancellationToken cancellationToken = default)
+        => CreateCopyOfFallbackAsync(destinationFolder, fileToCopy, overwrite, fileToCopy.Name, cancellationToken);
+
+    private static async Task<IChildFile> CreateCopyOfFallbackAsync(IModifiableFolder destinationFolder, IFile fileToCopy, bool overwrite, string newName, CancellationToken cancellationToken = default)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+
+        // If the destination file exists and overwrite is false, it shouldn't be overwritten or returned as-is. Throw an exception instead.
+        if (!overwrite)
+        {
+            try
+            {
+                var existing = await destinationFolder.GetFirstByNameAsync(newName, cancellationToken);
+                if (existing is not null)
+                    throw new FileAlreadyExistsException(newName);
+            }
+            catch (FileNotFoundException) { }
+        }
+
+        // Create the destination file.
+        // 'overwrite: false' would have thrown above if the file exists, so either overwrite is already true or the file doesn't exist yet.
+        // Always overwrite here so the file is empty. 
+        var newFile = await destinationFolder.CreateFileAsync(newName, overwrite: true, cancellationToken);
+        using var destinationStream = await newFile.OpenStreamAsync(FileAccess.Write, cancellationToken: cancellationToken);
+
+        // Open the source file
+        using var sourceStream = await fileToCopy.OpenStreamAsync(FileAccess.Read, cancellationToken: cancellationToken);
+
+        // Copy the src into the dest file
+        await sourceStream.CopyToAsync(destinationStream, bufferSize: 81920, cancellationToken);
+
+        return newFile;
+    }
+}

src/Extensions/CopyExtensions.cs

@@ -5,7 +5,7 @@
 namespace OwlCore.Storage;
 
 /// <summary>
-/// Provides a way for implementations to override behavior of the <see cref="ModifiableFolderExtensions.CreateCopyOfAsync"/> extension method.
+/// Provides a way for implementations to override behavior of the <see cref="ModifiableFolderExtensions.CreateCopyOfAsync(IModifiableFolder, IFile, bool, CancellationToken)"/> extension method.
 /// </summary>
 /// <exception cref="FileNotFoundException">The item was not found in the provided folder.</exception>
 public interface ICreateCopyOf : IModifiableFolder
@@ -26,3 +26,26 @@ public interface ICreateCopyOf : IModifiableFolder
 /// </summary>
 /// <returns></returns>
 public delegate Task<IChildFile> CreateCopyOfDelegate(IModifiableFolder destination, IFile fileToCopy, bool overwrite, CancellationToken cancellationToken);
+
+/// <summary>
+/// Provides a way for implementations to override behavior of the <see cref="ModifiableFolderExtensions.CreateCopyOfAsync(IModifiableFolder, IFile, bool, string, CancellationToken)"/> extension method.
+/// </summary>
+public interface ICreateRenamedCopyOf : ICreateCopyOf
+{
+    /// <summary>
+    /// Creates a copy of the provided file within this folder.
+    /// </summary>
+    /// <param name="fileToCopy">The file to be copied into this folder.</param>
+    /// <param name="overwrite">If there is an existing destination file, <c>true</c> will overwrite it; otherwise <c>false</c> and the existing file is opened.</param>
+    /// <param name="newName">The new name of the created file.</param>
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
+    /// <param name="fallback">The fallback to use if the provided <paramref name="fileToCopy"/> isn't supported.</param>
+    /// <returns>The newly created (or opened if existing) file.</returns>
+    Task<IChildFile> CreateCopyOfAsync(IFile fileToCopy, bool overwrite, string newName, CancellationToken cancellationToken, CreateRenamedCopyOfDelegate fallback);
+}
+
+/// <summary>
+/// A delegate that provides a fallback for the <see cref="IMoveFrom.MoveFromAsync"/> method.
+/// </summary>
+/// <returns></returns>
+public delegate Task<IChildFile> CreateRenamedCopyOfDelegate(IModifiableFolder destination, IFile fileToCopy, bool overwrite, string newName, CancellationToken cancellationToken);

src/Extensions/ICreateCopyOf.cs

@@ -1,12 +1,11 @@
-using System;
-using System.IO;
+using System.IO;
 using System.Threading;
 using System.Threading.Tasks;
 
 namespace OwlCore.Storage;
 
 /// <summary>
-/// Provides a fast-path for the <see cref="ModifiableFolderExtensions.MoveFromAsync"/> extension method.
+/// Provides a fast-path for the <see cref="ModifiableFolderExtensions.CreateCopyOfAsync(IModifiableFolder, IFile, bool, CancellationToken)"/> extension method.
 /// </summary>
 /// <exception cref="FileNotFoundException">The item was not found in the provided folder.</exception>
 public interface IMoveFrom : IModifiableFolder
@@ -26,4 +25,31 @@ public interface IMoveFrom : IModifiableFolder
 /// <summary>
 /// A delegate that provides a fallback for the <see cref="IMoveFrom.MoveFromAsync"/> method.
 /// </summary>
-public delegate Task<IChildFile> MoveFromDelegate(IModifiableFolder modifiableFolder, IChildFile file, IModifiableFolder source, bool overwrite, CancellationToken cancellationToken);
+public delegate Task<IChildFile> MoveFromDelegate(IModifiableFolder modifiableFolder, IChildFile file, IModifiableFolder source, bool overwrite, CancellationToken cancellationToken);
+
+/// <summary>
+/// Provides a fast-path for the <see cref="ModifiableFolderExtensions.CreateCopyOfAsync(IModifiableFolder, IFile, bool, string, CancellationToken)"/> extension method.
+/// </summary>
+/// <remarks>
+/// This interface derives from <see cref="IMoveFrom"/> to enforce non-fallback compatibility with the non-rename overload.
+/// </remarks>
+/// <exception cref="FileNotFoundException">The item was not found in the provided folder.</exception>
+public interface IMoveRenamedFrom : IMoveFrom
+{
+    /// <summary>
+    /// Moves a storable item out of the provided folder, and into this folder. Returns the new item that resides in this folder.
+    /// </summary>
+    /// <param name="fileToMove">The file being moved into this folder.</param>
+    /// <param name="source">The folder that <paramref name="fileToMove"/> is being moved from.</param>
+    /// <param name="overwrite">If there is an existing destination file, <c>true</c> will overwrite it; otherwise <c>false</c> and the existing file is opened.</param>
+    /// <param name="newName">The new name of the created file.</param>
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
+    /// <param name="fallback">The fallback to use if the provided <paramref name="fileToMove"/> isn't supported.</param>
+    /// <returns>The newly created (or opened if existing) file.</returns>
+    Task<IChildFile> MoveFromAsync(IChildFile fileToMove, IModifiableFolder source, bool overwrite, string newName, CancellationToken cancellationToken, MoveRenamedFromDelegate fallback);
+}
+
+/// <summary>
+/// A delegate that provides a fallback for the <see cref="IMoveFrom.MoveFromAsync"/> method.
+/// </summary>
+public delegate Task<IChildFile> MoveRenamedFromDelegate(IModifiableFolder modifiableFolder, IChildFile file, IModifiableFolder source, bool overwrite, string newName, CancellationToken cancellationToken);