v2

package
v1.5.0-rc1 Latest Latest
Warning

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

 Go to latest Published: Jan 22, 2015 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package v2 describes routes, urls and the error codes used in the Docker Registry JSON HTTP API V2. In addition to declarations, descriptors are provided for routes and error codes that can be used for implementation and automatically generating documentation.

Definitions here are considered to be locked down for the V2 registry api. Any changes must be considered carefully and should not proceed without a change proposal.

Currently, while the HTTP API definitions are considered stable, the Go API exports are considered unstable. Go API consumers should take care when relying on these definitions until this message is deleted.

Index

Constants

View Source 
const (
	RouteNameBase            = "base"
	RouteNameManifest        = "manifest"
	RouteNameTags            = "tags"
	RouteNameBlob            = "blob"
	RouteNameBlobUpload      = "blob-upload"
	RouteNameBlobUploadChunk = "blob-upload-chunk"
)

The following are definitions of the name under which all V2 routes are registered. These symbols can be used to look up a route based on the name.

Variables

View Source 
var ErrorDescriptors = []ErrorDescriptor{
	{
		Code:    ErrorCodeUnknown,
		Value:   "UNKNOWN",
		Message: "unknown error",
		Description: `Generic error returned when the error does not have an
		API classification.`,
	},
	{
		Code:    ErrorCodeDigestInvalid,
		Value:   "DIGEST_INVALID",
		Message: "provided digest did not match uploaded content",
		Description: `When a blob is uploaded, the registry will check that
		the content matches the digest provided by the client. The error may
		include a detail structure with the key "digest", including the
		invalid digest string. This error may also be returned when a manifest
		includes an invalid layer digest.`,
		HTTPStatusCodes: []int{http.StatusBadRequest, http.StatusNotFound},
	},
	{
		Code:    ErrorCodeSizeInvalid,
		Value:   "SIZE_INVALID",
		Message: "provided length did not match content length",
		Description: `When a layer is uploaded, the provided size will be
		checked against the uploaded content. If they do not match, this error
		will be returned.`,
		HTTPStatusCodes: []int{http.StatusBadRequest},
	},
	{
		Code:    ErrorCodeNameInvalid,
		Value:   "NAME_INVALID",
		Message: "manifest name did not match URI",
		Description: `During a manifest upload, if the name in the manifest
		does not match the uri name, this error will be returned.`,
		HTTPStatusCodes: []int{http.StatusBadRequest, http.StatusNotFound},
	},
	{
		Code:    ErrorCodeTagInvalid,
		Value:   "TAG_INVALID",
		Message: "manifest tag did not match URI",
		Description: `During a manifest upload, if the tag in the manifest
		does not match the uri tag, this error will be returned.`,
		HTTPStatusCodes: []int{http.StatusBadRequest, http.StatusNotFound},
	},
	{
		Code:    ErrorCodeNameUnknown,
		Value:   "NAME_UNKNOWN",
		Message: "repository name not known to registry",
		Description: `This is returned if the name used during an operation is
		unknown to the registry.`,
		HTTPStatusCodes: []int{http.StatusNotFound},
	},
	{
		Code:    ErrorCodeManifestUnknown,
		Value:   "MANIFEST_UNKNOWN",
		Message: "manifest unknown",
		Description: `This error is returned when the manifest, identified by
		name and tag is unknown to the repository.`,
		HTTPStatusCodes: []int{http.StatusNotFound},
	},
	{
		Code:    ErrorCodeManifestInvalid,
		Value:   "MANIFEST_INVALID",
		Message: "manifest invalid",
		Description: `During upload, manifests undergo several checks ensuring
		validity. If those checks fail, this error may be returned, unless a
		more specific error is included. The detail will contain information
		the failed validation.`,
		HTTPStatusCodes: []int{http.StatusBadRequest},
	},
	{
		Code:    ErrorCodeManifestUnverified,
		Value:   "MANIFEST_UNVERIFIED",
		Message: "manifest failed signature verification",
		Description: `During manifest upload, if the manifest fails signature
		verification, this error will be returned.`,
		HTTPStatusCodes: []int{http.StatusBadRequest},
	},
	{
		Code:    ErrorCodeBlobUnknown,
		Value:   "BLOB_UNKNOWN",
		Message: "blob unknown to registry",
		Description: `This error may be returned when a blob is unknown to the
		registry in a specified repository. This can be returned with a
		standard get or if a manifest references an unknown layer during
		upload.`,
		HTTPStatusCodes: []int{http.StatusBadRequest, http.StatusNotFound},
	},

	{
		Code:    ErrorCodeBlobUploadUnknown,
		Value:   "BLOB_UPLOAD_UNKNOWN",
		Message: "blob upload unknown to registry",
		Description: `If a blob upload has been cancelled or was never
		started, this error code may be returned.`,
		HTTPStatusCodes: []int{http.StatusNotFound},
	},
}

ErrorDescriptors provides a list of HTTP API Error codes that may be encountered when interacting with the registry API.

View Source 
var RepositoryNameComponentRegexp = regexp.MustCompile(`[a-z0-9]+(?:[._-][a-z0-9]+)*`)

RepositoryNameComponentRegexp restricts registtry path components names to start with at least two letters or numbers, with following parts able to separated by one period, dash or underscore.

View Source 
var RepositoryNameRegexp = regexp.MustCompile(`(?:` + RepositoryNameComponentRegexp.String() + `/){1,4}` + RepositoryNameComponentRegexp.String())

