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
- Variables
- func Router() *mux.Router
- type Error
- type ErrorCode
- type ErrorDescriptor
- type Errors
- type URLBuilder
- func (ub *URLBuilder) BuildBaseURL() (string, error)
- func (ub *URLBuilder) BuildBlobURL(name string, dgst string) (string, error)
- func (ub *URLBuilder) BuildBlobUploadChunkURL(name, uuid string, values ...url.Values) (string, error)
- func (ub *URLBuilder) BuildBlobUploadURL(name string, values ...url.Values) (string, error)
- func (ub *URLBuilder) BuildManifestURL(name, reference string) (string, error)
- func (ub *URLBuilder) BuildTagsURL(name string) (string, error)
Constants ¶
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 ¶
var DigestRegexp = regexp.MustCompile(`[a-zA-Z0-9-_+.]+:[a-zA-Z0-9-_+.=]+`)
DigestRegexp matches valid digest types.
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.
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.
var RepositoryNameRegexp = regexp.MustCompile(`(?:` + RepositoryNameComponentRegexp.String() + `/){0,4}` + RepositoryNameComponentRegexp.String())
RepositoryNameRegexp builds on RepositoryNameComponentRegexp to allow 1 to 5 path components, separated by a forward slash.
var TagNameRegexp = regexp.MustCompile(`[\w][\w.-]{0,127}`)
TagNameRegexp matches valid tag names. From docker/docker:graph/tags.go.
Functions ¶
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.
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 ¶
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 ¶
MarshalText encodes the receiver into UTF-8-encoded text and returns the result.
func (*ErrorCode) UnmarshalText ¶
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.
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 ¶
BuildBlobUploadURL constructs a url to begin a blob upload in the repository identified by name.
func (*URLBuilder) BuildManifestURL ¶
func (ub *URLBuilder) BuildManifestURL(name, reference string) (string, error)
BuildManifestURL constructs a url for the manifest identified by name and reference.
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