oras

package module
v2.0.0-rc.6 Latest Latest
Warning

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

 Go to latest Published: Dec 12, 2022 License: Apache-2.0 Imports: 24 Imported by: 72

README

ORAS Go library

ORAS

Project status

Versioning

The ORAS Go library follows Semantic Versioning, where breaking changes are reserved for MAJOR releases, and MINOR and PATCH releases must be 100% backwards compatible.

v1: stable

Build Status Go Report Card GoDoc

As there are various stable projects depending on the ORAS Go library, the v1 branch is maintained for API stability, dependency updates, and security patches. All v1.* releases are based upon this branch.

If you are seeking stability over new features, you are highly encouraged to use releases with major version 1.

v2: experimental

Build Status codecov Go Report Card GoDoc

In contrast to the v1 branch, the main branch is where all new feature development will occur. Since ORAS is a primary staging ground for the ORAS Artifacts Specification, changes are expected to occur regularly to meet new requirements. Any backward-incompatible changes will follow our versioning policy and be reserved for the next major version of the library (2), which users may opt into.

Examples for common use cases can be found below:

If you are seeking new features over stability, you should use the main branch (or a specific commit hash) when including the ORAS Go library in your project's go.mod.

To migrate from v1 to v2, see MIGRATION_GUIDE.md.

Docs

Code of Conduct

This project has adopted the CNCF Code of Conduct. See CODE_OF_CONDUCT.md for further details.

Documentation

Overview

Example (CopyArtifactManifestRemoteToLocal)

Example_copyArtifactManifestRemoteToLocal gives an example of copying an artifact manifest from a remote repository to local. 

src, err := remote.NewRepository(fmt.Sprintf("%s/source", remoteHost))
if err != nil {
	panic(err)
}
dst := memory.New()
ctx := context.Background()

exampleDigest := "sha256:70c29a81e235dda5c2cebb8ec06eafd3cca346cbd91f15ac74cefd98681c5b3d"
descriptor, err := src.Resolve(ctx, exampleDigest)
if err != nil {
	panic(err)
}
err = oras.CopyGraph(ctx, src, dst, descriptor, oras.DefaultCopyGraphOptions)
if err != nil {
	panic(err)
}

// verify that the artifact manifest described by the descriptor exists in dst
contentExists, err := dst.Exists(ctx, descriptor)
if err != nil {
	panic(err)
}
fmt.Println(contentExists)

Output:

true
Example (ExtendedCopyArtifactAndReferrersRemoteToLocal)

Example_extendedCopyArtifactAndReferrersRemoteToLocal gives an example of copying an artifact along with its referrers from a remote repository to local. 

src, err := remote.NewRepository(fmt.Sprintf("%s/source", remoteHost))
if err != nil {
	panic(err)
}
dst := memory.New()
ctx := context.Background()

tagName := "latest"
// ExtendedCopy will copy the artifact tagged by "latest" along with all of its
// referrers from src to dst.
desc, err := oras.ExtendedCopy(ctx, src, tagName, dst, tagName, oras.DefaultExtendedCopyOptions)
if err != nil {
	panic(err)
}

fmt.Println(desc.Digest)

Output:

sha256:f396bc4d300934a39ca28ab0d5ac8a3573336d7d63c654d783a68cd1e2057662

Index

Examples

Constants

View Source 
const (
	// MediaTypeUnknownConfig is the default mediaType used when no
	// config media type is specified.
	MediaTypeUnknownConfig = "application/vnd.unknown.config.v1+json"
	// MediaTypeUnknownArtifact is the default artifactType used when no
	// artifact type is specified.
	MediaTypeUnknownArtifact = "application/vnd.unknown.artifact.v1"
)

Variables

View Source 
var ErrInvalidDateTimeFormat = errors.New("invalid date and time format")

ErrInvalidDateTimeFormat is returned by Pack() when AnnotationArtifactCreated or AnnotationCreated is provided, but its value is not in RFC 3339 format. Reference: https://www.rfc-editor.org/rfc/rfc3339#section-5.6

Functions

func Copy 

func Copy(ctx context.Context, src ReadOnlyTarget, srcRef string, dst Target, dstRef string, opts CopyOptions) (ocispec.Descriptor, error)

