contentstore

package
v0.42.3 Latest Latest
Warning

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

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

Documentation

Overview

Package contentstore holds the pieces shared by the readers of a local content bundle -- a hauler store, a zarf package -- so that two readers of the same OCI layout cannot drift apart in how they open it or how they key an image reference.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CanonicalFileRef added in v0.40.0

func CanonicalFileRef(src string) string

CanonicalFileRef puts a file source into the one spelling a bundle and a definition share.

A bundle records what it collected from, and for an artifact pulled out of a registry that is a bare reference: hauler writes `registry.example.com/vendor/engine:v1.37.1` into `hauler.dev/original-ref`, with no scheme, because that is what a registry client was given. A distro definition has to write `oci://` in front of the same string, since `source` also takes URLs and paths and the scheme is what tells them apart.

So the two spellings of one artifact differ by exactly the prefix, and a file staged from a store would otherwise never be found. Everything that is not an OCI reference is returned unchanged: a URL keeps its scheme, because that is part of what a bundle recorded.

func CanonicalImageRef

func CanonicalImageRef(ref string) string

CanonicalImageRef puts an image reference into the one spelling two equal references share, so that a bundle is indexed and searched by the same key.

Both bundle formats record what they collected under the registry's canonical host: an image added as docker.io/rancher/pause:3.10 comes back as index.docker.io/rancher/pause:3.10, which is the same image under a name a distro definition does not use. The same split applies to an official image, where docker.io/nginx, nginx and docker.io/library/nginx are one reference written three ways. A reference that will not parse is keyed as it was written -- it would not have matched anything anyway, and failing the lookup beats failing the open.

func FileRef

func FileRef(target, source string) (string, error)

FileRef is where the file declared as coming from source lives in a mirror under target.

It is the one rule a writer and a reader of a mirrored file both apply, which is what lets a reader recompute a reference instead of discovering it -- a registry offers a repository catalogue and per-repository tags, never one annotated index the way a hauler store or a zarf package does, so there is nothing to walk and nothing to match against.

The name carries the file's basename so a repository listing is legible to a person, and the tag is a digest of the whole source so it is correct. Keying on the basename alone would be wrong rather than merely ugly: every rke2 and etcd release archive is named the same across versions, so one version's file would be served for another's.

func LayoutFS

func LayoutFS(fsys fs.FS) fs.FS

LayoutFS presents a directory as an OCI image layout, serving the oci-layout marker from memory when the directory has none.

A live hauler store is a complete layout except for that marker -- hauler writes one only when saving an archive. The reader needs it (oras refuses a layout without one) and must not create it, because cargoship was asked to read the operator's store, not to modify it. So it is supplied here instead, for the lifetime of the read.

A zarf package's images/ directory normally does carry the marker, because zarf writes that layout through oras, which creates one. The fallback below defers to a real file whenever there is one, so wrapping both readers in this costs nothing and leaves neither depending on a marker it did not write.

func Unpack

func Unpack(ctx context.Context, path string) (dir string, tempDir string, err error)

Unpack makes the content bundle at path readable as a directory, returning the directory to read and the temporary directory the caller must remove when it is done -- which is empty when path was already a directory, because an operator's own store is never written to or removed.

It is the one place a bundle is decompressed, so that deciding which format a bundle is can be a stat against the unpacked tree rather than a second pass over the archive.

Types

type FileRequest added in v0.40.0

type FileRequest struct {
	// Source is the source the definition declared, which is the string a bundle recorded as
	// the content's original reference.
	Source string
	// Arch is the single architecture the entry's selector names, and is empty when the entry
	// names none or several. A bundle holding one platform of a file answers without it; a
	// bundle holding several cannot, and refuses rather than choosing.
	Arch string
	// Layer is the layer title the entry names, and is empty when it names none. A file
	// artifact that carries every file in a release as its own titled layer needs it; one
	// carrying a single layer does not.
	Layer string
}

FileRequest is what a distro definition's file entry asks a content bundle for. It is a struct rather than a reference string because one reference is not always enough to name the bytes: a vendor-published file artifact is commonly an image index over one manifest per platform, and the entry's own selector is the only thing that says which to take.

Jump to

Keyboard shortcuts

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