feat(copy): introduces CopyGraphOptions with events support

src/OrasProject.Oras/AsyncInvocationExtensions.cs

@@ -0,0 +1,39 @@
+// 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.Linq;
+using System.Threading.Tasks;
+
+namespace OrasProject.Oras;
+
+internal static class AsyncInvocationExtensions
+{
+    /// <summary>
+    /// Asynchronously invokes all handlers from an event that returns a <see cref="Task"/>.
+    /// <remarks>All handlers are executed in parallel</remarks>
+    /// </summary>
+    /// <param name="eventDelegate"></param>
+    /// <param name="args"></param>
+    /// <typeparam name="TEventArgs"></typeparam>
+    internal static Task InvokeAsync<TEventArgs>(
+        this Func<TEventArgs, Task>? eventDelegate, TEventArgs args)
+    {
+        if (eventDelegate == null) return Task.CompletedTask;
+
+        var tasks = eventDelegate.GetInvocationList()
+            .Select(d => (Task?)d.DynamicInvoke(args) ?? Task.CompletedTask);
+
+        return Task.WhenAll(tasks);
+    }
+}

src/OrasProject.Oras/CopyGraphOptions.cs

@@ -0,0 +1,74 @@
+// 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 struct 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;
+
+    internal Task OnPreCopyAsync(Descriptor descriptor)
+    {
+        PreCopy?.Invoke(descriptor);
+        return PreCopyAsync?.InvokeAsync(descriptor) ?? Task.CompletedTask;
+    }
+
+    internal Task OnPostCopyAsync(Descriptor descriptor)
+    {
+        PostCopy?.Invoke(descriptor);
+        return PostCopyAsync?.InvokeAsync(descriptor) ?? Task.CompletedTask;
+    }
+
+    internal Task OnCopySkippedAsync(Descriptor descriptor)
+    {
+        CopySkipped?.Invoke(descriptor);
+        return CopySkippedAsync?.Invoke(descriptor) ?? Task.CompletedTask;
+    }
+}

src/OrasProject.Oras/CopyOptions.cs

@@ -0,0 +1,22 @@
+// 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 struct CopyOptions
+{
+    public CopyGraphOptions 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 OrasProject.Oras.Oci;
 using static OrasProject.Oras.Content.Extensions;
 
 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,51 @@ 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 = default, 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.CopyGraphOptions, 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 = default, CancellationToken cancellationToken = default)
     {
         // check if node exists in target
         if (await dst.ExistsAsync(node, cancellationToken).ConfigureAwait(false))
         {
+            await copyGraphOptions.OnCopySkippedAsync(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.OnPreCopyAsync(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.OnPostCopyAsync(node).ConfigureAwait(false);
     }
 }