RepositoryNameRegexp builds on RepositoryNameComponentRegexp to allow 2 to 5 path components, separated by a forward slash.

View Source 
var TagNameRegexp = regexp.MustCompile(`[\w][\w.-]{0,127}`)

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

Functions

func Router 

func Router() *mux.Router

Router builds a gorilla router with named routes for the various API methods. This can be used directly by both server implementations and clients.

Types

type Error 

type Error struct {
	Code    ErrorCode   `json:"code"`
	Message string      `json:"message,omitempty"`
	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.

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. 

const (
	// ErrorCodeUnknown is a catch-all for errors not defined below.
	ErrorCodeUnknown ErrorCode = iota

	// ErrorCodeDigestInvalid is returned when uploading a blob if the
	// provided digest does not match the blob contents.
	ErrorCodeDigestInvalid

	// ErrorCodeSizeInvalid is returned when uploading a blob if the provided
	// size does not match the content length.
	ErrorCodeSizeInvalid

	// ErrorCodeNameInvalid is returned when the name in the manifest does not
	// match the provided name.
	ErrorCodeNameInvalid

	// ErrorCodeTagInvalid is returned when the tag in the manifest does not
	// match the provided tag.
	ErrorCodeTagInvalid

	// ErrorCodeNameUnknown when the repository name is not known.
	ErrorCodeNameUnknown

	// ErrorCodeManifestUnknown returned when image manifest is unknown.
	ErrorCodeManifestUnknown

	// ErrorCodeManifestInvalid returned when an image manifest is invalid,
	// typically during a PUT operation. This error encompasses all errors
	// encountered during manifest validation that aren't signature errors.
	ErrorCodeManifestInvalid

	// ErrorCodeManifestUnverified is returned when the manifest fails
	// signature verfication.
	ErrorCodeManifestUnverified

	// ErrorCodeBlobUnknown is returned when a blob is unknown to the
	// registry. This can happen when the manifest references a nonexistent
	// layer or the result is not found by a blob fetch.
	ErrorCodeBlobUnknown

	// ErrorCodeBlobUploadUnknown is returned when an upload is unknown.
	ErrorCodeBlobUploadUnknown
)

func ParseErrorCode 

func ParseErrorCode(s string) ErrorCode

ParseErrorCode attempts to parse the error code string, returning ErrorCodeUnknown if the error is not known.

func (ErrorCode) Descriptor 

func (ec ErrorCode) Descriptor() ErrorDescriptor

Descriptor returns the descriptor for the error code.

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.

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

	// HTTPStatusCodes provides a list of status under which this error
	// condition may arise. If it is empty, the error condition may be seen
	// for any status code.
	HTTPStatusCodes []int
}

ErrorDescriptor provides relevant information about a given error code.

type Errors 

type Errors struct {
	Errors []Error `json:"errors,omitempty"`
}

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

func (*Errors) Clear 

func (errs *Errors) Clear()

Clear clears the errors.

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

func (errs *Errors) Push(code ErrorCode, details ...interface{})

Push pushes an error on to the error stack, with the optional detail argument. It is a programming error (ie panic) to push more than one detail at a time.

func (*Errors) PushErr 

func (errs *Errors) PushErr(err error)

PushErr pushes an error interface onto the error stack.

type URLBuilder 

type URLBuilder struct {
	// contains filtered or unexported fields
}

URLBuilder creates registry API urls from a single base endpoint. It can be used to create urls for use in a registry client or server.

All urls will be created from the given base, including the api version. For example, if a root of "/foo/" is provided, urls generated will be fall under "/foo/v2/...". Most application will only provide a schema, host and port, such as "https://localhost:5000/".

func NewURLBuilder 

func NewURLBuilder(root *url.URL) *URLBuilder

NewURLBuilder creates a URLBuilder with provided root url object.

func NewURLBuilderFromRequest 

func NewURLBuilderFromRequest(r *http.Request) *URLBuilder

NewURLBuilderFromRequest uses information from an *http.Request to construct the root url.

func NewURLBuilderFromString 

func NewURLBuilderFromString(root string) (*URLBuilder, error)

NewURLBuilderFromString workes identically to NewURLBuilder except it takes a string argument for the root, returning an error if it is not a valid url.

func (*URLBuilder) BuildBaseURL 

func (ub *URLBuilder) BuildBaseURL() (string, error)

BuildBaseURL constructs a base url for the API, typically just "/v2/".

func (*URLBuilder) BuildBlobURL 

func (ub *URLBuilder) BuildBlobURL(name string, dgst string) (string, error)

BuildBlobURL constructs the url for the blob identified by name and dgst.

func (*URLBuilder) BuildBlobUploadChunkURL 

func (ub *URLBuilder) BuildBlobUploadChunkURL(name, uuid string, values ...url.Values) (string, error)

BuildBlobUploadChunkURL constructs a url for the upload identified by uuid, including any url values. This should generally not be used by clients, as this url is provided by server implementations during the blob upload process.

func (*URLBuilder) BuildBlobUploadURL 

func (ub *URLBuilder) BuildBlobUploadURL(name string, values ...url.Values) (string, error)

BuildBlobUploadURL constructs a url to begin a blob upload in the repository identified by name.

func (*URLBuilder) BuildManifestURL 

func (ub *URLBuilder) BuildManifestURL(name, tag string) (string, error)

BuildManifestURL constructs a url for the manifest identified by name and tag.

func (*URLBuilder) BuildTagsURL 

func (ub *URLBuilder) BuildTagsURL(name string) (string, error)

BuildTagsURL constructs a url to list the tags in the named repository.

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.