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,8 @@ 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")
+	ErrInvalidManifestTagQuery          = errors.New("invalid tag query parameter: not a valid OCI/Docker tag")
 	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,23 @@ 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 raw `tag=` query parameters accepted on
+	// PUT .../manifests/<digest>?tag=... (draft OCI distribution-spec: registries MUST support at
+	// least 10 and MAY respond with 414 beyond this limit). It uses the OCI tag max length (128;
+	// must match pkg/regexp.TagMaxLen) and an ~8KiB request-target budget, reserving 2048 bytes
+	// for path and digest:
+	//
+	//	(8192 - 2048) / (len("tag=") + 128 + 1) == 46
+	MaxManifestDigestQueryTags   = (8192 - 2048) / (len("tag=") + 128 + 1)
 	BlobUploadUUID               = "Blob-Upload-UUID"
 	DefaultMediaType             = "application/json"
 	BinaryMediaType              = "application/octet-stream"

pkg/api/constants/consts_test.go

@@ -0,0 +1,18 @@
+package constants_test
+
+import (
+	"testing"
+
+	"zotregistry.dev/zot/v2/pkg/api/constants"
+	zreg "zotregistry.dev/zot/v2/pkg/regexp"
+)
+
+func TestMaxManifestDigestQueryTagsDerived(t *testing.T) {
+	t.Parallel()
+
+	want := (8192 - 2048) / (len("tag=") + zreg.TagMaxLen + 1)
+
+	if constants.MaxManifestDigestQueryTags != want {
+		t.Fatalf("MaxManifestDigestQueryTags = %d, want %d", constants.MaxManifestDigestQueryTags, want)
+	}
+}

pkg/api/controller_test.go

