feat(copy): introduces CopyGraphOptions with events support

src/OrasProject.Oras/AsyncInvocationExtensions.cs

@@ -0,0 +1,47 @@
+// Copyright The ORAS Authors.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading.Tasks;
+
+namespace OrasProject.Oras;
+
+/// <summary>
+/// Provides extension methods for invoking asynchronous event delegates in a safe and consistent manner.
+/// </summary>
+internal static class AsyncInvocationExtensions
+{
+
+    /// <summary>
+    ///  Asynchronously invokes all handlers from an event.
+    ///  All handlers are executed in parallel. If <paramref name="eventDelegate"/> is null,
+    /// a collection containing a completed task is returned.
+    /// </summary>
+    /// <typeparam name="TEventArgs">The type of the event arguments.</typeparam>
+    /// <param name="eventDelegate">The event delegate to invoke.</param>
+    /// <param name="args">The arguments to pass to the event handlers.</param>
+    /// <returns>An enumerable of tasks representing the asynchronous event handler invocations.</returns>
+    internal static IEnumerable<Task> InvokeAsync<TEventArgs>(
+       this Func<TEventArgs, Task>? eventDelegate, TEventArgs args)
+    {
+        if (eventDelegate is null)
+            return [Task.CompletedTask];
+
+        return eventDelegate
+            .GetInvocationList()
+            .Select(d => d is Func<TEventArgs, Task> handler ? handler(args) : Task.CompletedTask)
+            .ToArray();
+    }
+}

src/OrasProject.Oras/CopyGraphOptions.cs

@@ -0,0 +1,105 @@
+// Copyright The ORAS Authors.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// 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 class CopyGraphOptions
+{
+    /// <summary>
+    /// PreCopyAsync handles the current descriptor before it is copied.
+    /// </summary>
+    public event Func<Descriptor, Task>? PreCopyAsync;
+
+    /// <summary>
+    /// PreCopy handles the current descriptor before it is copied.
+    /// </summary>
+    public event Action<Descriptor>? PreCopy;
+
+    /// <summary>
+    /// PostCopyAsync handles the current descriptor after it is copied.
+    /// </summary>
+    public event Func<Descriptor, Task>? PostCopyAsync;
+
+    /// <summary>
+    /// PostCopy handles the current descriptor after it is copied.
+    /// </summary>
+    public event Action<Descriptor>? PostCopy;
+
+    /// <summary>
+    /// CopySkippedAsync will be called when the sub-DAG rooted by the current node
+    /// is skipped.
+    /// </summary>
+    public event Func<Descriptor, Task>? CopySkippedAsync;
+
+    /// <summary>
+    /// CopySkipped will be called when the sub-DAG rooted by the current node
+    /// is skipped.
+    /// </summary>
+    public event Action<Descriptor>? CopySkipped;
+
+
+
+    /// <summary>
+    /// Invokes the <see cref="PreCopyAsync"/> event handlers asynchronously for the specified descriptor,
+    /// then invokes the <see cref="PreCopy"/> event handlers synchronously.
+    /// </summary>
+    /// <param name="descriptor">The <see cref="Descriptor"/> to process before copying.</param>
+    /// <returns>
+    /// A <see cref="Task"/> that represents the asynchronous operation of all <see cref="PreCopyAsync"/> handlers.
+    /// </returns>
+    internal Task InvokePreCopyAsync(Descriptor descriptor)
+    {
+        var tasks = PreCopyAsync?.InvokeAsync(descriptor) ?? [Task.CompletedTask];
+        PreCopy?.Invoke(descriptor);
+        return Task.WhenAll(tasks);
+    }
+
+
+    /// <summary>
+    /// Invokes the <see cref="PostCopyAsync"/> event handlers asynchronously for the specified descriptor,
+    /// then invokes the <see cref="PostCopy"/> event handlers synchronously.
+    /// </summary>
+    /// <param name="descriptor">The <see cref="Descriptor"/> to process after copying.</param>
+    /// <returns>
+    /// A <see cref="Task"/> that represents the asynchronous operation of all <see cref="PostCopyAsync"/> handlers.
+    /// </returns>
+    internal Task InvokePostCopyAsync(Descriptor descriptor)
+    {
+        var tasks = PostCopyAsync?.InvokeAsync(descriptor) ?? [Task.CompletedTask];
+        PostCopy?.Invoke(descriptor);
+        return Task.WhenAll(tasks);
+    }
+
+
+    /// <summary>
+    /// Invokes the <see cref="CopySkippedAsync"/> event handlers asynchronously for the specified descriptor,
+    /// then invokes the <see cref="CopySkipped"/> event handlers synchronously.
+    /// </summary>
+    /// <param name="descriptor">The <see cref="Descriptor"/> whose sub-DAG is being skipped.</param>
+    /// <returns>
+    /// A <see cref="Task"/> that represents the asynchronous operation of all <see cref="CopySkippedAsync"/> handlers.
+    /// </returns>
+    internal Task InvokeCopySkippedAsync(Descriptor descriptor)
+    {
+        var tasks = CopySkippedAsync?.InvokeAsync(descriptor) ?? [Task.CompletedTask];
+        CopySkipped?.Invoke(descriptor);
+        return Task.WhenAll(tasks);
+    }
+}

