feat(copy): introduces CopyGraphOptions with events support

src/OrasProject.Oras/CopyGraphOptions.cs

@@ -12,30 +12,44 @@
 // limitations under the License.
 
 using System;
+using System.Threading.Tasks;
 using OrasProject.Oras.Oci;
 
 namespace OrasProject.Oras;
 
+/// <summary>
+/// CopyGraphOptions contains parameters for <see cref="Extensions.CopyGraphAsync(OrasProject.Oras.ITarget,OrasProject.Oras.ITarget,OrasProject.Oras.Oci.Descriptor,System.Threading.CancellationToken)"/>
+/// </summary>
 public struct CopyGraphOptions
 {
-    public event Action<Descriptor> PreCopy;
-
-    public event Action<Descriptor> PostCopy;
-
-    public event Action<Descriptor> CopySkipped;
-
-    internal void OnPreCopy(Descriptor descriptor)
+    /// <summary>
+    /// PreCopy handles the current descriptor before it is copied.
+    /// </summary>
+    public event Func<Descriptor, Task> PreCopy;
+
+    /// <summary>
+    /// PostCopy handles the current descriptor after it is copied.
+    /// </summary>
+    public event Func<Descriptor, Task> PostCopy;
+
+    /// <summary>
+    /// CopySkipped will be called when the sub-DAG rooted by the current node
+    /// is skipped.
+    /// </summary>
+    public event Func<Descriptor, Task> CopySkipped;
+
+    internal Task OnPreCopyAsync(Descriptor descriptor)
     {
-        PreCopy?.Invoke(descriptor);
+        return PreCopy?.Invoke(descriptor) ?? Task.CompletedTask;
     }
 
-    internal void OnPostCopy(Descriptor descriptor)
+    internal Task OnPostCopyAsync(Descriptor descriptor)
     {
-        PostCopy?.Invoke(descriptor);
+        return PostCopy?.Invoke(descriptor) ?? Task.CompletedTask;
     }
 
-    internal void OnCopySkipped(Descriptor descriptor)
+    internal Task OnCopySkippedAsync(Descriptor descriptor)
     {
-        CopySkipped?.Invoke(descriptor);
+        return CopySkipped?.Invoke(descriptor) ?? Task.CompletedTask;
     }
 }

src/OrasProject.Oras/CopyOptions.cs

@@ -13,6 +13,9 @@
 
 namespace OrasProject.Oras;
 
+/// <summary>
+/// CopyOptions contains parameters for <see cref="Extensions.CopyAsync(OrasProject.Oras.ITarget,string,OrasProject.Oras.ITarget,string,System.Threading.CancellationToken)"/>
+/// </summary>
 public struct CopyOptions
 {
     public CopyGraphOptions CopyGraphOptions;

src/OrasProject.Oras/Extensions.cs

@@ -56,14 +56,14 @@ public static Task<Descriptor> CopyAsync(this ITarget src, string srcRef, ITarge
     /// <param name="cancellationToken"></param>
     /// <returns></returns>
     /// <exception cref="Exception"></exception>
-    public static async Task<Descriptor> CopyAsync(this ITarget src, string srcRef, ITarget dst, string dstRef, CopyOptions? copyOptions = default, CancellationToken cancellationToken = default)
+    public static async Task<Descriptor> CopyAsync(this ITarget src, string srcRef, ITarget dst, string dstRef, CopyOptions copyOptions = default, CancellationToken cancellationToken = default)
     {
         if (string.IsNullOrEmpty(dstRef))
         {
             dstRef = srcRef;
         }
         var root = await src.ResolveAsync(srcRef, cancellationToken).ConfigureAwait(false);
-        await src.CopyGraphAsync(dst, root, copyOptions?.CopyGraphOptions, cancellationToken).ConfigureAwait(false);
+        await src.CopyGraphAsync(dst, root, copyOptions.CopyGraphOptions, cancellationToken).ConfigureAwait(false);
         await dst.TagAsync(root, dstRef, cancellationToken).ConfigureAwait(false);
         return root;
     }
@@ -73,12 +73,12 @@ public static Task CopyGraphAsync(this ITarget src, ITarget dst, Descriptor node
         return src.CopyGraphAsync(dst, node, new CopyGraphOptions(), cancellationToken);
     }
 
-    public static async Task CopyGraphAsync(this ITarget src, ITarget dst, Descriptor node, CopyGraphOptions? copyGraphOptions = default, CancellationToken cancellationToken = default)
+    public static async Task CopyGraphAsync(this ITarget src, ITarget dst, Descriptor node, CopyGraphOptions copyGraphOptions = default, CancellationToken cancellationToken = default)
     {
         // check if node exists in target
         if (await dst.ExistsAsync(node, cancellationToken).ConfigureAwait(false))
         {
-            copyGraphOptions?.OnCopySkipped(node);
+            await copyGraphOptions.OnCopySkippedAsync(node);
             return;
         }
 
@@ -92,12 +92,12 @@ public static async Task CopyGraphAsync(this ITarget src, ITarget dst, Descripto
         }
 
         // perform the copy
-        copyGraphOptions?.OnPreCopy(node);
+        await copyGraphOptions.OnPreCopyAsync(node);
         var dataStream = await src.FetchAsync(node, cancellationToken).ConfigureAwait(false);
         await dst.PushAsync(node, dataStream, cancellationToken).ConfigureAwait(false);
 
         // we copied it
-        copyGraphOptions?.OnPostCopy(node);
+        await copyGraphOptions.OnPostCopyAsync(node);
     }
 }
 

tests/OrasProject.Oras.Tests/CopyTest.cs

@@ -196,15 +196,19 @@ void GenerateManifest(Descriptor config, params Descriptor[] layers)
         // Tag root node in source
         await src.TagAsync(root, refTag, CancellationToken.None);
 
-        // Prepare copy options with OnCopySkipped
+        // Prepare copy options with OnCopySkippedAsync
         var skippedCount = 0;
         var copyOptions = new CopyOptions
         {
             CopyGraphOptions = new CopyGraphOptions()
             {
             }
         };
-        copyOptions.CopyGraphOptions.CopySkipped += d => skippedCount++;
+        copyOptions.CopyGraphOptions.CopySkipped += d =>
+        {
+            skippedCount++;
+            return Task.CompletedTask;
+        };
 
         // Copy with the source tag
         var gotDesc = await src.CopyAsync(refTag, dst, "", copyOptions, CancellationToken.None);
@@ -229,7 +233,7 @@ void GenerateManifest(Descriptor config, params Descriptor[] layers)
         gotDesc = await dst.ResolveAsync(newTag, CancellationToken.None);
         Assert.Equal(root, gotDesc);
 
-        // Verify the OnCopySkipped invocation count
+        // Verify the OnCopySkippedAsync invocation count
         Assert.Equal(1, skippedCount);
     }
 
@@ -419,8 +423,16 @@ void GenerateIndex(params Descriptor[] manifests)
             }
         };
 
-        copyOptions.CopyGraphOptions.PreCopy += d => preCopyCount++;
-        copyOptions.CopyGraphOptions.PostCopy += d => postCopyCount++;
+        copyOptions.CopyGraphOptions.PreCopy += d =>
+        {
+            preCopyCount++;
+            return Task.CompletedTask;
+        };
+        copyOptions.CopyGraphOptions.PostCopy += d =>
+        {
+            postCopyCount++;
+            return Task.CompletedTask;
+        };
 
         var expectedDesc = descs[6];
         var gotDesc = await src.CopyAsync(refTag, dst, "", copyOptions, cancellationToken);