haulerstore

package
v0.42.2 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: 14 Imported by: 0

Documentation

Overview

Package haulerstore reads a hauler store (https://github.com/hauler-dev/hauler) as a source of images and files for a package build.

A store is a plain OCI image layout, and every entry in its index carries a "hauler.dev/original-ref" annotation holding the content's original identity: a registry/repo:tag for an image, and the source URL for a file. Those are the same strings a distro definition writes in imageConfig.images and File.Source, so resolving a definition against a haul is a map lookup rather than a heuristic.

Index

Constants

View Source
const (
	// AnnotationOriginalRef holds a registry/repo:tag for an image and the source URL for a
	// file, as hauler recorded it at `hauler store add` time.
	AnnotationOriginalRef = "hauler.dev/original-ref"
	// AnnotationSubjectDigest is set on an entry that describes another entry -- a signature,
	// an attestation, an SBOM.
	AnnotationSubjectDigest = "hauler.dev/subject-digest"
	// AnnotationKind is hauler's own content classification. It is not a reliable way to tell
	// a file from an image (see classify), but it does reliably mark the attached kinds.
	AnnotationKind = "kind"
)

Hauler's index annotations. OriginalRef is the only one cargoship matches on; the other two are read to exclude entries that are attached to content rather than being content.

View Source
const (
	// MediaTypeFileConfigLocal is what hauler records for a file added from a local path.
	MediaTypeFileConfigLocal = "application/vnd.content.hauler.file.local.config.v1+json"
	// MediaTypeFileConfigDirectory is what hauler records for a file added from a directory.
	MediaTypeFileConfigDirectory = "application/vnd.content.hauler.file.directory.config.v1+json"
	// MediaTypeFileConfigHTTP is what hauler records for a file added from a URL. It is also
	// what cargoship writes when it mirrors a package's files to a registry, so that what the
	// mirror holds is a shape this reader and hauler's own tooling both already understand.
	MediaTypeFileConfigHTTP = "application/vnd.content.hauler.file.http.config.v1+json"
)

The config media types hauler gives a file artifact, one per source it was added from.

Variables

This section is empty.

Functions

This section is empty.

Types

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store is an opened hauler store. Close removes anything Open unpacked, so every Store must be closed.

func Open

func Open(ctx context.Context, path string) (*Store, error)

Open reads the hauler store at path, which may be a store directory or an archive written by `hauler store save`. An archive is unpacked into a temporary directory owned by the returned Store.

func OpenDir added in v0.39.0

func OpenDir(ctx context.Context, dir, source string) (*Store, error)

OpenDir reads an already-unpacked hauler store at dir, naming it in messages and recorded provenance as source. The caller keeps ownership of dir: the returned Store's Close does not remove it.

This is the entry point for a caller that has unpacked a bundle itself in order to work out which format it is -- see openContentStore in pkg/distro.

func (*Store) Close

func (s *Store) Close() error

Close removes anything Open unpacked. A store directory is left untouched.

func (*Store) Describe

func (s *Store) Describe() string

Describe names the store in log lines, satisfying images.ImageSource.

func (*Store) Fetch

func (s *Store) Fetch(ctx context.Context, req contentstore.FileRequest, dst string) (err error)

Fetch writes the file the store recorded as coming from req.Source to dst, creating it.

func (*Store) File

func (s *Store) File(req contentstore.FileRequest) (string, bool, error)

File reports whether the store holds the file it recorded as coming from req.Source -- a URL or an absolute path as it appeared in a distro definition -- and the name hauler recorded it under.

It returns an error, rather than reporting the file as absent, when the store holds the reference for several architectures and the request names none. That is not a miss: the bytes are there, and more than one answer is. Falling back to the declared source would reach the network for content the operator staged, and picking a platform would ship a binary the node cannot run.

func (*Store) HasImage

func (s *Store) HasImage(ref string) bool

HasImage reports whether the store holds the image ref, spelled as a distro definition spells it.

func (*Store) Source

func (s *Store) Source() string

Source is the path the store was opened from, for messages and provenance.

func (*Store) Target

func (s *Store) Target() oras.ReadOnlyTarget

Target presents the store as an oras target that resolves the references a distro definition uses.

The store's own tag index cannot: hauler strips the registry host from org.opencontainers.image.ref.name, so "registry.k8s.io/pause:3.10" is tagged there as "pause:3.10" and would not resolve. This maps the full reference back through hauler.dev/original-ref.

Jump to

Keyboard shortcuts

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