diff --git a/docs/spec/api.md b/docs/spec/api.md index 747b4f816..1f7a4a7b1 100644 --- a/docs/spec/api.md +++ b/docs/spec/api.md @@ -1142,6 +1142,7 @@ The error codes encountered via the API are enumerated in the following table: `MANIFEST_UNVERIFIED` | manifest failed signature verification | During manifest upload, if the manifest fails signature verification, this error will be returned. `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. + `PAGINATION_NUMBER_INVALID` | invalid number of results requested | Returned when the `n` parameter (number of results to return) is not an integer, or `n` is negative. `SIZE_INVALID` | provided length did not match content length | When a layer is uploaded, the provided size will be checked against the uploaded content. If they do not match, this error will be returned. `TAG_INVALID` | manifest tag did not match URI | During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned. `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. diff --git a/registry/api/v2/descriptors.go b/registry/api/v2/descriptors.go index 56bfdcdfb..1dbe68239 100644 --- a/registry/api/v2/descriptors.go +++ b/registry/api/v2/descriptors.go @@ -490,6 +490,18 @@ var routeDescriptors = []RouteDescriptor{ }, }, Failures: []ResponseDescriptor{ + { + Name: "Invalid pagination number", + Description: "The received parameter n was invalid in some way, as described by the error code. The client should resolve the issue and retry the request.", + StatusCode: http.StatusBadRequest, + Body: BodyDescriptor{ + ContentType: "application/json", + Format: errorsBody, + }, + ErrorCodes: []errcode.ErrorCode{ + ErrorCodePaginationNumberInvalid, + }, + }, unauthorizedResponseDescriptor, repositoryNotFoundResponseDescriptor, deniedResponseDescriptor, diff --git a/registry/api/v2/errors.go b/registry/api/v2/errors.go index cf5c818e8..23a87f8c0 100644 --- a/registry/api/v2/errors.go +++ b/registry/api/v2/errors.go @@ -144,4 +144,14 @@ var ( longer proceed.`, HTTPStatusCode: http.StatusNotFound, }) + + // ErrorCodePaginationNumberInvalid is returned when the `n` parameter is + // not an integer, or `n` is negative. + ErrorCodePaginationNumberInvalid = errcode.Register(errGroup, errcode.ErrorDescriptor{ + Value: "PAGINATION_NUMBER_INVALID", + Message: "invalid number of results requested", + Description: `Returned when the "n" parameter (number of results + to return) is not an integer, or "n" is negative.`, + HTTPStatusCode: http.StatusBadRequest, + }) ) diff --git a/registry/handlers/tags.go b/registry/handlers/tags.go index 72d1dc8ff..0cc38102f 100644 --- a/registry/handlers/tags.go +++ b/registry/handlers/tags.go @@ -3,6 +3,8 @@ package handlers import ( "encoding/json" "net/http" + "sort" + "strconv" "github.com/distribution/distribution/v3" "github.com/distribution/distribution/v3/registry/api/errcode" @@ -49,6 +51,51 @@ func (th *tagsHandler) GetTags(w http.ResponseWriter, r *http.Request) { return } + // do pagination if requested + q := r.URL.Query() + // get entries after latest, if any specified + if lastEntry := q.Get("last"); lastEntry != "" { + lastEntryIndex := sort.SearchStrings(tags, lastEntry) + + // as`sort.SearchStrings` can return len(tags), if the + // specified `lastEntry` is not found, we need to + // ensure it does not panic when slicing. + if lastEntryIndex == len(tags) { + tags = []string{} + } else { + tags = tags[lastEntryIndex+1:] + } + } + + // if no error, means that the user requested `n` entries + if n := q.Get("n"); n != "" { + maxEntries, err := strconv.Atoi(n) + if err != nil || maxEntries < 0 { + th.Errors = append(th.Errors, v2.ErrorCodePaginationNumberInvalid.WithDetail(map[string]string{"n": n})) + return + } + + // if there is requested more than or + // equal to the amount of tags we have, + // then set the request to equal `len(tags)`. + // the reason for the `=`, is so the else + // clause will only activate if there + // are tags left the user needs. + if maxEntries >= len(tags) { + maxEntries = len(tags) + } else if maxEntries > 0 { + // defined in `catalog.go` + urlStr, err := createLinkEntry(r.URL.String(), maxEntries, tags[maxEntries-1]) + if err != nil { + th.Errors = append(th.Errors, errcode.ErrorCodeUnknown.WithDetail(err)) + return + } + w.Header().Set("Link", urlStr) + } + + tags = tags[:maxEntries] + } + w.Header().Set("Content-Type", "application/json") enc := json.NewEncoder(w) diff --git a/registry/storage/tagstore.go b/registry/storage/tagstore.go index e33bf9da7..7bbb2f01f 100644 --- a/registry/storage/tagstore.go +++ b/registry/storage/tagstore.go @@ -3,6 +3,7 @@ package storage import ( "context" "path" + "sort" "github.com/distribution/distribution/v3" storagedriver "github.com/distribution/distribution/v3/registry/storage/driver" @@ -47,6 +48,10 @@ func (ts *tagStore) All(ctx context.Context) ([]string, error) { tags = append(tags, filename) } + // there is no guarantee for the order, + // therefore sort before return. + sort.Strings(tags) + return tags, nil }