remote

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: 30 Imported by: 89

Documentation

Overview

Package remote provides a client to the remote registry. Reference: https://github.com/distribution/distribution

Example (HandleWarning) 
repo, err := remote.NewRepository(fmt.Sprintf("%s/%s", host, exampleRepositoryName))
if err != nil {
	panic(err)
}
// 1. specify HandleWarning
repo.HandleWarning = func(warning remote.Warning) {
	fmt.Printf("Warning from %s: %s\n", repo.Reference.Repository, warning.Text)
}

ctx := context.Background()
exampleDigest := "sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7"
// 2. resolve the descriptor
descriptor, err := repo.Resolve(ctx, exampleDigest)
if err != nil {
	panic(err)
}
fmt.Println(descriptor.Digest)
fmt.Println(descriptor.Size)

// 3. fetch the content byte[] from the repository
pulledBlob, err := content.FetchAll(ctx, repo, descriptor)
if err != nil {
	panic(err)
}
fmt.Println(string(pulledBlob))

Output:

Warning from example: This image is deprecated and will be removed soon.
sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7
337
Warning from example: This image is deprecated and will be removed soon.
{"schemaVersion":2,"config":{"mediaType":"application/vnd.oci.image.config.v1+json","digest":"sha256:569224ae188c06e97b9fcadaeb2358fb0fb7c4eb105d49aee2620b2719abea43","size":22},"layers":[{"mediaType":"application/vnd.oci.image.layer.v1.tar","digest":"sha256:ef79e47691ad1bc702d7a256da6323ec369a8fc3159b4f1798a47136f3b38c10","size":21}]}
Example (PullByDigest) 
repo, err := remote.NewRepository(fmt.Sprintf("%s/%s", host, exampleRepositoryName))
if err != nil {
	panic(err)
}
ctx := context.Background()

exampleDigest := "sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7"
// 1. resolve the descriptor
descriptor, err := repo.Resolve(ctx, exampleDigest)
if err != nil {
	panic(err)
}
fmt.Println(descriptor.Digest)
fmt.Println(descriptor.Size)
// 2. fetch the content byte[] from the repository
pulledBlob, err := content.FetchAll(ctx, repo, descriptor)
if err != nil {
	panic(err)
}

fmt.Println(string(pulledBlob))

Output:

sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7
337
{"schemaVersion":2,"config":{"mediaType":"application/vnd.oci.image.config.v1+json","digest":"sha256:569224ae188c06e97b9fcadaeb2358fb0fb7c4eb105d49aee2620b2719abea43","size":22},"layers":[{"mediaType":"application/vnd.oci.image.layer.v1.tar","digest":"sha256:ef79e47691ad1bc702d7a256da6323ec369a8fc3159b4f1798a47136f3b38c10","size":21}]}
Example (PullByTag) 
repo, err := remote.NewRepository(fmt.Sprintf("%s/%s", host, exampleRepositoryName))
if err != nil {
	panic(err)
}
ctx := context.Background()

// 1. resolve the descriptor
tag := "latest"
descriptor, err := repo.Resolve(ctx, tag)
if err != nil {
	panic(err)
}
fmt.Println(descriptor.Digest)
fmt.Println(descriptor.Size)
// 2. fetch the content byte[] from the repository
pulledBlob, err := content.FetchAll(ctx, repo, descriptor)
if err != nil {
	panic(err)
}

fmt.Println(string(pulledBlob))

Output:

sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7
337
{"schemaVersion":2,"config":{"mediaType":"application/vnd.oci.image.config.v1+json","digest":"sha256:569224ae188c06e97b9fcadaeb2358fb0fb7c4eb105d49aee2620b2719abea43","size":22},"layers":[{"mediaType":"application/vnd.oci.image.layer.v1.tar","digest":"sha256:ef79e47691ad1bc702d7a256da6323ec369a8fc3159b4f1798a47136f3b38c10","size":21}]}
Example (PushAndIgnoreReferrersIndexError)

Example_pushAndIgnoreReferrersIndexError gives example snippets on how to ignore referrer index deletion error during push a referrer manifest. 

repo, err := remote.NewRepository(fmt.Sprintf("%s/%s", host, referrersAPIUnavailableRepositoryName))
if err != nil {
	panic(err)
}
ctx := context.Background()

// push a referrer manifest and ignore cleaning up error
err = repo.Push(ctx, referrerDescriptor, bytes.NewReader(referrerManifestContent))
if err != nil {
	var re *remote.ReferrersError
	if !errors.As(err, &re) || !re.IsReferrersIndexDelete() {
		panic(err)
	}
	fmt.Println("ignoring error occurred during cleaning obsolete referrers index")
}
fmt.Println("Push finished")

Output:

ignoring error occurred during cleaning obsolete referrers index
Push finished
Example (PushAndTag)

Example_pushAndTag gives example snippet of pushing an OCI image with a tag. 

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

// Assemble the below OCI image, push and tag it
//   +---------------------------------------------------+
//   |                                +----------------+ |
//   |                             +--> "Hello Config" | |
//   |            +-------------+  |  +---+ Config +---+ |
//   | (latest)+-->     ...     +--+                     |
//   |            ++ Manifest  ++  |  +----------------+ |
//   |                             +--> "Hello Layer"  | |
//   |                                +---+ Layer  +---+ |
//   |                                                   |
//   +--------+ localhost:5000/example/registry +--------+

generateManifest := func(config ocispec.Descriptor, layers ...ocispec.Descriptor) ([]byte, error) {
	content := ocispec.Manifest{
		Config:    config,
		Layers:    layers,
		Versioned: specs.Versioned{SchemaVersion: 2},
	}
	return json.Marshal(content)
}
// 1. assemble descriptors and manifest
layerBlob := []byte("Hello layer")
layerDesc := content.NewDescriptorFromBytes(ocispec.MediaTypeImageLayer, layerBlob)
configBlob := []byte("Hello config")
configDesc := content.NewDescriptorFromBytes(ocispec.MediaTypeImageConfig, configBlob)
manifestBlob, err := generateManifest(configDesc, layerDesc)
if err != nil {
	panic(err)
}
manifestDesc := content.NewDescriptorFromBytes(ocispec.MediaTypeImageManifest, manifestBlob)

// 2. push and tag
err = repo.Push(ctx, layerDesc, bytes.NewReader(layerBlob))
if err != nil {
	panic(err)
}
err = repo.Push(ctx, configDesc, bytes.NewReader(configBlob))
if err != nil {
	panic(err)
}
err = repo.PushReference(ctx, manifestDesc, bytes.NewReader(manifestBlob), "latest")
if err != nil {
	panic(err)
}

fmt.Println("Succeed")

Output:

Succeed
Example (TagReference)

Example_tagReference gives example snippets for tagging a manifest. 

reg, err := remote.NewRegistry(host)
if err != nil {
	panic(err)
}
ctx := context.Background()
repo, err := reg.Repository(ctx, exampleRepositoryName)
if err != nil {
	panic(err)
}

// tag a manifest referenced by the exampleDigest below
exampleDigest := "sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7"
tag := "latest"
desc, err := oras.Tag(ctx, repo, exampleDigest, tag)
if err != nil {
	panic(err)
}
fmt.Println("Tagged", desc.Digest, "as", tag)

Output:

Tagged sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7 as latest

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrReferrersCapabilityAlreadySet is returned by SetReferrersCapability()
	// when the Referrers API capability has been already set.
	ErrReferrersCapabilityAlreadySet = errors.New("referrers capability cannot be changed once set")
)

Functions

This section is empty.

Types

type Client 

type Client interface {
	// Do sends an HTTP request and returns an HTTP response.
	//
	// Unlike http.RoundTripper, Client can attempt to interpret the response
	// and handle higher-level protocol details such as redirects and
	// authentication.
	//
	// Like http.RoundTripper, Client should not modify the request, and must
	// always close the request body.
	Do(*http.Request) (*http.Response, error)
}

Client is an interface for a HTTP client.

type ReferrersError added in v2.1.0 

type ReferrersError struct {
	// Op represents the failing operation.
	Op string
	// Subject is the descriptor of referenced artifact.
	Subject ocispec.Descriptor
	// Err is the entity of referrers error.
	Err error
}

ReferrersError records an error and the operation and the subject descriptor.

func (*ReferrersError) Error added in v2.1.0 

func (e *ReferrersError) Error() string

Error returns error msg of IgnorableError.

func (*ReferrersError) IsReferrersIndexDelete added in v2.1.0 

func (e *ReferrersError) IsReferrersIndexDelete() bool

IsIndexDelete tells if e is kind of error related to referrers index deletion.

func (*ReferrersError) Unwrap added in v2.1.0 

func (e *ReferrersError) Unwrap() error

Unwrap returns the inner error of IgnorableError.

type Registry 

type Registry struct {
	// RepositoryOptions contains common options for Registry and Repository.
	// It is also used as a template for derived repositories.
	RepositoryOptions

	// RepositoryListPageSize specifies the page size when invoking the catalog
	// API.
	// If zero, the page size is determined by the remote registry.
	// Reference: https://docs.docker.com/registry/spec/api/#catalog
	RepositoryListPageSize int
}

Registry is an HTTP client to a remote registry.

func NewRegistry 

func NewRegistry(name string) (*Registry, error)

NewRegistry creates a client to the remote registry with the specified domain name. Example: localhost:5000

func (*Registry) Ping 

func (r *Registry) Ping(ctx context.Context) error

Ping checks whether or not the registry implement Docker Registry API V2 or OCI Distribution Specification. Ping can be used to check authentication when an auth client is configured.

References:

func (*Registry) Repositories 

func (r *Registry) Repositories(ctx context.Context, last string, fn func(repos []string) error) error

Repositories lists the name of repositories available in the registry. See also `RepositoryListPageSize`.

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.

Reference: https://docs.docker.com/registry/spec/api/#catalog

Example

ExampleRegistry_Repositories gives example snippets for listing respositories in a HTTPS registry with pagination. 

reg, err := remote.NewRegistry(host)
if err != nil {
	panic(err)
}
// Override the `host` variable to play with local registry.
// Uncomment below line to reset HTTP option:
// reg.PlainHTTP = true
ctx := context.Background()
err = reg.Repositories(ctx, "", func(repos []string) error {
	for _, repo := range repos {
		fmt.Println(repo)
	}
	return nil
})
if err != nil {
	panic(err)
}

Output:

public/repo1
public/repo2
internal/repo3

func (*Registry) Repository 

func (r *Registry) Repository(ctx context.Context, name string) (registry.Repository, error)

Repository returns a repository reference by the given name.

type Repository 

type Repository struct {
	// Client is the underlying HTTP client used to access the remote registry.
	// If nil, auth.DefaultClient is used.
	Client Client

	// Reference references the remote repository.
	Reference registry.Reference

	// PlainHTTP signals the transport to access the remote repository via HTTP
	// instead of HTTPS.
	PlainHTTP bool

	// ManifestMediaTypes is used in `Accept` header for resolving manifests
	// from references. It is also used in identifying manifests and blobs from
	// descriptors. If an empty list is present, default manifest media types
	// are used.
	ManifestMediaTypes []string

	// TagListPageSize specifies the page size when invoking the tag list API.
	// If zero, the page size is determined by the remote registry.
	// Reference: https://docs.docker.com/registry/spec/api/#tags
	TagListPageSize int

	// ReferrerListPageSize specifies the page size when invoking the Referrers
	// API.
	// If zero, the page size is determined by the remote registry.
	// Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers
	ReferrerListPageSize int

	// MaxMetadataBytes specifies a limit on how many response bytes are allowed
	// in the server's response to the metadata APIs, such as catalog list, tag
	// list, and referrers list.
	// If less than or equal to zero, a default (currently 4MiB) is used.
	MaxMetadataBytes int64

	// SkipReferrersGC specifies whether to delete the dangling referrers
	// index when referrers tag schema is utilized.
	//  - If false, the old referrers index will be deleted after the new one
	//    is successfully uploaded.
	//  - If true, the old referrers index is kept.
	// By default, it is disabled (set to false). See also:
	//  - https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#referrers-tag-schema
	//  - https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#pushing-manifests-with-subject
	//  - https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#deleting-manifests
	SkipReferrersGC bool

	// HandleWarning handles the warning returned by the remote server.
	// Callers SHOULD deduplicate warnings from multiple associated responses.
	//
	// References:
	//   - https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#warnings
	//   - https://www.rfc-editor.org/rfc/rfc7234#section-5.5
	HandleWarning func(warning Warning)
	// contains filtered or unexported fields
}

Repository is an HTTP client to a remote repository.

Example (FetchArtifactBlobs)

ExampleRepository_fetchArtifactBlobs gives an example of pulling the blobs of an artifact manifest. 

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

// 1. Fetch the artifact manifest by digest.
exampleDigest := "sha256:f3550fd0947402d140fd0470702abc92c69f7e9b08d5ca2438f42f8a0ea3fd97"
descriptor, rc, err := repo.FetchReference(ctx, exampleDigest)
if err != nil {
	panic(err)
}
defer rc.Close()

pulledContent, err := content.ReadAll(rc, descriptor)
if err != nil {
	panic(err)
}
fmt.Println(string(pulledContent))

// 2. Parse the pulled manifest and fetch its blobs.
var pulledManifest spec.Artifact
if err := json.Unmarshal(pulledContent, &pulledManifest); err != nil {
	panic(err)
}
for _, blob := range pulledManifest.Blobs {
	content, err := content.FetchAll(ctx, repo, blob)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(content))
}

Output:

{"mediaType":"application/vnd.oci.artifact.manifest.v1+json","artifactType":"example/manifest","blobs":[{"mediaType":"application/tar","digest":"sha256:8d6497c94694a292c04f85cd055d8b5c03eda835dd311e20dfbbf029ff9748cc","size":20}],"subject":{"mediaType":"application/vnd.oci.image.manifest.v1+json","digest":"sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7","size":337}}
example blob content

func NewRepository 

func NewRepository(reference string) (*Repository, error)

NewRepository creates a client to the remote repository identified by a reference. Example: localhost:5000/hello-world

func (*Repository) Blobs 

func (r *Repository) Blobs() registry.BlobStore

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

func (*Repository) Delete 

func (r *Repository) Delete(ctx context.Context, target ocispec.Descriptor) error

Delete removes the content identified by the descriptor.

func (*Repository) Exists 

func (r *Repository) Exists(ctx context.Context, target ocispec.Descriptor) (bool, error)

Exists returns true if the described content exists.

func (*Repository) Fetch 

func (r *Repository) Fetch(ctx context.Context, target ocispec.Descriptor) (io.ReadCloser, error)

Fetch fetches the content identified by the descriptor.

Example (ArtifactReferenceManifest)

ExampleRepository_Fetch_artifactReferenceManifest gives an example of fetching the referrers of a given manifest by using the Referrers API. 

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

// resolve a manifest by tag
tag := "latest"
descriptor, err := repo.Resolve(ctx, tag)
if err != nil {
	panic(err)
}
// find its referrers by calling Referrers
if err := repo.Referrers(ctx, descriptor, "", func(referrers []ocispec.Descriptor) error {
	// for each page of the results, do the following:
	for _, referrer := range referrers {
		// for each item in this page, pull the manifest and verify its content
		rc, err := repo.Fetch(ctx, referrer)
		if err != nil {
			panic(err)
		}
		defer rc.Close() // don't forget to close
		pulledBlob, err := content.ReadAll(rc, referrer)
		if err != nil {
			panic(err)
		}
		fmt.Println(string(pulledBlob))
	}
	return nil
}); err != nil {
	panic(err)
}

Output:

{"mediaType":"application/vnd.oci.artifact.manifest.v1+json","artifactType":"example/SBoM","subject":{"mediaType":"application/vnd.oci.image.manifest.v1+json","digest":"sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7","size":337}}
{"mediaType":"application/vnd.oci.artifact.manifest.v1+json","artifactType":"example/signature","subject":{"mediaType":"application/vnd.oci.image.manifest.v1+json","digest":"sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7","size":337}}
Example (Layer)

ExampleRepository_Fetch_layer gives example snippets for downloading a layer blob by digest. 

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

descriptor, err := repo.Blobs().Resolve(ctx, exampleLayerDigest)
if err != nil {
	panic(err)
}
rc, err := repo.Fetch(ctx, descriptor)
if err != nil {
	panic(err)
}
defer rc.Close() // don't forget to close

// option 1: sequential fetch
pulledBlob, err := content.ReadAll(rc, descriptor)
if err != nil {
	panic(err)
}
fmt.Println(string(pulledBlob))