Copy copies a rooted directed acyclic graph (DAG) with the tagged root node in the source Target to the destination Target. The destination reference will be the same as the source reference if the destination reference is left blank. Returns the descriptor of the root node on successful copy.

Example (LocalToLocal) 
src := exampleMemoryStore
dst := memory.New()

tagName := "latest"
ctx := context.Background()
desc, err := oras.Copy(ctx, src, tagName, dst, tagName, oras.DefaultCopyOptions)
if err != nil {
	panic(err) // Handle error
}
fmt.Println(desc.Digest)

Output:

sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
Example (LocalToOciFile) 
src := exampleMemoryStore
tempDir, err := os.MkdirTemp("", "oras_oci_example_*")
if err != nil {
	panic(err) // Handle error
}
defer os.RemoveAll(tempDir)
dst, err := oci.New(tempDir)
if err != nil {
	panic(err) // Handle error
}

tagName := "latest"
ctx := context.Background()
desc, err := oras.Copy(ctx, src, tagName, dst, tagName, oras.DefaultCopyOptions)
if err != nil {
	panic(err) // Handle error
}
fmt.Println(desc.Digest)

Output:

sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
Example (LocalToRemote) 
src := exampleMemoryStore
reg, err := remote.NewRegistry(remoteHost)
if err != nil {
	panic(err) // Handle error
}
ctx := context.Background()
dst, err := reg.Repository(ctx, "target")
if err != nil {
	panic(err) // Handle error
}

tagName := "latest"
desc, err := oras.Copy(ctx, src, tagName, dst, tagName, oras.DefaultCopyOptions)
if err != nil {
	panic(err) // Handle error
}
fmt.Println(desc.Digest)

Output:

sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
Example (RemoteToLocal) 
reg, err := remote.NewRegistry(remoteHost)
if err != nil {
	panic(err) // Handle error
}

ctx := context.Background()
src, err := reg.Repository(ctx, "source")
if err != nil {
	panic(err) // Handle error
}
dst := memory.New()

tagName := "latest"
desc, err := oras.Copy(ctx, src, tagName, dst, tagName, oras.DefaultCopyOptions)
if err != nil {
	panic(err) // Handle error
}
fmt.Println(desc.Digest)

Output:

sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
Example (RemoteToRemote) 
reg, err := remote.NewRegistry(remoteHost)
if err != nil {
	panic(err) // Handle error
}
ctx := context.Background()
src, err := reg.Repository(ctx, "source")
if err != nil {
	panic(err) // Handle error
}
dst, err := reg.Repository(ctx, "target")
if err != nil {
	panic(err) // Handle error
}

tagName := "latest"
desc, err := oras.Copy(ctx, src, tagName, dst, tagName, oras.DefaultCopyOptions)
if err != nil {
	panic(err) // Handle error
}
fmt.Println(desc.Digest)

Output:

sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1

func CopyGraph 

func CopyGraph(ctx context.Context, src content.ReadOnlyStorage, dst content.Storage, root ocispec.Descriptor, opts CopyGraphOptions) error

CopyGraph copies a rooted directed acyclic graph (DAG) from the source CAS to the destination CAS.

func ExtendedCopy 

func ExtendedCopy(ctx context.Context, src ReadOnlyGraphTarget, srcRef string, dst Target, dstRef string, opts ExtendedCopyOptions) (ocispec.Descriptor, error)

ExtendedCopy copies the directed acyclic graph (DAG) that are reachable from the given tagged node from the source GraphTarget to the destination Target. The destination reference will be the same as the source reference if the destination reference is left blank. Returns the descriptor of the tagged node on successful copy.

func ExtendedCopyGraph 

func ExtendedCopyGraph(ctx context.Context, src content.ReadOnlyGraphStorage, dst content.Storage, node ocispec.Descriptor, opts ExtendedCopyGraphOptions) error

ExtendedCopyGraph copies the directed acyclic graph (DAG) that are reachable from the given node from the source GraphStorage to the destination Storage.

func Fetch 

func Fetch(ctx context.Context, target ReadOnlyTarget, reference string, opts FetchOptions) (ocispec.Descriptor, io.ReadCloser, error)

Fetch fetches the content identified by the reference.

func FetchBytes 

