package reference

import "github.com/docker/distribution/reference"

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                            := [hostname '/'] component ['/' component]*
hostname                        := hostcomponent ['.' hostcomponent]* [':' port-number]
hostcomponent                   := /([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])/
port-number                     := /[0-9]+/
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

Index ¶

• Constants
• Variables
• func Match(pattern string, ref Reference) (bool, error)
• func SplitHostname(named Named) (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 ParseNamed(s string) (Named, error)
• 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)
• 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)
)

var (

	// 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 hostname and name part omitting
	// the separating forward slash from either.
	NameRegexp = expression(
		optional(hostnameRegexp, 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)))
)

Functions ¶

func Match ¶

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

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

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

Types ¶

type Canonical ¶

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

Canonical reference is an object with a fully unique name including a name with hostname 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 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, 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 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.

type Tagged ¶

type Tagged interface {
	Reference
	Tag() string
}

Tagged is an object which has a tag

Source Files ¶

reference.go regexp.go