Documentation

Index

Constants

View Source
const LegacyConfigMediaType = "application/octet-stream"

    LegacyConfigMediaType should be replaced by OCI image spec.

    More detail: docker/distribution#1622

    Variables

    View Source
    var (
    	// ErrorCodeUnknown is a generic error that can be used as a last
    	// resort if there is no situation-specific error message that can be used
    	ErrorCodeUnknown = Register("errcode", ErrorDescriptor{
    		Value:   "UNKNOWN",
    		Message: "unknown error",
    		Description: `Generic error returned when the error does not have an
    			                                            API classification.`,
    		HTTPStatusCode: http.StatusInternalServerError,
    	})
    
    	// ErrorCodeUnsupported is returned when an operation is not supported.
    	ErrorCodeUnsupported = Register("errcode", ErrorDescriptor{
    		Value:   "UNSUPPORTED",
    		Message: "The operation is unsupported.",
    		Description: `The operation was unsupported due to a missing
    		implementation or invalid set of parameters.`,
    		HTTPStatusCode: http.StatusMethodNotAllowed,
    	})
    
    	// ErrorCodeUnauthorized is returned if a request requires
    	// authentication.
    	ErrorCodeUnauthorized = Register("errcode", ErrorDescriptor{
    		Value:   "UNAUTHORIZED",
    		Message: "authentication required",
    		Description: `The access controller was unable to authenticate
    		the client. Often this will be accompanied by a
    		Www-Authenticate HTTP response header indicating how to
    		authenticate.`,
    		HTTPStatusCode: http.StatusUnauthorized,
    	})
    
    	// ErrorCodeDenied is returned if a client does not have sufficient
    	// permission to perform an action.
    	ErrorCodeDenied = Register("errcode", ErrorDescriptor{
    		Value:   "DENIED",
    		Message: "requested access to the resource is denied",
    		Description: `The access controller denied access for the
    		operation on a resource.`,
    		HTTPStatusCode: http.StatusForbidden,
    	})
    
    	// ErrorCodeUnavailable provides a common error to report unavailability
    	// of a service or endpoint.
    	ErrorCodeUnavailable = Register("errcode", ErrorDescriptor{
    		Value:          "UNAVAILABLE",
    		Message:        "service unavailable",
    		Description:    "Returned when a service is not available",
    		HTTPStatusCode: http.StatusServiceUnavailable,
    	})
    
    	// ErrorCodeTooManyRequests is returned if a client attempts too many
    	// times to contact a service endpoint.
    	ErrorCodeTooManyRequests = Register("errcode", ErrorDescriptor{
    		Value:   "TOOMANYREQUESTS",
    		Message: "too many requests",
    		Description: `Returned when a client attempts to contact a
    		service too many times`,
    		HTTPStatusCode: http.StatusTooManyRequests,
    	})
    )
    View Source
    var (
    	// ErrNoToken is returned if a request is successful but the body does not
    	// contain an authorization token.
    	ErrNoToken = errors.New("authorization server did not include a token in the response")
    
    	// ErrInvalidAuthorization is used when credentials are passed to a server but
    	// those credentials are rejected.
    	ErrInvalidAuthorization = errors.New("authorization failed")
    
    	// MaxManifestSize represents the largest size accepted from a registry
    	// during resolution. Larger manifests may be accepted using a
    	// resolution method other than the registry.
    	//
    	// NOTE: The max supported layers by some runtimes is 128 and individual
    	// layers will not contribute more than 256 bytes, making a
    	// reasonable limit for a large image manifests of 32K bytes.
    	// 4M bytes represents a much larger upper bound for images which may
    	// contain large annotations or be non-images. A proper manifest
    	// design puts large metadata in subobjects, as is consistent the
    	// intent of the manifest design.
    	MaxManifestSize int64 = 4 * 1048 * 1048
    )

    Functions

    func AppendDistributionSourceLabel

    func AppendDistributionSourceLabel(manager content.Manager, ref string) (images.HandlerFunc, error)

      AppendDistributionSourceLabel updates the label of blob with distribution source.

      func ConvertManifest

      func ConvertManifest(ctx context.Context, store content.Store, desc ocispec.Descriptor) (ocispec.Descriptor, error)

        ConvertManifest changes application/octet-stream to schema2 config media type if need.

        NOTE: 1. original manifest will be deleted by next gc round. 2. don't cover manifest list.

        func DefaultHost

        func DefaultHost(ns string) (string, error)

          DefaultHost is the default host function.

          func GetGroupNames

          func GetGroupNames() []string

            GetGroupNames returns the list of Error group names that are registered

            func GetTokenScopes

            func GetTokenScopes(ctx context.Context, common []string) []string

              GetTokenScopes returns deduplicated and sorted scopes from ctx.Value(tokenScopesKey{}) and common scopes.

              func MatchAllHosts

              func MatchAllHosts(string) (bool, error)

                MatchAllHosts is a host match function which is always true.

                func MatchLocalhost

                func MatchLocalhost(host string) (bool, error)

                  MatchLocalhost is a host match function which returns true for localhost.

                  func NewResolver

                  func NewResolver(options ResolverOptions) remotes.Resolver

                    NewResolver returns a new resolver to a Docker registry

                    func WithScope

                    func WithScope(ctx context.Context, scope string) context.Context

                      WithScope appends a custom registry auth scope to the context.

                      Types

                      type Authorizer

                      type Authorizer interface {
                      	// Authorize sets the appropriate `Authorization` header on the given
                      	// request.
                      	//
                      	// If no authorization is found for the request, the request remains
                      	// unmodified. It may also add an `Authorization` header as
                      	//  "bearer <some bearer token>"
                      	//  "basic <base64 encoded credentials>"
                      	Authorize(context.Context, *http.Request) error
                      
                      	// AddResponses adds a 401 response for the authorizer to consider when
                      	// authorizing requests. The last response should be unauthorized and
                      	// the previous requests are used to consider redirects and retries
                      	// that may have led to the 401.
                      	//
                      	// If response is not handled, returns `ErrNotImplemented`
                      	AddResponses(context.Context, []*http.Response) error
                      }

                        Authorizer is used to authorize HTTP requests based on 401 HTTP responses. An Authorizer is responsible for caching tokens or credentials used by requests.

                        func NewAuthorizer

                        func NewAuthorizer(client *http.Client, f func(string) (string, string, error)) Authorizer

                          NewAuthorizer creates a Docker authorizer using the provided function to get credentials for the token server or basic auth. Deprecated: Use NewDockerAuthorizer

                          func NewDockerAuthorizer

                          func NewDockerAuthorizer(opts ...AuthorizerOpt) Authorizer

                            NewDockerAuthorizer creates an authorizer using Docker's registry authentication spec. See https://docs.docker.com/registry/spec/auth/

                            type AuthorizerOpt

                            type AuthorizerOpt func(*authorizerConfig)

                              AuthorizerOpt configures an authorizer

                              func WithAuthClient

                              func WithAuthClient(client *http.Client) AuthorizerOpt

                                WithAuthClient provides the HTTP client for the authorizer

                                func WithAuthCreds

                                func WithAuthCreds(creds func(string) (string, string, error)) AuthorizerOpt

                                  WithAuthCreds provides a credential function to the authorizer

                                  func WithAuthHeader

                                  func WithAuthHeader(hdr http.Header) AuthorizerOpt

                                    WithAuthHeader provides HTTP headers for authorization

                                    type Error

                                    type Error struct {
                                    	Code    ErrorCode   `json:"code"`
                                    	Message string      `json:"message"`
                                    	Detail  interface{} `json:"detail,omitempty"`
                                    }

                                      Error provides a wrapper around ErrorCode with extra Details provided.

                                      func (Error) Error

                                      func (e Error) Error() string

                                        Error returns a human readable representation of the error.

                                        func (Error) ErrorCode

                                        func (e Error) ErrorCode() ErrorCode

                                          ErrorCode returns the ID/Value of this Error

                                          func (Error) WithArgs

                                          func (e Error) WithArgs(args ...interface{}) Error

                                            WithArgs uses the passed-in list of interface{} as the substitution variables in the Error's Message string, but returns a new Error

                                            func (Error) WithDetail

                                            func (e Error) WithDetail(detail interface{}) Error

                                              WithDetail will return a new Error, based on the current one, but with some Detail info added

                                              type ErrorCode

                                              type ErrorCode int

                                                ErrorCode represents the error type. The errors are serialized via strings and the integer format may change and should *never* be exported.

                                                func ParseErrorCode

                                                func ParseErrorCode(value string) ErrorCode

                                                  ParseErrorCode returns the value by the string error code. `ErrorCodeUnknown` will be returned if the error is not known.

                                                  func Register

                                                  func Register(group string, descriptor ErrorDescriptor) ErrorCode

                                                    Register will make the passed-in error known to the environment and return a new ErrorCode

                                                    func (ErrorCode) Descriptor

                                                    func (ec ErrorCode) Descriptor() ErrorDescriptor

                                                      Descriptor returns the descriptor for the error code.

                                                      func (ErrorCode) Error

                                                      func (ec ErrorCode) Error() string

                                                        Error returns the ID/Value

                                                        func (ErrorCode) ErrorCode

                                                        func (ec ErrorCode) ErrorCode() ErrorCode

                                                          ErrorCode just returns itself

                                                          func (ErrorCode) MarshalText

                                                          func (ec ErrorCode) MarshalText() (text []byte, err error)

                                                            MarshalText encodes the receiver into UTF-8-encoded text and returns the result.

                                                            func (ErrorCode) Message

                                                            func (ec ErrorCode) Message() string

                                                              Message returned the human-readable error message for this error code.

                                                              func (ErrorCode) String

                                                              func (ec ErrorCode) String() string

                                                                String returns the canonical identifier for this error code.

                                                                func (*ErrorCode) UnmarshalText

                                                                func (ec *ErrorCode) UnmarshalText(text []byte) error

                                                                  UnmarshalText decodes the form generated by MarshalText.

                                                                  func (ErrorCode) WithArgs

                                                                  func (ec ErrorCode) WithArgs(args ...interface{}) Error

                                                                    WithArgs creates a new Error struct and sets the Args slice

                                                                    func (ErrorCode) WithDetail

                                                                    func (ec ErrorCode) WithDetail(detail interface{}) Error

                                                                      WithDetail creates a new Error struct based on the passed-in info and set the Detail property appropriately

                                                                      func (ErrorCode) WithMessage

                                                                      func (ec ErrorCode) WithMessage(message string) Error

                                                                        WithMessage creates a new Error struct based on the passed-in info and overrides the Message property.

                                                                        type ErrorCoder

                                                                        type ErrorCoder interface {
                                                                        	ErrorCode() ErrorCode
                                                                        }

                                                                          ErrorCoder is the base interface for ErrorCode and Error allowing users of each to just call ErrorCode to get the real ID of each

                                                                          type ErrorDescriptor

                                                                          type ErrorDescriptor struct {
                                                                          	// Code is the error code that this descriptor describes.
                                                                          	Code ErrorCode
                                                                          
                                                                          	// Value provides a unique, string key, often captilized with
                                                                          	// underscores, to identify the error code. This value is used as the
                                                                          	// keyed value when serializing api errors.
                                                                          	Value string
                                                                          
                                                                          	// Message is a short, human readable decription of the error condition
                                                                          	// included in API responses.
                                                                          	Message string
                                                                          
                                                                          	// Description provides a complete account of the errors purpose, suitable
                                                                          	// for use in documentation.
                                                                          	Description string
                                                                          
                                                                          	// HTTPStatusCode provides the http status code that is associated with
                                                                          	// this error condition.
                                                                          	HTTPStatusCode int
                                                                          }

                                                                            ErrorDescriptor provides relevant information about a given error code.

                                                                            func GetErrorAllDescriptors

                                                                            func GetErrorAllDescriptors() []ErrorDescriptor

                                                                              GetErrorAllDescriptors returns a slice of all ErrorDescriptors that are registered, irrespective of what group they're in

                                                                              func GetErrorCodeGroup

                                                                              func GetErrorCodeGroup(name string) []ErrorDescriptor

                                                                                GetErrorCodeGroup returns the named group of error descriptors

                                                                                type Errors

                                                                                type Errors []error

                                                                                  Errors provides the envelope for multiple errors and a few sugar methods for use within the application.

                                                                                  func (Errors) Error

                                                                                  func (errs Errors) Error() string

                                                                                  func (Errors) Len

                                                                                  func (errs Errors) Len() int

                                                                                    Len returns the current number of errors.

                                                                                    func (Errors) MarshalJSON

                                                                                    func (errs Errors) MarshalJSON() ([]byte, error)

                                                                                      MarshalJSON converts slice of error, ErrorCode or Error into a slice of Error - then serializes

                                                                                      func (*Errors) UnmarshalJSON

                                                                                      func (errs *Errors) UnmarshalJSON(data []byte) error

                                                                                        UnmarshalJSON deserializes []Error and then converts it into slice of Error or ErrorCode

                                                                                        type HostCapabilities

                                                                                        type HostCapabilities uint8

                                                                                          HostCapabilities represent the capabilities of the registry host. This also represents the set of operations for which the registry host may be trusted to perform.

                                                                                          For example pushing is a capability which should only be performed on an upstream source, not a mirror. Resolving (the process of converting a name into a digest) must be considered a trusted operation and only done by a host which is trusted (or more preferably by secure process which can prove the provenance of the mapping). A public mirror should never be trusted to do a resolve action.

                                                                                          | Registry Type | Pull | Resolve | Push | |------------------|------|---------|------| | Public Registry | yes | yes | yes | | Private Registry | yes | yes | yes | | Public Mirror | yes | no | no | | Private Mirror | yes | yes | no |

                                                                                          const (
                                                                                          	// HostCapabilityPull represents the capability to fetch manifests
                                                                                          	// and blobs by digest
                                                                                          	HostCapabilityPull HostCapabilities = 1 << iota
                                                                                          
                                                                                          	// HostCapabilityResolve represents the capability to fetch manifests
                                                                                          	// by name
                                                                                          	HostCapabilityResolve
                                                                                          
                                                                                          	// HostCapabilityPush represents the capability to push blobs and
                                                                                          	// manifests
                                                                                          	HostCapabilityPush
                                                                                          )

                                                                                          func (HostCapabilities) Has

                                                                                          type RegistryHost

                                                                                          type RegistryHost struct {
                                                                                          	Client       *http.Client
                                                                                          	Authorizer   Authorizer
                                                                                          	Host         string
                                                                                          	Scheme       string
                                                                                          	Path         string
                                                                                          	Capabilities HostCapabilities
                                                                                          	Header       http.Header
                                                                                          }

                                                                                            RegistryHost represents a complete configuration for a registry host, representing the capabilities, authorizations, connection configuration, and location.

                                                                                            type RegistryHosts

                                                                                            type RegistryHosts func(string) ([]RegistryHost, error)

                                                                                              RegistryHosts fetches the registry hosts for a given namespace, provided by the host component of an distribution image reference.

                                                                                              func ConfigureDefaultRegistries

                                                                                              func ConfigureDefaultRegistries(ropts ...RegistryOpt) RegistryHosts

                                                                                                ConfigureDefaultRegistries is used to create a default configuration for registries. For more advanced configurations or per-domain setups, the RegistryHosts interface should be used directly. NOTE: This function will always return a non-empty value or error

                                                                                                func Registries

                                                                                                func Registries(registries ...RegistryHosts) RegistryHosts

                                                                                                  Registries joins multiple registry configuration functions, using the same order as provided within the arguments. When an empty registry configuration is returned with a nil error, the next function will be called. NOTE: This function will not join configurations, as soon as a non-empty configuration is returned from a configuration function, it will be returned to the caller.

                                                                                                  type RegistryOpt

                                                                                                  type RegistryOpt func(*registryOpts)

                                                                                                    RegistryOpt defines a registry default option

                                                                                                    func WithAuthorizer

                                                                                                    func WithAuthorizer(a Authorizer) RegistryOpt

                                                                                                      WithAuthorizer configures the default authorizer for a registry

                                                                                                      func WithClient

                                                                                                      func WithClient(c *http.Client) RegistryOpt

                                                                                                        WithClient configures the default http client for a registry

                                                                                                        func WithHostTranslator

                                                                                                        func WithHostTranslator(h func(string) (string, error)) RegistryOpt

                                                                                                          WithHostTranslator defines the default translator to use for registry hosts

                                                                                                          func WithPlainHTTP

                                                                                                          func WithPlainHTTP(f func(string) (bool, error)) RegistryOpt

                                                                                                            WithPlainHTTP configures registries to use plaintext http scheme for the provided host match function.

                                                                                                            type ResolverOptions

                                                                                                            type ResolverOptions struct {
                                                                                                            	// Hosts returns registry host configurations for a namespace.
                                                                                                            	Hosts RegistryHosts
                                                                                                            
                                                                                                            	// Headers are the HTTP request header fields sent by the resolver
                                                                                                            	Headers http.Header
                                                                                                            
                                                                                                            	// Tracker is used to track uploads to the registry. This is used
                                                                                                            	// since the registry does not have upload tracking and the existing
                                                                                                            	// mechanism for getting blob upload status is expensive.
                                                                                                            	Tracker StatusTracker
                                                                                                            
                                                                                                            	// Authorizer is used to authorize registry requests
                                                                                                            	// Deprecated: use Hosts
                                                                                                            	Authorizer Authorizer
                                                                                                            
                                                                                                            	// Credentials provides username and secret given a host.
                                                                                                            	// If username is empty but a secret is given, that secret
                                                                                                            	// is interpreted as a long lived token.
                                                                                                            	// Deprecated: use Hosts
                                                                                                            	Credentials func(string) (string, string, error)
                                                                                                            
                                                                                                            	// Host provides the hostname given a namespace.
                                                                                                            	// Deprecated: use Hosts
                                                                                                            	Host func(string) (string, error)
                                                                                                            
                                                                                                            	// PlainHTTP specifies to use plain http and not https
                                                                                                            	// Deprecated: use Hosts
                                                                                                            	PlainHTTP bool
                                                                                                            
                                                                                                            	// Client is the http client to used when making registry requests
                                                                                                            	// Deprecated: use Hosts
                                                                                                            	Client *http.Client
                                                                                                            }

                                                                                                              ResolverOptions are used to configured a new Docker register resolver

                                                                                                              type Status

                                                                                                              type Status struct {
                                                                                                              	content.Status
                                                                                                              
                                                                                                              	// UploadUUID is used by the Docker registry to reference blob uploads
                                                                                                              	UploadUUID string
                                                                                                              }

                                                                                                                Status of a content operation

                                                                                                                type StatusTracker

                                                                                                                type StatusTracker interface {
                                                                                                                	GetStatus(string) (Status, error)
                                                                                                                	SetStatus(string, Status)
                                                                                                                }

                                                                                                                  StatusTracker to track status of operations

                                                                                                                  func NewInMemoryTracker

                                                                                                                  func NewInMemoryTracker() StatusTracker

                                                                                                                    NewInMemoryTracker returns a StatusTracker that tracks content status in-memory

                                                                                                                    Directories

                                                                                                                    Path Synopsis
                                                                                                                    config package containers utilities for helping configure the Docker resolver
                                                                                                                    config package containers utilities for helping configure the Docker resolver