docker: Index | Files | Directories

package registry

import ""

Package registry contains client primitives to interact with a remote Docker registry.


Package Files

auth.go config.go config_unix.go endpoint_v1.go errors.go registry.go service.go service_v2.go session.go types.go


const (
    // DefaultNamespace is the default namespace
    DefaultNamespace = ""
    // DefaultRegistryVersionHeader is the name of the default HTTP header
    // that carries Registry version info
    DefaultRegistryVersionHeader = "Docker-Distribution-Api-Version"

    // IndexHostname is the index hostname
    IndexHostname = ""
    // IndexServer is used for user auth and image search
    IndexServer = "https://" + IndexHostname + "/v1/"
    // IndexName is the name of the index
    IndexName = ""
const (
    // AuthClientID is used the ClientID used for the token server
    AuthClientID = "docker"
const (
    // DefaultSearchLimit is the default value for maximum number of returned search results.
    DefaultSearchLimit = 25


var (
    // DefaultV2Registry is the URI of the default v2 registry
    DefaultV2Registry = &url.URL{
        Scheme: "https",
        Host:   "",

    // ErrInvalidRepositoryName is an error returned if the repository name did
    // not have the correct form
    ErrInvalidRepositoryName = errors.New("Invalid repository name (ex: \"registry.domain.tld/myrepos\")")
var (
    // ErrAlreadyExists is an error returned if an image being pushed
    // already exists on the remote side
    ErrAlreadyExists = errors.New("Image already exists")

func AuthTransport Uses

func AuthTransport(base http.RoundTripper, authConfig *types.AuthConfig, alwaysSetBasicAuth bool) http.RoundTripper

AuthTransport handles the auth layer when communicating with a v1 registry (private or official)

For private v1 registries, set alwaysSetBasicAuth to true.

For the official v1 registry, if there isn't already an Authorization header in the request, but there is an X-Docker-Token header set to true, then Basic Auth will be used to set the Authorization header. After sending the request with the provided base http.RoundTripper, if an X-Docker-Token header, representing a token, is present in the response, then it gets cached and sent in the Authorization header of all subsequent requests.

If the server sends a token without the client having requested it, it is ignored.

This RoundTripper also has a CancelRequest method important for correct timeout handling.

func CertsDir Uses

func CertsDir() string

CertsDir is the directory where certificates are stored

func ConvertToHostname Uses

func ConvertToHostname(url string) string

ConvertToHostname converts a registry url which has http|https prepended to just an hostname.

func GetAuthConfigKey Uses

func GetAuthConfigKey(index *registrytypes.IndexInfo) string

GetAuthConfigKey special-cases using the full index address of the official index as the AuthConfig key, and uses the (host)name[:port] for private indexes.

func HTTPClient Uses

func HTTPClient(transport http.RoundTripper) *http.Client

HTTPClient returns an HTTP client structure which uses the given transport and contains the necessary headers for redirected requests

func Headers Uses

func Headers(userAgent string, metaHeaders http.Header) []transport.RequestModifier

Headers returns request modifiers with a User-Agent and metaHeaders

func HostCertsDir Uses

func HostCertsDir(hostname string) (string, error)

HostCertsDir returns the config directory for a specific host

func NewStaticCredentialStore Uses

func NewStaticCredentialStore(auth *types.AuthConfig) auth.CredentialStore

NewStaticCredentialStore returns a credential store which always returns the same credential values.

func NewTransport Uses

func NewTransport(tlsConfig *tls.Config) *http.Transport

NewTransport returns a new HTTP transport. If tlsConfig is nil, it uses the default TLS configuration.

func ParseSearchIndexInfo Uses

func ParseSearchIndexInfo(reposName string) (*registrytypes.IndexInfo, error)

ParseSearchIndexInfo will use repository name to get back an indexInfo.

func PingV2Registry Uses

func PingV2Registry(endpoint *url.URL, transport http.RoundTripper) (challenge.Manager, bool, error)

PingV2Registry attempts to ping a v2 registry and on success return a challenge manager for the supported authentication types and whether v2 was confirmed by the response. If a response is received but cannot be interpreted a PingResponseError will be returned.

func ReadCertsDirectory Uses

func ReadCertsDirectory(tlsConfig *tls.Config, directory string) error

ReadCertsDirectory reads the directory for TLS certificates including roots and certificate pairs and updates the provided TLS configuration.

func ResolveAuthConfig Uses

func ResolveAuthConfig(authConfigs map[string]types.AuthConfig, index *registrytypes.IndexInfo) types.AuthConfig

ResolveAuthConfig matches an auth configuration to a server address or a URL

func ValidateIndexName Uses

func ValidateIndexName(val string) (string, error)

ValidateIndexName validates an index name.

func ValidateMirror Uses

func ValidateMirror(val string) (string, error)

ValidateMirror validates an HTTP(S) registry mirror

type APIEndpoint Uses

type APIEndpoint struct {
    Mirror                         bool
    URL                            *url.URL
    Version                        APIVersion
    AllowNondistributableArtifacts bool
    Official                       bool
    TrimHostname                   bool
    TLSConfig                      *tls.Config

APIEndpoint represents a remote API endpoint

func (APIEndpoint) ToV1Endpoint Uses

func (e APIEndpoint) ToV1Endpoint(userAgent string, metaHeaders http.Header) *V1Endpoint

ToV1Endpoint returns a V1 API endpoint based on the APIEndpoint Deprecated: this function is deprecated and will be removed in a future update

type APIVersion Uses

type APIVersion int

APIVersion is an integral representation of an API version (presently either 1 or 2)

const (
    APIVersion1 APIVersion = iota

API Version identifiers.

func (APIVersion) String Uses

func (av APIVersion) String() string

type DefaultService Uses

type DefaultService struct {
    // contains filtered or unexported fields

DefaultService is a registry service. It tracks configuration data such as a list of mirrors.

func NewService Uses

func NewService(options ServiceOptions) (*DefaultService, error)

NewService returns a new instance of DefaultService ready to be installed into an engine.

func (*DefaultService) Auth Uses

func (s *DefaultService) Auth(ctx context.Context, authConfig *types.AuthConfig, userAgent string) (status, token string, err error)

Auth contacts the public registry with the provided credentials, and returns OK if authentication was successful. It can be used to verify the validity of a client's credentials.

func (*DefaultService) LoadAllowNondistributableArtifacts Uses

func (s *DefaultService) LoadAllowNondistributableArtifacts(registries []string) error

LoadAllowNondistributableArtifacts loads allow-nondistributable-artifacts registries for Service.

func (*DefaultService) LoadInsecureRegistries Uses

func (s *DefaultService) LoadInsecureRegistries(registries []string) error

LoadInsecureRegistries loads insecure registries for Service

func (*DefaultService) LoadMirrors Uses

func (s *DefaultService) LoadMirrors(mirrors []string) error

LoadMirrors loads registry mirrors for Service

func (*DefaultService) LookupPullEndpoints Uses

func (s *DefaultService) LookupPullEndpoints(hostname string) (endpoints []APIEndpoint, err error)

LookupPullEndpoints creates a list of v2 endpoints to try to pull from, in order of preference. It gives preference to mirrors over the actual registry, and HTTPS over plain HTTP.

func (*DefaultService) LookupPushEndpoints Uses

func (s *DefaultService) LookupPushEndpoints(hostname string) (endpoints []APIEndpoint, err error)

LookupPushEndpoints creates a list of v2 endpoints to try to push to, in order of preference. It gives preference to HTTPS over plain HTTP. Mirrors are not included.

func (*DefaultService) ResolveRepository Uses

func (s *DefaultService) ResolveRepository(name reference.Named) (*RepositoryInfo, error)

ResolveRepository splits a repository name into its components and configuration of the associated registry.

func (*DefaultService) Search Uses

func (s *DefaultService) Search(ctx context.Context, term string, limit int, authConfig *types.AuthConfig, userAgent string, headers map[string][]string) (*registrytypes.SearchResults, error)

Search queries the public registry for images matching the specified search terms, and returns the results.

func (*DefaultService) ServiceConfig Uses

func (s *DefaultService) ServiceConfig() *registrytypes.ServiceConfig

ServiceConfig returns the public registry service configuration.

func (*DefaultService) TLSConfig Uses

func (s *DefaultService) TLSConfig(hostname string) (*tls.Config, error)

TLSConfig constructs a client TLS configuration based on server defaults

type ImgData Uses

type ImgData struct {
    // ID is an opaque string that identifies the image
    ID              string `json:"id"`
    Checksum        string `json:"checksum,omitempty"`
    ChecksumPayload string `json:"-"`
    Tag             string `json:",omitempty"`

ImgData is used to transfer image checksums to and from the registry

type PingResponseError Uses

type PingResponseError struct {
    Err error

PingResponseError is used when the response from a ping was received but invalid.

func (PingResponseError) Error Uses

func (err PingResponseError) Error() string

type PingResult Uses

type PingResult struct {
    // Version is the registry version supplied by the registry in an HTTP
    // header
    Version string `json:"version"`
    // Standalone is set to true if the registry indicates it is a
    // standalone registry in the X-Docker-Registry-Standalone
    // header
    Standalone bool `json:"standalone"`

PingResult contains the information returned when pinging a registry. It indicates the registry's version and whether the registry claims to be a standalone registry.

type RepositoryData Uses

type RepositoryData struct {
    // ImgList is a list of images in the repository
    ImgList map[string]*ImgData
    // Endpoints is a list of endpoints returned in X-Docker-Endpoints
    Endpoints []string

RepositoryData tracks the image list, list of endpoints for a repository

type RepositoryInfo Uses

type RepositoryInfo struct {
    Name reference.Named
    // Index points to registry information
    Index *registrytypes.IndexInfo
    // Official indicates whether the repository is considered official.
    // If the registry is official, and the normalized name does not
    // contain a '/' (e.g. "foo"), then it is considered an official repo.
    Official bool
    // Class represents the class of the repository, such as "plugin"
    // or "image".
    Class string

RepositoryInfo describes a repository

func ParseRepositoryInfo Uses

func ParseRepositoryInfo(reposName reference.Named) (*RepositoryInfo, error)

ParseRepositoryInfo performs the breakdown of a repository name into a RepositoryInfo, but lacks registry configuration.

type Service Uses

type Service interface {
    Auth(ctx context.Context, authConfig *types.AuthConfig, userAgent string) (status, token string, err error)
    LookupPullEndpoints(hostname string) (endpoints []APIEndpoint, err error)
    LookupPushEndpoints(hostname string) (endpoints []APIEndpoint, err error)
    ResolveRepository(name reference.Named) (*RepositoryInfo, error)
    Search(ctx context.Context, term string, limit int, authConfig *types.AuthConfig, userAgent string, headers map[string][]string) (*registrytypes.SearchResults, error)
    ServiceConfig() *registrytypes.ServiceConfig
    TLSConfig(hostname string) (*tls.Config, error)
    LoadAllowNondistributableArtifacts([]string) error
    LoadMirrors([]string) error
    LoadInsecureRegistries([]string) error

Service is the interface defining what a registry service should implement.

type ServiceOptions Uses

type ServiceOptions struct {
    AllowNondistributableArtifacts []string `json:"allow-nondistributable-artifacts,omitempty"`
    Mirrors                        []string `json:"registry-mirrors,omitempty"`
    InsecureRegistries             []string `json:"insecure-registries,omitempty"`

ServiceOptions holds command line options.

type Session Uses

type Session struct {
    // contains filtered or unexported fields

A Session is used to communicate with a V1 registry

func NewSession Uses

func NewSession(client *http.Client, authConfig *types.AuthConfig, endpoint *V1Endpoint) (*Session, error)

NewSession creates a new session TODO(tiborvass): remove authConfig param once registry client v2 is vendored

func (*Session) SearchRepositories Uses

func (r *Session) SearchRepositories(term string, limit int) (*registrytypes.SearchResults, error)

SearchRepositories performs a search against the remote repository

type V1Endpoint Uses

type V1Endpoint struct {
    URL      *url.URL
    IsSecure bool
    // contains filtered or unexported fields

V1Endpoint stores basic information about a V1 registry endpoint.

func NewV1Endpoint Uses

func NewV1Endpoint(index *registrytypes.IndexInfo, userAgent string, metaHeaders http.Header) (*V1Endpoint, error)

NewV1Endpoint parses the given address to return a registry endpoint.

func (*V1Endpoint) Path Uses

func (e *V1Endpoint) Path(path string) string

Path returns a formatted string for the URL of this endpoint with the given path appended.

func (*V1Endpoint) Ping Uses

func (e *V1Endpoint) Ping() (PingResult, error)

Ping returns a PingResult which indicates whether the registry is standalone or not.

func (*V1Endpoint) String Uses

func (e *V1Endpoint) String() string

Get the formatted URL for the root of this registry Endpoint



Package registry imports 34 packages (graph) and is imported by 5287 packages. Updated 2020-11-12. Refresh now. Tools for package owners.