Implement OCI Image Layout support

[jonjohnsonjr]

Ref #255

Feedback welcome :)

what changes

layout.Write takes an ImageIndex and writes it to disk as an OCI Image Layout. This writes the top-level manifest as index.json.

layout.Read returns a LayoutPath for the given path. You use this as the entrypoint into reading from a layout.

LayoutPath.Append{Image,Index} writes an image or index to the image layout and updates the index.json.

LayoutPath.WriteBlob writes a blob to the OCI Image Layout, but doesn't update the index.json.

LayoutPath.AppendDescriptor adds a descriptor to the index.json. This + WriteBlob lets you store arbitrary stuff in the image layout.

LayoutPath.Image reads a specific image by digest from the image layout.

LayoutPath.ImageIndex reads the whole image layout as and image index.

how do you use it?

You can construct arbitrary layouts via WriteBlob and AppendDescriptor. I think we'll want to make this a bit more ergonomic, e.g. Append{Image,Index} are going to be common operations, probably, since they just write an artifact to the blobs/ directory and update the index.json. There are some options, e.g. WithURLs and WithAnnotations to make it easier to Append things with the right descriptor.

[codecov-io]

Codecov Report

Merging #261 into master will increase coverage by 1.23%.
The diff coverage is 69.96%.

@@            Coverage Diff            @@
##           master    #261      +/-   ##
=========================================
+ Coverage   52.36%   53.6%   +1.23%     
=========================================
  Files          78      85       +7     
  Lines        3739    4022     +283     
=========================================
+ Hits         1958    2156     +198     
- Misses       1486    1531      +45     
- Partials      295     335      +40

Impacted Files	Coverage Δ
pkg/v1/manifest.go	50% <ø> (ø)	⬆️
pkg/v1/layout/blob.go	100% <100%> (ø)
pkg/v1/layout/layoutpath.go	100% <100%> (ø)
pkg/v1/layout/read.go	100% <100%> (ø)
pkg/v1/layout/options.go	100% <100%> (ø)
pkg/v1/layout/write.go	53.57% <53.57%> (ø)
pkg/v1/layout/image.go	80% <80%> (ø)
pkg/v1/layout/index.go	83.6% <83.6%> (ø)
... and 5 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 8c1640a...177baa5. Read the comment docs.

[imjasonh]

Lookin' good so far! 🎉

[glyn]

A couple of general questions on the pkg/v1/layout API. It looks sufficient at a detailed level - I'd just like to understand the general approach better and whether it could be framed a bit more cleanly.

[googlebot]

So there's good news and bad news.

👍 The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

😕 The bad news is that it appears that one or more commits were authored or co-authored by someone other than the pull request submitter. We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this state. It's up to you to confirm consent of all the commit author(s), set the cla label to yes (if enabled on your project), and then merge this pull request when appropriate.

ℹ️ Googlers: Go here for more info.

[glyn]

@jonjohnsonjr I confirm I'm ok with my commits being contributed to this project.

[jonjohnsonjr]

@imjasonh I think this if RFAL.

[glyn]

My previous concerns have been addressed, thanks.

[imjasonh]

This change looks okay to me, but I'd love to get some eyes on it belonging to someone more familiar with OCI image layouts. @vbatts perhaps?

[jonjohnsonjr]

@glyn I renamed a few things to satisfy the go linter, hope that's alright with you.