func FetchBytes(ctx context.Context, target ReadOnlyTarget, reference string, opts FetchBytesOptions) (ocispec.Descriptor, []byte, error)

FetchBytes fetches the content bytes identified by the reference.

func Pack 

func Pack(ctx context.Context, pusher content.Pusher, artifactType string, blobs []ocispec.Descriptor, opts PackOptions) (ocispec.Descriptor, error)

Pack packs the given blobs, generates a manifest for the pack, and pushes it to a content storage. When opts.PackImageManifest is true, artifactType will be used as the the config descriptor mediaType of the image manifest. If succeeded, returns a descriptor of the manifest.

func PushBytes 

func PushBytes(ctx context.Context, pusher content.Pusher, mediaType string, contentBytes []byte) (ocispec.Descriptor, error)

PushBytes describes the contentBytes using the given mediaType and pushes it. If mediaType is not specified, "application/octet-stream" is used.

func Resolve 

func Resolve(ctx context.Context, target ReadOnlyTarget, reference string, opts ResolveOptions) (ocispec.Descriptor, error)

Resolve resolves a descriptor with provided reference from the target.

func Tag 

func Tag(ctx context.Context, target Target, src, dst string) error

Tag tags the descriptor identified by src with dst.

func TagBytes 

func TagBytes(ctx context.Context, target Target, mediaType string, contentBytes []byte, reference string) (ocispec.Descriptor, error)

TagBytes describes the contentBytes using the given mediaType, pushes it, and tag it with the given reference. If mediaType is not specified, "application/octet-stream" is used.

func TagBytesN 

func TagBytesN(ctx context.Context, target Target, mediaType string, contentBytes []byte, references []string, opts TagBytesNOptions) (ocispec.Descriptor, error)

TagBytesN describes the contentBytes using the given mediaType, pushes it, and tag it with the given references. If mediaType is not specified, "application/octet-stream" is used.

func TagN 

func TagN(ctx context.Context, target Target, srcReference string, dstReferences []string, opts TagNOptions) error

TagN tags the descriptor identified by srcReference with dstReferences.

Types

type CopyGraphOptions 

type CopyGraphOptions struct {
	// Concurrency limits the maximum number of concurrent copy tasks.
	// If less than or equal to 0, a default (currently 3) is used.
	Concurrency int
	// MaxMetadataBytes limits the maximum size of the metadata that can be
	// cached in the memory.
	// If less than or equal to 0, a default (currently 4 MiB) is used.
	MaxMetadataBytes int64
	// PreCopy handles the current descriptor before copying it.
	PreCopy func(ctx context.Context, desc ocispec.Descriptor) error
	// PostCopy handles the current descriptor after copying it.
	PostCopy func(ctx context.Context, desc ocispec.Descriptor) error
	// OnCopySkipped will be called when the sub-DAG rooted by the current node
	// is skipped.
	OnCopySkipped func(ctx context.Context, desc ocispec.Descriptor) error
	// FindSuccessors finds the successors of the current node.
	// fetcher provides cached access to the source storage, and is suitable
	// for fetching non-leaf nodes like manifests. Since anything fetched from
	// fetcher will be cached in the memory, it is recommended to use original
	// source storage to fetch large blobs.
	// If FindSuccessors is nil, content.Successors will be used.
	FindSuccessors func(ctx context.Context, fetcher content.Fetcher, desc ocispec.Descriptor) ([]ocispec.Descriptor, error)
}

CopyGraphOptions contains parameters for oras.CopyGraph. 

var DefaultCopyGraphOptions CopyGraphOptions

DefaultCopyGraphOptions provides the default CopyGraphOptions.

type CopyOptions 

type CopyOptions struct {
	CopyGraphOptions
	// MapRoot maps the resolved root node to a desired root node for copy.
	// When MapRoot is provided, the descriptor resolved from the source
	// reference will be passed to MapRoot, and the mapped descriptor will be
	// used as the root node for copy.
	MapRoot func(ctx context.Context, src content.ReadOnlyStorage, root ocispec.Descriptor) (ocispec.Descriptor, error)
}

CopyOptions contains parameters for oras.Copy. 

var DefaultCopyOptions CopyOptions = CopyOptions{
	CopyGraphOptions: DefaultCopyGraphOptions,
}

