oci

package
v1.0.0-rc1 Latest Latest
Warning

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

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

Documentation

Overview

Package oci provides Zarf's ORAS registry client and OCI descriptor helpers.

Use NewOrasRemote to configure registry access. WithRetryPolicy enables resumable blob reads.

Index

Examples

Constants

View Source
const (
	// MultiOS is the OS used for multi-platform packages
	MultiOS = "multi"
)

Variables

This section is empty.

Functions

func FetchJSONFile

func FetchJSONFile[T any](ctx context.Context, fetcher content.Fetcher, manifest *Manifest, path string) (result T, err error)

FetchJSONFile fetches and unmarshals the JSON file at path, located via the manifest.

func FetchUnmarshal

func FetchUnmarshal[T any](ctx context.Context, fetcher content.Fetcher, unmarshaler func(data []byte, v any) error, descriptor ocispec.Descriptor) (result T, err error)

FetchUnmarshal fetches (and digest-verifies, via content.FetchAll) the descriptor and unmarshals it.

func IsEmptyDescriptor

func IsEmptyDescriptor(descriptor ocispec.Descriptor) bool

IsEmptyDescriptor returns true if the given descriptor is empty.

func PlatformForArch

func PlatformForArch(arch string) ocispec.Platform

PlatformForArch sets the target architecture for the remote

func RemoveDuplicateDescriptors

func RemoveDuplicateDescriptors(descriptors []ocispec.Descriptor) []ocispec.Descriptor

RemoveDuplicateDescriptors removes duplicate descriptors from the given list.

func SumDescsSize

func SumDescsSize(descriptors []ocispec.Descriptor) int64

SumDescsSize returns the size of all the descriptors added together

func UpdateIndexWithDescriptor

func UpdateIndexWithDescriptor(ctx context.Context, repo *registryremote.Repository, tag string, platform ocispec.Platform, manifest ocispec.Descriptor) (ocispec.Descriptor, error)

UpdateIndexWithDescriptor updates the index referenced by tag for platform and pushes the resulting immutable descriptor without changing the tag.

Types

type Manifest

type Manifest struct{ v1.Manifest }

Manifest wraps an OCI image manifest.

func (*Manifest) Locate

func (manifest *Manifest) Locate(pathOrDigest string) v1.Descriptor

Locate returns the layer whose title annotation or digest matches pathOrDigest.

func (*Manifest) MarshalJSON

func (manifest *Manifest) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

type Modifier

type Modifier func(*OrasRemote)

Modifier is a function that modifies an OrasRemote

func WithCache

func WithCache(cache content.Storage) Modifier

WithCache sets the cache for the remote

func WithCredentialFunc added in v0.89.0

func WithCredentialFunc(fn auth.CredentialFunc) Modifier

WithCredentialFunc sets fn as the source of registry credentials. If fn is nil, the Docker credential store is used instead.

func WithInsecureSkipVerify

func WithInsecureSkipVerify(insecure bool) Modifier

WithInsecureSkipVerify sets the insecure TLS flag for the remote. An explicit value takes precedence over WithTransport regardless of modifier order.

func WithLogger

func WithLogger(logger *slog.Logger) Modifier

WithLogger sets the logger for the remote

func WithPlainHTTP

func WithPlainHTTP(plainHTTP bool) Modifier

WithPlainHTTP sets the plain HTTP flag for the remote

func WithRetryPolicy added in v1.0.0

func WithRetryPolicy(policy retry.Policy) Modifier

WithRetryPolicy configures HTTP retries and resumable blob reads. Nil keeps default HTTP retries and disables read recovery.

On policy-approved read failures, the returned reader automatically continues after the bytes already returned to the caller. If recovery fails or retries are exhausted, Read returns an error.

Read recovery requires range-capable blobs and lasts only for one reader. Manifest bodies, destination uploads, and later processes are not resumed.

The policy may be called concurrently. For read failures, the response is nil.

Example
package main

import (
	"errors"
	"io"
	"net/http"
	"time"

	"github.com/zarf-dev/zarf/src/pkg/oci"
	"oras.land/oras-go/v2/registry/remote/retry"
)

