v2

package
v0.4.1-rc1 Latest Latest
Warning

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

 Go to latest Published: Nov 13, 2015 License: Apache-2.0, Apache-2.0 Imports: 8 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 in docker core.

Index

Constants

View Source 
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.

View Source 
const (
	// RepositoryNameTotalLengthMax is the maximum total number of characters in
	// a repository name
	RepositoryNameTotalLengthMax = 255
)

Variables

View Source 
var (
	// ErrorCodeUnsupported is returned when an operation is not supported.
	ErrorCodeUnsupported = errcode.Register(errGroup, errcode.ErrorDescriptor{
		Value:   "UNSUPPORTED",
		Message: "The operation is unsupported.",
		Description: `The operation was unsupported due to a missing
		implementation or invalid set of parameters.`,
	})

	// ErrorCodeUnauthorized is returned if a request is not authorized.
	ErrorCodeUnauthorized = errcode.Register(errGroup, errcode.ErrorDescriptor{
		Value:   "UNAUTHORIZED",
		Message: "access to the requested resource is not authorized",
		Description: `The access controller denied access for the operation on
		a resource. Often this will be accompanied by a 401 Unauthorized
		response status.`,
		HTTPStatusCode: http.StatusUnauthorized,
	})

	// 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,
	})
)
View Source 
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())
)
View Source 
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.

View Source 
var RepositoryNameComponentAnchoredRegexp = regexp.MustCompile(`^` + RepositoryNameComponentRegexp.String() + `$`)

RepositoryNameComponentAnchoredRegexp is the version of RepositoryNameComponentRegexp which must completely match the content

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

RepositoryNameComponentRegexp restricts registry path component names to start with at least one letter or number, with following parts able to be separated by one period, dash or underscore.

View Source 
var RepositoryNameRegexp = regexp.MustCompile(`(?:` + RepositoryNameComponentRegexp.String() + `/)*` + RepositoryNameComponentRegexp.String())

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

View Source 
var TagNameAnchoredRegexp = regexp.MustCompile("^" + TagNameRegexp.String() + "$")

TagNameAnchoredRegexp matches valid tag names, anchored at the start and end of the matched string.

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.

func RouterWithPrefix 

func RouterWithPrefix(prefix string) *mux.Router

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

func ValidateRepositoryName 

func ValidateRepositoryName(name string) error

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 

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

func (ub *URLBuilder) BuildBlobURL(name string, dgst digest.Digest) (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) 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.

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.