DefaultCopyOptions provides the default CopyOptions.

func (*CopyOptions) WithTargetPlatform 

func (opts *CopyOptions) WithTargetPlatform(p *ocispec.Platform)

WithTargetPlatform configures opts.MapRoot to select the manifest whose platform matches the given platform. When MapRoot is provided, the platform selection will be applied on the mapped root node. - If the given platform is nil, no platform selection will be applied. - If the root node is a manifest, it will remain the same if platform matches, otherwise ErrNotFound will be returned. - If the root node is a manifest list, it will be mapped to the first matching manifest if exists, otherwise ErrNotFound will be returned. - Otherwise ErrUnsupported will be returned.

type ExtendedCopyGraphOptions 

type ExtendedCopyGraphOptions struct {
	CopyGraphOptions
	// Depth limits the maximum depth of the directed acyclic graph (DAG) that
	// will be extended-copied.
	// If Depth is no specified, or the specified value is less than or
	// equal to 0, the depth limit will be considered as infinity.
	Depth int
	// FindPredecessors finds the predecessors of the current node.
	// If FindPredecessors is nil, src.Predecessors will be adapted and used.
	FindPredecessors func(ctx context.Context, src content.ReadOnlyGraphStorage, desc ocispec.Descriptor) ([]ocispec.Descriptor, error)
}

ExtendedCopyGraphOptions contains parameters for oras.ExtendedCopyGraph. 

var DefaultExtendedCopyGraphOptions ExtendedCopyGraphOptions = ExtendedCopyGraphOptions{
	CopyGraphOptions: DefaultCopyGraphOptions,
}

DefaultExtendedCopyGraphOptions provides the default ExtendedCopyGraphOptions.

func (*ExtendedCopyGraphOptions) FilterAnnotation 

func (opts *ExtendedCopyGraphOptions) FilterAnnotation(key string, regex *regexp.Regexp)

FilterAnnotation configures opts.FindPredecessors to filter the predecessors whose annotation matches a given regex pattern. A predecessor is kept if key is in its annotations and the annotation value matches regex. If regex is nil, predecessors whose annotations contain key will be kept, no matter of the annotation value. For performance consideration, when using both FilterArtifactType and FilterAnnotation, it's recommended to call FilterArtifactType first.

func (*ExtendedCopyGraphOptions) FilterArtifactType 

func (opts *ExtendedCopyGraphOptions) FilterArtifactType(regex *regexp.Regexp)

FilterArtifactType configures opts.FindPredecessors to filter the predecessors whose artifact type matches a given regex pattern. A predecessor is kept if its artifact type matches regex. If regex is nil, all predecessors will be kept. For performance consideration, when using both FilterArtifactType and FilterAnnotation, it's recommended to call FilterArtifactType first.

type ExtendedCopyOptions 

type ExtendedCopyOptions struct {
	ExtendedCopyGraphOptions
}

ExtendedCopyOptions contains parameters for oras.ExtendedCopy. 

var DefaultExtendedCopyOptions ExtendedCopyOptions = ExtendedCopyOptions{
	ExtendedCopyGraphOptions: DefaultExtendedCopyGraphOptions,
}

DefaultExtendedCopyOptions provides the default ExtendedCopyOptions.

type FetchBytesOptions 

type FetchBytesOptions struct {
	// FetchOptions contains parameters for fetching content.
	FetchOptions
	// MaxBytes limits the maximum size of the fetched content bytes.
	// If less than or equal to 0, a default (currently 4 MiB) is used.
	MaxBytes int64
}

FetchBytesOptions contains parameters for oras.FetchBytes. 

var DefaultFetchBytesOptions FetchBytesOptions

DefaultFetchBytesOptions provides the default FetchBytesOptions.

type FetchOptions 

type FetchOptions struct {
	// ResolveOptions contains parameters for resolving reference.
	ResolveOptions
}

FetchOptions contains parameters for oras.Fetch. 

var DefaultFetchOptions FetchOptions

DefaultFetchOptions provides the default FetchOptions.

type GraphTarget 

type GraphTarget interface {
	content.GraphStorage
	content.TagResolver
}

GraphTarget is a CAS with generic tags that supports direct predecessor node finding.

