Draft: Add sorting support to container registry tags endpoint

• Please check this box if this contribution uses AI-generated content (including content generated by GitLab Duo features) as outlined in the GitLab DCO & CLA. As a benefit of being a GitLab Community Contributor, you receive complimentary access to GitLab Duo.

What does this MR do and why?

Implements comprehensive sorting for the Container Registry Tags REST API endpoint to align with GraphQL API capabilities and enable efficient tag management workflows. Developers can now sort tags by name, published_at, created_at, and updated_at using standard GitLab sorting parameters.

The implementation adds order_by and sort parameters following GitLab's established REST API conventions used across issues, merge requests, and other resources. This enables API consumers to retrieve tags in their preferred order without client-side sorting of potentially large tag lists.

Technical changes

• Added sort_options helper to ContainerRegistryHelpers module
• Implemented transform_sort_parameter for registry format conversion (order_by + sort to -prefix notation)
• Updated pagination link generation to preserve sort params
• Added sort_tags_legacy for non-keyset pagination path
• Enhanced TagDetails entity with published_at and updated_at timestamp fields
• Graceful fallback to name sorting when published_at not supported by GitLab API client

The implementation handles both keyset pagination (modern GitlabApiClient path supporting all sort fields) and legacy pagination (limited to name sorting only). When published_at sorting is requested but the registry client does not support the GitLab API, the system falls back to name sorting to maintain compatibility.

Test coverage includes parameterized tests for all sorting combinations across both pagination paths, fallback scenarios, and pagination link verification using RSpec table syntax.

Parameters default to order_by=name and sort=asc to maintain backward compatibility with existing API consumers.

🛠️ with ❤️ at Siemens

References

• Closes #573326
• Builds on keyset pagination work from !143730 (merged)

Screenshots or screen recordings

N/A - Backend API enhancement only

How to set up and validate locally

1. Ensure you have a project with container registry repositories and tags

2. Enable keyset pagination for your repository (if testing with keyset):

   # In rails console
   project = Project.find_by_full_path('your-namespace/your-project')
   repository = project.container_repositories.first
   # Ensure GitLab API client is supported (typically on GitLab.com or recent self-managed)

3. Test sorting with legacy pagination:

   # Sort by name ascending (default)
   curl -H "PRIVATE-TOKEN: $TOKEN" \
     "http://localhost:3000/api/v4/projects/1/registry/repositories/1/tags"
   
   # Sort by name descending
   curl -H "PRIVATE-TOKEN: $TOKEN" \
     "http://localhost:3000/api/v4/projects/1/registry/repositories/1/tags?order_by=name&sort=desc"

4. Test sorting with keyset pagination:

   # Sort by name ascending
   curl -H "PRIVATE-TOKEN: $TOKEN" \
     "http://localhost:3000/api/v4/projects/1/registry/repositories/1/tags?pagination=keyset&order_by=name&sort=asc"
   
   # Sort by published_at descending
   curl -H "PRIVATE-TOKEN: $TOKEN" \
     "http://localhost:3000/api/v4/projects/1/registry/repositories/1/tags?pagination=keyset&order_by=published_at&sort=desc"
   
   # Sort by created_at ascending
   curl -H "PRIVATE-TOKEN: $TOKEN" \
     "http://localhost:3000/api/v4/projects/1/registry/repositories/1/tags?pagination=keyset&order_by=created_at&sort=asc"
   
   # Sort by updated_at descending
   curl -H "PRIVATE-TOKEN: $TOKEN" \
     "http://localhost:3000/api/v4/projects/1/registry/repositories/1/tags?pagination=keyset&order_by=updated_at&sort=desc"

5. Verify pagination links include sort parameters:

   # Check Link header in response
   curl -I -H "PRIVATE-TOKEN: $TOKEN" \
     "http://localhost:3000/api/v4/projects/1/registry/repositories/1/tags?pagination=keyset&order_by=published_at&sort=desc&per_page=5"

6. Test fallback behavior when published_at is not supported:

   # On registries without GitLab API support, verify it falls back to name sorting
   curl -H "PRIVATE-TOKEN: $TOKEN" \
     "http://localhost:3000/api/v4/projects/1/registry/repositories/1/tags?pagination=keyset&order_by=published_at&sort=desc"

7. Run the test suite:

   bundle exec rspec spec/requests/api/project_container_repositories_spec.rb

8. Verify RuboCop compliance:

   bundle exec rubocop -A lib/api/helpers/container_registry_helpers.rb
   bundle exec rubocop -A lib/api/project_container_repositories.rb
   bundle exec rubocop -A lib/api/entities/container_registry.rb

MR acceptance checklist

Please evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

MR Checklist (@gerardo-navarro)

• Changelog entry added, if necessary
• Documentation created/updated via this MR
• Documentation reviewed by technical writer or follow-up review issue created
• Tests added for this feature/bug
• Tested in all supported browsers - N/A (backend only)
• Conforms to the code review guidelines
• Conforms to the style guides
• Conforms to the javascript style guides - N/A (backend only)
• Conforms to the database guides - N/A (no database changes)
• Conforms to the merge request performance guidelines
• Follows established GitLab API sorting patterns (order_by/sort parameters)
• Maintains backward compatibility with existing API consumers
• Implements graceful fallback for unsupported sort fields
• Includes parameterized tests for all sorting combinations
• Pagination links preserve sort parameters correctly