coci

package
v0.42.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 39 Imported by: 0

Documentation

Overview

Package coci contains functions for interacting with Cargoship packages stored in OCI registries, derived from github.com/zarf-dev/src/pkg/zoci.

Index

Constants

View Source
const (
	// CargoshipConfigMediaType is the media type for the manifest config
	CargoshipConfigMediaType = "application/vnd.cargoship.config.v1+json"
	// CargoshipLayerMediaTypeBlob is the media type for all Zarf layers due to the range of possible content
	CargoshipLayerMediaTypeBlob = "application/vnd.cargoship.layer.v1.blob"
	// CargoshipMirrorConfigMediaType is the media type of the config blob on the record a mirror
	// writes about itself. It is what classifies that artifact, so it is what a reader matches on
	// rather than trusting the repository name it was found under.
	CargoshipMirrorConfigMediaType = "application/vnd.cargoship.mirror.v1+json"
	// DefaultConcurrency is the default concurrency used for operations
	DefaultConcurrency = 6
	//DefaultRetries is the default number of retries for operations
	DefaultRetries = 1
)
View Source
const OCITimestampFormat = time.RFC3339

OCITimestampFormat is the format used for the OCI timestamp annotation

Variables

View Source
var (
	// ErrArchRequired is returned when a reference resolves to an image index covering more
	// than one architecture and the selector named none.
	ErrArchRequired = errors.New("no single architecture was selected")
	// ErrLayerRequired is returned when the resolved manifest carries more than one layer and
	// the selector named no layer title.
	ErrLayerRequired = errors.New("no layer title was selected")
)

A caller resolves these two by supplying something the reference does not carry, and each caller spells that differently -- a distro definition has selector.arch and layer fields, the sha256sum command has --arch and --layer -- so the error says what is missing and leaves the caller to say where to put it.

View Source
var (
	// PackageAlwaysPull is a list of paths that will always be pulled from the remote repository.
	PackageAlwaysPull = []string{
		config.DistroYAML,
		config.Checksums,
		config.Bundle,
	}
)

Functions

func AssembleLayers

func AssembleLayers(ctx context.Context, root *oci.Manifest, fetcher content.Fetcher, include ...layers.LayerType) ([]ocispec.Descriptor, error)

AssembleLayers returns the OCI layer descriptors for the requested components. The include parameter specifies which layer types to return. All layers are included if include is empty and Metadata layers are always included

func FetchDistroYAML

func FetchDistroYAML(ctx context.Context, root *oci.Manifest, fetcher content.Fetcher) (distro.Distro, error)

FetchDistroYAML fetches the distro.yaml file from the remote repository.

func FetchFile added in v0.40.0

func FetchFile(ctx context.Context, ref string, sel FileSelector, dst string, opts FileOptions) (err error)

FetchFile writes the file ref and sel name to dst, creating dst's parent as needed.

The layer is verified against the digest its manifest gives it as it is read, so a truncated or substituted transfer fails here whatever the caller does afterwards.

func FetchLayerFile added in v0.40.0

func FetchLayerFile(ctx context.Context, ref string, sel FileSelector, dir string, opts FileOptions) (_ string, err error)

FetchLayerFile writes the layer ref and sel select into dir, under the name the artifact gave it, and returns the path it wrote.

The name is not cosmetic. An extraction identifies an archive's format from its file name rather than from its bytes, so a layer staged as anything but its own title cannot be extracted from -- which is why a layer carrying no title is refused here rather than left to fail inside an extractor, naming a temporary path the caller never chose.

func FileMembers added in v0.40.0

func FileMembers(ctx context.Context, ref string, sel FileSelector, opts FileOptions) (_ []string, err error)

FileMembers lists the paths inside the layer ref and sel select, for a layer that is an archive. The result is what --extract-path or a file entry's extractPath can name.

Unlike FileArches and FileLayers this reads the layer itself rather than a manifest, which for a vendor engine bundle is tens of mebibytes. Two things make that acceptable rather than rude, and both are why the caller should only ask once a layer has actually been chosen:

  • it is exactly the blob the command being completed is about to fetch anyway, into the same cache, so a completion that is followed through costs nothing extra; and
  • a second ask is served from that cache without touching the network.

Pass a context with a deadline. A caller offering suggestions must not block, and an abandoned transfer is dropped rather than cached: the blob is verified against its digest before the cache commits it.

