feat(libstore): support S3 Transfer Acceleration

Implements AWS S3 Transfer Acceleration for binary cache stores to
improve upload and download performance when accessing S3 buckets from
geographically distant locations. Transfers are routed through
CloudFront edge locations for better performance.

Usage:
  nix copy nixpkgs.hello \
    --to 's3://my-cache?region=ap-northeast-1&use-transfer-acceleration=true'

Requirements:
- DNS-compliant bucket names (3-63 chars, lowercase, numbers, hyphens)
- No dots in bucket names
- Transfer Acceleration enabled on the S3 bucket
- Only applies to AWS S3 (ignored for custom endpoints)

Author: lovesegfault

doc/manual/rl-next/s3-transfer-acceleration.md

@@ -0,0 +1,32 @@
+---
+synopsis: "S3 Transfer Acceleration support for faster remote cache access"
+issues: [12973]
+prs: [14277]
+---
+
+S3 binary cache stores now support AWS S3 Transfer Acceleration for faster
+uploads and downloads when accessing buckets from geographically distant
+locations.
+
+Transfer Acceleration routes S3 requests through CloudFront edge locations,
+which can significantly improve performance for users far from the bucket's
+region. For example, US-based users accessing Tokyo-region buckets can see
+substantial speed improvements.
+
+To enable transfer acceleration, add `use-transfer-acceleration=true` to your
+S3 URL:
+
+```console
+$ nix copy nixpkgs.hello \
+  --to 's3://my-cache?region=ap-northeast-1&use-transfer-acceleration=true'
+```
+
+Requirements:
+- Bucket names must be DNS-compliant (3-63 characters, lowercase letters,
+  numbers, and hyphens only)
+- Bucket names with dots are not supported
+- Transfer Acceleration must be enabled on the S3 bucket
+- Additional AWS charges apply for Transfer Acceleration
+
+This feature only applies to AWS S3 buckets and has no effect when using custom
+endpoints for S3-compatible services.

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

@@ -122,4 +122,68 @@ TEST(S3BinaryCacheStore, parameterFiltering)
     EXPECT_EQ(ref.params["priority"], "10");
 }
 
+/**
+ * Test that transfer acceleration parameter is properly preserved
+ */
+TEST(S3BinaryCacheStore, transferAccelerationParameter)
+{
+    StringMap params;
+    params["use-transfer-acceleration"] = "true";
+
+    S3BinaryCacheStoreConfig config("s3", "my-cache", params);
+
+    // Transfer acceleration param should be in cacheUri.query
+    EXPECT_EQ(
+        config.cacheUri,
+        (ParsedURL{
+            .scheme = "s3",
+            .authority = ParsedURL::Authority{.host = "my-cache"},
+            .query = (StringMap) {{"use-transfer-acceleration", "true"}},
+        }));
+
+    // And the config setting should be set
+    EXPECT_EQ(config.use_transfer_acceleration.get(), true);
+}
+
+/**
+ * Test that transfer acceleration works with other S3 parameters
+ */
+TEST(S3BinaryCacheStore, transferAccelerationWithOtherParams)
+{
+    StringMap params;
+    params["region"] = "ap-northeast-1";
+    params["use-transfer-acceleration"] = "true";
+    params["profile"] = "production";
+
+    S3BinaryCacheStoreConfig config("s3", "tokyo-cache", params);
+
+    EXPECT_EQ(
+        config.cacheUri,
+        (ParsedURL{
+            .scheme = "s3",
+            .authority = ParsedURL::Authority{.host = "tokyo-cache"},
+            .query =
+                (StringMap) {
+                    {"region", "ap-northeast-1"},
+                    {"use-transfer-acceleration", "true"},
+                    {"profile", "production"},
+                },
+        }));
+
+    EXPECT_EQ(config.region.get(), "ap-northeast-1");
+    EXPECT_EQ(config.use_transfer_acceleration.get(), true);
+    EXPECT_EQ(config.profile.get(), "production");
+}
+
+/**
+ * Test default value for transfer acceleration
+ */
+TEST(S3BinaryCacheStore, transferAccelerationDefaultValue)
+{
+    S3BinaryCacheStoreConfig config("s3", "test-bucket", {});
+
+    // Default should be false
+    EXPECT_EQ(config.use_transfer_acceleration.get(), false);
+}
+
 } // namespace nix

src/libstore-tests/s3-url.cc

@@ -85,6 +85,33 @@ INSTANTIATE_TEST_SUITE_P(
                     },
             },
             "with_absolute_endpoint_uri",
