registry

Documentation

Overview

Package registry provides high-level operations to manage registries.

Index

• func Repositories(ctx context.Context, reg Registry) ([]string, error)
• func Tags(ctx context.Context, repo Repository) ([]string, error)
• type BlobStore
• type Reference
  • func ParseReference(raw string) (Reference, error)
  • func (r Reference) Digest() (digest.Digest, error)
  • func (r Reference) Host() string
  • func (r Reference) ReferenceOrDefault() string
  • func (r Reference) String() string
  • func (r Reference) Validate() error
  • func (r Reference) ValidateReference() error
  • func (r Reference) ValidateRegistry() error
  • func (r Reference) ValidateRepository() error
• type ReferenceFetcher
• type ReferencePusher
• type ReferenceTagger
• type Registry
• type Repository

Examples

• Repositories

Functions

func Repositories

func Repositories(ctx context.Context, reg Registry) ([]string, error)

Repositories lists the name of repositories available in the registry.

Example

ExampleRepositories gives example snippets for listing respositories in the registry without pagination.

package main

import (
	"context"
	"fmt"

	"oras.land/oras-go/v2/registry"
	"oras.land/oras-go/v2/registry/remote"
)

var host string

func main() {
	reg, err := remote.NewRegistry(host)
	if err != nil {
		panic(err) // Handle error
	}

	ctx := context.Background()
	repos, err := registry.Repositories(ctx, reg)
	if err != nil {
		panic(err) // Handle error
	}
	for _, repo := range repos {
		fmt.Println(repo)
	}
}

Output:

public/repo1
public/repo2
internal/repo3

func Tags

func Tags(ctx context.Context, repo Repository) ([]string, error)

Tags lists the tags available in the repository.

Types

type BlobStore

type BlobStore interface {
	content.Storage
	content.Deleter
	content.Resolver
	ReferenceFetcher
}

BlobStore is a CAS with the ability to stat and delete its content.

type Reference

type Reference struct {
	// Registry is the name of the registry.
	// It is usually the domain name of the registry optionally with a port.
	Registry string

	// Repository is the name of the repository.
	Repository string

	// Reference is the reference of the object in the repository.
	// A reference can be a tag or a digest.
	Reference string
}

Reference references to a descriptor in the registry.

func ParseReference

func ParseReference(raw string) (Reference, error)

ParseReference parses a string into a artifact reference. If the reference contains both the tag and the digest, the tag will be dropped. Digest is recognized only if the corresponding algorithm is available.

func (Reference) Digest

func (r Reference) Digest() (digest.Digest, error)

Digest returns the reference as a digest.

func (Reference) Host

func (r Reference) Host() string

Host returns the host name of the registry.

func (Reference) ReferenceOrDefault

func (r Reference) ReferenceOrDefault() string

ReferenceOrDefault returns the reference or the default reference if empty.

func (Reference) String

func (r Reference) String() string

String implements `fmt.Stringer` and returns the reference string. The resulted string is meaningful only if the reference is valid.

func (Reference) Validate

func (r Reference) Validate() error

Validate validates the entire reference.

func (Reference) ValidateReference

func (r Reference) ValidateReference() error

ValidateReference validates the reference.

func (Reference) ValidateRegistry

func (r Reference) ValidateRegistry() error

ValidateRegistry validates the registry.

func (Reference) ValidateRepository

func (r Reference) ValidateRepository() error

ValidateRepository validates the repository.

type ReferenceFetcher

type ReferenceFetcher interface {
	// FetchReference fetches the content identified by the reference.
	FetchReference(ctx context.Context, reference string) (ocispec.Descriptor, io.ReadCloser, error)
}

ReferenceFetcher provides advanced fetch with the tag service.

type ReferencePusher

type ReferencePusher interface {
	// PushReference pushes the manifest with a reference tag.
	PushReference(ctx context.Context, expected ocispec.Descriptor, content io.Reader, reference string) error
}

ReferencePusher provides advanced push with the tag service.

type ReferenceTagger

type ReferenceTagger interface {
	// TagReference tags the descriptor identified by src with dst.
	TagReference(ctx context.Context, src, dst string) error
}

ReferenceTagger provides reference tagging.

type Registry

type Registry interface {
	// Repositories lists the name of repositories available in the registry.
	// Since the returned repositories may be paginated by the underlying
	// implementation, a function should be passed in to process the paginated
	// repository list.
	// `last` argument is the `last` parameter when invoking the catalog API.
	// If `last` is NOT empty, the entries in the response start after the
	// repo specified by `last`. Otherwise, the response starts from the top
	// of the Repositories list.
	// Note: When implemented by a remote registry, the catalog API is called.
	// However, not all registries supports pagination or conforms the
	// specification.
	// Reference: https://docs.docker.com/registry/spec/api/#catalog
	// See also `Repositories()` in this package.
	Repositories(ctx context.Context, last string, fn func(repos []string) error) error

	// Repository returns a repository reference by the given name.
	Repository(ctx context.Context, name string) (Repository, error)
}

Registry represents a collection of repositories.

type Repository

type Repository interface {
	BlobStore
	content.TagResolver
	ReferencePusher

	// Blobs provides access to the blob CAS only, which contains config blobs,
	// layers, and other generic blobs.
	Blobs() BlobStore

	// Manifests provides access to the manifest CAS only.
	Manifests() BlobStore

	// Tags lists the tags available in the repository.
	// Since the returned tag list may be paginated by the underlying
	// implementation, a function should be passed in to process the paginated
	// tag list.
	// `last` argument is the `last` parameter when invoking the tags API.
	// If `last` is NOT empty, the entries in the response start after the
	// tag specified by `last`. Otherwise, the response starts from the top
	// of the Tags list.
	// Note: When implemented by a remote registry, the tags API is called.
	// However, not all registries supports pagination or conforms the
	// specification.
	// References:
	// - https://github.com/opencontainers/distribution-spec/blob/main/spec.md#content-discovery
	// - https://docs.docker.com/registry/spec/api/#tags
	// See also `Tags()` in this package.
	Tags(ctx context.Context, last string, fn func(tags []string) error) error
}

Repository is an ORAS target and an union of the blob and the manifest CASs. As specified by https://docs.docker.com/registry/spec/api/, it is natural to assume that content.Resolver interface only works for manifests. Tagging a blob may be resulted in an `ErrUnsupported` error. However, this interface does not restrict tagging blobs. Since a repository is an union of the blob and the manifest CASs, all operations defined in the `BlobStore` are executed depending on the media type of the given descriptor accordingly. Furthurmore, this interface also provides the ability to enforce the separation of the blob and the manifests CASs.