feat: introduce CopyError to identify error source in copy operations (#933)

1. Introduce a new error type `CopyError` and return it from `Copy` and
`ExtendedCopy` when necessary
2. Add corresponding unit tests
3. Add a example for the `CopyError` type

Resolve #677
Signed-off-by: Lixia (Sylvia) Lei <[email protected]>

Author: Wwwsylvia

copy.go

@@ -131,10 +131,10 @@ type CopyGraphOptions struct {
 // Returns the descriptor of the root node on successful copy.
 func Copy(ctx context.Context, src ReadOnlyTarget, srcRef string, dst Target, dstRef string, opts CopyOptions) (ocispec.Descriptor, error) {
 	if src == nil {
-		return ocispec.Descriptor{}, errors.New("nil source target")
+		return ocispec.Descriptor{}, newCopyError("Copy", CopyErrorOriginSource, errors.New("nil source target"))
 	}
 	if dst == nil {
-		return ocispec.Descriptor{}, errors.New("nil destination target")
+		return ocispec.Descriptor{}, newCopyError("Copy", CopyErrorOriginDestination, errors.New("nil destination target"))
 	}
 	if dstRef == "" {
 		dstRef = srcRef
@@ -147,14 +147,14 @@ func Copy(ctx context.Context, src ReadOnlyTarget, srcRef string, dst Target, ds
 	proxy := cas.NewProxyWithLimit(src, cas.NewMemory(), opts.MaxMetadataBytes)
 	root, err := resolveRoot(ctx, src, srcRef, proxy)
 	if err != nil {
-		return ocispec.Descriptor{}, fmt.Errorf("failed to resolve %s: %w", srcRef, err)
+		return ocispec.Descriptor{}, err
 	}
 
 	if opts.MapRoot != nil {
 		proxy.StopCaching = true
 		root, err = opts.MapRoot(ctx, proxy, root)
 		if err != nil {
-			return ocispec.Descriptor{}, err
+			return ocispec.Descriptor{}, newCopyError("MapRoot", CopyErrorOriginSource, err)
 		}
 		proxy.StopCaching = false
 	}
@@ -174,6 +174,12 @@ func Copy(ctx context.Context, src ReadOnlyTarget, srcRef string, dst Target, ds
 // from the source CAS to the destination CAS.
 // The root node (e.g. a manifest of the artifact) is identified by a descriptor.
 func CopyGraph(ctx context.Context, src content.ReadOnlyStorage, dst content.Storage, root ocispec.Descriptor, opts CopyGraphOptions) error {
+	if src == nil {
+		return newCopyError("CopyGraph", CopyErrorOriginSource, errors.New("nil source target"))
+	}
+	if dst == nil {
+		return newCopyError("CopyGraph", CopyErrorOriginDestination, errors.New("nil destination target"))
+	}
 	return copyGraph(ctx, src, dst, root, nil, nil, nil, opts)
 }
 
@@ -222,7 +228,7 @@ func copyGraph(ctx context.Context, src content.ReadOnlyStorage, dst content.Sto
 		// skip if a rooted sub-DAG exists
 		exists, err := dst.Exists(ctx, desc)
 		if err != nil {
-			return err
+			return newCopyError("Exists", CopyErrorOriginDestination, err)
 		}
 		if exists {
 			if opts.OnCopySkipped != nil {
@@ -236,7 +242,7 @@ func copyGraph(ctx context.Context, src content.ReadOnlyStorage, dst content.Sto
 		// find successors while non-leaf nodes will be fetched and cached
 		successors, err := opts.FindSuccessors(ctx, proxy, desc)
 		if err != nil {
-			return err
+			return newCopyError("FindSuccessors", CopyErrorOriginSource, err)
 		}
 		successors = removeForeignLayers(successors)
 
@@ -264,7 +270,7 @@ func copyGraph(ctx context.Context, src content.ReadOnlyStorage, dst content.Sto
 
 		exists, err = proxy.Cache.Exists(ctx, desc)
 		if err != nil {
-			return err
+			return fmt.Errorf("failed to check cache existence: %s: %w", desc.Digest, err)
 		}
 		if exists {
 			return copyNode(ctx, proxy.Cache, dst, desc, opts)
@@ -324,7 +330,7 @@ func mountOrCopyNode(ctx context.Context, src content.ReadOnlyStorage, dst conte
 
 		// Mount or copy
 		if err := mounter.Mount(ctx, desc, sourceRepository, getContent); err != nil && !errors.Is(err, skipSource) {
-			return err
+			return newCopyError("Mount", CopyErrorOriginDestination, err)
 		}
 
 		if !mountFailed {
@@ -352,12 +358,12 @@ func mountOrCopyNode(ctx context.Context, src content.ReadOnlyStorage, dst conte
 func doCopyNode(ctx context.Context, src content.ReadOnlyStorage, dst content.Storage, desc ocispec.Descriptor) error {
 	rc, err := src.Fetch(ctx, desc)
 	if err != nil {
-		return err
+		return newCopyError("Fetch", CopyErrorOriginSource, err)
 	}
 	defer rc.Close()
 	err = dst.Push(ctx, desc, rc)
 	if err != nil && !errors.Is(err, errdef.ErrAlreadyExists) {
-		return err
+		return newCopyError("Push", CopyErrorOriginDestination, err)
 	}
 	return nil
 }
@@ -389,13 +395,13 @@ func copyNode(ctx context.Context, src content.ReadOnlyStorage, dst content.Stor
 func copyCachedNodeWithReference(ctx context.Context, src *cas.Proxy, dst registry.ReferencePusher, desc ocispec.Descriptor, dstRef string) error {
 	rc, err := src.FetchCached(ctx, desc)
 	if err != nil {
-		return err
+		return newCopyError("Fetch", CopyErrorOriginSource, err)
 	}
 	defer rc.Close()
 
 	err = dst.PushReference(ctx, desc, rc, dstRef)
 	if err != nil && !errors.Is(err, errdef.ErrAlreadyExists) {
-		return err
+		return newCopyError("PushReference", CopyErrorOriginDestination, err)
 	}
 	return nil
 }
@@ -404,7 +410,11 @@ func copyCachedNodeWithReference(ctx context.Context, src *cas.Proxy, dst regist
 func resolveRoot(ctx context.Context, src ReadOnlyTarget, srcRef string, proxy *cas.Proxy) (ocispec.Descriptor, error) {
 	refFetcher, ok := src.(registry.ReferenceFetcher)
 	if !ok {
-		return src.Resolve(ctx, srcRef)
+		desc, err := src.Resolve(ctx, srcRef)
+		if err != nil {
+			return ocispec.Descriptor{}, newCopyError("Resolve", CopyErrorOriginSource, err)
+		}
+		return desc, nil
 	}
 
 	// optimize performance for ReferenceFetcher targets
@@ -414,7 +424,7 @@ func resolveRoot(ctx context.Context, src ReadOnlyTarget, srcRef string, proxy *
 	}
 	root, rc, err := refProxy.FetchReference(ctx, srcRef)
 	if err != nil {
-		return ocispec.Descriptor{}, err
+		return ocispec.Descriptor{}, newCopyError("FetchReference", CopyErrorOriginSource, err)
 	}
 	defer rc.Close()
 	// cache root if it is a non-leaf node
@@ -425,7 +435,7 @@ func resolveRoot(ctx context.Context, src ReadOnlyTarget, srcRef string, proxy *
 		return nil, errors.New("fetching only root node expected")
 	})
 	if _, err = content.Successors(ctx, fetcher, root); err != nil {
-		return ocispec.Descriptor{}, err
+		return ocispec.Descriptor{}, newCopyError("Successors", CopyErrorOriginSource, err)
 	}
 
 	// TODO: optimize special case where root is a leaf node (i.e. a blob)
@@ -434,7 +444,7 @@ func resolveRoot(ctx context.Context, src ReadOnlyTarget, srcRef string, proxy *
 }
 
 // prepareCopy prepares the hooks for copy.
-func prepareCopy(ctx context.Context, dst Target, dstRef string, proxy *cas.Proxy, root ocispec.Descriptor, opts *CopyOptions) error {
+func prepareCopy(_ context.Context, dst Target, dstRef string, proxy *cas.Proxy, root ocispec.Descriptor, opts *CopyOptions) error {
 	if refPusher, ok := dst.(registry.ReferencePusher); ok {
 		// optimize performance for ReferencePusher targets
 		preCopy := opts.PreCopy
@@ -467,7 +477,7 @@ func prepareCopy(ctx context.Context, dst Target, dstRef string, proxy *cas.Prox
 			if content.Equal(desc, root) {
 				// for root node, tag it after copying it
 				if err := dst.Tag(ctx, root, dstRef); err != nil {
-					return err
+					return newCopyError("Tag", CopyErrorOriginDestination, err)
 				}
 			}
 			if postCopy != nil {
@@ -499,7 +509,10 @@ func prepareCopy(ctx context.Context, dst Target, dstRef string, proxy *cas.Prox
 				return err
 			}
 		}
-		return dst.Tag(ctx, root, dstRef)
+		if err := dst.Tag(ctx, root, dstRef); err != nil {
+			return newCopyError("Tag", CopyErrorOriginDestination, err)
+		}
+		return nil
 	}
 
 	return nil