name

package
Version: v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2021 License: Apache-2.0 Imports: 7 Imported by: 425

README

name

GoDoc

Documentation

Overview

Package name defines structured types for representing image references.

What's in a name? For image references, not nearly enough!

Image references look a lot like URLs, but they differ in that they don't contain the scheme (http or https), they can end with a :tag or a @digest (the latter being validated), and they perform defaulting for missing components.

Since image references don't contain the scheme, we do our best to infer if we use http or https from the given hostname. We allow http fallback for any host that looks like localhost (localhost, 127.0.0.1, ::1), ends in ".local", or is in the "private" address space per RFC 1918. For everything else, we assume https only. To override this heuristic, use the Insecure option.

Image references with a digest signal to us that we should verify the content of the image matches the digest. E.g. when pulling a Digest reference, we'll calculate the sha256 of the manifest returned by the registry and error out if it doesn't match what we asked for.

For defaulting, we interpret "ubuntu" as "index.docker.io/library/ubuntu:latest" because we add the missing repo "library", the missing registry "index.docker.io", and the missing tag "latest". To disable this defaulting, use the StrictValidation option. This is useful e.g. to only allow image references that explicitly set a tag or digest, so that you don't accidentally pull "latest".

Index

Constants

View Source
const (
	// DefaultRegistry is the registry name that will be used if no registry
	// provided and the default is not overridden.
	DefaultRegistry = "index.docker.io"

	// DefaultTag is the tag name that will be used if no tag provided and the
	// default is not overridden.
	DefaultTag = "latest"
)

Variables

This section is empty.

Functions

func Insecure

func Insecure(opts *options)

Insecure is an Option that allows image references to be fetched without TLS.

func IsErrBadName deprecated

func IsErrBadName(err error) bool

IsErrBadName returns true if the given error is an ErrBadName.

Deprecated: Use errors.Is.

func StrictValidation

func StrictValidation(opts *options)

StrictValidation is an Option that requires image references to be fully specified; i.e. no defaulting for registry (dockerhub), repo (library), or tag (latest).

func WeakValidation

func WeakValidation(opts *options)

WeakValidation is an Option that sets defaults when parsing names, see StrictValidation.

Types

type Digest

type Digest struct {
	Repository
	// contains filtered or unexported fields
}

Digest stores a digest name in a structured form.

func NewDigest

func NewDigest(name string, opts ...Option) (Digest, error)

NewDigest returns a new Digest representing the given name.

func (Digest) Context

func (d Digest) Context() Repository

Context implements Reference.

func (Digest) DigestStr

func (d Digest) DigestStr() string

DigestStr returns the digest component of the Digest.

func (Digest) Identifier

func (d Digest) Identifier() string

Identifier implements Reference.

func (Digest) Name

func (d Digest) Name() string

Name returns the name from which the Digest was derived.

func (Digest) String

func (d Digest) String() string

String returns the original input string.

type ErrBadName

type ErrBadName struct {
	// contains filtered or unexported fields
}

ErrBadName is an error for when a bad docker name is supplied.

func (*ErrBadName) Error

func (e *ErrBadName) Error() string

type Option

type Option func(*options)

Option is a functional option for name parsing.

func WithDefaultRegistry added in v0.2.0

func WithDefaultRegistry(r string) Option

WithDefaultRegistry sets the default registry that will be used if one is not provided.

func WithDefaultTag added in v0.2.0

func WithDefaultTag(t string) Option

WithDefaultTag sets the default tag that will be used if one is not provided.

type OptionFn added in v0.2.0

type OptionFn func() Option

OptionFn is a function that returns an option.

type Reference

type Reference interface {
	fmt.Stringer

	// Context accesses the Repository context of the reference.
	Context() Repository

	// Identifier accesses the type-specific portion of the reference.
	Identifier() string

	// Name is the fully-qualified reference name.
	Name() string

	// Scope is the scope needed to access this reference.
	Scope(string) string
}

Reference defines the interface that consumers use when they can take either a tag or a digest.

func MustParseReference added in v0.5.0

func MustParseReference(s stringConst, opts ...Option) Reference

MustParseReference behaves like ParseReference, but panics instead of returning an error. It's intended for use in tests, or when a value is expected to be valid at code authoring time.

To discourage its use in scenarios where the value is not known at code authoring time, it must be passed a string constant:

const str = "valid/string"
MustParseReference(str)
MustParseReference("another/valid/string")
MustParseReference(str + "/and/more")

These will not compile:

var str = "valid/string"
MustParseReference(str)
MustParseReference(strings.Join([]string{"valid", "string"}, "/"))

func ParseReference

func ParseReference(s string, opts ...Option) (Reference, error)

ParseReference parses the string as a reference, either by tag or digest.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry stores a docker registry name in a structured form.

func NewInsecureRegistry deprecated

func NewInsecureRegistry(name string, opts ...Option) (Registry, error)

NewInsecureRegistry returns an Insecure Registry based on the given name.

Deprecated: Use the Insecure Option with NewRegistry instead.

func NewRegistry

func NewRegistry(name string, opts ...Option) (Registry, error)

NewRegistry returns a Registry based on the given name. Strict validation requires explicit, valid RFC 3986 URI authorities to be given.

func (Registry) Name

func (r Registry) Name() string

Name returns the name from which the Registry was derived.

func (Registry) RegistryStr

func (r Registry) RegistryStr() string

RegistryStr returns the registry component of the Registry.

func (Registry) Scheme

func (r Registry) Scheme() string

Scheme returns https scheme for all the endpoints except localhost or when explicitly defined.

func (Registry) Scope

func (r Registry) Scope(string) string

Scope returns the scope required to access the registry.

func (Registry) String

func (r Registry) String() string

type Repository

type Repository struct {
	Registry
	// contains filtered or unexported fields
}

Repository stores a docker repository name in a structured form.

func NewRepository

func NewRepository(name string, opts ...Option) (Repository, error)

NewRepository returns a new Repository representing the given name, according to the given strictness.

func (Repository) Digest

func (r Repository) Digest(identifier string) Digest

Digest returns a Digest in this Repository.

func (Repository) Name

func (r Repository) Name() string

Name returns the name from which the Repository was derived.

func (Repository) RepositoryStr

func (r Repository) RepositoryStr() string

RepositoryStr returns the repository component of the Repository.

func (Repository) Scope

func (r Repository) Scope(action string) string

Scope returns the scope required to perform the given action on the registry. TODO(jonjohnsonjr): consider moving scopes to a separate package.

func (Repository) String

func (r Repository) String() string

func (Repository) Tag

func (r Repository) Tag(identifier string) Tag

Tag returns a Tag in this Repository.

type Tag

type Tag struct {
	Repository
	// contains filtered or unexported fields
}

Tag stores a docker tag name in a structured form.

func NewTag

func NewTag(name string, opts ...Option) (Tag, error)

NewTag returns a new Tag representing the given name, according to the given strictness.

func (Tag) Context

func (t Tag) Context() Repository

Context implements Reference.

func (Tag) Identifier

func (t Tag) Identifier() string

Identifier implements Reference.

func (Tag) Name

func (t Tag) Name() string

Name returns the name from which the Tag was derived.

func (Tag) Scope

func (t Tag) Scope(action string) string

Scope returns the scope required to perform the given action on the tag.

func (Tag) String

func (t Tag) String() string

String returns the original input string.

func (Tag) TagStr

func (t Tag) TagStr() string

TagStr returns the tag component of the Tag.

Jump to

Keyboard shortcuts

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