feat: support pushing multiple tags for a single manifest

See opencontainers/distribution-spec#600

Signed-off-by: Andrei Aaron <andreifdaaron@gmail.com>

Author: andaaron

errors/errors.go

@@ -117,6 +117,7 @@ var (
 	ErrEmptyRepoName                    = errors.New("repo name can't be empty string")
 	ErrEmptyTag                         = errors.New("tag can't be empty string")
 	ErrEmptyDigest                      = errors.New("digest can't be empty string")
+	ErrEmptyManifestTagQuery            = errors.New("empty tag query parameter")
 	ErrInvalidRepoRefFormat             = errors.New("invalid image reference format, use [repo:tag] or [repo@digest]")
 	ErrLimitIsNegative                  = errors.New("pagination limit has negative value")
 	ErrLimitIsExcessive                 = errors.New("pagination limit has excessive value")

pkg/api/constants/consts.go

@@ -3,12 +3,19 @@ package constants
 import "time"
 
 const (
-	RoutePrefix                  = "/v2"
-	Blobs                        = "blobs"
-	Uploads                      = "uploads"
-	DistAPIVersion               = "Docker-Distribution-API-Version"
-	DistContentDigestKey         = "Docker-Content-Digest"
-	SubjectDigestKey             = "OCI-Subject"
+	RoutePrefix          = "/v2"
+	Blobs                = "blobs"
+	Uploads              = "uploads"
+	DistAPIVersion       = "Docker-Distribution-API-Version"
+	DistContentDigestKey = "Docker-Content-Digest"
+	// OCITagResponseKey is returned on digest manifest pushes that include tag query
+	// parameters (distribution-spec PR #600).
+	OCITagResponseKey = "OCI-Tag"
+	SubjectDigestKey  = "OCI-Subject"
+	// MaxManifestDigestQueryTags is the maximum number of tag query parameters accepted on
+	// PUT .../manifests/<digest>?tag=... (draft OCI distribution-spec: registries MUST
+	// support at least this many and MAY respond with 414 beyond it).
+	MaxManifestDigestQueryTags   = 10
 	BlobUploadUUID               = "Blob-Upload-UUID"
 	DefaultMediaType             = "application/json"
 	BinaryMediaType              = "application/octet-stream"

pkg/api/controller_test.go

@@ -7808,6 +7808,115 @@ func TestManifestValidation(t *testing.T) {
 	})
 }
 
