Merge pull request #208 from bloodorangeio/head-requests

Add test and spec section for HEAD requests

Author: dmcgowan

conformance/01_pull_test.go

@@ -81,6 +81,27 @@ var test01Pull = func() {
 		})
 
 		g.Context("Pull blobs", func() {
+			g.Specify("HEAD request to nonexistent blob should result in 404 response", func() {
+				SkipIfDisabled(pull)
+				req := client.NewRequest(reggie.HEAD, "/v2/<name>/blobs/<digest>",
+					reggie.WithDigest(dummyDigest))
+				resp, err := client.Do(req)
+				Expect(err).To(BeNil())
+				Expect(resp.StatusCode()).To(Equal(http.StatusNotFound))
+			})
+
+			g.Specify("HEAD request to existing blob should yield 200", func() {
+				SkipIfDisabled(pull)
+				req := client.NewRequest(reggie.HEAD, "/v2/<name>/blobs/<digest>",
+					reggie.WithDigest(configBlobDigest))
+				resp, err := client.Do(req)
+				Expect(err).To(BeNil())
+				Expect(resp.StatusCode()).To(Equal(http.StatusOK))
+				if h := resp.Header().Get("Docker-Content-Digest"); h != "" {
+					Expect(h).To(Equal(configBlobDigest))
+				}
+			})
+
 			g.Specify("GET nonexistent blob should result in 404 response", func() {
 				SkipIfDisabled(pull)
 				req := client.NewRequest(reggie.GET, "/v2/<name>/blobs/<digest>",
@@ -100,6 +121,40 @@ var test01Pull = func() {
 		})
 
 		g.Context("Pull manifests", func() {
+			g.Specify("HEAD request to nonexistent manifest should return 404", func() {
+				SkipIfDisabled(pull)
+				req := client.NewRequest(reggie.HEAD, "/v2/<name>/manifests/<reference>",
+					reggie.WithReference(nonexistentManifest))
+				resp, err := client.Do(req)
+				Expect(err).To(BeNil())
+				Expect(resp.StatusCode()).To(Equal(http.StatusNotFound))
+			})
+
+			g.Specify("HEAD request to manifest path (digest) should yield 200 response", func() {
+				SkipIfDisabled(pull)
+				req := client.NewRequest(reggie.HEAD, "/v2/<name>/manifests/<digest>", reggie.WithDigest(manifestDigest)).
+					SetHeader("Accept", "application/vnd.oci.image.manifest.v1+json")
+				resp, err := client.Do(req)
+				Expect(err).To(BeNil())
+				Expect(resp.StatusCode()).To(Equal(http.StatusOK))
+				if h := resp.Header().Get("Docker-Content-Digest"); h != "" {
+					Expect(h).To(Equal(manifestDigest))
+				}
+			})
+
+			g.Specify("HEAD request to manifest path (tag) should yield 200 response", func() {
+				SkipIfDisabled(pull)
+				Expect(tag).ToNot(BeEmpty())
+				req := client.NewRequest(reggie.GET, "/v2/<name>/manifests/<reference>", reggie.WithReference(tag)).
+					SetHeader("Accept", "application/vnd.oci.image.manifest.v1+json")
+				resp, err := client.Do(req)
+				Expect(err).To(BeNil())
+				Expect(resp.StatusCode()).To(Equal(http.StatusOK))
+				if h := resp.Header().Get("Docker-Content-Digest"); h != "" {
+					Expect(h).To(Equal(manifestDigest))
+				}
+			})
+
 			g.Specify("GET nonexistent manifest should return 404", func() {
 				SkipIfDisabled(pull)
 				req := client.NewRequest(reggie.GET, "/v2/<name>/manifests/<reference>",

conformance/go.mod

@@ -4,6 +4,7 @@ go 1.13
 
 require (
 	github.com/bloodorangeio/reggie v0.4.0
+	github.com/google/uuid v1.1.2
 	github.com/onsi/ginkgo v1.11.0
 	github.com/onsi/gomega v1.8.1
 	github.com/opencontainers/go-digest v1.0.0-rc1

conformance/go.sum

@@ -6,6 +6,8 @@ github.com/go-resty/resty/v2 v2.1.0 h1:Z6IefCpUMfnvItVJaJXWv/pMiiD11So35QgwEELsl
 github.com/go-resty/resty/v2 v2.1.0/go.mod h1:dZGr0i9PLlaaTD4H/hoZIDjQ+r6xq8mgbRzHZf7f2J8=
 github.com/golang/protobuf v1.2.0 h1:P3YflyNX/ehuJFLhxviNdFxQPkGK5cDcApsge1SqnvM=
 github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/google/uuid v1.1.2 h1:EVhdT+1Kseyi1/pUmXKaFxYsDNy9RQYkMWRH68J/W7Y=
+github.com/google/uuid v1.1.2/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/hpcloud/tail v1.0.0 h1:nfCOvKYfkgYP8hkirhJocXT2+zOD8yUNjXaWfTlyFKI=
 github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
 github.com/mitchellh/mapstructure v1.1.2 h1:fmNYVwqnSfB9mZU6OS2O6GsXM+wcskZDuKQzvN1EDeE=

conformance/reporter.go

@@ -581,6 +581,7 @@ func (reporter *HTMLReporter) SpecSuiteWillBegin(config config.GinkgoConfigType,
 		envVarTagList,
 		envVarHideSkippedWorkflows,
 		envVarAuthScope,
+		envVarCrossmountNamespace,
 	}
 	for _, v := range varsToCheck {
 		var replacement string

conformance/setup.go

@@ -10,6 +10,7 @@ import (
 	"strconv"
 
 	"github.com/bloodorangeio/reggie"
+	"github.com/google/uuid"
 	g "github.com/onsi/ginkgo"
 	godigest "github.com/opencontainers/go-digest"
 	imagespec "github.com/opencontainers/image-spec/specs-go/v1"
@@ -139,6 +140,9 @@ func init() {
 	password := os.Getenv(envVarPassword)
 	authScope := os.Getenv(envVarAuthScope)
 	crossmountNamespace = os.Getenv(envVarCrossmountNamespace)
+	if len(crossmountNamespace) == 0 {
+		crossmountNamespace = fmt.Sprintf("conformance-%s", uuid.New())
+	}
 
 	debug, _ := strconv.ParseBool(os.Getenv(envVarDebug))
 

spec.md

@@ -128,7 +128,7 @@ Typically, the first step in pulling an artifact is to retrieve the manifest. Ho
 
 ##### Pulling manifests
 
-To pull a manifest, perform a `GET` request to a url in the following form:
+To pull a manifest, perform a `GET` request to a URL in the following form:
 `/v2/<name>/manifests/<reference>` <sup>[end-3](#endpoints)</sup>
 
 `<name>` refers to the namespace of the repository. `<reference>` MUST be either (a) the digest of the manifest or (b) a tag name.
@@ -137,26 +137,41 @@ The `<reference>` MUST NOT be in any other format. Throughout this document, `<n
 `[a-z0-9]+([._-][a-z0-9]+)*(/[a-z0-9]+([._-][a-z0-9]+)*)*`
 
 A GET request to an existing manifest URL MUST provide the expected manifest, with a response code that MUST be `200 OK`.
+A successful response SHOULD contain the digest of the uploaded blob in the header `Docker-Content-Digest`.
 
-The `OCI-Content-Digest` header (or, as a fallback, `Docker-Content-Digest` header), if present on the response, returns the canonical
+The `Docker-Content-Digest` header, if present on the response, returns the canonical
 digest of the uploaded blob which MAY differ from the provided digest. If the digest does differ, it MAY be the case that
 the hashing algorithms used do not match. See [Content Digests](./detail.md) for information on how to detect the hashing
 algorithm in use. Most clients MAY ignore the value, but if it is used, the client MUST verify the value against the uploaded
 blob data.
 
 If the manifest is not found in the registry, the response code MUST be `404 Not Found`.
 
-##### Pulling Blobs
+##### Pulling blobs
 
-To pull a blob, perform a `GET` request to a url in the following form:
+To pull a blob, perform a `GET` request to a URL in the following form:
 `/v2/<name>/blobs/<digest>` <sup>[end-2](#endpoints)</sup>
 
 `<name>` is the namespace of the repository, and `<digest>` is the blob's digest.
 
 A GET request to an existing blob URL MUST provide the expected blob, with a response code that MUST be `200 OK`.
+A successful response SHOULD contain the digest of the uploaded blob in the header `Docker-Content-Digest`. If present,
+the value of this header MUST be a digest matching that of the response body.
 
 If the blob is not found in the registry, the response code MUST be `404 Not Found`.
 
+##### Checking if content exists in the registry
+
+In order to verify that a repository contains a given manifest or blob, make a `HEAD` request to a URL in the following form:
+
+`/v2/<name>/manifests/<reference>` <sup>[end-3](#endpoints)</sup> (for manifests), or
+
+`/v2/<name>/blobs/<digest>` <sup>[end-2](#endpoints)</sup> (for blobs).
+
+A HEAD request to an existing blob or manifest URL MUST return `200 OK`. A successful response SHOULD contain the digest
+of the uploaded blob in the header `Docker-Content-Digest`.
+
+If the blob or manifest is not found in the registry, the response code MUST be `404 Not Found`.
 
 #### Push
 
@@ -452,21 +467,21 @@ of this specification.
 
 #### Endpoints
 
-| ID     | Method   | API endpoint                                                      | Accepted Successful Response Codes | Accepted Failure Response Codes |
-| ------ | -------- | ----------------------------------------------------------------- | ---------------------------------- | ------------------------------- |
-| end-1  | `GET`    | `/v2/`                                                            | `200`                              | `404`/`401`                     |
-| end-2  | `GET`    | `/v2/<name>/blobs/<digest>`                                       | `200`                              | `404`                           |
-| end-3  | `GET`    | `/v2/<name>/manifests/<reference>`                                | `200`                              | `404`                           |
-| end-4a | `POST`   | `/v2/<name>/blobs/uploads/`                                       | `202`                              | `404`                           |
-| end-4b | `POST`   | `/v2/<name>/blobs/uploads/?digest=<digest>`                       | `201`/`202`                        | `404`/`400`                     |
-| end-5  | `PATCH`  | `/v2/<name>/blobs/uploads/<reference>`                            | `202`                              | `404`/`416`                     |
-| end-6  | `PUT`    | `/v2/<name>/blobs/uploads/<reference>?digest=<digest>`            | `201`                              | `404`/`400`                     |
-| end-7  | `PUT`    | `/v2/<name>/manifests/<reference>`                                | `201`                              | `404`                           |
-| end-8a | `GET`    | `/v2/<name>/tags/list`                                            | `200`                              | `404`                           |
-| end-8b | `GET`    | `/v2/<name>/tags/list?n=<integer>&last=<integer>`                 | `200`                              | `404`                           |
-| end-9  | `DELETE` | `/v2/<name>/manifests/<reference>`                                | `202`                              | `404`/`400`/`405`               |
-| end-10 | `DELETE` | `/v2/<name>/blobs/<digest>`                                       | `202`                              | `404`/`405`                     |
-| end-11 | `POST`   | `/v2/<name>/blobs/uploads/?mount=<digest>&from=<other_namespace>` | `201`                              | `404`                           |
+| ID     | Method         | API endpoint                                                      | Accepted Successful Response Codes | Accepted Failure Response Codes |
+| ------ | -------------- | ----------------------------------------------------------------- | ---------------------------------- | ------------------------------- |
+| end-1  | `GET`          | `/v2/`                                                            | `200`                              | `404`/`401`                     |
+| end-2  | `GET` / `HEAD` | `/v2/<name>/blobs/<digest>`                                       | `200`                              | `404`                           |
+| end-3  | `GET` / `HEAD` | `/v2/<name>/manifests/<reference>`                                | `200`                              | `404`                           |
+| end-4a | `POST`         | `/v2/<name>/blobs/uploads/`                                       | `202`                              | `404`                           |
+| end-4b | `POST`         | `/v2/<name>/blobs/uploads/?digest=<digest>`                       | `201`/`202`                        | `404`/`400`                     |
+| end-5  | `PATCH`        | `/v2/<name>/blobs/uploads/<reference>`                            | `202`                              | `404`/`416`                     |
+| end-6  | `PUT`          | `/v2/<name>/blobs/uploads/<reference>?digest=<digest>`            | `201`                              | `404`/`400`                     |
+| end-7  | `PUT`          | `/v2/<name>/manifests/<reference>`                                | `201`                              | `404`                           |
+| end-8a | `GET`          | `/v2/<name>/tags/list`                                            | `200`                              | `404`                           |
+| end-8b | `GET`          | `/v2/<name>/tags/list?n=<integer>&last=<integer>`                 | `200`                              | `404`                           |
+| end-9  | `DELETE`       | `/v2/<name>/manifests/<reference>`                                | `202`                              | `404`/`400`/`405`               |
+| end-10 | `DELETE`       | `/v2/<name>/blobs/<digest>`                                       | `202`                              | `404`/`405`                     |
+| end-11 | `POST`         | `/v2/<name>/blobs/uploads/?mount=<digest>&from=<other_namespace>` | `201`                              | `404`                           |
 
 #### Error Codes