@@ -59,6 +59,7 @@ import (
 	extconf "zotregistry.dev/zot/v2/pkg/extensions/config"
 	"zotregistry.dev/zot/v2/pkg/log"
 	"zotregistry.dev/zot/v2/pkg/meta"
+	zreg "zotregistry.dev/zot/v2/pkg/regexp"
 	"zotregistry.dev/zot/v2/pkg/storage"
 	storageConstants "zotregistry.dev/zot/v2/pkg/storage/constants"
 	"zotregistry.dev/zot/v2/pkg/storage/gc"
@@ -7808,6 +7809,142 @@ 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()
+
+			manifestPutURL, perr := url.Parse(baseURL + fmt.Sprintf("/v2/%s/manifests/%s", repoName, manifestDigest.String()))
+			So(perr, ShouldBeNil)
+			manifestPutURL.RawQuery = rawQuery
+
+			resp, rerr := resty.R().
+				SetHeader("Content-Type", ispec.MediaTypeImageManifest).
+				SetBody(manifestBytes).
+				Put(manifestPutURL.String())
+			So(rerr, ShouldBeNil)
+
+			return resp
+		}
+
+		Convey("multiple tag query parameters add tags and return OCI-Tag headers", func() {
+			manifestPutURL, err := url.Parse(baseURL + fmt.Sprintf("/v2/%s/manifests/%s", repoName, manifestDigest.String()))
+			So(err, ShouldBeNil)
+
+			q := manifestPutURL.Query()
+			q.Add("tag", "v1.0.0")
+			q.Add("tag", "v1.0")
+			q.Add("tag", "edge")
+			manifestPutURL.RawQuery = q.Encode()
+
+			resp, err := resty.R().
+				SetHeader("Content-Type", ispec.MediaTypeImageManifest).
+				SetBody(manifestBytes).
+				Put(manifestPutURL.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() {
+			manifestPutURL, err := url.Parse(baseURL + fmt.Sprintf("/v2/%s/manifests/initial", repoName))
+			So(err, ShouldBeNil)
+			manifestPutURL.RawQuery = "tag=notallowed"
+
+			resp, err := resty.R().
+				SetHeader("Content-Type", ispec.MediaTypeImageManifest).
+				SetBody(manifestBytes).
+				Put(manifestPutURL.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("more than max raw tag parameters returns 414 even when values are duplicates", func() {
+			q := url.Values{}
+			for range constants.MaxManifestDigestQueryTags + 1 {
+				q.Add("tag", "same")
+			}
+
+			resp := putManifestByDigest(q.Encode())
+			So(resp.StatusCode(), ShouldEqual, http.StatusRequestURITooLong)
+		})
+
+		Convey("invalid tag query value returns 400", func() {
+			q := url.Values{}
+			q.Set("tag", "bad/ref")
+
+			resp := putManifestByDigest(q.Encode())
+			So(resp.StatusCode(), ShouldEqual, http.StatusBadRequest)
+		})
+
+		Convey("tag query value longer than distribution-spec max length returns 400", func() {
+			longTag := strings.Repeat("a", zreg.TagMaxLen+1)
+			q := url.Values{}
+			q.Set("tag", longTag)
+
+			resp := putManifestByDigest(q.Encode())
+			So(resp.StatusCode(), ShouldEqual, http.StatusBadRequest)
+		})
+
+		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

@@ -676,13 +676,16 @@ func (rh *RouteHandler) GetReferrers(response http.ResponseWriter, request *http
 
 // UpdateManifest godoc
 // @Summary Update image manifest
-// @Description Update an image's manifest given a reference or a digest
+// @Description Update an image's manifest given a reference or a digest. On digest pushes with `tag=` query
+// @Description parameters, 201 responses repeat the `OCI-Tag` header once per tag value.
 // @Accept  json
 // @Produce json
 // @Param   name         path    string     true        "repository name"
 // @Param   reference    path    string     true        "image reference or digest"
-// @Header  201 {object} constants.DistContentDigestKey
+// @Param   tag          query   []string   false       "additional tag(s) for digest pushes" collectionFormat(multi)
 // @Success 201 {string} string "created"
+// @Header  201 {object} constants.DistContentDigestKey
+// @Header  201 {string} constants.OCITagResponseKey "echoed tag= value (one header per query tag)"
 // @Failure 400 {string} string "bad request"
 // @Failure 404 {string} string "not found"
 // @Failure 500 {string} string "internal server error"
@@ -717,6 +720,30 @@ func (rh *RouteHandler) UpdateManifest(response http.ResponseWriter, request *ht
 		return
 	}
 
+	var digestQueryTags []string
+
+	rawTagQuery := request.URL.Query()["tag"]
+	if len(rawTagQuery) > 0 {
+		if len(rawTagQuery) > 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
+		}
+
+		var normErr error
+
+		digestQueryTags, normErr = normalizeManifestExtraTags(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
+		}
+	}
+
 	body, err := io.ReadAll(request.Body)
 	// hard to reach test case, injected error (simulates an interrupted image manifest upload)
 	// err could be io.ErrUnexpectedEOF
@@ -727,7 +754,16 @@ func (rh *RouteHandler) UpdateManifest(response http.ResponseWriter, request *ht
 		return
 	}
 
-	digest, subjectDigest, err := imgStore.PutImageManifest(name, reference, mediaType, body)
+	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
+	}
+
+	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 +805,22 @@ 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 {
+			err := meta.OnUpdateManifestDigestTags(request.Context(), name, digestQueryTags, mediaType,
+				digest, body, rh.c.StoreController, rh.c.MetaDB, rh.c.Log)
+			if err != nil {
+				response.WriteHeader(http.StatusInternalServerError)
 
-			return
+				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 +830,42 @@ 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, rejects empty components, and
+// requires each value to match the OCI distribution-spec tag grammar (zreg.IsDistributionSpecTag).
+func normalizeManifestExtraTags(raw []string) ([]string, error) {
+	seen := map[string]struct{}{}
+
+	out := make([]string, 0, len(raw))
+
+	for _, rawTag := range raw {
+		cleanedTag := strings.TrimSpace(rawTag)
+		if cleanedTag == "" {
+			return nil, zerr.ErrEmptyManifestTagQuery
+		}
+
+		if !zreg.IsDistributionSpecTag(cleanedTag) {
+			return nil, zerr.ErrInvalidManifestTagQuery
+		}
+
+		if _, ok := seen[cleanedTag]; ok {
+			continue
+		}
+
+		seen[cleanedTag] = struct{}{}
+		out = append(out, cleanedTag)
+	}
+
+	return out, nil
+}
+
 // DeleteManifest godoc
 // @Summary Delete image manifest
 // @Description Delete an image's manifest given a reference or a digest