Make errSkipDesc a publicly available error

[Noxsios]

With this change, oras.ErrSkipDesc can be used during PreCopy to do custom filtering during copy operations.

This error is needed to be public as errors.New will always create a new error instance, even if the text is the same, so you cannot utilize errors.New("skip descriptor").

ex (psuedo code):

        only := []string{"hello.txt", "world.txt"}
	copyOpts.PreCopy = func(ctx context.Context, desc ocispec.Descriptor) error {
		if len(only) > 0 {
			if !utils.sliceContains(only, desc.Annotations[ocispec.AnnotationTitle]) {
				return oras.ErrSkipDesc
			}
		}
		return nil
	}

[TerryHowe]

Is there any other data that should be in this error like #482

[Noxsios]

Is there any other data that should be in this error like #482

AFAIK, no.

[codecov-commenter]

Codecov Report

Merging #487 (925ef9e) into main (264f5f2) will increase coverage by 0.22%.
The diff coverage is 0.00%.

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

@@            Coverage Diff             @@
##             main     #487      +/-   ##
==========================================
+ Coverage   72.92%   73.14%   +0.22%     
==========================================
  Files          49       49              
  Lines        4528     4528              
==========================================
+ Hits         3302     3312      +10     
+ Misses        919      911       -8     
+ Partials      307      305       -2     

Impacted Files	Coverage Δ
copy.go	62.86% <0.00%> (ø)

... and 1 file with indirect coverage changes

[qweeah]

@Noxsios IMHO, it's better to do this work in FindSuccessors?

only := []string{"hello.txt", "world.txt"}
copyOpts.FindSuccessors = func(ctx context.Context, fetcher content.Fetcher, desc ocispec.Descriptor) ([]ocispec.Descriptor, error) {
  nodes, err := func Successors(ctx, fetcher, desc)
  if err != nil {
    return nil, err
  }
  if len(only) == 0 {
    return nodes
  }
  var ret []ocispec.Descriptor
  for _, n := range nodes {
    if utils.sliceContains(only, n.Annotations[ocispec.AnnotationTitle]) /* or it's a non-leaf node like manifest/index */ {
      append(ret, n)     
    }
  }
  return ret
})

[Wwwsylvia]

Hi @Noxsios, can you check if @qweeah's suggestion works for you?
My concern is that ErrSkipDesc might be easily misused by users.

[Noxsios]

@Wwwsylvia Agreed. I was unaware that FindSuccessors could mutate the fetched manifest before layers were pulled. I will test and close if it works as intended.

[Noxsios]

Looks like that works! Final function looks similar to this in case others want the same behavior.

// where optional is a slice of strings
// estimatedBytes is the result of calculating the total size of a OCI artifact
		alwaysPull := []string{"zarf.yaml", "checksums.txt", "zarf.yaml.sig"}
		toPull = append(optional, alwaysPull...)
		copyOpts.FindSuccessors = func(ctx context.Context, fetcher content.Fetcher, desc ocispec.Descriptor) ([]ocispec.Descriptor, error) {
			nodes, err := content.Successors(ctx, fetcher, desc)
			if err != nil {
				return nil, err
			}
			var ret []ocispec.Descriptor
			for _, node := range nodes {
				if utils.SliceContains(toPull, node.Annotations[ocispec.AnnotationTitle]) {
					ret = append(ret, node)
				} else {
					estimatedBytes -= node.Size
				}
			}
			return ret, nil
		}

estimatedBytes is used in our byte by byte progress bar for download / upload progress