+        },
+        ParsedS3URLTestCase{
+            "s3://my-bucket/key?use-transfer-acceleration=true",
+            {
+                .bucket = "my-bucket",
+                .key = {"key"},
+                .use_transfer_acceleration = true,
+            },
+            "with_transfer_acceleration",
+        },
+        ParsedS3URLTestCase{
+            "s3://my-bucket/key?use-transfer-acceleration=false",
+            {
+                .bucket = "my-bucket",
+                .key = {"key"},
+                .use_transfer_acceleration = false,
+            },
+            "with_transfer_acceleration_false",
+        },
+        ParsedS3URLTestCase{
+            "s3://my-bucket/key?use-transfer-acceleration=1",
+            {
+                .bucket = "my-bucket",
+                .key = {"key"},
+                .use_transfer_acceleration = true,
+            },
+            "with_transfer_acceleration_numeric",
         }),
     [](const ::testing::TestParamInfo<ParsedS3URLTestCase> & info) { return info.param.description; });
 
@@ -119,6 +146,75 @@ INSTANTIATE_TEST_SUITE_P(
         InvalidS3URLTestCase{"s3://bucket", "error: URI has a missing or invalid key", "missing_key"}),
     [](const ::testing::TestParamInfo<InvalidS3URLTestCase> & info) { return info.param.description; });
 
+// =============================================================================
+// Transfer Acceleration Bucket Name Validation Tests
+// =============================================================================
+
+struct InvalidTransferAccelerationBucketTestCase
+{
+    std::string url;
+    std::string expectedErrorSubstring;
+    std::string description;
+};
+
+class InvalidTransferAccelerationBucketTest
+    : public ::testing::WithParamInterface<InvalidTransferAccelerationBucketTestCase>,
+      public ::testing::Test
+{};
+
+TEST_P(InvalidTransferAccelerationBucketTest, rejectsInvalidBucketNames)
+{
+    const auto & testCase = GetParam();
+    auto parsed = ParsedS3URL::parse(parseURL(testCase.url));
+
+    ASSERT_THAT(
+        [&parsed]() { parsed.toHttpsUrl(); },
+        ::testing::ThrowsMessage<Error>(testing::HasSubstrIgnoreANSIMatcher(testCase.expectedErrorSubstring)));
+}
+
+INSTANTIATE_TEST_SUITE_P(
+    InvalidBucketNames,
+    InvalidTransferAccelerationBucketTest,
+    ::testing::Values(
+        InvalidTransferAccelerationBucketTestCase{
+            "s3://bucket.with.dots/key?use-transfer-acceleration=true",
+            "is not compatible with S3 Transfer Acceleration",
+            "bucket_with_dots",
+        },
+        InvalidTransferAccelerationBucketTestCase{
+            "s3://BucketWithCaps/key?use-transfer-acceleration=true",
+            "is not compatible with S3 Transfer Acceleration",
+            "bucket_with_uppercase",
+        },
+        InvalidTransferAccelerationBucketTestCase{
+            "s3://ab/key?use-transfer-acceleration=true",
+            "is not compatible with S3 Transfer Acceleration",
+            "bucket_too_short",
+        },
+        InvalidTransferAccelerationBucketTestCase{
+            "s3://this-is-a-very-long-bucket-name-that-exceeds-the-maximum-length-limit/key?use-transfer-acceleration=true",
+            "is not compatible with S3 Transfer Acceleration",
+            "bucket_too_long",
+        },
+        InvalidTransferAccelerationBucketTestCase{
+            "s3://bucket_with_underscore/key?use-transfer-acceleration=true",
+            "is not compatible with S3 Transfer Acceleration",
+            "bucket_with_underscore",
+        },
+        InvalidTransferAccelerationBucketTestCase{
+            "s3://-starts-with-hyphen/key?use-transfer-acceleration=true",
+            "is not compatible with S3 Transfer Acceleration",
+            "bucket_starts_with_hyphen",
+        },
+        InvalidTransferAccelerationBucketTestCase{
+            "s3://ends-with-hyphen-/key?use-transfer-acceleration=true",
+            "is not compatible with S3 Transfer Acceleration",
+            "bucket_ends_with_hyphen",
+        }),
+    [](const ::testing::TestParamInfo<InvalidTransferAccelerationBucketTestCase> & info) {
+        return info.param.description;
+    });
+
 // =============================================================================
 // S3 URL to HTTPS Conversion Tests
 // =============================================================================
@@ -222,6 +318,64 @@ INSTANTIATE_TEST_SUITE_P(
             },
             "https://s3.ap-southeast-2.amazonaws.com/bucket/path/to/file.txt",
             "complex_path_and_region",
