From f46a1b73e8d7b26716a5164afd7f9fc756e7fca7 Mon Sep 17 00:00:00 2001 From: Stephen J Day Date: Wed, 25 Feb 2015 18:04:28 -0800 Subject: [PATCH] spec: fetch manifests by tag or digest Manifests are now fetched by a field called "reference", which may be a tag or a digest. When using digests to reference a manifest, the data is immutable. The routes and specification have been updated to allow this. There are a few caveats to this approach: 1. It may be problematic to rely on data format to differentiate between a tag and a digest. Currently, they are disjoint but there may modifications on either side that break this guarantee. 2. The caching characteristics of returned content are very different for digest versus tag-based references. Digest urls can be cached forever while tag urls cannot. Both of these are minimal caveats that we can live with in the future. Signed-off-by: Stephen J Day --- docs/api/v2/descriptors.go | 33 +++++++++++++++++++++++++++------ docs/api/v2/errors.go | 3 +++ docs/api/v2/routes_test.go | 20 ++++++++++++++------ docs/api/v2/urls.go | 7 ++++--- 4 files changed, 48 insertions(+), 15 deletions(-) diff --git a/docs/api/v2/descriptors.go b/docs/api/v2/descriptors.go index 301fd596..5f091bbc 100644 --- a/docs/api/v2/descriptors.go +++ b/docs/api/v2/descriptors.go @@ -79,6 +79,13 @@ var ( Format: "", } + digestHeader = ParameterDescriptor{ + Name: "Docker-Content-Digest", + Description: "Digest of the targeted content for the request.", + Type: "digest", + Format: "", + } + unauthorizedResponse = ResponseDescriptor{ Description: "The client does not have access to the repository.", StatusCode: http.StatusUnauthorized, @@ -454,13 +461,13 @@ var routeDescriptors = []RouteDescriptor{ }, { Name: RouteNameManifest, - Path: "/v2/{name:" + RepositoryNameRegexp.String() + "}/manifests/{tag:" + TagNameRegexp.String() + "}", + Path: "/v2/{name:" + RepositoryNameRegexp.String() + "}/manifests/{reference:" + TagNameRegexp.String() + "|" + digest.DigestRegexp.String() + "}", Entity: "Manifest", Description: "Create, update and retrieve manifests.", Methods: []MethodDescriptor{ { Method: "GET", - Description: "Fetch the manifest identified by `name` and `tag`.", + Description: "Fetch the manifest identified by `name` and `reference` where `reference` can be a tag or digest.", Requests: []RequestDescriptor{ { Headers: []ParameterDescriptor{ @@ -473,8 +480,11 @@ var routeDescriptors = []RouteDescriptor{ }, Successes: []ResponseDescriptor{ { - Description: "The manifest idenfied by `name` and `tag`. The contents can be used to identify and resolve resources required to run the specified image.", + Description: "The manifest idenfied by `name` and `reference`. The contents can be used to identify and resolve resources required to run the specified image.", StatusCode: http.StatusOK, + Headers: []ParameterDescriptor{ + digestHeader, + }, Body: BodyDescriptor{ ContentType: "application/json; charset=utf-8", Format: manifestBody, @@ -483,7 +493,7 @@ var routeDescriptors = []RouteDescriptor{ }, Failures: []ResponseDescriptor{ { - Description: "The name or tag was invalid.", + Description: "The name or reference was invalid.", StatusCode: http.StatusBadRequest, ErrorCodes: []ErrorCode{ ErrorCodeNameInvalid, @@ -523,7 +533,7 @@ var routeDescriptors = []RouteDescriptor{ }, { Method: "PUT", - Description: "Put the manifest identified by `name` and `tag`.", + Description: "Put the manifest identified by `name` and `reference` where `reference` can be a tag or digest.", Requests: []RequestDescriptor{ { Headers: []ParameterDescriptor{ @@ -550,6 +560,7 @@ var routeDescriptors = []RouteDescriptor{ Format: "", }, contentLengthZeroHeader, + digestHeader, }, }, }, @@ -628,7 +639,7 @@ var routeDescriptors = []RouteDescriptor{ }, { Method: "DELETE", - Description: "Delete the manifest identified by `name` and `tag`.", + Description: "Delete the manifest identified by `name` and `reference` where `reference` can be a tag or digest.", Requests: []RequestDescriptor{ { Headers: []ParameterDescriptor{ @@ -729,6 +740,7 @@ var routeDescriptors = []RouteDescriptor{ Description: "The length of the requested blob content.", Format: "", }, + digestHeader, }, Body: BodyDescriptor{ ContentType: "application/octet-stream", @@ -745,6 +757,7 @@ var routeDescriptors = []RouteDescriptor{ Description: "The location where the layer should be accessible.", Format: "", }, + digestHeader, }, }, }, @@ -1193,6 +1206,7 @@ var routeDescriptors = []RouteDescriptor{ Format: "", Description: "Length of the chunk being uploaded, corresponding the length of the request body.", }, + digestHeader, }, }, }, @@ -1312,6 +1326,13 @@ var errorDescriptors = []ErrorDescriptor{ Description: `Generic error returned when the error does not have an API classification.`, }, + { + Code: ErrorCodeUnsupported, + Value: "UNSUPPORTED", + Message: "The operation is unsupported.", + Description: `The operation was unsupported due to a missing + implementation or invalid set of parameters.`, + }, { Code: ErrorCodeUnauthorized, Value: "UNAUTHORIZED", diff --git a/docs/api/v2/errors.go b/docs/api/v2/errors.go index 4d5d55c7..cbae020e 100644 --- a/docs/api/v2/errors.go +++ b/docs/api/v2/errors.go @@ -13,6 +13,9 @@ 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 diff --git a/docs/api/v2/routes_test.go b/docs/api/v2/routes_test.go index 9157e21e..afab71fc 100644 --- a/docs/api/v2/routes_test.go +++ b/docs/api/v2/routes_test.go @@ -39,16 +39,24 @@ func TestRouter(t *testing.T) { RouteName: RouteNameManifest, RequestURI: "/v2/foo/manifests/bar", Vars: map[string]string{ - "name": "foo", - "tag": "bar", + "name": "foo", + "reference": "bar", }, }, { RouteName: RouteNameManifest, RequestURI: "/v2/foo/bar/manifests/tag", Vars: map[string]string{ - "name": "foo/bar", - "tag": "tag", + "name": "foo/bar", + "reference": "tag", + }, + }, + { + RouteName: RouteNameManifest, + RequestURI: "/v2/foo/bar/manifests/sha256:abcdef01234567890", + Vars: map[string]string{ + "name": "foo/bar", + "reference": "sha256:abcdef01234567890", }, }, { @@ -112,8 +120,8 @@ func TestRouter(t *testing.T) { RouteName: RouteNameManifest, RequestURI: "/v2/foo/bar/manifests/manifests/tags", Vars: map[string]string{ - "name": "foo/bar/manifests", - "tag": "tags", + "name": "foo/bar/manifests", + "reference": "tags", }, }, { diff --git a/docs/api/v2/urls.go b/docs/api/v2/urls.go index e36afdab..4b42dd16 100644 --- a/docs/api/v2/urls.go +++ b/docs/api/v2/urls.go @@ -107,11 +107,12 @@ func (ub *URLBuilder) BuildTagsURL(name string) (string, error) { return tagsURL.String(), nil } -// BuildManifestURL constructs a url for the manifest identified by name and tag. -func (ub *URLBuilder) BuildManifestURL(name, tag 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 (ub *URLBuilder) BuildManifestURL(name, reference string) (string, error) { route := ub.cloneRoute(RouteNameManifest) - manifestURL, err := route.URL("name", name, "tag", tag) + manifestURL, err := route.URL("name", name, "reference", reference) if err != nil { return "", err }