func main() {
	policy := &retry.GenericPolicy{
		MaxRetry: 8,
		MinWait:  250 * time.Millisecond,
		MaxWait:  3 * time.Second,
		Backoff:  retry.DefaultBackoff,
		Retryable: func(response *http.Response, err error) (bool, error) {
			// Retry truncated responses, which ORAS's default predicate does not retry.
			if errors.Is(err, io.ErrUnexpectedEOF) {
				return true, nil
			}
			return retry.DefaultPredicate(response, err)
		},
	}
	_, err := oci.NewOrasRemote("registry.example.com/packages/demo", oci.PlatformForArch("amd64"),
		oci.WithRetryPolicy(policy))
	if err != nil {
		panic(err)
	}
}

func WithTransport

func WithTransport(transport *http.Transport) Modifier

WithTransport sets the HTTP transport for the remote.

func WithUserAgent

func WithUserAgent(userAgent string) Modifier

WithUserAgent sets the user agent for the remote

type OrasRemote

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

OrasRemote is a wrapper around the Oras remote repository.

func NewOrasRemote

func NewOrasRemote(url string, platform ocispec.Platform, modifiers ...Modifier) (*OrasRemote, error)

NewOrasRemote returns an oras remote repository client and context for the given url.

Registry credentials come from the Docker credential store by default. Use WithCredentialFunc to provide a different credential source.

func (*OrasRemote) CopyToTarget

func (o *OrasRemote) CopyToTarget(ctx context.Context, layers []ocispec.Descriptor, target oras.Target, copyOpts oras.CopyOptions) error

CopyToTarget copies the given layers from the remote repository to the given target

func (*OrasRemote) Fetch

func (o *OrasRemote) Fetch(ctx context.Context, desc ocispec.Descriptor) (io.ReadCloser, error)

Fetch fetches the content for the given descriptor, honoring the layer cache when configured. This satisfies oras content.Fetcher, so an OrasRemote can be passed directly to oras helpers such as content.FetchAll and FetchJSONFile.

func (*OrasRemote) FetchLayer

func (o *OrasRemote) FetchLayer(ctx context.Context, desc ocispec.Descriptor) (bytes []byte, err error)

FetchLayer fetches (and digest-verifies) the layer with the given descriptor.

func (*OrasRemote) FetchLayerReader

func (o *OrasRemote) FetchLayerReader(ctx context.Context, desc ocispec.Descriptor) (*content.VerifyReader, error)

FetchLayerReader fetches the layer with the given descriptor from the remote repository.

func (*OrasRemote) FetchManifest

func (o *OrasRemote) FetchManifest(ctx context.Context, desc ocispec.Descriptor) (manifest *Manifest, err error)

FetchManifest fetches the manifest with the given descriptor from the remote repository.

func (*OrasRemote) FetchRoot

func (o *OrasRemote) FetchRoot(ctx context.Context) (*Manifest, error)

FetchRoot fetches the root manifest from the remote repository.

func (*OrasRemote) GetDefaultCopyOpts

func (o *OrasRemote) GetDefaultCopyOpts() oras.CopyOptions

GetDefaultCopyOpts returns the default copy options

func (*OrasRemote) Log

func (o *OrasRemote) Log() *slog.Logger

Log gives you access to the OrasRemote logger

func (*OrasRemote) Repo

func (o *OrasRemote) Repo() *remote.Repository

Repo gives you access to the underlying remote repository

func (*OrasRemote) ResolveRoot

func (o *OrasRemote) ResolveRoot(ctx context.Context) (ocispec.Descriptor, error)

ResolveRoot returns the root descriptor for the remote repository

func (*OrasRemote) UpdateIndex

func (o *OrasRemote) UpdateIndex(ctx context.Context, tag string, publishedDesc ocispec.Descriptor) error

UpdateIndex updates the index for the given package.

Directories

Path Synopsis
Package cache creates cache-backed ORAS read targets.
Package cache creates cache-backed ORAS read targets.

Jump to

Keyboard shortcuts

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