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 in docker core.
Index ¶
- Constants
- Variables
- func Router() *mux.Router
- func RouterWithPrefix(prefix string) *mux.Router
- func ValidateRepositoryName(name string) error
- type BodyDescriptor
- type MethodDescriptor
- type ParameterDescriptor
- type RequestDescriptor
- type ResponseDescriptor
- type RouteDescriptor
- type URLBuilder
- func (ub *URLBuilder) BuildBaseURL() (string, error)
- func (ub *URLBuilder) BuildBlobURL(name string, dgst digest.Digest) (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) BuildCatalogURL(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" RouteNameCatalog = "catalog" )
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.
const ( // RepositoryNameTotalLengthMax is the maximum total number of characters in // a repository name RepositoryNameTotalLengthMax = 255 )
Variables ¶
var ( // ErrorCodeDigestInvalid is returned when uploading a blob if the // provided digest does not match the blob contents. ErrorCodeDigestInvalid = errcode.Register(errGroup, errcode.ErrorDescriptor{ 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.`, HTTPStatusCode: http.StatusBadRequest, }) // ErrorCodeSizeInvalid is returned when uploading a blob if the provided ErrorCodeSizeInvalid = errcode.Register(errGroup, errcode.ErrorDescriptor{ 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.`, HTTPStatusCode: http.StatusBadRequest, }) // ErrorCodeNameInvalid is returned when the name in the manifest does not // match the provided name. ErrorCodeNameInvalid = errcode.Register(errGroup, errcode.ErrorDescriptor{ Value: "NAME_INVALID", Message: "invalid repository name", Description: `Invalid repository name encountered either during manifest validation or any API operation.`, HTTPStatusCode: http.StatusBadRequest, }) // ErrorCodeTagInvalid is returned when the tag in the manifest does not // match the provided tag. ErrorCodeTagInvalid = errcode.Register(errGroup, errcode.ErrorDescriptor{ 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.`, HTTPStatusCode: http.StatusBadRequest, }) // ErrorCodeNameUnknown when the repository name is not known. ErrorCodeNameUnknown = errcode.Register(errGroup, errcode.ErrorDescriptor{ 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.`, HTTPStatusCode: http.StatusNotFound, }) // ErrorCodeManifestUnknown returned when image manifest is unknown. ErrorCodeManifestUnknown = errcode.Register(errGroup, errcode.ErrorDescriptor{ Value: "MANIFEST_UNKNOWN", Message: "manifest unknown", Description: `This error is returned when the manifest, identified by name and tag is unknown to the repository.`, HTTPStatusCode: http.StatusNotFound, }) // 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 = errcode.Register(errGroup, errcode.ErrorDescriptor{ 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.`, HTTPStatusCode: http.StatusBadRequest, }) // ErrorCodeManifestUnverified is returned when the manifest fails // signature verfication. ErrorCodeManifestUnverified = errcode.Register(errGroup, errcode.ErrorDescriptor{ Value: "MANIFEST_UNVERIFIED", Message: "manifest failed signature verification", Description: `During manifest upload, if the manifest fails signature verification, this error will be returned.`, HTTPStatusCode: http.StatusBadRequest, }) // ErrorCodeManifestBlobUnknown is returned when a manifest blob is // unknown to the registry. ErrorCodeManifestBlobUnknown = errcode.Register(errGroup, errcode.ErrorDescriptor{ Value: "MANIFEST_BLOB_UNKNOWN", Message: "blob unknown to registry", Description: `This error may be returned when a manifest blob is unknown to the registry.`, HTTPStatusCode: http.StatusBadRequest, }) // 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 = errcode.Register(errGroup, errcode.ErrorDescriptor{ 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.`, HTTPStatusCode: http.StatusNotFound, }) // ErrorCodeBlobUploadUnknown is returned when an upload is unknown. ErrorCodeBlobUploadUnknown = errcode.Register(errGroup, errcode.ErrorDescriptor{ 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.`, HTTPStatusCode: http.StatusNotFound, }) // ErrorCodeBlobUploadInvalid is returned when an upload is invalid. ErrorCodeBlobUploadInvalid = errcode.Register(errGroup, errcode.ErrorDescriptor{ Value: "BLOB_UPLOAD_INVALID", Message: "blob upload invalid", Description: `The blob upload encountered an error and can no longer proceed.`, HTTPStatusCode: http.StatusNotFound, }) )
var ( // ErrRepositoryNameEmpty is returned for empty, invalid repository names. ErrRepositoryNameEmpty = fmt.Errorf("repository name must have at least one component") // ErrRepositoryNameLong is returned when a repository name is longer than // RepositoryNameTotalLengthMax ErrRepositoryNameLong = fmt.Errorf("repository name must not be more than %v characters", RepositoryNameTotalLengthMax) // ErrRepositoryNameComponentInvalid is returned when a repository name does // not match RepositoryNameComponentRegexp ErrRepositoryNameComponentInvalid = fmt.Errorf("repository name component must match %q", RepositoryNameComponentRegexp.String()) )
var APIDescriptor = struct { // RouteDescriptors provides a list of the routes available in the API. RouteDescriptors []RouteDescriptor }{ RouteDescriptors: routeDescriptors, }
APIDescriptor exports descriptions of the layout of the v2 registry API.
var RepositoryNameComponentAnchoredRegexp = regexp.MustCompile(`^` + RepositoryNameComponentRegexp.String() + `$`)
RepositoryNameComponentAnchoredRegexp is the version of RepositoryNameComponentRegexp which must completely match the content
var RepositoryNameComponentRegexp = regexp.MustCompile(
domainLabelRegexp.String() + `(?:[._]` + domainLabelRegexp.String() + `)*`)
RepositoryNameComponentRegexp restricts registry path component names to the allow valid hostnames according to: https://www.ietf.org/rfc/rfc2396.txt with the following differences:
- It DOES NOT allow for fully-qualified domain names, which include a trailing '.', e.g. "google.com."
- It DOES NOT restrict 'top-level' domain labels to start with just alpha characters.
- It DOES allow for underscores to appear in the same situations as dots.
RFC-2396 uses the BNF construct:
hostname = *( domainlabel "." ) toplabel [ "." ]
var RepositoryNameRegexp = regexp.MustCompile(`(?:` + RepositoryNameComponentRegexp.String() + `/)*` + RepositoryNameComponentRegexp.String())
RepositoryNameRegexp builds on RepositoryNameComponentRegexp to allow multiple path components, separated by a forward slash.
var TagNameAnchoredRegexp = regexp.MustCompile("^" + TagNameRegexp.String() + "$")
TagNameAnchoredRegexp matches valid tag names, anchored at the start and end of the matched string.
var TagNameRegexp = regexp.MustCompile(`[\w][\w.-]{0,127}`)
TagNameRegexp matches valid tag names. From docker/docker:graph/tags.go.
Functions ¶
func 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.
func RouterWithPrefix ¶
RouterWithPrefix builds a gorilla router with a configured prefix on all routes.
func ValidateRepositoryName ¶
ValidateRepositoryName ensures the repository name is valid for use in the registry. This function accepts a superset of what might be accepted by docker core or docker hub. If the name does not pass validation, an error, describing the conditions, is returned.
Effectively, the name should comply with the following grammar:
alpha-numeric := /[a-z0-9]+/ separator := /[._-]/ component := alpha-numeric [separator alpha-numeric]* namespace := component ['/' component]*
The result of the production, known as the "namespace", should be limited to 255 characters.
Types ¶
type BodyDescriptor ¶
BodyDescriptor describes a request body and its expected content type. For the most part, it should be example json or some placeholder for body data in documentation.
type MethodDescriptor ¶
type MethodDescriptor struct { // Method is an HTTP method, such as GET, PUT or POST. Method string // Description should provide an overview of the functionality provided by // the covered method, suitable for use in documentation. Use of markdown // here is encouraged. Description string // Requests is a slice of request descriptors enumerating how this // endpoint may be used. Requests []RequestDescriptor }
MethodDescriptor provides a description of the requests that may be conducted with the target method.
type ParameterDescriptor ¶
type ParameterDescriptor struct { // Name is the name of the parameter, either of the path component or // query parameter. Name string // Type specifies the type of the parameter, such as string, integer, etc. Type string // Description provides a human-readable description of the parameter. Description string // Required means the field is required when set. Required bool // Format is a specifying the string format accepted by this parameter. Format string // Regexp is a compiled regular expression that can be used to validate // the contents of the parameter. Regexp *regexp.Regexp // Examples provides multiple examples for the values that might be valid // for this parameter. Examples []string }
ParameterDescriptor describes the format of a request parameter, which may be a header, path parameter or query parameter.
type RequestDescriptor ¶
type RequestDescriptor struct { // Name provides a short identifier for the request, usable as a title or // to provide quick context for the particalar request. Name string // Description should cover the requests purpose, covering any details for // this particular use case. Description string // Headers describes headers that must be used with the HTTP request. Headers []ParameterDescriptor // PathParameters enumerate the parameterized path components for the // given request, as defined in the route's regular expression. PathParameters []ParameterDescriptor // QueryParameters provides a list of query parameters for the given // request. QueryParameters []ParameterDescriptor // Body describes the format of the request body. Body BodyDescriptor // Successes enumerates the possible responses that are considered to be // the result of a successful request. Successes []ResponseDescriptor // Failures covers the possible failures from this particular request. Failures []ResponseDescriptor }
RequestDescriptor covers a particular set of headers and parameters that can be carried out with the parent method. Its most helpful to have one RequestDescriptor per API use case.
type ResponseDescriptor ¶
type ResponseDescriptor struct { // Name provides a short identifier for the response, usable as a title or // to provide quick context for the particalar response. Name string // Description should provide a brief overview of the role of the // response. Description string // StatusCode specifies the status recieved by this particular response. StatusCode int // Headers covers any headers that may be returned from the response. Headers []ParameterDescriptor // Fields describes any fields that may be present in the response. Fields []ParameterDescriptor // ErrorCodes enumerates the error codes that may be returned along with // the response. ErrorCodes []errcode.ErrorCode // Body describes the body of the response, if any. Body BodyDescriptor }
ResponseDescriptor describes the components of an API response.
type RouteDescriptor ¶
type RouteDescriptor struct { // Name is the name of the route, as specified in RouteNameXXX exports. // These names a should be considered a unique reference for a route. If // the route is registered with gorilla, this is the name that will be // used. Name string // Path is a gorilla/mux-compatible regexp that can be used to match the // route. For any incoming method and path, only one route descriptor // should match. Path string // Entity should be a short, human-readalbe description of the object // targeted by the endpoint. Entity string // Description should provide an accurate overview of the functionality // provided by the route. Description string // Methods should describe the various HTTP methods that may be used on // this route, including request and response formats. Methods []MethodDescriptor }
RouteDescriptor describes a route specified by name.
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 ¶
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) BuildCatalogURL ¶
func (ub *URLBuilder) BuildCatalogURL(values ...url.Values) (string, error)
BuildCatalogURL constructs a url get a catalog of repositories
func (*URLBuilder) BuildManifestURL ¶
func (ub *URLBuilder) BuildManifestURL(name, reference string) (string, error)
BuildManifestURL constructs a url for the manifest identified by name and reference. The argument reference may be either a tag or digest.
func (*URLBuilder) BuildTagsURL ¶
func (ub *URLBuilder) BuildTagsURL(name string) (string, error)
BuildTagsURL constructs a url to list the tags in the named repository.