feat(libstore): support S3 object versioning via versionId parameter

S3 buckets support object versioning to prevent unexpected changes,
but Nix previously lacked the ability to fetch specific versions of
S3 objects. This adds support for a `versionId` query parameter in S3
URLs, enabling users to pin to specific object versions:

```
s3://bucket/key?region=us-east-1&versionId=abc123
```

Author: lovesegfault

src/libstore-tests/s3-url.cc

@@ -70,6 +70,25 @@ INSTANTIATE_TEST_SUITE_P(
             },
             "with_profile_and_region",
         },
+        ParsedS3URLTestCase{
+            "s3://my-bucket/my-key.txt?versionId=abc123xyz",
+            {
+                .bucket = "my-bucket",
+                .key = {"my-key.txt"},
+                .versionId = "abc123xyz",
+            },
+            "with_versionId",
+        },
+        ParsedS3URLTestCase{
+            "s3://bucket/path/to/object?region=eu-west-1&versionId=version456",
+            {
+                .bucket = "bucket",
+                .key = {"path", "to", "object"},
+                .region = "eu-west-1",
+                .versionId = "version456",
+            },
+            "with_region_and_versionId",
+        },
         ParsedS3URLTestCase{
             "s3://bucket/key?endpoint=https://minio.local&scheme=http",
             {
@@ -222,6 +241,37 @@ INSTANTIATE_TEST_SUITE_P(
             },
             "https://s3.ap-southeast-2.amazonaws.com/bucket/path/to/file.txt",
             "complex_path_and_region",
+        },
+        S3ToHttpsConversionTestCase{
+            ParsedS3URL{
+                .bucket = "my-bucket",
+                .key = {"my-key.txt"},
+                .versionId = "abc123xyz",
+            },
+            ParsedURL{
+                .scheme = "https",
+                .authority = ParsedURL::Authority{.host = "s3.us-east-1.amazonaws.com"},
+                .path = {"", "my-bucket", "my-key.txt"},
+                .query = {{"versionId", "abc123xyz"}},
+            },
+            "https://s3.us-east-1.amazonaws.com/my-bucket/my-key.txt?versionId=abc123xyz",
+            "with_versionId",
+        },
+        S3ToHttpsConversionTestCase{
+            ParsedS3URL{
+                .bucket = "versioned-bucket",
+                .key = {"path", "to", "object"},
+                .region = "eu-west-1",
+                .versionId = "version456",
+            },
+            ParsedURL{
+                .scheme = "https",
+                .authority = ParsedURL::Authority{.host = "s3.eu-west-1.amazonaws.com"},
+                .path = {"", "versioned-bucket", "path", "to", "object"},
+                .query = {{"versionId", "version456"}},
+            },
+            "https://s3.eu-west-1.amazonaws.com/versioned-bucket/path/to/object?versionId=version456",
+            "with_region_and_versionId",
         }),
     [](const ::testing::TestParamInfo<S3ToHttpsConversionTestCase> & info) { return info.param.description; });
 

src/libstore/include/nix/store/s3-url.hh

@@ -26,6 +26,7 @@ struct ParsedS3URL
     std::optional<std::string> profile;
     std::optional<std::string> region;
     std::optional<std::string> scheme;
