errcode

Documentation

Index

• Variables
• func GetGroupNames() []string
• func ServeJSON(w http.ResponseWriter, err error) error
• type Error
  • func (e Error) Error() string
  • func (e Error) ErrorCode() ErrorCode
  • func (e Error) WithArgs(args ...interface{}) Error
  • func (e Error) WithDetail(detail interface{}) Error
• type ErrorCode
  • func ParseErrorCode(value string) ErrorCode
  • func Register(group string, descriptor ErrorDescriptor) ErrorCode
  • func (ec ErrorCode) Descriptor() ErrorDescriptor
  • func (ec ErrorCode) Error() string
  • func (ec ErrorCode) ErrorCode() ErrorCode
  • func (ec ErrorCode) MarshalText() (text []byte, err error)
  • func (ec ErrorCode) Message() string
  • func (ec ErrorCode) String() string
  • func (ec *ErrorCode) UnmarshalText(text []byte) error
  • func (ec ErrorCode) WithArgs(args ...interface{}) Error
  • func (ec ErrorCode) WithDetail(detail interface{}) Error
  • func (ec ErrorCode) WithMessage(message string) Error
• type ErrorCoder
• type ErrorDescriptor
  • func GetErrorAllDescriptors() []ErrorDescriptor
  • func GetErrorCodeGroup(name string) []ErrorDescriptor
• type Errors
  • func (errs Errors) Error() string
  • func (errs Errors) Len() int
  • func (errs Errors) MarshalJSON() ([]byte, error)
  • func (errs *Errors) UnmarshalJSON(data []byte) error

Variables

var (
	// ErrorCodeUnknown is a generic error that can be used as a last
	// resort if there is no situation-specific error message that can be used
	ErrorCodeUnknown = register("errcode", ErrorDescriptor{
		Value:   "UNKNOWN",
		Message: "unknown error",
		Description: `Generic error returned when the error does not have an
			                                            API classification.`,
		HTTPStatusCode: http.StatusInternalServerError,
	})

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

	// ErrorCodeUnauthorized is returned if a request requires
	// authentication.
	ErrorCodeUnauthorized = register("errcode", ErrorDescriptor{
		Value:   "UNAUTHORIZED",
		Message: "authentication required",
		Description: `The access controller was unable to authenticate
		the client. Often this will be accompanied by a
		Www-Authenticate HTTP response header indicating how to
		authenticate.`,
		HTTPStatusCode: http.StatusUnauthorized,
	})

	// ErrorCodeDenied is returned if a client does not have sufficient
	// permission to perform an action.
	ErrorCodeDenied = register("errcode", ErrorDescriptor{
		Value:   "DENIED",
		Message: "requested access to the resource is denied",
		Description: `The access controller denied access for the
		operation on a resource.`,
		HTTPStatusCode: http.StatusForbidden,
	})

	// ErrorCodeUnavailable provides a common error to report unavailability
	// of a service or endpoint.
	ErrorCodeUnavailable = register("errcode", ErrorDescriptor{
		Value:          "UNAVAILABLE",
		Message:        "service unavailable",
		Description:    "Returned when a service is not available",
		HTTPStatusCode: http.StatusServiceUnavailable,
	})

	// ErrorCodeTooManyRequests is returned if a client attempts too many
	// times to contact a service endpoint.
	ErrorCodeTooManyRequests = register("errcode", ErrorDescriptor{
		Value:   "TOOMANYREQUESTS",
		Message: "too many requests",
		Description: `Returned when a client attempts to contact a
		service too many times`,
		HTTPStatusCode: http.StatusTooManyRequests,
	})
)

