README

name

GoDoc

Expand ▾ Collapse ▴

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

      func IsErrBadName(err error) bool

        IsErrBadName returns true if the given error is an ErrBadName.

        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 NewErrBadName

                            func NewErrBadName(fmtStr string, args ...interface{}) *ErrBadName

                              NewErrBadName returns a ErrBadName which returns the given formatted string from Error().

                              func (*ErrBadName) Error

                              func (e *ErrBadName) Error() string

                              type Option

                              type Option func(*options)

                                Option is a functional option for name parsing.

                                func WithDefaultRegistry

                                func WithDefaultRegistry(r string) Option

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

                                  func WithDefaultTag

                                  func WithDefaultTag(t string) Option

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

                                    type OptionFn

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

                                            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.