v2

package
v2.0.0-rc.3+incompatible Latest Latest
Warning

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

 Go to latest Published: Apr 10, 2015 License: Apache-2.0 Imports: 7 Imported by: 1,852

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 (
	// RepositoryNameComponentMinLength is the minimum number of characters in a
	// single repository name slash-delimited component
	RepositoryNameComponentMinLength = 2

	// RepositoryNameMinComponents is the minimum number of slash-delimited
	// components that a repository name must have
	RepositoryNameMinComponents = 1

	// RepositoryNameTotalLengthMax is the maximum total number of characters in
	// a repository name
	RepositoryNameTotalLengthMax = 255
)
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 (
	// ErrRepositoryNameComponentShort is returned when a repository name
	// contains a component which is shorter than
	// RepositoryNameComponentMinLength
	ErrRepositoryNameComponentShort = fmt.Errorf("respository name component must be %v or more characters", RepositoryNameComponentMinLength)

	// ErrRepositoryNameMissingComponents is returned when a repository name
	// contains fewer than RepositoryNameMinComponents components
	ErrRepositoryNameMissingComponents = fmt.Errorf("repository name must have at least %v components", RepositoryNameMinComponents)

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

	// ErrorDescriptors provides a list of the error codes and their
	// associated documentation and metadata.
	ErrorDescriptors []ErrorDescriptor
}{
	RouteDescriptors: routeDescriptors,
	ErrorDescriptors: errorDescriptors,
}

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

func ValidateRespositoryName(name string) error

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

	// ErrorCodeUnsupported is returned when an operation is not supported.
	ErrorCodeUnsupported

	// ErrorCodeUnauthorized is returned if a request is not authorized.
	ErrorCodeUnauthorized

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

	// ErrorCodeBlobUploadInvalid is returned when an upload is invalid.
	ErrorCodeBlobUploadInvalid
)

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

	// ErrorCodes enumerates the error codes that may be returned along with
	// the response.
	ErrorCodes []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) 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.