Documentation
¶
Overview ¶
Package name 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}/
NOTE ¶
This package is draw inspiration deeply from the follow repositories:
- github.com/docker/distribution/reference
- oras.land/oras-go/v2/registry/reference.go
- github.com/google/go-containerregistry/pkg/name
Index ¶
- Constants
- Variables
- func Hostname(addr string) string
- func Namespace(path string) string
- func ValidateDigest(dgst digest.Digest) error
- func ValidateReference(r Reference) error
- func ValidateRegistry(r Registry) error
- func ValidateRegistryScheme(scheme string) error
- func ValidateRepository(r Repository) error
- func ValidateRepositoryPath(path string) error
- func ValidateTag(tag string) error
- type Digested
- type Option
- type Reference
- type Registry
- type Repository
- type Tagged
Constants ¶
const ( // DefaultRegistry is the registry name that will be used if no registry // provided and the default is not overridden. DefaultRegistry = "registry-1.docker.io" // DefaultNamespace is the top-level repository path that will be used // if no namespace provided. DefaultNamespace = "library" // DefaultTag is the tag name that will be used if no tag provided and the // default is not overridden. DefaultTag = "latest" // DockerIOHostname is the hostname of DockerHub server. DockerIOHostname = "docker.io" // IndexHostname is the index hostname of DockerHub server. DockerIndexHostname = "index.docker.io" // DockerIndexServer is used for user auth and image search. DockerIndexServer = "https://" + DockerIndexHostname + "/v1/" )
Variables ¶
var ( // ErrBadName is an error for when a bad name is supplied. ErrBadName = errors.New("bad name") )
Functions ¶
func Namespace ¶
Namespace returns the top-level path-component in the path separated by "/", if not exists returns the default namespace "library".
func ValidateDigest ¶
func ValidateDigest(dgst digest.Digest) error
ValidateDigest checks whether the digest is valid.
func ValidateReference ¶
ValidateReference checks whether the reference is valid.
func ValidateRegistry ¶
ValidateRegistry checks whether the Registry is valid.
func ValidateRegistryScheme ¶
ValidateRegistryScheme checks whether the scheme provided is valid. Only "http", "https" or "" is allowed.
func ValidateRepository ¶
func ValidateRepository(r Repository) error
ValidateRepository checks whether the Repository is valid.
func ValidateRepositoryPath ¶
ValidateRepositoryPath checks whether the path provided is valid.
Types ¶
type Digested ¶
type Digested interface {
Reference
// Digest returns the digest of the reference.
Digest() digest.Digest
}
Digested is an object which has a digest in which it can be referenced by.
func MustWithDigest ¶
func MustWithDigest(r Repository, dgst digest.Digest) Digested
MustWithDigest wraps WithDigest with error panic.
func WithDigest ¶
func WithDigest(r Repository, dgst digest.Digest) (Digested, error)
WithDigest combines the repository and the digest to a Digested reference.
type Option ¶
type Option func(*options)
Option is a functional option for name parsing.
func WithDefaultRegistry ¶
WithDefaultRegistry sets the default registry that will be used if one is not provided. If not set, "registry-1.docker.io" will be used as default.
func WithDefaultTag ¶
WithDefaultTag sets the default tag that will be used if one is not provided. If not set, "latest" will be used as default.
func WithStrict ¶
WithStrict sets the parse mode. When set to "true", it enforces strict parsing rules, requiring image references to be fully specified. This disables default behavior and returns an error if any inconsistencies are found during parsing.
type Reference ¶
type Reference interface {
fmt.Stringer
// Repository returns the name component as a Repository object.
Repository() Repository
}
Reference is an opaque object reference identifier that may include modifiers such as a hostname, name, tag, and digest.
type Registry ¶
type Registry interface {
fmt.Stringer
// Scheme returns the scheme ("http" or "https") of the registry. The
// scheme may including by the raw domain string, or guessed by the
// hostname such as "localhost" represents to "http", or set by user.
// Otherwise it will return empty string "".
Scheme() string
// Hostname returns the hostname of the registry. A hostname can be
// formatted as a domain-name, IPv4 address, or IPv6 address. More to
// see RFC3986 appendix-A.
Hostname() string
// WithScheme returns a copy of Registry and overwrites with the scheme
// provided.
WithScheme(scheme string) Registry
}
Registry is a reference to a registry domain. A Registry has both scheme and hostname components.
type Repository ¶
type Repository interface {
fmt.Stringer
// Domain returns the domain component as a Registry object.
Domain() Registry
// Path returns the path (or "remote-name") component.
Path() string
}
Repository is a reference to a repository with a name. A Repository has both domain and path components.
func MustWithPath ¶
func MustWithPath(r Registry, path string) Repository
MustWithPath wraps WithPath with error panic.
func NewRepository ¶
func NewRepository(name string, opts ...Option) (Repository, error)
NewRepository returns a Repository representing the given name.
type Tagged ¶
Tagged is an object which has a tag.
func MustWithTag ¶
func MustWithTag(r Repository, tag string) Tagged
MustWithTag wraps WithTag with error panic.
Source Files
Directories