reference package - github.com/distribution/reference - Go Packages (original) (raw)

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

• 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
• type Canonical
• • func WithDigest(name Named, digest digest.Digest) (Canonical, error)
• type Digested
• type Field
• • func AsField(reference Reference) Field
• • func (f Field) MarshalText() (p []byte, err error)
  • func (f Field) Reference() Reference
  • func (f *Field) UnmarshalText(p []byte) error
• type Named
• • func ParseDockerRef(ref string) (Named, error)
  • func ParseNamed(s string) (Named, error)
  • func ParseNormalizedNamed(s string) (Named, error)
  • func TagNameOnly(ref Named) Named
  • func TrimNamed(ref Named) Named
  • func WithName(name string) (Named, error)
• type NamedTagged
• • func WithTag(name Named, tag string) (NamedTagged, error)
• type Reference
• • func Parse(s string) (Reference, error)
  • func ParseAnyReference(ref string) (Reference, error)
• type Tagged

View Source

const (

RepositoryNameTotalLengthMax = 255


NameTotalLengthMax = [RepositoryNameTotalLengthMax](#RepositoryNameTotalLengthMax)

)

View Source

var (

ErrReferenceInvalidFormat = [errors](/errors).[New](/errors#New)("invalid reference format")


ErrTagInvalidFormat = [errors](/errors).[New](/errors#New)("invalid tag format")


ErrDigestInvalidFormat = [errors](/errors).[New](/errors#New)("invalid digest format")


ErrNameContainsUppercase = [errors](/errors).[New](/errors#New)("repository name must be lowercase")


ErrNameEmpty = [errors](/errors).[New](/errors#New)("repository name must have at least one component")


ErrNameTooLong = [fmt](/fmt).[Errorf](/fmt#Errorf)("repository name must not be more than %v characters", [RepositoryNameTotalLengthMax](#RepositoryNameTotalLengthMax))


ErrNameNotCanonical = [errors](/errors).[New](/errors#New)("repository name must be canonical")

)

DigestRegexp matches well-formed digests, including algorithm (e.g. "sha256:").

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 RFC 6874 or special addresses such as IPv4-Mapped).

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.

NameRegexp is the format for the name component of references, including an optional domain and port, but without tag or digest suffix.

ReferenceRegexp is the full supported format of a reference. The regexp is anchored and has capturing groups for name, tag, and digest components.

TagRegexp matches valid tag names. From docker/docker:graph/tags.go.

func Domain ¶

Domain returns the domain part of the Named reference.

FamiliarMatch reports whether ref matches the specified pattern. See path.Match for supported patterns.

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

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

func IsNameOnly(ref Named) bool

IsNameOnly returns true if reference only contains a repo name.

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

Sort sorts string references preferring higher information references.

The precedence is as follows:

1. Named + Tagged + Digested (e.g., "docker.io/library/busybox:latest@sha256:")
2. Named + Tagged (e.g., "docker.io/library/busybox:latest")
3. Named + Digested (e.g., "docker.io/library/busybo@sha256:")
4. Named (e.g., "docker.io/library/busybox")
5. Digested (e.g., "docker.io@sha256:")
6. Parse error

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(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 interface { Reference Digest() digest.Digest }

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

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

func AsField(reference Reference) Field

AsField wraps a reference in a Field for encoding.

MarshalText serializes the field to byte text which is the string of the 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.

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

type Named interface { Reference Name() string }

Named is an object with a full name

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

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.

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(ref Named) Named

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

func TrimNamed(ref Named) Named

TrimNamed removes any tag or digest from the named reference.

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

type NamedTagged interface { Named Tag() string }

NamedTagged is an object including a name and tag.

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

type Reference interface {

String() [string](/builtin#string)

}

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

Parse parses s and returns a syntactically valid Reference. If an error was encountered it is returned, along with a nil Reference.

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

type Tagged interface { Reference Tag() string }

Tagged is an object which has a tag