var (
	// ErrorCodeDigestInvalid is returned when uploading a blob if the
	// provided digest does not match the blob contents.
	ErrorCodeDigestInvalid = register(errGroup, 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 = register(errGroup, 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,
	})

	// ErrorCodeRangeInvalid is returned when uploading a blob if the provided
	// content range is invalid.
	ErrorCodeRangeInvalid = register(errGroup, ErrorDescriptor{
		Value:   "RANGE_INVALID",
		Message: "invalid content range",
		Description: `When a layer is uploaded, the provided range is checked
		against the uploaded chunk. This error is returned if the range is
		out of order.`,
		HTTPStatusCode: http.StatusRequestedRangeNotSatisfiable,
	})

	// ErrorCodeNameInvalid is returned when the name in the manifest does not
	// match the provided name.
	ErrorCodeNameInvalid = register(errGroup, 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 = register(errGroup, 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 = register(errGroup, 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 = register(errGroup, 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 = register(errGroup, 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 = register(errGroup, 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 = register(errGroup, 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 = register(errGroup, 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 = register(errGroup, 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 = register(errGroup, ErrorDescriptor{
		Value:   "BLOB_UPLOAD_INVALID",
		Message: "blob upload invalid",
		Description: `The blob upload encountered an error and can no
		longer proceed.`,
		HTTPStatusCode: http.StatusNotFound,
	})

	// ErrorCodePaginationNumberInvalid is returned when the `n` parameter is
	// not an integer, or `n` is negative.
	ErrorCodePaginationNumberInvalid = register(errGroup, ErrorDescriptor{
		Value:   "PAGINATION_NUMBER_INVALID",
		Message: "invalid number of results requested",
		Description: `Returned when the "n" parameter (number of results
		to return) is not an integer, "n" is negative or "n" is bigger than
		the maximum allowed.`,
		HTTPStatusCode: http.StatusBadRequest,
	})
)

Functions

func GetGroupNames

func GetGroupNames() []string

GetGroupNames returns the list of Error group names that are registered

func ServeJSON

func ServeJSON(w http.ResponseWriter, err error) error

ServeJSON attempts to serve the errcode in a JSON envelope. It marshals err and sets the content-type header to 'application/json'. It will handle ErrorCoder and Errors, and if necessary will create an envelope.

Types

type Error

type Error struct {
	Code    ErrorCode   `json:"code"`
	Message string      `json:"message"`
	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.

func (Error) ErrorCode

func (e Error) ErrorCode() ErrorCode

ErrorCode returns the ID/Value of this Error

func (Error) WithArgs

func (e Error) WithArgs(args ...interface{}) Error

WithArgs uses the passed-in list of interface{} as the substitution variables in the Error's Message string, but returns a new Error

func (Error) WithDetail

func (e Error) WithDetail(detail interface{}) Error

WithDetail will return a new Error, based on the current one, but with some Detail info added

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.

func ParseErrorCode

func ParseErrorCode(value string) ErrorCode

ParseErrorCode returns the value by the string error code. `ErrorCodeUnknown` will be returned if the error is not known.

func Register

func Register(group string, descriptor ErrorDescriptor) ErrorCode

Register will make the passed-in error known to the environment and return a new ErrorCode

func (ErrorCode) Descriptor

func (ec ErrorCode) Descriptor() ErrorDescriptor

Descriptor returns the descriptor for the error code.

func (ErrorCode) Error

func (ec ErrorCode) Error() string

Error returns the ID/Value

func (ErrorCode) ErrorCode

func (ec ErrorCode) ErrorCode() ErrorCode

ErrorCode just returns itself

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.

func (ErrorCode) WithArgs

func (ec ErrorCode) WithArgs(args ...interface{}) Error

WithArgs creates a new Error struct and sets the Args slice

func (ErrorCode) WithDetail

func (ec ErrorCode) WithDetail(detail interface{}) Error

WithDetail creates a new Error struct based on the passed-in info and set the Detail property appropriately

func (ErrorCode) WithMessage

func (ec ErrorCode) WithMessage(message string) Error

WithMessage creates a new Error struct based on the passed-in info and overrides the Message property.

type ErrorCoder

type ErrorCoder interface {
	ErrorCode() ErrorCode
}

ErrorCoder is the base interface for ErrorCode and Error allowing users of each to just call ErrorCode to get the real ID of each

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

	// HTTPStatusCode provides the http status code that is associated with
	// this error condition.
	HTTPStatusCode int
}

ErrorDescriptor provides relevant information about a given error code.

func GetErrorAllDescriptors

func GetErrorAllDescriptors() []ErrorDescriptor

GetErrorAllDescriptors returns a slice of all ErrorDescriptors that are registered, irrespective of what group they're in

func GetErrorCodeGroup

func GetErrorCodeGroup(name string) []ErrorDescriptor

GetErrorCodeGroup returns the named group of error descriptors

type Errors

type Errors []error

Errors provides the envelope for multiple errors and a few sugar methods for use within the application.

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

func (errs Errors) MarshalJSON() ([]byte, error)

MarshalJSON converts slice of error, ErrorCode or Error into a slice of Error - then serializes

func (*Errors) UnmarshalJSON

func (errs *Errors) UnmarshalJSON(data []byte) error

UnmarshalJSON deserializes []Error and then converts it into slice of Error or ErrorCode