feature: allow for skip unpack on pull

[vsoch]

Problem

Currently, the logic to decide if an archive artifact is unpacked is determiend on push via an annotation. Here is how I set that to a "path" ".":

# contents of annotations.go
{".": {"io.deis.oras.content.unpack": "false"}}

# push, targeting annotations.go
oras push --annotation-file ./annotations.json ${pushto} --plain-http .

And the resulting manifest is how I want it.

However, the problem is that when it's time to pull, I (as the pulling user) have no control about this unpack. And in fact, I might want different outcomes depending on where I'm doing the extraction and the size of the archive.

Proposed Solution

While we can default to the preference of the annotation set on push (this makes sense as the pusher knows most about the artifact) ideally I as the user can make this choice at pull time, via a flag:

oras pull --skip-unpack localhost:5000/hello:v1

The above says that I don't want to unpack, regardless of what the annotation says. Since this is globally applied to the layers, I would propose we apply to all layers where it's relevant. The use case of wanting to fine grained control the unpack might be addressed if/when an actual user calls for it.

Use Case

My use case is the oras-operator - https://github.com/converged-computing/oras-operator. I did an analysis today using something called hpctoolkit that generates huuuge databases and results, and I don't want it to unpack on my local machine. But depending on where I'm pulling it, I might want it to. The point being, I should be able to decide on pull.

From @FeynmanZhou:

Thanks for sharing the use case. Your scenario looks interesting and new! Now you are unblocked in customizing annotation, but are looking for a switch to control the unpack behavior in oras pull and corresponding AnnotationUnpack function in oras-go?

And yes, this is spot on. Thank you!

[FeynmanZhou]

Hi @vsoch ,

Thanks for the feature request. This is a common scenario and I do see the value of this feature.
Are you interested in contributing to this implementation?

[vsoch]

hey @FeynmanZhou ! I remember looking at the code when I opened the issue, and I think I could take a first shot but I need some guidance about the logic. I've had a hard time following it since the refactor from push/pull to the more abstract design now. If someone can provide that guidance I'm happy to take a shot, otherwise feel free to assign to someone familiar with the codebase.

[Wwwsylvia]

Hi @vsoch , if you are still interested to contribute, maybe you can use this unit test as an entry point to get familiar with the code base of File Store. You may debug into this line which pushes a tar.gz file.
The test code is not very readable though (I was trying to recall why I did this when I looked at it 😂).
Similarly, you can also check other unit tests, such as this one.

The idea is that, feel free to ping me if you are blocked. 🙂
If you don't have time or are no longer interested, we can leave this issue for someone else in the community to pick it up.

[vsoch]

@Wwwsylvia it's probably good to open up to the community - I could have made time over break but now that we are back to work, I would be able to make time akin to others that might help.