src/OrasProject.Oras/CopyOptions.cs

@@ -0,0 +1,19 @@
+// Copyright The ORAS Authors.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+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 class CopyOptions : CopyGraphOptions { }

src/OrasProject.Oras/Extensions.cs

@@ -11,16 +11,35 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-using OrasProject.Oras.Oci;
 using System;
 using System.Threading;
 using System.Threading.Tasks;
-using static OrasProject.Oras.Content.Extensions;
+using OrasProject.Oras.Content;
+using OrasProject.Oras.Oci;
 
 namespace OrasProject.Oras;
 
 public static class Extensions
 {
+    /// <summary>
+    /// Copy copies a rooted directed acyclic graph (DAG) with the tagged root node
+    /// in the source Target to the destination Target.
+    /// The destination reference will be the same as the source reference if the
+    /// destination reference is left blank.
+    /// Returns the descriptor of the root node on successful copy.
+    /// </summary>
+    /// <param name="src"></param>
+    /// <param name="srcRef"></param>
+    /// <param name="dst"></param>
+    /// <param name="dstRef"></param>
+    /// <param name="cancellationToken"></param>
+    /// <returns></returns>
+    /// <exception cref="Exception"></exception>
+    public static Task<Descriptor> CopyAsync(this ITarget src, string srcRef, ITarget dst, string dstRef,
+        CancellationToken cancellationToken = default)
+    {
+        return src.CopyAsync(srcRef, dst, dstRef, new CopyOptions(), cancellationToken);
+    }
 
     /// <summary>
     /// Copy copies a rooted directed acyclic graph (DAG) with the tagged root node
@@ -33,41 +52,52 @@ public static class Extensions
     /// <param name="srcRef"></param>
     /// <param name="dst"></param>
     /// <param name="dstRef"></param>
+    /// <param name="copyOptions"></param>
     /// <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, CancellationToken cancellationToken = default)
+    public static async Task<Descriptor> CopyAsync(this ITarget src, string srcRef, ITarget dst, string dstRef, CopyOptions copyOptions, CancellationToken cancellationToken = default)
     {
         if (string.IsNullOrEmpty(dstRef))
         {
             dstRef = srcRef;
         }
+
         var root = await src.ResolveAsync(srcRef, cancellationToken).ConfigureAwait(false);
-        await src.CopyGraphAsync(dst, root, cancellationToken).ConfigureAwait(false);
+        await src.CopyGraphAsync(dst, root, copyOptions, cancellationToken).ConfigureAwait(false);
         await dst.TagAsync(root, dstRef, cancellationToken).ConfigureAwait(false);
         return root;
     }
 
-    public static async Task CopyGraphAsync(this ITarget src, ITarget dst, Descriptor node, CancellationToken cancellationToken)
+    public static Task CopyGraphAsync(this ITarget src, ITarget dst, Descriptor node, CancellationToken cancellationToken = default)
+    {
+        return src.CopyGraphAsync(dst, node, new CopyGraphOptions(), cancellationToken);
+    }
+
+    public static async Task CopyGraphAsync(this ITarget src, ITarget dst, Descriptor node, CopyGraphOptions copyGraphOptions, CancellationToken cancellationToken = default)
     {
         // check if node exists in target
         if (await dst.ExistsAsync(node, cancellationToken).ConfigureAwait(false))
         {
+            await copyGraphOptions.InvokeCopySkippedAsync(node).ConfigureAwait(false);
             return;
         }
 
         // retrieve successors
         var successors = await src.GetSuccessorsAsync(node, cancellationToken).ConfigureAwait(false);
-        // obtain data stream
-        var dataStream = await src.FetchAsync(node, cancellationToken).ConfigureAwait(false);
+
         // check if the node has successors
-        if (successors != null)
+        foreach (var childNode in successors)
         {
-            foreach (var childNode in successors)
-            {
-                await src.CopyGraphAsync(dst, childNode, cancellationToken).ConfigureAwait(false);
-            }
+            await src.CopyGraphAsync(dst, childNode, copyGraphOptions, cancellationToken).ConfigureAwait(false);
         }
+
+        // perform the copy
+        await copyGraphOptions.InvokePreCopyAsync(node).ConfigureAwait(false);
+        var dataStream = await src.FetchAsync(node, cancellationToken).ConfigureAwait(false);
         await dst.PushAsync(node, dataStream, cancellationToken).ConfigureAwait(false);
+
+        // we copied it
+        await copyGraphOptions.InvokePostCopyAsync(node).ConfigureAwait(false);
     }
 }