func GetOCICacheModifier

func GetOCICacheModifier(ctx context.Context, cachePath string) (oci.Modifier, error)

GetOCICacheModifier takes in a Cargoship cachePath and uses it to return an oci.WithCache modifier

func LayerDigest added in v0.40.0

func LayerDigest(ctx context.Context, ref string, sel FileSelector, opts FileOptions) (string, error)

LayerDigest returns the digest of the layer ref and sel select, without fetching it.

It costs one reference resolution and, for an index, one manifest read -- both of which the fetch that usually follows would do anyway, and both of which are small and cached. It exists so a caller can ask "have I already got what comes out of this archive?" before spending tens of mebibytes finding out.

The digest is the registry's, verified on any subsequent fetch, so it is a safe key for anything derived from the layer's content.

func LayersFromFiles

func LayersFromFiles(ctx context.Context, root *oci.Manifest, files v1alpha1.Files, folder string) ([]ocispec.Descriptor, error)

LayersFromFiles returns the file oci blob layers referenced by annotation.

func LayersFromImages

func LayersFromImages(ctx context.Context, root *oci.Manifest, fetcher content.Fetcher, imageList []string) ([]ocispec.Descriptor, error)

LayersFromImages returns the image blob layers referenced by imageList, selecting from root. fetcher reads image manifests/indexes to walk multi-arch children.

func PinReference added in v0.40.0

func PinReference(ref, digest string) string

PinReference returns ref with whatever tag it carries replaced by digest, leaving a reference that resolves to the same bytes forever. A reference already naming a digest is returned unchanged.

func ReferenceFromMetadataWithOptions

func ReferenceFromMetadataWithOptions(registryLocation string, pkg distro.Distro, opts ReferenceFromMetadataOptions) (registry.Reference, error)

ReferenceFromMetadataWithOptions returns a reference for the given metadata with optional overrides

Types

type ArtifactPlatform added in v0.40.0

type ArtifactPlatform struct {
	// Arch is the architecture, which is what a caller selects by.
	Arch string
	// OS is how the artifact spells the operating system -- "linux" for a vendor bundle,
	// "multi" for a zarf or cargoship package index. See acceptedPlatformOS.
	OS string
}

ArtifactPlatform is one architecture an OCI artifact offers, and the platform its index declares for it.

func FileArches added in v0.40.0

func FileArches(ctx context.Context, ref string, opts FileOptions) ([]ArtifactPlatform, error)

FileArches lists the architectures ref offers, sorted, for a reference resolving to an image index. It returns nothing for an artifact published as a single manifest, which needs no architecture to read.

Only children a linux node could use are listed, so this answers the same question FetchFile's selection asks. It exists for shell completion, which is why it reads nothing but the index: a caller offering --arch suggestions should not pull a layer to do it.

type FileOptions added in v0.40.0

type FileOptions struct {
	types.RemoteOptions
	// CachePath roots the shared blob cache, so an artifact's layers are fetched once per
	// cache rather than once per read. Caching is skipped when it is empty.
	CachePath string
}

FileOptions is the registry transport and caching an artifact is read with.

type FileSelector added in v0.40.0

type FileSelector struct {
	// Arch is the platform architecture to resolve, for a reference that is an image index.
	// It may be empty for an artifact published as a single manifest.
	Arch string
	// Layer names a layer by its org.opencontainers.image.title annotation. It is required
	// when the manifest carries more than one layer.
	Layer string
	// ExtractPath is a path inside the selected layer, for a layer that is an archive. The
	// layer must carry a title, because the archive format is identified from its file name.
	ExtractPath string
}

FileSelector narrows an OCI artifact to the one file a caller wants out of it.

A reference alone frequently does not name bytes. A vendor-published artifact is commonly an image index over one manifest per platform, and a manifest can carry one layer or fifty -- so the architecture picks the manifest, the layer title picks the layer, and an extract path picks a member out of a layer that is itself an archive.

type LayerListing added in v0.40.0

type LayerListing struct {
	// Titles is every titled layer of the manifest read, sorted.
	Titles []string
	// Arch is the architecture whose manifest was read. It is empty for an artifact published
	// as a single manifest, which has no architecture to report.
	Arch string
	// Assumed is true when no architecture was asked for, the reference turned out to be an
	// index over several, and one was read anyway. The titles are then a good guess rather
	// than an answer -- see FileLayers.
	Assumed bool
}

