registry

package
v2.5.0 Latest Latest
Warning

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

 Go to latest Published: Mar 21, 2024 License: Apache-2.0 Imports: 13 Imported by: 71

Documentation

Overview

Package registry provides high-level operations to manage registries.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Referrers added in v2.4.0 

func Referrers(ctx context.Context, store content.ReadOnlyGraphStorage, desc ocispec.Descriptor, artifactType string) ([]ocispec.Descriptor, error)

Referrers lists the descriptors of image or artifact manifests directly referencing the given manifest descriptor.

Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers

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 Mounter added in v2.2.0 

type Mounter interface {
	// Mount makes the blob with the given descriptor in fromRepo
	// available in the repository signified by the receiver.
	Mount(ctx context.Context,
		desc ocispec.Descriptor,
		fromRepo string,
		getContent func() (io.ReadCloser, error),
	) error
}

Mounter allows cross-repository blob mounts. For backward compatibility reasons, this is not implemented by BlobStore: use a type assertion to check availability.

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`. Corresponding cryptographic hash implementations are required to be imported as specified by https://pkg.go.dev/github.com/opencontainers/go-digest#readme-usage if the string contains a digest.

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.

Example (Digest)

ExampleParseReference_digest demonstrates parsing a reference string with digest and print its components. 

package main

import (
	"fmt"

	_ "crypto/sha256"
	"oras.land/oras-go/v2/registry"
)

func main() {
	rawRef := "ghcr.io/oras-project/oras-go@sha256:601d05a48832e7946dab8f49b14953549bebf42e42f4d7973b1a5a287d77ab76"
	ref, err := registry.ParseReference(rawRef)
	if err != nil {
		panic(err)
	}

	fmt.Println("Registry:", ref.Registry)
	fmt.Println("Repository:", ref.Repository)

	digest, err := ref.Digest()
	if err != nil {
		panic(err)
	}
	fmt.Println("Digest:", digest)

}

Output:

Registry: ghcr.io
Repository: oras-project/oras-go
Digest: sha256:601d05a48832e7946dab8f49b14953549bebf42e42f4d7973b1a5a287d77ab76

func (Reference) Digest 

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

Digest returns the reference as a digest. Corresponding cryptographic hash implementations are required to be imported as specified by https://pkg.go.dev/github.com/opencontainers/go-digest#readme-usage

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/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/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.

Source Files

View all Source files

Directories

Path Synopsis
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.
Package remote provides a client to the remote registry.
 Package remote provides a client to the remote registry.
auth
Package auth provides authentication for a client to a remote registry.
 Package auth provides authentication for a client to a remote registry.
credentials
Package credentials supports reading, saving, and removing credentials from Docker configuration files and external credential stores that follow the Docker credential helper protocol.
 Package credentials supports reading, saving, and removing credentials from Docker configuration files and external credential stores that follow the Docker credential helper protocol.
credentials/internal/config
credentials/internal/config/configtest
credentials/internal/executer
Package executer is an abstraction for the docker credential helper protocol binaries.
 Package executer is an abstraction for the docker credential helper protocol binaries.
credentials/internal/ioutil
credentials/trace
errcode
internal/errutil
retry

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.