type PackOptions 

type PackOptions struct {
	// Subject is the subject of the manifest.
	Subject *ocispec.Descriptor
	// ManifestAnnotations is the annotation map of the manifest.
	ManifestAnnotations map[string]string

	// PackImageManifest controls whether to pack an image manifest or not.
	//   - If true, pack an image manifest; artifactType will be used as the
	// the config descriptor mediaType of the image manifest.
	//   - If false, pack an artifact manifest.
	// Default: false.
	PackImageManifest bool
	// ConfigDescriptor is a pointer to the descriptor of the config blob.
	// If not nil, artifactType will be implied by the mediaType of the
	// specified ConfigDescriptor, and ConfigAnnotations will be ignored.
	// This option is valid only when PackImageManifest is true.
	ConfigDescriptor *ocispec.Descriptor
	// ConfigAnnotations is the annotation map of the config descriptor.
	// This option is valid only when PackImageManifest is true
	// and ConfigDescriptor is nil.
	ConfigAnnotations map[string]string
}

PackOptions contains parameters for oras.Pack.

type ReadOnlyGraphTarget 

type ReadOnlyGraphTarget interface {
	content.ReadOnlyGraphStorage
	content.Resolver
}

ReadOnlyGraphTarget represents a read-only GraphTarget.

type ReadOnlyTarget 

type ReadOnlyTarget interface {
	content.ReadOnlyStorage
	content.Resolver
}

ReadOnlyTarget represents a read-only Target.

type ResolveOptions 

type ResolveOptions struct {
	// TargetPlatform ensures the resolved content matches the target platform
	// if the node is a manifest, or selects the first resolved content that
	// matches the target platform if the node is a manifest list.
	TargetPlatform *ocispec.Platform

	// MaxMetadataBytes limits the maximum size of metadata that can be cached
	// in the memory.
	// If less than or equal to 0, a default (currently 4 MiB) is used.
	MaxMetadataBytes int64
}

ResolveOptions contains parameters for oras.Resolve. 

var DefaultResolveOptions ResolveOptions

DefaultResolveOptions provides the default ResolveOptions.

type TagBytesNOptions 

type TagBytesNOptions struct {
	// Concurrency limits the maximum number of concurrent tag tasks.
	// If less than or equal to 0, a default (currently 5) is used.
	Concurrency int
}

TagBytesNOptions contains parameters for oras.TagBytesN. 

var DefaultTagBytesNOptions TagBytesNOptions

DefaultTagBytesNOptions provides the default TagBytesNOptions.

type TagNOptions 

type TagNOptions struct {
	// Concurrency limits the maximum number of concurrent tag tasks.
	// If less than or equal to 0, a default (currently 5) is used.
	Concurrency int

	// MaxMetadataBytes limits the maximum size of metadata that can be cached
	// in the memory.
	// If less than or equal to 0, a default (currently 4 MiB) is used.
	MaxMetadataBytes int64
}

TagNOptions contains parameters for oras.TagN. 

var DefaultTagNOptions TagNOptions

DefaultTagNOptions provides the default TagNOptions.

type Target 

type Target interface {
	content.Storage
	content.TagResolver
}

Target is a CAS with generic tags.

Source Files

View all Source files

Directories

Path Synopsis
Package content provides implementations to access content stores.
 Package content provides implementations to access content stores.
file
Package file provides implementation of a content store based on file system.
 Package file provides implementation of a content store based on file system.
memory
Package memory provides implementation of a memory backed content store.
 Package memory provides implementation of a memory backed content store.
oci
Package oci provides access to an OCI content store.
 Package oci provides access to an OCI content store.
internal
cas
copyutil
descriptor
docker
fs/tarfs
graph
httputil
interfaces
ioutil
platform
registryutil
resolver
slices
status
syncutil
Package registry provides high-level operations to manage registries.
 Package registry provides high-level operations to manage registries.
internal/doc
Package doc provides the constant can be used in example test files.
 Package doc provides the constant can be used in example test files.
remote
Package remote provides a client to the remote registry.
 Package remote provides a client to the remote registry.
remote/auth
Package auth provides authentication for a client to a remote registry.
 Package auth provides authentication for a client to a remote registry.
remote/errcode
remote/internal/errutil

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.