feat: Allow devs to override the reuse hash calculation (#1688)

Author: HofmeisterAn

Directory.Packages.props

@@ -52,7 +52,7 @@
         <PackageVersion Include="Confluent.SchemaRegistry.Serdes.Json" Version="2.8.0"/>
         <PackageVersion Include="Confluent.SchemaRegistry" Version="2.8.0"/>
         <PackageVersion Include="Consul" Version="1.6.10.9"/>
-        <PackageVersion Include="CouchbaseNetClient" Version="3.7.2"/>
+        <PackageVersion Include="CouchbaseNetClient" Version="3.9.2"/>
         <PackageVersion Include="DotPulsar" Version="3.6.0"/>
         <PackageVersion Include="Elastic.Clients.Elasticsearch" Version="8.19.15"/>
         <PackageVersion Include="EventStore.Client.Grpc.Streams" Version="23.3.9"/>
@@ -66,13 +66,13 @@
         <PackageVersion Include="JanusGraph.Net" Version="1.1.0"/>
         <PackageVersion Include="Keycloak.Net.Core" Version="1.0.20"/>
         <PackageVersion Include="KubernetesClient" Version="17.0.14"/>
-        <PackageVersion Include="KurrentDB.Client" Version="1.2.0"/>
+        <PackageVersion Include="KurrentDB.Client" Version="1.4.0"/>
         <PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.32.1"/>
         <PackageVersion Include="Microsoft.Azure.Kusto.Data" Version="12.2.8"/>
         <PackageVersion Include="Microsoft.Data.SqlClient" Version="5.2.2"/>
         <PackageVersion Include="Microsoft.Playwright" Version="1.55.0"/>
         <PackageVersion Include="Milvus.Client" Version="2.3.0-preview.1"/>
-        <PackageVersion Include="MongoDB.Driver" Version="3.2.0"/>
+        <PackageVersion Include="MongoDB.Driver" Version="3.8.0"/>
         <PackageVersion Include="MQTTnet" Version="5.0.1.1416"/>
         <PackageVersion Include="MyCouch" Version="7.6.0"/>
         <PackageVersion Include="MySqlConnector" Version="2.2.5"/>

docs/api/resource_reuse.md

@@ -15,6 +15,17 @@ _ = new ContainerBuilder("alpine:3.20.0")
   .WithLabel("reuse-id", "WeatherForecast");
 ```
 
+To take full control over the hash value, pass a custom function to the `WithReuse` overload. The function receives the resource configuration and returns the hash string used to identify and match the resource.
+
+```csharp title="Override the reuse hash calculation"
+_ = new ContainerBuilder("alpine:3.20.0")
+  .WithReuse(_ => "custom-hash");
+```
+
+!!! warning
+
+    A matching custom hash does not guarantee that the resource is compatible. The default implementation derives the hash from the builder configuration, so a match implies an identical configuration. With a custom hash, it is the caller's responsibility to ensure that the hash uniquely and accurately reflects the intended configuration.
+
 The current implementation considers the following resource configurations and their corresponding builder APIs when calculating the hash value.
 
 !!! note

src/Testcontainers.WebDriver/WebDriverContainer.cs

@@ -114,7 +114,7 @@ static FFmpegContainer()
         /// Initializes a new instance of the <see cref="FFmpegContainer" /> class.
         /// </summary>
         private FFmpegContainer()
-            : base(new ContainerConfiguration(new ResourceConfiguration<CreateContainerParameters>(new DockerEndpointAuthenticationConfiguration(new Uri("tcp://ffmpeg")), null, null, false, NullLogger.Instance)))
+            : base(new ContainerConfiguration(new ResourceConfiguration<CreateContainerParameters>(new DockerEndpointAuthenticationConfiguration(new Uri("tcp://ffmpeg")), null, null, false, null, NullLogger.Instance)))
         {
         }
 

src/Testcontainers/Builders/AbstractBuilder`4.cs

@@ -65,6 +65,13 @@ public TBuilderEntity WithReuse(bool reuse)
       return Clone(new ResourceConfiguration<TCreateResourceEntity>(reuse: reuse)).WithCleanUp(!reuse);
     }
 
