v2

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
• type BodyDescriptor
• type MethodDescriptor
• type ParameterDescriptor
• type RequestDescriptor
• type ResponseDescriptor
• type RouteDescriptor
• type URLBuilder
  • func NewURLBuilder(root *url.URL, relative bool) *URLBuilder
  • func NewURLBuilderFromRequest(r *http.Request, relative bool) *URLBuilder
  • func NewURLBuilderFromString(root string, relative bool) (*URLBuilder, error)
  • func (ub *URLBuilder) BuildBaseURL() (string, error)
  • func (ub *URLBuilder) BuildBlobURL(ref reference.Canonical) (string, error)
  • func (ub *URLBuilder) BuildBlobUploadChunkURL(name reference.Named, uuid string, values ...url.Values) (string, error)
  • func (ub *URLBuilder) BuildBlobUploadURL(name reference.Named, values ...url.Values) (string, error)
  • func (ub *URLBuilder) BuildCatalogURL(values ...url.Values) (string, error)
  • func (ub *URLBuilder) BuildManifestURL(ref reference.Named) (string, error)
  • func (ub *URLBuilder) BuildRegistriesURL(values ...url.Values) (string, error)
  • func (ub *URLBuilder) BuildTagsURL(name reference.Named) (string, error)

Constants

const (
	RouteNameBase            = "base"
	RouteNameManifest        = "manifest"
	RouteNameTags            = "tags"
	RouteNameBlob            = "blob"
	RouteNameBlobUpload      = "blob-upload"
	RouteNameBlobUploadChunk = "blob-upload-chunk"
	RouteNameCatalog         = "catalog"
	RouteNameRegistries      = "registries"
)

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 (
	// 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 verification.
	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 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.

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.

func RouterWithPrefix

func RouterWithPrefix(prefix string) *mux.Router

RouterWithPrefix builds a gorilla router with a configured prefix on all routes.

Types

type BodyDescriptor

type BodyDescriptor struct {
	ContentType string
	Format      string
}

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 particular 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 particular response.
	Name string

	// Description should provide a brief overview of the role of the
	// response.
	Description string

	// StatusCode specifies the status received 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, relative bool) *URLBuilder

NewURLBuilder creates a URLBuilder with provided root url object.

func NewURLBuilderFromRequest

func NewURLBuilderFromRequest(r *http.Request, relative bool) *URLBuilder

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

func NewURLBuilderFromString

func NewURLBuilderFromString(root string, relative bool) (*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(ref reference.Canonical) (string, error)

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

func (*URLBuilder) BuildBlobUploadChunkURL

func (ub *URLBuilder) BuildBlobUploadChunkURL(name reference.Named, 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 reference.Named, values ...url.Values) (string, error)

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(ref reference.Named) (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) BuildRegistriesURL

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

BuildRegistryURL constructs a url get a catalog of registreis

func (*URLBuilder) BuildTagsURL

func (ub *URLBuilder) BuildTagsURL(name reference.Named) (string, error)

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