LayerListing is the titles an artifact's manifest carries, and which manifest they came from.

func FileLayers added in v0.40.0

func FileLayers(ctx context.Context, ref string, arch string, opts FileOptions) (LayerListing, error)

FileLayers lists the layer titles ref offers for arch.

It exists for shell completion, and its contract is looser than FetchFile's on purpose. With no architecture given and a reference that is an index over several, FetchFile refuses -- there is no safe way to pick bytes. Here the first candidate child is read instead and Assumed is set, because every artifact this has been used against titles its layers identically across platforms, and a completion that offers nothing until another flag is typed teaches an operator nothing. The caller is expected to say that it guessed.

Nothing is decided by this: a title it suggests is still resolved for real, against the architecture actually requested, when the file is fetched.

type PublishOptions

type PublishOptions struct {
	// Retries is the number of times to retry a failed operation
	Retries int
	// OCIConcurrency configures the amount of layers to push in parallel
	OCIConcurrency int
	// Tag allows for overriding the destination reference
	Tag string
}

PublishOptions contains options for the publish operation

type ReferenceFromMetadataOptions

type ReferenceFromMetadataOptions struct {
	// Tag specifies the OCI reference to use instead of package.metadata.version
	Tag string
}

ReferenceFromMetadataOptions provides extensible options

type Remote

type Remote struct {
	*oci.OrasRemote
}

Remote is a wrapper around the Oras remote repository with cargoship specific functions

func NewRemote

func NewRemote(ctx context.Context, url string, platform ocispec.Platform, mods ...oci.Modifier) (*Remote, error)

NewRemote returns an oras remote repository client and context for the given url with cargoship opination embedded

func (*Remote) AssembleLayers

func (r *Remote) AssembleLayers(ctx context.Context, include ...layers.LayerType) ([]ocispec.Descriptor, error)

AssembleLayers returns the OCI layer descriptors for the requested components. The include parameter specifies which layer types to return. All layers are included if include is empty and Metadata layers are always included

func (*Remote) PullDistro

func (r *Remote) PullDistro(ctx context.Context, destinationDir string, concurrency int, layersToPull ...ocispec.Descriptor) (_ []ocispec.Descriptor, err error)

PullDistro pulls the package from the remote repository and saves it to the given path.

func (*Remote) PushPackage

func (r *Remote) PushPackage(ctx context.Context, disLayout *layout.DistroLayout, opts PublishOptions) (_ ocispec.Descriptor, err error)

PushPackage publishes the zarf package to the remote repository.

func (*Remote) SoleManifestDigest

func (r *Remote) SoleManifestDigest(ctx context.Context) (digest.Digest, error)

SoleManifestDigest returns the digest of the only package manifest the index at the remote's reference lists. A package published for one architecture holds a single manifest, so there is nothing to choose between and the caller can pull it whatever platform the index records it under. It errors when the index lists more than one distinct manifest, since picking between those is what platform matching is for.

type Resolution added in v0.40.0

type Resolution struct {
	// Reference is ref with its tag replaced by the digest it resolved to, so re-resolving it
	// can only ever return the same bytes. For an index it is the index's own digest, which
	// keeps the selector doing the same job it did for the tag.
	Reference string
	// ManifestDigest is the digest of the manifest the architecture selected, which for an
	// index is one of its children and otherwise is the root itself.
	ManifestDigest string
	// LayerDigest is the digest of the layer the selector picked out of that manifest.
	LayerDigest string
}

Resolution is what a reference and selector resolved to, for a caller that wants to record or re-pin what it read.

func Resolve added in v0.40.0

func Resolve(ctx context.Context, ref string, sel FileSelector, opts FileOptions) (Resolution, error)

Resolve reports what ref and sel name, without fetching any layer.

It costs one reference resolution and, for an index, one manifest read - both of which a fetch would do anyway and both of which are small and cached. A caller that resolves first and then fetches by Reference also closes the window between the two: a tag re-pushed in between cannot swap the bytes underneath it.

Directories

Path Synopsis
Package layers contains functions for interacting with Cargoship layers stored in OCI registries, derived from github.com/zarf-dev/src/pkg/zoci.
Package layers contains functions for interacting with Cargoship layers stored in OCI registries, derived from github.com/zarf-dev/src/pkg/zoci.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL