remote

package

v2.0.0-...-c472316 Latest Latest Go to latest Published: Apr 12, 2024 License: Apache-2.0 Imports: 30 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/dtroyer-salad/og2

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 ¶

Variables
type BlobStoreHead
type Client
type FetcherHead
type ReferrersError
type Registry
- func NewRegistry(name string) (*Registry, error)
type Repository
- func NewRepository(reference string) (*Repository, error)
type RepositoryOptions
type Warning
type WarningValue

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 BlobStoreHead ¶

type BlobStoreHead interface {
	registry.BlobStore
	FetcherHead
}

BlobStoreHead is a BlobStore with the ability to retrieve content headers.

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 ¶

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 ¶

func (e *ReferrersError) Error() string

Error returns error msg of IgnorableError.

func (*ReferrersError) IsReferrersIndexDelete ¶

func (e *ReferrersError) IsReferrersIndexDelete() bool

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

func (*ReferrersError) Unwrap ¶

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) FetchHead ¶

func (r *Repository) FetchHead(ctx context.Context, target ocispec.Descriptor) (*http.Header, error)

FetchHead fetches the content headers identified by the descriptor.

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 ¶

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.

When the capability is set to true, the Referrers() function will always request the Referrers API. Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers
When the capability is set to false, the Referrers() function will always request the Referrers Tag. Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#referrers-tag-schema
When the capability is not set, the Referrers() function will automatically determine which API to use.

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 ¶

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 ¶

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
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.
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
errcode
internal
errutil
retry

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Documentation ¶

Overview ¶

Index ¶

Examples ¶

Constants ¶

Variables ¶

Functions ¶

Types ¶

type BlobStoreHead ¶

type Client ¶

type FetcherHead ¶

type ReferrersError ¶

func (*ReferrersError) Error ¶

func (*ReferrersError) IsReferrersIndexDelete ¶

func (*ReferrersError) Unwrap ¶

type Registry ¶

func NewRegistry ¶

func (*Registry) Ping ¶

func (*Registry) Repositories ¶

func (*Registry) Repository ¶

type Repository ¶

func NewRepository ¶

func (*Repository) Blobs ¶

func (*Repository) Delete ¶

func (*Repository) Exists ¶

func (*Repository) Fetch ¶

func (*Repository) FetchHead ¶

func (*Repository) FetchReference ¶

func (*Repository) Manifests ¶

func (*Repository) Mount ¶

func (*Repository) ParseReference ¶

func (*Repository) Predecessors ¶

func (*Repository) Push ¶

func (*Repository) PushReference ¶

func (*Repository) Referrers ¶

func (*Repository) Resolve ¶

func (*Repository) SetReferrersCapability ¶

func (*Repository) Tag ¶

func (*Repository) Tags ¶

type RepositoryOptions ¶

type Warning ¶

type WarningValue ¶

Source Files ¶

Directories ¶