registry

Documentation

Index

• Constants
• Variables
• func Client(host string, opts *ociclient.Options) (ociregistry.Interface, error)
• func CopyBlob(ctx context.Context, srcRef, dstRef Reference) (ociregistry.Descriptor, error)
• func CopyManifest(ctx context.Context, srcRef, dstRef Reference, ...) (ociregistry.Descriptor, error)
• func EnsureBlob(ctx context.Context, ref Reference, size int64, content io.Reader) (ociregistry.Descriptor, error)
• func EnsureManifest(ctx context.Context, ref Reference, manifest json.RawMessage, mediaType string, ...) (ociregistry.Descriptor, error)
• func Lookup(ctx context.Context, ref Reference, opts *LookupOptions) (ociregistry.BlobReader, error)
• func RegistryCache(r ociregistry.Interface) ociregistry.Interface
• func SynthesizeIndex(ctx context.Context, ref Reference) (*ocispec.Index, error)
• type LookupOptions
• type LookupType
• type ManifestChildren
  • func ParseManifestChildren(manifest []byte) (ManifestChildren, error)
• type Reference
  • func ParseRef(img string) (Reference, error)
  • func (ref Reference) MarshalText() ([]byte, error)
  • func (ref *Reference) Normalize()
  • func (ref Reference) String() string
  • func (ref Reference) StringWithKnownDigest(commonDigest ociregistry.Digest) string
  • func (ref *Reference) UnmarshalText(text []byte) error

Constants

const (
	AnnotationBashbrewArch = "com.docker.official-images.bashbrew.arch"
)

Variables

var (
	// if a blob is more than this many bytes, we'll do a pre-flight HEAD request to verify whether we need to even bother pushing it before we do so (65535 is the theoretical maximum size of a single TCP packet, although MTU means it's usually closer to 1448 bytes, but this seemed like a sane place to draw a line to where a second request that might fail is worth our time)
	BlobSizeWorthHEAD = int64(65535)
)

Functions

func Client

func Client(host string, opts *ociclient.Options) (ociregistry.Interface, error)

returns an ociregistry.Interface that automatically implements an in-memory cache (see RegistryCache) *and* transparent rate limiting + retry (see [registryRateLimiters]/[rateLimitedRetryingDoer]) / `DOCKERHUB_PUBLIC_PROXY` support for Docker Hub (cached such that multiple calls for the same registry transparently return the same client object / in-memory registry cache)

func CopyBlob

func CopyBlob(ctx context.Context, srcRef, dstRef Reference) (ociregistry.Descriptor, error)

this copies a blob from one repository to another

func CopyManifest

func CopyManifest(ctx context.Context, srcRef, dstRef Reference, childRefs map[ociregistry.Digest]Reference) (ociregistry.Descriptor, error)

this copies a manifest (index or image) and all child objects (manifests or config+layers) from one name to another

func EnsureBlob

func EnsureBlob(ctx context.Context, ref Reference, size int64, content io.Reader) (ociregistry.Descriptor, error)

this takes an io.Reader of content and makes sure it is available as a blob in the given repository+digest (if larger than BlobSizeWorthHEAD, this might return without consuming any of the provided io.Reader)

func EnsureManifest

func EnsureManifest(ctx context.Context, ref Reference, manifest json.RawMessage, mediaType string, childRefs map[ociregistry.Digest]Reference) (ociregistry.Descriptor, error)

this makes sure the given manifest (index or image) is available at the provided name (tag or digest), including copying any children (manifests or config+layers) if necessary and able (via the provided child lookup map)

func Lookup

func Lookup(ctx context.Context, ref Reference, opts *LookupOptions) (ociregistry.BlobReader, error)

a wrapper around ociregistry.Interface.GetManifest (and `GetTag`, `GetBlob`, and the `Resolve*` versions of the above) that accepts a Reference and always returns a ociregistry.BlobReader (in the case of a HEAD request, it will be a zero-length reader with just a valid descriptor)

func RegistryCache

func RegistryCache(r ociregistry.Interface) ociregistry.Interface

this implements a transparent in-memory cache on top of objects less than 4MiB in size from the given registry -- it (currently) assumes a short lifecycle, not a long-running program, so use with care!

TODO options (so we can control *what* gets cached, such as our size limit, whether to cache tag lookups, whether cached data should have a TTL, etc; see manifestSizeLimit and getBlob)

func SynthesizeIndex

func SynthesizeIndex(ctx context.Context, ref Reference) (*ocispec.Index, error)

returns a synthesized ocispec.Index object for the given reference that includes automatically pulling up ocispec.Platform objects for entries missing them plus annotations for bashbrew architecture (AnnotationBashbrewArch) and where to find the "upstream" object if it needs to be copied/pulled (ocispec.AnnotationRefName)

Types

type LookupOptions

type LookupOptions struct {
	// unspecified implies [LookupTypeManifest]
	Type LookupType

	// whether or not to do a HEAD instead of a GET (will still return an [ociregistry.BlobReader], but with an empty body / zero bytes)
	Head bool
}

type LookupType

type LookupType string

see `LookupType*` consts for possible values for this type

const (
	LookupTypeManifest LookupType = "manifest"
	LookupTypeBlob     LookupType = "blob"
)

type ManifestChildren

type ManifestChildren struct {

	// intentional subset of https://github.com/opencontainers/image-spec/blob/v1.1.0/specs-go/v1/index.go#L21 to minimize parsing
	Manifests []ocispec.Descriptor `json:"manifests"`

	// intentional subset of https://github.com/opencontainers/image-spec/blob/v1.1.0/specs-go/v1/manifest.go#L20 to minimize parsing
	Config *ocispec.Descriptor  `json:"config"` // have to turn this into a pointer so we can recognize when it's not set easier / more correctly
	Layers []ocispec.Descriptor `json:"layers"`
}

func ParseManifestChildren

func ParseManifestChildren(manifest []byte) (ManifestChildren, error)

opportunistically parse a given manifest for any *potential* child objects; will return JSON parsing errors for non-JSON

type Reference

type Reference ociref.Reference

copy ociref.Reference so we can add methods (especially for JSON round-trip, but also Docker-isms like the implied default [Reference.Host] and `library/` prefix for DOI)

func ParseRef

func ParseRef(img string) (Reference, error)

parse a string ref like `hello-world:latest` directly into a Reference object, with Docker Hub canonicalization applied: `docker.io/library/hello-world:latest`

See also Reference.Normalize and ociref.ParseRelative (which are the underlying implementation details of this method).

func (Reference) MarshalText

func (ref Reference) MarshalText() ([]byte, error)

implements encoding.TextMarshaler (especially for Reference-in-JSON)

func (*Reference) Normalize

func (ref *Reference) Normalize()

normalize Docker Hub refs like `hello-world:latest`: `docker.io/library/hello-world:latest`

NOTE: this explicitly does *not* normalize Tag to `:latest` because it's useful to be able to parse a reference and know it did not specify either tag or digest (and `if ref.Tag == "" { ref.Tag = "latest" }` is really trivial code outside this for that case)

func (Reference) String

func (ref Reference) String() string

like ociref.Reference.String, but with Docker Hub "denormalization" applied (no explicit `docker.io` host, no `library/` prefix for DOI)

func (Reference) StringWithKnownDigest

func (ref Reference) StringWithKnownDigest(commonDigest ociregistry.Digest) string

like Reference.String, but also stripping a known digest if this object's value matches

func (*Reference) UnmarshalText

func (ref *Reference) UnmarshalText(text []byte) error

implements encoding.TextUnmarshaler (especially for Reference-from-JSON)