reference

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 15, 2024 License: Apache-2.0 Imports: 2 Imported by: 1

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

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

Variables

View Source 
var (
	// ErrReferenceInvalidFormat represents an error while trying to parse a string as a reference.
	ErrReferenceInvalidFormat = reference.ErrReferenceInvalidFormat

	// ErrTagInvalidFormat represents an error while trying to parse a string as a tag.
	ErrTagInvalidFormat = reference.ErrTagInvalidFormat

	// ErrDigestInvalidFormat represents an error while trying to parse a string as a tag.
	ErrDigestInvalidFormat = reference.ErrDigestInvalidFormat

	// ErrNameContainsUppercase is returned for invalid repository names that contain uppercase characters.
	ErrNameContainsUppercase = reference.ErrNameContainsUppercase

	// ErrNameEmpty is returned for empty, invalid repository names.
	ErrNameEmpty = reference.ErrNameEmpty

	// ErrNameTooLong is returned when a repository name is longer than NameTotalLengthMax.
	ErrNameTooLong = reference.ErrNameTooLong

	// ErrNameNotCanonical is returned when a name is not canonical.
	ErrNameNotCanonical = reference.ErrNameNotCanonical
)
View Source 
var DigestRegexp = reference.DigestRegexp

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

View Source 
var DomainRegexp = reference.DomainRegexp

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).

View Source 
var IdentifierRegexp = reference.IdentifierRegexp

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.

View Source 
var NameRegexp = reference.NameRegexp

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

View Source 
var ReferenceRegexp = reference.ReferenceRegexp

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

View Source 
var TagRegexp = reference.TagRegexp

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

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 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 Sort 

func Sort(references []string) []string

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:<digest>")
  2. Named + Tagged (e.g., "docker.io/library/busybox:latest")
  3. Named + Digested (e.g., "docker.io/library/busybo@sha256:<digest>")
  4. Named (e.g., "docker.io/library/busybox")
  5. Digested (e.g., "docker.io@sha256:<digest>")
  6. Parse error

func SplitHostname deprecated 

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 = reference.Canonical

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 = reference.Digested

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

type Field 

type Field = reference.Field

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

func AsField 

func AsField(ref Reference) Field

AsField wraps a reference in a Field for encoding.

type Named 

type Named = reference.Named

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, 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 

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.

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 = reference.NamedTagged

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 = reference.Reference

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.

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 = reference.Tagged

Tagged is an object which has a tag

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.