github.com/dougm/docker@v1.5.0/registry/v2/descriptors.go (about)

     1  package v2
     2  
     3  import "net/http"
     4  
     5  // TODO(stevvooe): Add route descriptors for each named route, along with
     6  // accepted methods, parameters, returned status codes and error codes.
     7  
     8  // ErrorDescriptor provides relevant information about a given error code.
     9  type ErrorDescriptor struct {
    10  	// Code is the error code that this descriptor describes.
    11  	Code ErrorCode
    12  
    13  	// Value provides a unique, string key, often captilized with
    14  	// underscores, to identify the error code. This value is used as the
    15  	// keyed value when serializing api errors.
    16  	Value string
    17  
    18  	// Message is a short, human readable decription of the error condition
    19  	// included in API responses.
    20  	Message string
    21  
    22  	// Description provides a complete account of the errors purpose, suitable
    23  	// for use in documentation.
    24  	Description string
    25  
    26  	// HTTPStatusCodes provides a list of status under which this error
    27  	// condition may arise. If it is empty, the error condition may be seen
    28  	// for any status code.
    29  	HTTPStatusCodes []int
    30  }
    31  
    32  // ErrorDescriptors provides a list of HTTP API Error codes that may be
    33  // encountered when interacting with the registry API.
    34  var ErrorDescriptors = []ErrorDescriptor{
    35  	{
    36  		Code:    ErrorCodeUnknown,
    37  		Value:   "UNKNOWN",
    38  		Message: "unknown error",
    39  		Description: `Generic error returned when the error does not have an
    40  		API classification.`,
    41  	},
    42  	{
    43  		Code:    ErrorCodeDigestInvalid,
    44  		Value:   "DIGEST_INVALID",
    45  		Message: "provided digest did not match uploaded content",
    46  		Description: `When a blob is uploaded, the registry will check that
    47  		the content matches the digest provided by the client. The error may
    48  		include a detail structure with the key "digest", including the
    49  		invalid digest string. This error may also be returned when a manifest
    50  		includes an invalid layer digest.`,
    51  		HTTPStatusCodes: []int{http.StatusBadRequest, http.StatusNotFound},
    52  	},
    53  	{
    54  		Code:    ErrorCodeSizeInvalid,
    55  		Value:   "SIZE_INVALID",
    56  		Message: "provided length did not match content length",
    57  		Description: `When a layer is uploaded, the provided size will be
    58  		checked against the uploaded content. If they do not match, this error
    59  		will be returned.`,
    60  		HTTPStatusCodes: []int{http.StatusBadRequest},
    61  	},
    62  	{
    63  		Code:    ErrorCodeNameInvalid,
    64  		Value:   "NAME_INVALID",
    65  		Message: "manifest name did not match URI",
    66  		Description: `During a manifest upload, if the name in the manifest
    67  		does not match the uri name, this error will be returned.`,
    68  		HTTPStatusCodes: []int{http.StatusBadRequest, http.StatusNotFound},
    69  	},
    70  	{
    71  		Code:    ErrorCodeTagInvalid,
    72  		Value:   "TAG_INVALID",
    73  		Message: "manifest tag did not match URI",
    74  		Description: `During a manifest upload, if the tag in the manifest
    75  		does not match the uri tag, this error will be returned.`,
    76  		HTTPStatusCodes: []int{http.StatusBadRequest, http.StatusNotFound},
    77  	},
    78  	{
    79  		Code:    ErrorCodeNameUnknown,
    80  		Value:   "NAME_UNKNOWN",
    81  		Message: "repository name not known to registry",
    82  		Description: `This is returned if the name used during an operation is
    83  		unknown to the registry.`,
    84  		HTTPStatusCodes: []int{http.StatusNotFound},
    85  	},
    86  	{
    87  		Code:    ErrorCodeManifestUnknown,
    88  		Value:   "MANIFEST_UNKNOWN",
    89  		Message: "manifest unknown",
    90  		Description: `This error is returned when the manifest, identified by
    91  		name and tag is unknown to the repository.`,
    92  		HTTPStatusCodes: []int{http.StatusNotFound},
    93  	},
    94  	{
    95  		Code:    ErrorCodeManifestInvalid,
    96  		Value:   "MANIFEST_INVALID",
    97  		Message: "manifest invalid",
    98  		Description: `During upload, manifests undergo several checks ensuring
    99  		validity. If those checks fail, this error may be returned, unless a
   100  		more specific error is included. The detail will contain information
   101  		the failed validation.`,
   102  		HTTPStatusCodes: []int{http.StatusBadRequest},
   103  	},
   104  	{
   105  		Code:    ErrorCodeManifestUnverified,
   106  		Value:   "MANIFEST_UNVERIFIED",
   107  		Message: "manifest failed signature verification",
   108  		Description: `During manifest upload, if the manifest fails signature
   109  		verification, this error will be returned.`,
   110  		HTTPStatusCodes: []int{http.StatusBadRequest},
   111  	},
   112  	{
   113  		Code:    ErrorCodeBlobUnknown,
   114  		Value:   "BLOB_UNKNOWN",
   115  		Message: "blob unknown to registry",
   116  		Description: `This error may be returned when a blob is unknown to the
   117  		registry in a specified repository. This can be returned with a
   118  		standard get or if a manifest references an unknown layer during
   119  		upload.`,
   120  		HTTPStatusCodes: []int{http.StatusBadRequest, http.StatusNotFound},
   121  	},
   122  
   123  	{
   124  		Code:    ErrorCodeBlobUploadUnknown,
   125  		Value:   "BLOB_UPLOAD_UNKNOWN",
   126  		Message: "blob upload unknown to registry",
   127  		Description: `If a blob upload has been cancelled or was never
   128  		started, this error code may be returned.`,
   129  		HTTPStatusCodes: []int{http.StatusNotFound},
   130  	},
   131  }
   132  
   133  var errorCodeToDescriptors map[ErrorCode]ErrorDescriptor
   134  var idToDescriptors map[string]ErrorDescriptor
   135  
   136  func init() {
   137  	errorCodeToDescriptors = make(map[ErrorCode]ErrorDescriptor, len(ErrorDescriptors))
   138  	idToDescriptors = make(map[string]ErrorDescriptor, len(ErrorDescriptors))
   139  
   140  	for _, descriptor := range ErrorDescriptors {
   141  		errorCodeToDescriptors[descriptor.Code] = descriptor
   142  		idToDescriptors[descriptor.Value] = descriptor
   143  	}
   144  }