Documentation

Overview

    Package docker provides a general type to represent any way of referencing images within the registry. Its main purpose is to abstract tags and digests (content-addressable hash).

    Grammar

    reference                       := name [ ":" tag ] [ "@" digest ]
    name                            := [domain '/'] path-component ['/' path-component]*
    domain                          := domain-component ['.' domain-component]* [':' port-number]
    domain-component                := /([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])/
    port-number                     := /[0-9]+/
    path-component                  := alpha-numeric [separator alpha-numeric]*
    alpha-numeric                   := /[a-z0-9]+/
    separator                       := /[_.]|__|[-]*/
    
    tag                             := /[\w][\w.-]{0,127}/
    
    digest                          := digest-algorithm ":" digest-hex
    digest-algorithm                := digest-algorithm-component [ digest-algorithm-separator digest-algorithm-component ]*
    digest-algorithm-separator      := /[+.-_]/
    digest-algorithm-component      := /[A-Za-z][A-Za-z0-9]*/
    digest-hex                      := /[0-9a-fA-F]{32,}/ ; At least 128 bit digest value
    
    identifier                      := /[a-f0-9]{64}/
    short-identifier                := /[a-f0-9]{6,64}/
    

    Index

    Constants

    View Source
    const (
    	// NameTotalLengthMax is the maximum total number of characters in a repository name.
    	NameTotalLengthMax = 255
    )

    Variables

    View Source
    var (
    	// ErrReferenceInvalidFormat represents an error while trying to parse a string as a reference.
    	ErrReferenceInvalidFormat = errors.New("invalid reference format")
    
    	// ErrTagInvalidFormat represents an error while trying to parse a string as a tag.
    	ErrTagInvalidFormat = errors.New("invalid tag format")
    
    	// ErrDigestInvalidFormat represents an error while trying to parse a string as a tag.
    	ErrDigestInvalidFormat = errors.New("invalid digest format")
    
    	// ErrNameContainsUppercase is returned for invalid repository names that contain uppercase characters.
    	ErrNameContainsUppercase = errors.New("repository name must be lowercase")
    
    	// ErrNameEmpty is returned for empty, invalid repository names.
    	ErrNameEmpty = errors.New("repository name must have at least one component")
    
    	// ErrNameTooLong is returned when a repository name is longer than NameTotalLengthMax.
    	ErrNameTooLong = fmt.Errorf("repository name must not be more than %v characters", NameTotalLengthMax)
    
    	// ErrNameNotCanonical is returned when a name is not canonical.
    	ErrNameNotCanonical = errors.New("repository name must be canonical")
    )
    View Source
    var (
    
    	// DomainRegexp defines the structure of potential domain components
    	// that may be part of image names. This is purposely a subset of what is
    	// allowed by DNS to ensure backwards compatibility with Docker image
    	// names.
    	DomainRegexp = expression(
    		domainComponentRegexp,
    		optional(repeated(literal(`.`), domainComponentRegexp)),
    		optional(literal(`:`), match(`[0-9]+`)))
    
    	// TagRegexp matches valid tag names. From docker/docker:graph/tags.go.
    	TagRegexp = match(`[\w][\w.-]{0,127}`)
    
    	// DigestRegexp matches valid digests.
    	DigestRegexp = match(`[A-Za-z][A-Za-z0-9]*(?:[-_+.][A-Za-z][A-Za-z0-9]*)*[:][[:xdigit:]]{32,}`)
    
    	// NameRegexp is the format for the name component of references. The
    	// regexp has capturing groups for the domain and name part omitting
    	// the separating forward slash from either.
    	NameRegexp = expression(
    		optional(DomainRegexp, literal(`/`)),
    		nameComponentRegexp,
    		optional(repeated(literal(`/`), nameComponentRegexp)))
    
    	// ReferenceRegexp is the full supported format of a reference. The regexp
    	// is anchored and has capturing groups for name, tag, and digest
    	// components.
    	ReferenceRegexp = anchored(capture(NameRegexp),
    		optional(literal(":"), capture(TagRegexp)),
    		optional(literal("@"), capture(DigestRegexp)))
    
    	// IdentifierRegexp is the format for string identifier used as a
    	// content addressable identifier using sha256. These identifiers
    	// are like digests without the algorithm, since sha256 is used.
    	IdentifierRegexp = match(`([a-f0-9]{64})`)
    
    	// ShortIdentifierRegexp is the format used to represent a prefix
    	// of an identifier. A prefix may be used to match a sha256 identifier
    	// within a list of trusted identifiers.
    	ShortIdentifierRegexp = match(`([a-f0-9]{6,64})`)
    )

    Functions

    func Domain

    func Domain(named Named) string

      Domain returns the domain part of the Named reference

      func FamiliarMatch

      func FamiliarMatch(pattern string, ref Reference) (bool, error)

        FamiliarMatch reports whether ref matches the specified pattern. See https://godoc.org/path#Match for supported patterns.

        func FamiliarName

        func FamiliarName(ref Named) string

          FamiliarName returns the familiar name string for the given named, familiarizing if needed.

          func FamiliarString

          func FamiliarString(ref Reference) string

            FamiliarString returns the familiar string representation for the given reference, familiarizing if needed.

            func IsNameOnly

            func IsNameOnly(ref Named) bool

              IsNameOnly returns true if reference only contains a repo name.

              func Path

              func Path(named Named) (name string)

                Path returns the name without the domain part of the Named reference

                func SplitHostname

                func SplitHostname(named Named) (string, string)

                  SplitHostname splits a named reference into a hostname and name string. If no valid hostname is found, the hostname is empty and the full value is returned as name DEPRECATED: Use Domain or Path

                  Types

                  type Canonical

                  type Canonical interface {
                  	Named
                  	Digest() digest.Digest
                  }

                    Canonical reference is an object with a fully unique name including a name with domain and digest

                    func WithDigest

                    func WithDigest(name Named, digest digest.Digest) (Canonical, error)

                      WithDigest combines the name from "name" and the digest from "digest" to form a reference incorporating both the name and the digest.

                      type Digested

                      type Digested interface {
                      	Reference
                      	Digest() digest.Digest
                      }

                        Digested is an object which has a digest in which it can be referenced by

                        type Field

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

                          Field provides a wrapper type for resolving correct reference types when working with encoding.

                          func AsField

                          func AsField(reference Reference) Field

                            AsField wraps a reference in a Field for encoding.

                            func (Field) MarshalText

                            func (f Field) MarshalText() (p []byte, err error)

                              MarshalText serializes the field to byte text which is the string of the reference.

                              func (Field) Reference

                              func (f Field) Reference() Reference

                                Reference unwraps the reference type from the field to return the Reference object. This object should be of the appropriate type to further check for different reference types.

                                func (*Field) UnmarshalText

                                func (f *Field) UnmarshalText(p []byte) error

                                  UnmarshalText parses text bytes by invoking the reference parser to ensure the appropriately typed reference object is wrapped by field.

                                  type Named

                                  type Named interface {
                                  	Reference
                                  	Name() string
                                  }

                                    Named is an object with a full name

                                    func ParseDockerRef

                                    func ParseDockerRef(ref string) (Named, error)

                                      ParseDockerRef normalizes the image reference following the docker convention. This is added mainly for backward compatibility. The reference returned can only be either tagged or digested. For reference contains both tag and digest, the function returns digested reference, e.g. docker.io/library/busybox:latest@ sha256:7cc4b5aefd1d0cadf8d97d4350462ba51c694ebca145b08d7d41b41acc8db5aa will be returned as docker.io/library/busybox@sha256:7cc4b5aefd1d0cadf8d97d4350462ba51c694ebca145b08d7d41b41acc8db5aa.

                                      func ParseNamed

                                      func ParseNamed(s string) (Named, error)

                                        ParseNamed parses s and returns a syntactically valid reference implementing the Named interface. The reference must have a name and be in the canonical form, otherwise an error is returned. If an error was encountered it is returned, along with a nil Reference. NOTE: ParseNamed will not handle short digests.

                                        func ParseNormalizedNamed

                                        func ParseNormalizedNamed(s string) (Named, error)

                                          ParseNormalizedNamed parses a string into a named reference transforming a familiar name from Docker UI to a fully qualified reference. If the value may be an identifier use ParseAnyReference.

                                          func TagNameOnly

                                          func TagNameOnly(ref Named) Named

                                            TagNameOnly adds the default tag "latest" to a reference if it only has a repo name.

                                            func TrimNamed

                                            func TrimNamed(ref Named) Named

                                              TrimNamed removes any tag or digest from the named reference.

                                              func WithName

                                              func WithName(name string) (Named, error)

                                                WithName returns a named object representing the given string. If the input is invalid ErrReferenceInvalidFormat will be returned.

                                                type NamedTagged

                                                type NamedTagged interface {
                                                	Named
                                                	Tag() string
                                                }

                                                  NamedTagged is an object including a name and tag.

                                                  func WithTag

                                                  func WithTag(name Named, tag string) (NamedTagged, error)

                                                    WithTag combines the name from "name" and the tag from "tag" to form a reference incorporating both the name and the tag.

                                                    type Reference

                                                    type Reference interface {
                                                    	// String returns the full reference
                                                    	String() string
                                                    }

                                                      Reference is an opaque object reference identifier that may include modifiers such as a hostname, name, tag, and digest.

                                                      func Parse

                                                      func Parse(s string) (Reference, error)

                                                        Parse parses s and returns a syntactically valid Reference. If an error was encountered it is returned, along with a nil Reference. NOTE: Parse will not handle short digests.

                                                        func ParseAnyReference

                                                        func ParseAnyReference(ref string) (Reference, error)

                                                          ParseAnyReference parses a reference string as a possible identifier, full digest, or familiar name.

                                                          type Tagged

                                                          type Tagged interface {
                                                          	Reference
                                                          	Tag() string
                                                          }

                                                            Tagged is an object which has a tag

                                                            Source Files