+        },
+        S3ToHttpsConversionTestCase{
+            ParsedS3URL{
+                .bucket = "my-cache",
+                .key = {"nix", "store", "abc123.nar.xz"},
+                .use_transfer_acceleration = true,
+            },
+            ParsedURL{
+                .scheme = "https",
+                .authority = ParsedURL::Authority{.host = "my-cache.s3-accelerate.amazonaws.com"},
+                .path = {"", "nix", "store", "abc123.nar.xz"},
+            },
+            "https://my-cache.s3-accelerate.amazonaws.com/nix/store/abc123.nar.xz",
+            "transfer_acceleration_enabled",
+        },
+        S3ToHttpsConversionTestCase{
+            ParsedS3URL{
+                .bucket = "tokyo-cache",
+                .key = {"key.txt"},
+                .region = "ap-northeast-1",
+                .use_transfer_acceleration = true,
+            },
+            ParsedURL{
+                .scheme = "https",
+                .authority = ParsedURL::Authority{.host = "tokyo-cache.s3-accelerate.amazonaws.com"},
+                .path = {"", "key.txt"},
+            },
+            "https://tokyo-cache.s3-accelerate.amazonaws.com/key.txt",
+            "transfer_acceleration_with_region",
+        },
+        S3ToHttpsConversionTestCase{
+            ParsedS3URL{
+                .bucket = "my-bucket",
+                .key = {"file"},
+                .use_transfer_acceleration = false,
+            },
+            ParsedURL{
+                .scheme = "https",
+                .authority = ParsedURL::Authority{.host = "s3.us-east-1.amazonaws.com"},
+                .path = {"", "my-bucket", "file"},
+            },
+            "https://s3.us-east-1.amazonaws.com/my-bucket/file",
+            "transfer_acceleration_explicitly_disabled",
+        },
+        S3ToHttpsConversionTestCase{
+            ParsedS3URL{
+                .bucket = "bucket",
+                .key = {"key"},
+                .use_transfer_acceleration = true,
+                .endpoint = ParsedURL::Authority{.host = "minio.local"},
+            },
+            ParsedURL{
+                .scheme = "https",
+                .authority = ParsedURL::Authority{.host = "minio.local"},
+                .path = {"", "bucket", "key"},
+            },
+            "https://minio.local/bucket/key",
+            "transfer_acceleration_with_custom_endpoint_ignored",
         }),
     [](const ::testing::TestParamInfo<S3ToHttpsConversionTestCase> & info) { return info.param.description; });
 

src/libstore/include/nix/store/s3-binary-cache-store.hh

@@ -63,6 +63,31 @@ public:
           > addressing instead of virtual host based addressing.
         )"};
 
+    const Setting<bool> use_transfer_acceleration{
+        this,
+        false,
+        "use-transfer-acceleration",
+        R"(
+          Whether to use AWS S3 Transfer Acceleration for faster uploads and downloads
+          by routing transfers through CloudFront edge locations. This is particularly
+          useful when accessing S3 buckets from geographically distant locations.
+
+          When enabled, requests are routed to `bucket-name.s3-accelerate.amazonaws.com`
+          instead of the standard regional endpoint.
+
+          > **Note**
+          >
+          > Transfer Acceleration requires DNS-compliant bucket names (3-63 characters,
+          > lowercase letters, numbers, and hyphens only). Bucket names with dots are
+          > not supported.
+          >
+          > This setting only applies to AWS S3 buckets. It has no effect when using
+          > custom endpoints for S3-compatible services.
+          >
+          > Additional charges apply for Transfer Acceleration. See AWS documentation
+          > for pricing details.
+        )"};
+
     static const std::string name()
     {
         return "S3 Binary Cache Store";

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<bool> use_transfer_acceleration;
     /**
      * 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,8 @@ 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", "use-transfer-acceleration"};
     for (const auto & [key, value] : params) {
         if (s3Params.contains(key)) {
             cacheUri.query[key] = value;

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

@@ -83,6 +83,28 @@ Your account will need an IAM policy to support uploading to the bucket:
 }
 ```
 
+### S3 Transfer Acceleration
+
+For faster uploads and downloads when accessing S3 buckets from geographically distant locations, you can enable AWS S3 Transfer Acceleration. This routes transfers through CloudFront edge locations for improved performance.
+
+To enable transfer acceleration, add the `use-transfer-acceleration=true` parameter to your S3 URL:
+
+```console
+$ nix copy nixpkgs.hello \
+  --to 's3://example-nix-cache?use-transfer-acceleration=true&region=ap-northeast-1'
+```
+
+#### Requirements for Transfer Acceleration
+
+- Your bucket name must be DNS-compliant (3-63 characters, lowercase letters, numbers, and hyphens only)
+- Bucket names containing dots (`.`) are not supported
+- Transfer Acceleration must be enabled on your S3 bucket (see [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/transfer-acceleration.html))
+- Additional charges apply for Transfer Acceleration (see AWS pricing)
+
+> **Note**
+>
+> Transfer Acceleration only works with AWS S3 buckets. It has no effect when using custom endpoints for S3-compatible services like MinIO.
+
 ### Examples
 
 With bucket policies and authentication set up as described above, uploading works via [`nix copy`](@docroot@/command-ref/new-cli/nix3-copy.md) (experimental).
@@ -101,4 +123,11 @@ With bucket policies and authentication set up as described above, uploading wor
     's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com'
   ```
 
+- To use S3 Transfer Acceleration for faster transfers from distant locations:
+
+  ```console
+  $ nix copy nixpkgs.hello \
+    --to 's3://my-cache?profile=cache-upload&region=ap-northeast-1&use-transfer-acceleration=true'
+  ```
+
 )"