// option 2: random access, if the remote registry supports
if seeker, ok := rc.(io.ReadSeeker); ok {
	offset := int64(8)
	_, err = seeker.Seek(offset, io.SeekStart)
	if err != nil {
		panic(err)
	}
	pulledBlob, err := io.ReadAll(rc)
	if err != nil {
		panic(err)
	}
	if descriptor.Size-offset != int64(len(pulledBlob)) {
		panic("wrong content")
	}
	fmt.Println(string(pulledBlob))
}

Output:

Example layer content
layer content
Example (ManifestByDigest)

ExampleRepository_Fetch_manifestByDigest gives example snippets for downloading a manifest by digest. 

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

exampleDigest := "sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7"
// resolve the blob descriptor to obtain the size of the blob
descriptor, err := repo.Resolve(ctx, exampleDigest)
if err != nil {
	panic(err)
}
rc, err := repo.Fetch(ctx, descriptor)
if err != nil {
	panic(err)
}
defer rc.Close() // don't forget to close
pulled, err := content.ReadAll(rc, descriptor)
if err != nil {
	panic(err)
}

fmt.Println(string(pulled))

Output:

{"schemaVersion":2,"config":{"mediaType":"application/vnd.oci.image.config.v1+json","digest":"sha256:569224ae188c06e97b9fcadaeb2358fb0fb7c4eb105d49aee2620b2719abea43","size":22},"layers":[{"mediaType":"application/vnd.oci.image.layer.v1.tar","digest":"sha256:ef79e47691ad1bc702d7a256da6323ec369a8fc3159b4f1798a47136f3b38c10","size":21}]}
Example (ManifestByTag)

ExampleRepository_Fetch_byTag gives example snippets for downloading a manifest by tag. 

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

tag := "latest"
descriptor, err := repo.Resolve(ctx, tag)
if err != nil {
	panic(err)
}
rc, err := repo.Fetch(ctx, descriptor)
if err != nil {
	panic(err)
}
defer rc.Close() // don't forget to close
pulledBlob, err := content.ReadAll(rc, descriptor)
if err != nil {
	panic(err)
}

fmt.Println(string(pulledBlob))

Output:

{"schemaVersion":2,"config":{"mediaType":"application/vnd.oci.image.config.v1+json","digest":"sha256:569224ae188c06e97b9fcadaeb2358fb0fb7c4eb105d49aee2620b2719abea43","size":22},"layers":[{"mediaType":"application/vnd.oci.image.layer.v1.tar","digest":"sha256:ef79e47691ad1bc702d7a256da6323ec369a8fc3159b4f1798a47136f3b38c10","size":21}]}

func (*Repository) FetchReference 

func (r *Repository) FetchReference(ctx context.Context, reference string) (ocispec.Descriptor, io.ReadCloser, error)

FetchReference fetches the manifest identified by the reference. The reference can be a tag or digest.

Example (ManifestByDigest)

ExampleRepository_FetchReference_manifestByDigest gives example snippets for downloading a manifest by digest. 

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

exampleDigest := "sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7"
descriptor, rc, err := repo.FetchReference(ctx, exampleDigest)
if err != nil {
	panic(err)
}
defer rc.Close() // don't forget to close
pulled, err := content.ReadAll(rc, descriptor)
if err != nil {
	panic(err)
}

fmt.Println(string(pulled))

Output:

{"schemaVersion":2,"config":{"mediaType":"application/vnd.oci.image.config.v1+json","digest":"sha256:569224ae188c06e97b9fcadaeb2358fb0fb7c4eb105d49aee2620b2719abea43","size":22},"layers":[{"mediaType":"application/vnd.oci.image.layer.v1.tar","digest":"sha256:ef79e47691ad1bc702d7a256da6323ec369a8fc3159b4f1798a47136f3b38c10","size":21}]}
Example (ManifestByTag)

ExampleRepository_FetchReference_manifestByTag gives example snippets for downloading a manifest by tag with only one API call. 

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

tag := "latest"
descriptor, rc, err := repo.FetchReference(ctx, tag)
if err != nil {
	panic(err)
}
defer rc.Close() // don't forget to close
pulledBlob, err := content.ReadAll(rc, descriptor)
if err != nil {
	panic(err)
}

fmt.Println(string(pulledBlob))

Output:

