Documentation
¶
Overview ¶
Package reference 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 '/'] remote-name
domain := host [':' port-number]
host := domain-name | IPv4address | \[ IPv6address \] ; rfc3986 appendix-A
domain-name := domain-component ['.' domain-component]*
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]*
path (or "remote-name") := path-component ['/' path-component]*
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}/
Index ¶
- Constants
- Variables
- func Domain(named Named) string
- func FamiliarMatch(pattern string, ref Reference) (bool, error)
- func FamiliarName(ref Named) string
- func FamiliarString(ref Reference) string
- func IsNameOnly(ref Named) bool
- func Path(named Named) (name string)
- func Sort(references []string) []string
- func SplitHostname(named Named) (string, string)deprecated
- type Canonical
- type Digested
- type Field
- type Named
- type NamedTagged
- type Reference
- type Tagged
Constants ¶
const (
// NameTotalLengthMax is the maximum total number of characters in a repository name.
NameTotalLengthMax = 255
)
Variables ¶
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") )
var ( // DomainRegexp matches hostname or IP-addresses, optionally including a port // number. It 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. It may be a subset of // DNS domain name, an IPv4 address in decimal format, or an IPv6 address between // square brackets (excluding zone identifiers as defined by [rfc6874] or special // addresses such as IPv4-Mapped). // // [rfc6874]: https://www.rfc-editor.org/rfc/rfc6874. DomainRegexp = regexp.MustCompile(domainAndPort) // TagRegexp matches valid tag names. From docker/docker:graph/tags.go. TagRegexp = regexp.MustCompile(tag) // DigestRegexp matches well-formed digests, including algorithm (e.g. "sha256:<encoded>"). DigestRegexp = regexp.MustCompile(digestPat) // NameRegexp is the format for the name component of references, including // an optional domain and port, but without tag or digest suffix. NameRegexp = regexp.MustCompile(namePat) // ReferenceRegexp is the full supported format of a reference. The regexp // is anchored and has capturing groups for name, tag, and digest // components. ReferenceRegexp = regexp.MustCompile(referencePat) // 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 = regexp.MustCompile(identifier) )
Functions ¶
func FamiliarMatch ¶
FamiliarMatch reports whether ref matches the specified pattern. See path.Match for supported patterns.
func FamiliarName ¶
FamiliarName returns the familiar name string for the given named, familiarizing if needed.
func FamiliarString ¶
FamiliarString returns the familiar string representation for the given reference, familiarizing if needed.
func IsNameOnly ¶
IsNameOnly returns true if reference only contains a repo name.
func Sort ¶
Sort sorts string references preferring higher information references.
The precedence is as follows:
- Named + Tagged + Digested (e.g., "docker.io/library/busybox:latest@sha256:<digest>")
- Named + Tagged (e.g., "docker.io/library/busybox:latest")
- Named + Digested (e.g., "docker.io/library/busybo@sha256:<digest>")
- Named (e.g., "docker.io/library/busybox")
- Digested (e.g., "docker.io@sha256:<digest>")
- Parse error
Types ¶
type Canonical ¶
Canonical reference is an object with a fully unique name including a name with domain and digest
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 (Field) MarshalText ¶
MarshalText serializes the field to byte text which is the string of the reference.
func (Field) 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 ¶
UnmarshalText parses text bytes by invoking the reference parser to ensure the appropriately typed reference object is wrapped by field.
type Named ¶
Named is an object with a full name
func ParseDockerRef ¶
ParseDockerRef normalizes the image reference following the docker convention, which allows for references to contain both a tag and a digest. It returns a reference that is either tagged or digested. For references containing both a tag and a digest, it returns a digested reference. For example, the following reference:
docker.io/library/busybox:latest@sha256:7cc4b5aefd1d0cadf8d97d4350462ba51c694ebca145b08d7d41b41acc8db5aa
Is returned as a digested reference (with the ":latest" tag removed):
docker.io/library/busybox@sha256:7cc4b5aefd1d0cadf8d97d4350462ba51c694ebca145b08d7d41b41acc8db5aa
References that are already "tagged" or "digested" are returned unmodified:
// Already a digested reference docker.io/library/busybox@sha256:7cc4b5aefd1d0cadf8d97d4350462ba51c694ebca145b08d7d41b41acc8db5aa // Already a named reference docker.io/library/busybox:latest
func ParseNamed ¶
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.
func ParseNormalizedNamed ¶
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 ¶
TagNameOnly adds the default tag "latest" to a reference if it only has a repo name.
type NamedTagged ¶
NamedTagged is an object including a name and 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 ¶
Parse parses s and returns a syntactically valid Reference. If an error was encountered it is returned, along with a nil Reference.
func ParseAnyReference ¶
ParseAnyReference parses a reference string as a possible identifier, full digest, or familiar name.