Make OCI code reuseable across projects without Zarf

[AustinAbro321]

Background

Currently Zarf is a CLI with portions of it's code available as a library; part of this library is OCI functions for Zarf packages. These functions have become generally useful across Defense Unicorns projects such as UDS CLI. However, we do not adhere to the same promises around breaking changes as we do for general zarf cli usage. This can lead to difficulty for consumers of Zarf as a library to keep pace and not cause churn around breaking changes. Additionally, the code is currently heavily opinionated towards Zarf and needs to be refactored to be more useful for other projects. It can also be slow to contribute to the Zarf library as it is coupled to the Zarf release cycle.

Objective

Goals

• Separate out the Zarf specific OCI code from the generally useful OCI code.
• Make it easier to interact with OCI primitives such as manifests, indexes, and layers in a common way.
• Clearly communicate breaking changes through practices like semver.

Non-goals

• Not a generic ORAS client, this is opinionated towards Zarf packages and UDS bundles
• In this transition we will not make zarf compatiable with gitlab or nexus or other non-compliant oci registries. But we should make a tech debt issue to make zarf work in this case with at least one architecture

Terminology

ORAS - https://oras.land/docs/. All references to ORAS refer to oras-go/v2

layers - https://github.com/opencontainers/image-spec/blob/main/layer.md. In our case, layers are not built in a series of steps. They represent the paths of a filesystem.

remote - ORAS's remote.Repository

descriptor - https://github.com/opencontainers/image-spec/blob/main/descriptor.md

Design

This library will be an opinionated wrapper client around the ORAS library to make it easier to execute common OCI operations such as pull, push, copy, and fetch. The client leverages the go option pattern for optional instantiation parameters.

• Pull functions pull down layers either from descriptors or paths, via the org.opencontainers.image.title annotation.

• Push functions take in content and push to the remote repository.

• Copy takes in two remotes and copies all the contents from one remote to another. Manifest creation and tagging is handled outside of this copy function. ProgressWriter is an interface in this package accepted as an optional parameter. It allows callers to write to a progress bar as the contents are copied.

type ProgressWriter interface {
	UpdateTitle(string)
	io.Writer
}

• ResolveRoot fetches the digest of the root manifest. Can also be used to ensure that the manifest exists for target platform.
• fetch functions return the content of the given descriptor as a byte array

This library will maintain a thin wrapper around ocispec.Manifest for ease of use for certain common manifest queries.

Similarly we expose some utility functions for common ORAS / descriptor use cases.

[AustinAbro321]

Note we should let uds-cli know the following:

• Users now need to add their own annotations, previously it was generated from zarf metadata
• We no longer have the PullLayers function, and users will now need to de-duplicate their layers before calling CopyToStore (previously called CopyWithProgress)