+func TestManifestDigestQueryTags(t *testing.T) {
+	Convey("Manifest PUT with digest ?tag= query parameters", t, func() {
+		port := test.GetFreePort()
+		baseURL := test.GetBaseURL(port)
+
+		conf := config.New()
+		conf.HTTP.Port = port
+
+		dir := t.TempDir()
+		ctlr := makeController(conf, dir)
+		cm := test.NewControllerManager(ctlr)
+		cm.StartServer()
+		time.Sleep(1000 * time.Millisecond)
+
+		defer cm.StopServer()
+
+		repoName := "digest-query-tags"
+		img := CreateRandomImage()
+		manifestBytes := img.ManifestDescriptor.Data
+		manifestDigest := img.ManifestDescriptor.Digest
+
+		err := UploadImage(img, baseURL, repoName, "initial")
+		So(err, ShouldBeNil)
+
+		putManifestByDigest := func(rawQuery string) *resty.Response {
+			t.Helper()
+
+			u, perr := url.Parse(baseURL + fmt.Sprintf("/v2/%s/manifests/%s", repoName, manifestDigest.String()))
+			So(perr, ShouldBeNil)
+			u.RawQuery = rawQuery
+
+			resp, rerr := resty.R().
+				SetHeader("Content-Type", ispec.MediaTypeImageManifest).
+				SetBody(manifestBytes).
+				Put(u.String())
+			So(rerr, ShouldBeNil)
+
+			return resp
+		}
+
+		Convey("multiple tag query parameters add tags and return OCI-Tag headers", func() {
+			u, err := url.Parse(baseURL + fmt.Sprintf("/v2/%s/manifests/%s", repoName, manifestDigest.String()))
+			So(err, ShouldBeNil)
+
+			q := u.Query()
+			q.Add("tag", "v1.0.0")
+			q.Add("tag", "v1.0")
+			q.Add("tag", "edge")
+			u.RawQuery = q.Encode()
+
+			resp, err := resty.R().
+				SetHeader("Content-Type", ispec.MediaTypeImageManifest).
+				SetBody(manifestBytes).
+				Put(u.String())
+			So(err, ShouldBeNil)
+			So(resp.StatusCode(), ShouldEqual, http.StatusCreated)
+			So(resp.Header().Get(constants.DistContentDigestKey), ShouldEqual, manifestDigest.String())
+
+			ociTags := resp.Header().Values(constants.OCITagResponseKey)
+			sort.Strings(ociTags)
+			So(ociTags, ShouldResemble, []string{"edge", "v1.0", "v1.0.0"})
+
+			for _, tag := range []string{"v1.0.0", "v1.0", "edge"} {
+				gresp, gerr := resty.R().Get(baseURL + fmt.Sprintf("/v2/%s/manifests/%s", repoName, tag))
+				So(gerr, ShouldBeNil)
+				So(gresp.StatusCode(), ShouldEqual, http.StatusOK)
+			}
+		})
+
+		Convey("tag query with non-digest path reference returns 400", func() {
+			u, err := url.Parse(baseURL + fmt.Sprintf("/v2/%s/manifests/initial", repoName))
+			So(err, ShouldBeNil)
+			u.RawQuery = "tag=notallowed"
+
+			resp, err := resty.R().
+				SetHeader("Content-Type", ispec.MediaTypeImageManifest).
+				SetBody(manifestBytes).
+				Put(u.String())
+			So(err, ShouldBeNil)
+			So(resp.StatusCode(), ShouldEqual, http.StatusBadRequest)
+		})
+
+		Convey("empty tag query parameter returns 400", func() {
+			resp := putManifestByDigest("tag=")
+			So(resp.StatusCode(), ShouldEqual, http.StatusBadRequest)
+		})
+
+		Convey("more than max tag query parameters returns 414", func() {
+			q := url.Values{}
+			for i := range constants.MaxManifestDigestQueryTags + 1 {
+				q.Add("tag", fmt.Sprintf("t%d", i))
+			}
+
+			resp := putManifestByDigest(q.Encode())
+			So(resp.StatusCode(), ShouldEqual, http.StatusRequestURITooLong)
+		})
+
+		Convey("duplicate tag query values are deduplicated in response headers", func() {
+			q := url.Values{}
+			q.Add("tag", "dup")
+			q.Add("tag", "dup")
+
+			resp := putManifestByDigest(q.Encode())
+			So(resp.StatusCode(), ShouldEqual, http.StatusCreated)
+			So(resp.Header().Values(constants.OCITagResponseKey), ShouldResemble, []string{"dup"})
+		})
+	})
+}
+
 func TestArtifactReferences(t *testing.T) {
 	Convey("Validate Artifact References", t, func() {
 		// start a new server

pkg/api/routes.go

@@ -727,7 +727,34 @@ func (rh *RouteHandler) UpdateManifest(response http.ResponseWriter, request *ht
 		return
 	}
 
-	digest, subjectDigest, err := imgStore.PutImageManifest(name, reference, mediaType, body)
+	rawTagQuery, tagQueryPresent := request.URL.Query()["tag"]
+	digestQueryTags, normErr := normalizeManifestExtraTags(tagQueryPresent, rawTagQuery)
+	if normErr != nil {
+		err := apiErr.NewError(apiErr.MANIFEST_INVALID).AddDetail(map[string]string{"reason": normErr.Error()})
+		zcommon.WriteJSON(response, http.StatusBadRequest, apiErr.NewErrorList(err))
+
+		return
+	}
+
+	if len(digestQueryTags) > 0 && !zcommon.IsDigest(reference) {
+		err := apiErr.NewError(apiErr.MANIFEST_INVALID).AddDetail(map[string]string{
+			"reason": "tag query parameters are only valid when pushing a manifest by digest",
+		})
+		zcommon.WriteJSON(response, http.StatusBadRequest, apiErr.NewErrorList(err))
+
+		return
+	}
+
+	if len(digestQueryTags) > constants.MaxManifestDigestQueryTags {
+		e := apiErr.NewError(apiErr.MANIFEST_INVALID).AddDetail(map[string]string{
+			"reason": fmt.Sprintf("too many tag query parameters (max %d)", constants.MaxManifestDigestQueryTags),
+		})
+		zcommon.WriteJSON(response, http.StatusRequestURITooLong, apiErr.NewErrorList(e))
+
+		return
+	}
+
+	digest, subjectDigest, err := imgStore.PutImageManifest(name, reference, mediaType, body, digestQueryTags)
 	if err != nil {
 		details := zerr.GetDetails(err)
 		if errors.Is(err, zerr.ErrRepoNotFound) { //nolint:gocritic // errorslint conflicts with gocritic:IfElseChain
@@ -769,12 +796,33 @@ func (rh *RouteHandler) UpdateManifest(response http.ResponseWriter, request *ht
 	}
 
 	if rh.c.MetaDB != nil {
-		err := meta.OnUpdateManifest(request.Context(), name, reference, mediaType,
-			digest, body, rh.c.StoreController, rh.c.MetaDB, rh.c.Log)
-		if err != nil {
-			response.WriteHeader(http.StatusInternalServerError)
+		if len(digestQueryTags) > 0 {
+			metaUpdateFailed := false
 
-			return
+			for _, tag := range digestQueryTags {
+				mErr := meta.SetImageMetaFromInput(request.Context(), name, tag, mediaType,
+					digest, body, imgStore, rh.c.MetaDB, rh.c.Log)
+				if mErr != nil {
+					rh.c.Log.Error().Err(mErr).Str("repository", name).Str("tag", tag).
+						Msg("multi-tag digest push: failed to update meta for tag")
+
+					metaUpdateFailed = true
+				}
+			}
+
+			if metaUpdateFailed {
+				response.WriteHeader(http.StatusInternalServerError)
+
+				return
+			}
+		} else {
+			err := meta.OnUpdateManifest(request.Context(), name, reference, mediaType,
+				digest, body, rh.c.StoreController, rh.c.MetaDB, rh.c.Log)
+			if err != nil {
+				response.WriteHeader(http.StatusInternalServerError)
+
+				return
+			}
 		}
 	}
 
@@ -784,9 +832,45 @@ func (rh *RouteHandler) UpdateManifest(response http.ResponseWriter, request *ht
 
 	response.Header().Set("Location", fmt.Sprintf("/v2/%s/manifests/%s", name, digest))
 	response.Header().Set(constants.DistContentDigestKey, digest.String())
+
+	for _, tag := range digestQueryTags {
+		response.Header().Add(constants.OCITagResponseKey, tag) //nolint:canonicalheader
+	}
+
 	response.WriteHeader(http.StatusCreated)
 }
 
+// normalizeManifestExtraTags deduplicates tag query values in order and rejects empty tag components.
+func normalizeManifestExtraTags(tagQueryPresent bool, raw []string) ([]string, error) {
+	if !tagQueryPresent {
+		return nil, nil
+	}
+
+	seen := map[string]struct{}{}
+
+	out := make([]string, 0, len(raw))
+
+	for _, rawTag := range raw {
+		rawTag = strings.TrimSpace(rawTag)
+		if rawTag == "" {
+			return nil, zerr.ErrEmptyManifestTagQuery
+		}
+
+		if _, ok := seen[rawTag]; ok {
+			continue
+		}
+
+		seen[rawTag] = struct{}{}
+		out = append(out, rawTag)
+	}
+
+	if len(out) == 0 {
+		return nil, zerr.ErrEmptyManifestTagQuery
+	}
+
+	return out, nil
+}
+
 // DeleteManifest godoc
 // @Summary Delete image manifest
 // @Description Delete an image's manifest given a reference or a digest

pkg/api/routes_test.go

@@ -265,7 +265,7 @@ func TestRoutes(t *testing.T) {
 					"reference": "reference",
 				},
 				&mocks.MockedImageStore{
-					PutImageManifestFn: func(repo, reference, mediaType string, body []byte) (godigest.Digest,
+					PutImageManifestFn: func(repo, reference, mediaType string, body []byte, _ []string) (godigest.Digest,
 						godigest.Digest, error,
 					) {
 						return "", "", zerr.ErrRepoNotFound
@@ -280,7 +280,7 @@ func TestRoutes(t *testing.T) {
 				},
 
 				&mocks.MockedImageStore{
-					PutImageManifestFn: func(repo, reference, mediaType string, body []byte) (godigest.Digest,
+					PutImageManifestFn: func(repo, reference, mediaType string, body []byte, _ []string) (godigest.Digest,
 						godigest.Digest, error,
 					) {
 						return "", "", zerr.ErrManifestNotFound
@@ -294,7 +294,7 @@ func TestRoutes(t *testing.T) {
 					"reference": "reference",
 				},
 				&mocks.MockedImageStore{
-					PutImageManifestFn: func(repo, reference, mediaType string, body []byte) (godigest.Digest,
+					PutImageManifestFn: func(repo, reference, mediaType string, body []byte, _ []string) (godigest.Digest,
 						godigest.Digest, error,
 					) {
 						return "", "", zerr.ErrBadManifest
@@ -308,7 +308,7 @@ func TestRoutes(t *testing.T) {
 					"reference": "reference",
 				},
 				&mocks.MockedImageStore{
-					PutImageManifestFn: func(repo, reference, mediaType string, body []byte) (godigest.Digest,
+					PutImageManifestFn: func(repo, reference, mediaType string, body []byte, _ []string) (godigest.Digest,
 						godigest.Digest, error,
 					) {
 						return "", "", zerr.ErrBlobNotFound
@@ -323,7 +323,7 @@ func TestRoutes(t *testing.T) {
 					"reference": "reference",
 				},
 				&mocks.MockedImageStore{
-					PutImageManifestFn: func(repo, reference, mediaType string, body []byte) (godigest.Digest,
+					PutImageManifestFn: func(repo, reference, mediaType string, body []byte, _ []string) (godigest.Digest,
 						godigest.Digest, error,
 					) {
 						return "", "", zerr.ErrRepoBadVersion