oras

README

ORAS Go library

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

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

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:

• Copy examples
• Registry interaction examples
• Repository interaction examples
• Authentication examples

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

• oras.land/client_libraries/go: Documentation for the ORAS Go library
• Reviewing guide: All reviewers must read the reviewing guide and agree to follow the project review guidelines.

Code of Conduct

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

Documentation

Index

• Constants
• Variables
• func Copy(ctx context.Context, src Target, srcRef string, dst Target, dstRef string, ...) (ocispec.Descriptor, error)
• func CopyGraph(ctx context.Context, src, dst content.Storage, root ocispec.Descriptor, ...) error
• func ExtendedCopy(ctx context.Context, src GraphTarget, srcRef string, dst Target, dstRef string, ...) (ocispec.Descriptor, error)
• func ExtendedCopyGraph(ctx context.Context, src content.GraphStorage, dst content.Storage, ...) error
• func Pack(ctx context.Context, pusher content.Pusher, layers []ocispec.Descriptor, ...) (ocispec.Descriptor, error)
• func PackArtifact(ctx context.Context, pusher content.Pusher, artifactType string, ...) (ocispec.Descriptor, error)
• func Tag(ctx context.Context, target Target, src, dst string) error
• type CopyGraphOptions
• type CopyOptions
• type ExtendedCopyGraphOptions
• type ExtendedCopyOptions
• type GraphTarget
• type PackArtifactOptions
• type PackOptions
• type Target

Examples

• Copy (LocalToLocal)
• Copy (LocalToOciFile)
• Copy (LocalToRemote)
• Copy (RemoteToLocal)
• Copy (RemoteToRemote)

Constants

const MediaTypeUnknownConfig = "application/vnd.unknown.config.v1+json"

MediaTypeUnknownConfig is the default mediaType used when no config media type is specified.

Variables

var (
	// DefaultCopyOptions provides the default CopyOptions.
	DefaultCopyOptions = CopyOptions{
		CopyGraphOptions: DefaultCopyGraphOptions,
	}
	// DefaultCopyGraphOptions provides the default CopyGraphOptions.
	DefaultCopyGraphOptions = CopyGraphOptions{
		Concurrency: 3,
	}
)

var (
	// DefaultExtendedCopyOptions provides the default ExtendedCopyOptions.
	DefaultExtendedCopyOptions = ExtendedCopyOptions{
		ExtendedCopyGraphOptions: DefaultExtendedCopyGraphOptions,
	}
	// DefaultExtendedCopyGraphOptions provides the default ExtendedCopyGraphOptions.
	DefaultExtendedCopyGraphOptions = ExtendedCopyGraphOptions{
		CopyGraphOptions: DefaultCopyGraphOptions,
	}
)

var (
	// ErrMissingArtifactType is returned by PackArtifact() when no artifact
	// type is specified.
	ErrMissingArtifactType = errors.New("missing artifact type")
	// ErrInvalidDateTimeFormat is returned by PackArtifact() when
	// AnnotationArtifactCreated is provided, but its value is not in RFC 3339
	// format.
	// Reference: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6
	ErrInvalidDateTimeFormat = errors.New("invalid date and time format")
)

Functions

func Copy

func Copy(ctx context.Context, src Target, 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:6f2590d54af17afaca41a6243e3c01b368117d24b32e7581a6dee1d856dd3c4b

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:6f2590d54af17afaca41a6243e3c01b368117d24b32e7581a6dee1d856dd3c4b

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:6f2590d54af17afaca41a6243e3c01b368117d24b32e7581a6dee1d856dd3c4b

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:6f2590d54af17afaca41a6243e3c01b368117d24b32e7581a6dee1d856dd3c4b

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:6f2590d54af17afaca41a6243e3c01b368117d24b32e7581a6dee1d856dd3c4b

func CopyGraph

func CopyGraph(ctx context.Context, src, 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 GraphTarget, 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.GraphStorage, 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 Pack

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

Pack packs the given layers, generates a manifest for the pack, and pushes it to a content storage. If succeeded, returns a descriptor of the manifest.

func PackArtifact

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

PackArtifact packs the given blobs, generates an ORAS Artifact Manifest for the pack, and pushes it to a content storage. If succeeded, returns a descriptor of the manifest. Returns ErrMissingArtifactType if artifactType is empty. Reference: https://github.com/oras-project/artifacts-spec/blob/main/artifact-manifest.md

func Tag

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

Tag tags the descriptor identified by src with dst.

Types

type CopyGraphOptions

type CopyGraphOptions struct {
	// Concurrency limits the maximum number of concurrent copy tasks.
	// If Concurrency is not specified, or the specified value is less
	// or equal to 0, the concurrency limit will be considered as infinity.
	Concurrency 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.

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.Storage, root ocispec.Descriptor) (ocispec.Descriptor, error)
}

CopyOptions contains parameters for oras.Copy.

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 or equal than 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.GraphStorage, desc ocispec.Descriptor) ([]ocispec.Descriptor, error)
}

ExtendedCopyGraphOptions contains parameters for oras.ExtendedCopyGraph.

type ExtendedCopyOptions

type ExtendedCopyOptions struct {
	ExtendedCopyGraphOptions
}

ExtendedCopyOptions contains parameters for oras.ExtendedCopy.

type GraphTarget

type GraphTarget interface {
	content.GraphStorage
	content.TagResolver
}

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

type PackArtifactOptions

type PackArtifactOptions struct {
	// Subject is the subject of the ORAS Artifact Manifest.
	Subject *artifactspec.Descriptor
	// ManifestAnnotations is the annotation map of the manifest.
	ManifestAnnotations map[string]string
}

PackArtifactOptions contains parameters for oras.PackArtifact.

type PackOptions

type PackOptions struct {
	// ConfigDescriptor is a pointer to the descriptor of the config blob.
	ConfigDescriptor *ocispec.Descriptor
	// ConfigMediaType is the media type of the config blob.
	// If not specified, MediaTypeUnknownConfig will be used.
	ConfigMediaType string
	// ConfigAnnotations is the annotation map of the config descriptor.
	ConfigAnnotations map[string]string
	// ManifestAnnotations is the annotation map of the manifest.
	ManifestAnnotations map[string]string
}

PackOptions contains parameters for oras.Pack.

type Target

type Target interface {
	content.Storage
	content.TagResolver
}

Target is a CAS with generic tags.