+    /// <inheritdoc />
+    public TBuilderEntity WithReuse(Func<IResourceConfiguration<TCreateResourceEntity>, string> reuseHashProvider)
+    {
+      var reuse = reuseHashProvider != null;
+      return Clone(new ResourceConfiguration<TCreateResourceEntity>(reuse: reuse, reuseHashProvider: reuseHashProvider)).WithCleanUp(!reuse);
+    }
+
     /// <inheritdoc />
     public TBuilderEntity WithLabel(string name, string value)
     {

src/Testcontainers/Builders/IAbstractBuilder`3.cs

@@ -14,7 +14,7 @@ namespace DotNet.Testcontainers.Builders
   /// <typeparam name="TResourceEntity">The resource entity.</typeparam>
   /// <typeparam name="TCreateResourceEntity">The underlying Docker.DotNet resource entity.</typeparam>
   [PublicAPI]
-  public interface IAbstractBuilder<out TBuilderEntity, out TResourceEntity, out TCreateResourceEntity>
+  public interface IAbstractBuilder<out TBuilderEntity, out TResourceEntity, TCreateResourceEntity>
   {
     /// <summary>
     /// Sets the Docker API endpoint.
@@ -80,6 +80,26 @@ public interface IAbstractBuilder<out TBuilderEntity, out TResourceEntity, out T
     [PublicAPI]
     TBuilderEntity WithReuse(bool reuse);
 
+    /// <summary>
+    /// Reuses an existing Docker resource with a custom reuse hash.
+    /// </summary>
+    /// <remarks>
+    /// If reuse is enabled, Testcontainers will label the resource with a hash value
+    /// according to the respective build/resource configuration. When Testcontainers finds a
+    /// matching resource, it will reuse this resource instead of creating a new one. Enabling
+    /// reuse will disable the resource reaper, meaning the resource will not be cleaned up
+    /// after the tests are finished.
+    ///
+    /// This is an <b>experimental</b> feature. Reuse does not take all builder
+    /// configurations into account when calculating the hash value. There might be configurations
+    /// where Testcontainers is not, or not yet, able to find a matching resource and
+    /// recreate the resource.
+    /// </remarks>
+    /// <param name="reuseHashProvider">A function that receives the resource configuration and returns the reuse hash, replacing the default SHA-1-based implementation.</param>
+    /// <returns>A configured instance of <typeparamref name="TBuilderEntity" />.</returns>
+    [PublicAPI]
+    TBuilderEntity WithReuse(Func<IResourceConfiguration<TCreateResourceEntity>, string> reuseHashProvider);
+
     /// <summary>
     /// Adds user-defined metadata to the Docker resource.
     /// </summary>

src/Testcontainers/Configurations/Commons/IResourceConfiguration.cs

@@ -10,7 +10,7 @@ namespace DotNet.Testcontainers.Configurations
   /// </summary>
   /// <typeparam name="TCreateResourceEntity">The underlying Docker.DotNet resource entity.</typeparam>
   [PublicAPI]
-  public interface IResourceConfiguration<in TCreateResourceEntity>
+  public interface IResourceConfiguration<TCreateResourceEntity>
   {
     /// <summary>
     /// Gets the test session id.
@@ -37,6 +37,11 @@ public interface IResourceConfiguration<in TCreateResourceEntity>
     /// </summary>
     bool? Reuse { get; }
 
+    /// <summary>
+    /// Gets a function to override the reuse hash calculation, or <c>null</c> to use the default SHA-1-based implementation.
+    /// </summary>
+    Func<IResourceConfiguration<TCreateResourceEntity>, string> ReuseHashProvider { get; }
+
     /// <summary>
     /// Gets the logger.
     /// </summary>

src/Testcontainers/Configurations/Commons/ResourceConfiguration.cs

@@ -21,19 +21,22 @@ public class ResourceConfiguration<TCreateResourceEntity> : IResourceConfigurati
     /// <param name="labels">The test session id.</param>
     /// <param name="parameterModifiers">A list of low level modifications of the Docker.DotNet entity.</param>
     /// <param name="reuse">A value indicating whether to reuse an existing resource configuration or not.</param>
+    /// <param name="reuseHashProvider">A function to override the reuse hash calculation, or <c>null</c> to use the default SHA-1-based implementation.</param>
     /// <param name="logger">The logger.</param>
     public ResourceConfiguration(
       IDockerEndpointAuthenticationConfiguration dockerEndpointAuthenticationConfiguration = null,
       IReadOnlyDictionary<string, string> labels = null,
       IReadOnlyList<Action<TCreateResourceEntity>> parameterModifiers = null,
       bool? reuse = null,
+      Func<IResourceConfiguration<TCreateResourceEntity>, string> reuseHashProvider = null,
       ILogger logger = null)
     {
       SessionId = labels != null && labels.TryGetValue(ResourceReaper.ResourceReaperSessionLabel, out var resourceReaperSessionId) && Guid.TryParseExact(resourceReaperSessionId, "D", out var sessionId) ? sessionId : Guid.Empty;
       DockerEndpointAuthConfig = dockerEndpointAuthenticationConfiguration;
       Labels = labels;
       ParameterModifiers = parameterModifiers;
       Reuse = reuse;
+      ReuseHashProvider = reuseHashProvider;
       Logger = logger;
     }
 
@@ -57,6 +60,7 @@ protected ResourceConfiguration(IResourceConfiguration<TCreateResourceEntity> ol
         labels: BuildConfiguration.Combine(oldValue.Labels, newValue.Labels),
         parameterModifiers: BuildConfiguration.Combine(oldValue.ParameterModifiers, newValue.ParameterModifiers),
         reuse: (oldValue.Reuse.HasValue && oldValue.Reuse.Value) || (newValue.Reuse.HasValue && newValue.Reuse.Value),
+        reuseHashProvider: BuildConfiguration.Combine(oldValue.ReuseHashProvider, newValue.ReuseHashProvider),
         logger: BuildConfiguration.Combine(oldValue.Logger, newValue.Logger))
     {
     }
@@ -81,13 +85,22 @@ protected ResourceConfiguration(IResourceConfiguration<TCreateResourceEntity> ol
     [JsonIgnore]
     public bool? Reuse { get; }
 
+    /// <inheritdoc />
+    [JsonIgnore]
+    public Func<IResourceConfiguration<TCreateResourceEntity>, string> ReuseHashProvider { get; }
+
     /// <inheritdoc />
     [JsonIgnore]
     public ILogger Logger { get; }
 
     /// <inheritdoc />
     public virtual string GetReuseHash()
     {
+      if (ReuseHashProvider != null)
+      {
+        return ReuseHashProvider(this);
+      }
+
       var jsonUtf8Bytes = JsonSerializer.SerializeToUtf8Bytes(this, GetType(), DefaultJsonSerializerOptions.Instance);
 
 #if NET6_0_OR_GREATER

tests/Testcontainers.Couchbase.Tests/CouchbaseContainerTest.cs

@@ -25,7 +25,7 @@ public async Task GetBucketReturnsDefaultBucket()
         clusterOptions.UserName = CouchbaseBuilder.DefaultUsername;
         clusterOptions.Password = CouchbaseBuilder.DefaultPassword;
 
-        var cluster = await Cluster.ConnectAsync(clusterOptions)
+        var cluster = await Cluster.ConnectAsync(clusterOptions, TestContext.Current.CancellationToken)
             .ConfigureAwait(true);
 
         // When

tests/Testcontainers.Platform.Linux.Tests/ReusableResourceTest.cs

@@ -172,6 +172,22 @@ public void ForSameConfigurationInDifferentOrder()
                 // Then
                 Assert.Equal(hash1, hash2);
             }
+
+            [Fact]
+            [Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]
+            public void ForCustomReuseHashProvider()
+            {
+                // Given
+                const string customHash = "custom-hash";
+
+                // When
+                var hash = new ReuseHashContainerBuilder()
+                    .WithReuse(_ => customHash)
+                    .GetReuseHash();
+
+                // Then
+                Assert.Equal(customHash, hash);
+            }
         }
 
         public sealed class NotEqualTest