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 TagLister) ([]string, error)
• type BlobStore
• type ManifestStore
• type Reference
  • func ParseReference(artifact 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) ValidateReferenceAsDigest() error
  • func (r Reference) ValidateReferenceAsTag() error
  • func (r Reference) ValidateRegistry() error
  • func (r Reference) ValidateRepository() error
• type ReferenceFetcher
• type ReferencePusher
• type ReferrerLister
• type Registry
• type Repository
• type TagLister

Examples

• Repositories
• Tags

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 repositories in the registry without pagination.

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 TagLister) ([]string, error)

Tags lists the tags available in the repository.

Example

ExampleTags gives example snippets for listing tags in the repository without pagination.

repo, err := remote.NewRepository(fmt.Sprintf("%s/%s", host, exampleRepositoryName))
if err != nil {
	panic(err) // Handle error
}

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

Output:

tag1
tag2

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 ManifestStore

type ManifestStore interface {
	BlobStore
	content.Tagger
	ReferencePusher
}

ManifestStore is a CAS with the ability to stat and delete its content. Besides, ManifestStore provides reference tagging.

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. This field
	// can take any one of the four valid forms (see ParseReference). In the
	// case where it's the empty string, it necessarily implies valid form D,
	// and where it is non-empty, then it is either a tag, or a digest
	// (implying one of valid forms A, B, or C).
	Reference string
}

Reference references either a resource descriptor (where Reference.Reference is a tag or a digest), or a resource repository (where Reference.Reference is the empty string).

func ParseReference

func ParseReference(artifact string) (Reference, error)

ParseReference parses a string (artifact) into an `artifact reference`.

Note: An "image" is an "artifact", however, an "artifact" is not necessarily an "image".

The token `artifact` is composed of other tokens, and those in turn are composed of others. This definition recursivity requires a notation capable of recursion, thus the following two forms have been adopted:

1. Backus–Naur Form (BNF) has been adopted to address the recursive nature of the definition.
2. Token opacity is revealed via its label letter-casing. That is, "opaque" tokens (i.e., tokens that are not final, and must therefore be further broken down into their constituents) are denoted in *lowercase*, while final tokens (i.e., leaf-node tokens that are final) are denoted in *uppercase*.

Finally, note that a number of the opaque tokens are polymorphic in nature; that is, they can take on one of numerous forms, not restricted to a single defining form.

The top-level token, `artifact`, is composed of two (opaque) tokens; namely `socketaddr` and `path`:

<artifact> ::= <socketaddr> "/" <path>

The former is described as follows:

   <socketaddr> ::= <host> | <host> ":" <PORT>
	     <host> ::= <ip> | <FQDN>
	       <ip> ::= <IPV4-ADDR> | <IPV6-ADDR>

The latter, which is of greater interest here, is described as follows:

     <path> ::= <REPOSITORY> | <REPOSITORY> <reference>
<reference> ::= "@" <digest> | ":" <TAG> "@" <DIGEST> | ":" <TAG>
   <digest> ::= <ALGO> ":" <HASH>

This second token--`path`--can take on exactly four forms, each of which will now be illustrated:

<--- path --------------------------------------------> |  - Decode `path`
<=== REPOSITORY ===> <--- reference ------------------> |    - Decode `reference`
<=== REPOSITORY ===> @ <=================== digest ===> |      - Valid Form A
<=== REPOSITORY ===> : <!!! TAG !!!> @ <=== digest ===> |      - Valid Form B (tag is dropped)
<=== REPOSITORY ===> : <=== TAG ======================> |      - Valid Form C
<=== REPOSITORY ======================================> |    - Valid Form D

Note: In the case of Valid Form B, TAG is dropped without any validation or further consideration.

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 the entire reference object; the registry, the repository, and the reference.

func (Reference) ValidateReference

func (r Reference) ValidateReference() error

ValidateReference where the reference is first tried as an ampty string, then as a digest, and if that fails, as a tag.

func (Reference) ValidateReferenceAsDigest

func (r Reference) ValidateReferenceAsDigest() error

ValidateReferenceAsDigest validates the reference as a digest.

func (Reference) ValidateReferenceAsTag

func (r Reference) ValidateReferenceAsTag() error

ValidateReferenceAsTag validates the reference as a tag.

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 ReferrerLister

type ReferrerLister interface {
	Referrers(ctx context.Context, desc ocispec.Descriptor, artifactType string, fn func(referrers []ocispec.Descriptor) error) error
}

ReferrerLister provides the Referrers API. Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers

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 {
	content.Storage
	content.Deleter
	content.TagResolver
	ReferenceFetcher
	ReferencePusher
	ReferrerLister
	TagLister

	// 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() ManifestStore
}

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. Furthermore, this interface also provides the ability to enforce the separation of the blob and the manifests CASs.

type TagLister

type TagLister interface {
	// 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/v1.1.0-rc1/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
}

TagLister lists tags by the tag service.