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 '/'] 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
- 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 SplitHostname(named Named) (string, string)
- 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 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 FamiliarMatch ¶ added in v2.7.0
FamiliarMatch reports whether ref matches the specified pattern. See https://godoc.org/path#Match for supported patterns.
func FamiliarName ¶ added in v2.7.0
FamiliarName returns the familiar name string for the given named, familiarizing if needed.
func FamiliarString ¶ added in v2.7.0
FamiliarString returns the familiar string representation for the given reference, familiarizing if needed.
func IsNameOnly ¶ added in v2.7.0
IsNameOnly returns true if reference only contains a repo name.
func SplitHostname ¶
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 ¶
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 (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 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. NOTE: ParseNamed will not handle short digests.
func ParseNormalizedNamed ¶ added in v2.7.0
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 ¶ added in v2.7.0
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. NOTE: Parse will not handle short digests.
func ParseAnyReference ¶ added in v2.7.0
ParseAnyReference parses a reference string as a possible identifier, full digest, or familiar name.