{"schemaVersion":2,"config":{"mediaType":"application/vnd.oci.image.config.v1+json","digest":"sha256:569224ae188c06e97b9fcadaeb2358fb0fb7c4eb105d49aee2620b2719abea43","size":22},"layers":[{"mediaType":"application/vnd.oci.image.layer.v1.tar","digest":"sha256:ef79e47691ad1bc702d7a256da6323ec369a8fc3159b4f1798a47136f3b38c10","size":21}]}

func (*Repository) Manifests 

func (r *Repository) Manifests() registry.ManifestStore

Manifests provides access to the manifest CAS only.

func (*Repository) Mount added in v2.2.0 

func (r *Repository) Mount(ctx context.Context, desc ocispec.Descriptor, fromRepo string, getContent func() (io.ReadCloser, error)) error

Mount makes the blob with the given digest in fromRepo available in the repository signified by the receiver.

This avoids the need to pull content down from fromRepo only to push it to r.

If the registry does not implement mounting, getContent will be used to get the content to push. If getContent is nil, the content will be pulled from the source repository. If getContent returns an error, it will be wrapped inside the error returned from Mount.

func (*Repository) ParseReference 

func (r *Repository) ParseReference(reference string) (registry.Reference, error)

ParseReference resolves a tag or a digest reference to a fully qualified reference from a base reference r.Reference. Tag, digest, or fully qualified references are accepted as input.

If reference is a fully qualified reference, then ParseReference parses it and returns the parsed reference. If the parsed reference does not share the same base reference with the Repository r, ParseReference returns a wrapped error ErrInvalidReference.

func (*Repository) Predecessors 

func (r *Repository) Predecessors(ctx context.Context, desc ocispec.Descriptor) ([]ocispec.Descriptor, error)

Predecessors returns the descriptors of image or artifact manifests directly referencing the given manifest descriptor. Predecessors internally leverages Referrers. Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers

func (*Repository) Push 

func (r *Repository) Push(ctx context.Context, expected ocispec.Descriptor, content io.Reader) error

Push pushes the content, matching the expected descriptor.

Example

ExampleRepository_Push gives example snippets for pushing a layer. 

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

// 1. assemble a descriptor
layer := []byte("Example layer content")
descriptor := content.NewDescriptorFromBytes(ocispec.MediaTypeImageLayer, layer)
// 2. push the descriptor and blob content
err = repo.Push(ctx, descriptor, bytes.NewReader(layer))
if err != nil {
	panic(err)
}

fmt.Println("Push finished")

Output:

Push finished
Example (ArtifactReferenceManifest)

ExampleRepository_Push_artifactReferenceManifest gives an example snippet for pushing a reference manifest. 

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

// 1. assemble the referenced artifact manifest
manifest := ocispec.Manifest{
	Versioned: specs.Versioned{
		SchemaVersion: 2, // historical value. does not pertain to OCI or docker version
	},
	MediaType: ocispec.MediaTypeImageManifest,
	Config:    content.NewDescriptorFromBytes(ocispec.MediaTypeImageConfig, []byte("config bytes")),
}
manifestContent, err := json.Marshal(manifest)
if err != nil {
	panic(err)
}
manifestDescriptor := content.NewDescriptorFromBytes(ocispec.MediaTypeImageManifest, manifestContent)

// 2. push the manifest descriptor and content
err = repo.Push(ctx, manifestDescriptor, bytes.NewReader(manifestContent))
if err != nil {
	panic(err)
}

// 3. assemble the reference artifact manifest
referenceManifest := spec.Artifact{
	MediaType:    spec.MediaTypeArtifactManifest,
	ArtifactType: "sbom/example",
	Subject:      &manifestDescriptor,
}
referenceManifestContent, err := json.Marshal(referenceManifest)
if err != nil {
	panic(err)
}
referenceManifestDescriptor := content.NewDescriptorFromBytes(spec.MediaTypeArtifactManifest, referenceManifestContent)
// 4. push the reference manifest descriptor and content
err = repo.Push(ctx, referenceManifestDescriptor, bytes.NewReader(referenceManifestContent))
if err != nil {
	panic(err)
}

fmt.Println("Push finished")

Output:

Push finished

func (*Repository) PushReference 

func (r *Repository) PushReference(ctx context.Context, expected ocispec.Descriptor, content io.Reader, reference string) error