+    std::optional<std::string> versionId;
     /**
      * The endpoint can be either missing, be an absolute URI (with a scheme like `http:`)
      * or an authority (so an IP address or a registered name).

src/libstore/s3-binary-cache-store.cc

@@ -22,7 +22,7 @@ S3BinaryCacheStoreConfig::S3BinaryCacheStoreConfig(
     assert(cacheUri.query.empty());
 
     // Only copy S3-specific parameters to the URL query
-    static const std::set<std::string> s3Params = {"region", "endpoint", "profile", "scheme"};
+    static const std::set<std::string> s3Params = {"region", "endpoint", "profile", "scheme", "versionId"};
     for (const auto & [key, value] : params) {
         if (s3Params.contains(key)) {
             cacheUri.query[key] = value;

src/libstore/s3-url.cc

@@ -48,6 +48,7 @@ try {
         .profile = getOptionalParam("profile"),
         .region = getOptionalParam("region"),
         .scheme = getOptionalParam("scheme"),
+        .versionId = getOptionalParam("versionId"),
         .endpoint = [&]() -> decltype(ParsedS3URL::endpoint) {
             if (!endpoint)
                 return std::monostate();
@@ -73,6 +74,12 @@ ParsedURL ParsedS3URL::toHttpsUrl() const
     auto regionStr = region.transform(toView).value_or("us-east-1");
     auto schemeStr = scheme.transform(toView).value_or("https");
 
+    // Build query parameters (e.g., versionId if present)
+    StringMap queryParams;
+    if (versionId) {
+        queryParams["versionId"] = *versionId;
+    }
+
     // Handle endpoint configuration using std::visit
     return std::visit(
         overloaded{
@@ -85,6 +92,7 @@ ParsedURL ParsedS3URL::toHttpsUrl() const
                     .scheme = std::string{schemeStr},
                     .authority = ParsedURL::Authority{.host = "s3." + regionStr + ".amazonaws.com"},
                     .path = std::move(path),
+                    .query = queryParams,
                 };
             },
             [&](const ParsedURL::Authority & auth) {
@@ -96,6 +104,7 @@ ParsedURL ParsedS3URL::toHttpsUrl() const
                     .scheme = std::string{schemeStr},
                     .authority = auth,
                     .path = std::move(path),
+                    .query = queryParams,
                 };
             },
             [&](const ParsedURL & endpointUrl) {
@@ -107,6 +116,7 @@ ParsedURL ParsedS3URL::toHttpsUrl() const
                     .scheme = endpointUrl.scheme,
                     .authority = endpointUrl.authority,
                     .path = std::move(path),
+                    .query = queryParams,
                 };
             },
         },

tests/nixos/s3-binary-cache-store.nix

@@ -133,19 +133,22 @@ in
               print(output)
               raise Exception(f"{error_msg}: expected {expected}, got {actual}")
 
-      def with_test_bucket(populate_with=[]):
+      def with_test_bucket(populate_with=[], versioned=False):
           """
           Decorator that creates/destroys a unique bucket for each test.
           Optionally pre-populates bucket with specified packages.
 
           Args:
               populate_with: List of packages to upload before test runs
+              versioned: If True, enable versioning on the bucket before populating
           """
           def decorator(test_func):
               def wrapper():
                   bucket = str(uuid.uuid4())
                   server.succeed(f"mc mb minio/{bucket}")
                   try:
+                      if versioned:
+                          server.succeed(f"mc version enable minio/{bucket}")
                       if populate_with:
                           store_url = make_s3_url(bucket)
                           for pkg in populate_with:
@@ -472,6 +475,47 @@ in
 
           print("  ✓ No compression applied by default")
 
+      @with_test_bucket(populate_with=[PKG_A], versioned=True)
+      def test_versioned_urls(bucket):
+          """Test that versionId parameter is accepted in S3 URLs"""
+          print("\n=== Testing Versioned URLs ===")
+
+          # Get the nix-cache-info file
+          cache_info_url = make_s3_url(bucket, path="/nix-cache-info")
+
+          # Fetch without versionId should work
+          client.succeed(
+              f"{ENV_WITH_CREDS} nix eval --impure --expr "
+              f"'builtins.fetchurl {{ name = \"cache-info\"; url = \"{cache_info_url}\"; }}'"
+          )
+          print("  ✓ Fetch without versionId works")
+
+          # List versions to get a version ID
+          # MinIO output format: [timestamp] size tier versionId versionNumber method filename
+          versions_output = server.succeed(f"mc ls --versions minio/{bucket}/nix-cache-info")
+
+          # Extract version ID from output (4th field after STANDARD)
+          import re
+          version_match = re.search(r'STANDARD\s+(\S+)\s+v\d+', versions_output)
+          if not version_match:
+              print(f"Debug: versions output: {versions_output}")
+              raise Exception("Could not extract version ID from MinIO output")
+
+          version_id = version_match.group(1)
+          print(f"  ✓ Found version ID: {version_id}")
+
+          # Version ID should not be "null" since versioning was enabled before upload
+          if version_id == "null":
+              raise Exception("Version ID is 'null' - versioning may not be working correctly")
+
+          # Fetch with versionId parameter
+          versioned_url = f"{cache_info_url}&versionId={version_id}"
+          client.succeed(
+              f"{ENV_WITH_CREDS} nix eval --impure --expr "
+              f"'builtins.fetchurl {{ name = \"cache-info-versioned\"; url = \"{versioned_url}\"; }}'"
+          )
+          print("  ✓ Fetch with versionId parameter works")
+
       # ============================================================================
       # Main Test Execution
       # ============================================================================
@@ -499,6 +543,7 @@ in
       test_compression_narinfo_gzip()
       test_compression_mixed()
       test_compression_disabled()
+      test_versioned_urls()
 
       print("\n" + "="*80)
       print("✓ All S3 Binary Cache Store Tests Passed!")