PushReference pushes the manifest with a reference tag.

func (*Repository) Referrers 

func (r *Repository) Referrers(ctx context.Context, desc ocispec.Descriptor, artifactType string, fn func(referrers []ocispec.Descriptor) error) error

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

fn is called for each page of the referrers result. If artifactType is not empty, only referrers of the same artifact type are fed to fn.

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

func (*Repository) Resolve 

func (r *Repository) Resolve(ctx context.Context, reference string) (ocispec.Descriptor, error)

Resolve resolves a reference to a manifest descriptor. See also `ManifestMediaTypes`.

Example (ByDigest)

ExampleRepository_Resolve_byDigest gives example snippets for resolving a digest to a manifest descriptor. 

repo, err := remote.NewRepository(fmt.Sprintf("%s/%s", host, exampleRepositoryName))
if err != nil {
	panic(err)
}
ctx := context.Background()
exampleDigest := "sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7"
descriptor, err := repo.Resolve(ctx, exampleDigest)
if err != nil {
	panic(err)
}

fmt.Println(descriptor.MediaType)
fmt.Println(descriptor.Digest)
fmt.Println(descriptor.Size)

Output:

application/vnd.oci.image.manifest.v1+json
sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7
337
Example (ByTag)

ExampleRepository_Resolve_byTag gives example snippets for resolving a tag to a manifest descriptor. 

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

tag := "latest"
descriptor, err := repo.Resolve(ctx, tag)
if err != nil {
	panic(err)
}

fmt.Println(descriptor.MediaType)
fmt.Println(descriptor.Digest)
fmt.Println(descriptor.Size)

Output:

application/vnd.oci.image.manifest.v1+json
sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7
337

func (*Repository) SetReferrersCapability 

func (r *Repository) SetReferrersCapability(capable bool) error

SetReferrersCapability indicates the Referrers API capability of the remote repository. true: capable; false: not capable.

SetReferrersCapability is valid only when it is called for the first time. SetReferrersCapability returns ErrReferrersCapabilityAlreadySet if the Referrers API capability has been already set.

func (*Repository) Tag 

func (r *Repository) Tag(ctx context.Context, desc ocispec.Descriptor, reference string) error

Tag tags a manifest descriptor with a reference string.

Example

ExampleRepository_Tag gives example snippets for tagging a descriptor. 

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

exampleDigest := "sha256:b53dc03a49f383ba230d8ac2b78a9c4aec132e4a9f36cc96524df98163202cc7"
descriptor, err := repo.Resolve(ctx, exampleDigest)
if err != nil {
	panic(err)
}
tag := "latest"
err = repo.Tag(ctx, descriptor, tag)
if err != nil {
	panic(err)
}
fmt.Println("Succeed")

Output:

Succeed

func (*Repository) Tags 

func (r *Repository) Tags(ctx context.Context, last string, fn func(tags []string) error) error

Tags lists the tags available in the repository. See also `TagListPageSize`. 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.

References:

Example

ExampleRepository_Tags gives example snippets for listing tags in a repository. 

repo, err := remote.NewRepository(fmt.Sprintf("%s/%s", host, exampleRepositoryName))
if err != nil {
	panic(err)
}
ctx := context.Background()
err = repo.Tags(ctx, "", func(tags []string) error {
	for _, tag := range tags {
		fmt.Println(tag)
	}
	return nil
})

if err != nil {
	panic(err)
}

Output:

tag1
tag2

type RepositoryOptions 

type RepositoryOptions Repository

RepositoryOptions is an alias of Repository to avoid name conflicts. It also hides all methods associated with Repository.

type Warning added in v2.3.0 

type Warning struct {
	// WarningValue is the value of the warning header.
	WarningValue
}

Warning contains the value of the warning header and may contain other information related to the warning.

References:

type WarningValue added in v2.3.0 

type WarningValue struct {
	// Code is the warn-code.
	Code int
	// Agent is the warn-agent.
	Agent string
	// Text is the warn-text.
	Text string
}

WarningValue represents the value of the Warning header.

References:

Source Files

View all Source files

Directories

Path Synopsis
Package auth provides authentication for a client to a remote registry.
 Package auth provides authentication for a client to a remote registry.
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.
internal/config
internal/config/configtest
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.
internal/ioutil
trace
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.