[testcontainers#466] #IMPLEMENT 'assemblyName: DotNet.Testcontainers;…

… function: Image Name Substitution'

src/DotNet.Testcontainers/Builders/IImageNameSubstitutor.cs

@@ -0,0 +1,22 @@
+namespace DotNet.Testcontainers.Builders
+{
+  using DotNet.Testcontainers.Images;
+
+  /// <summary>
+  /// Substitutes the fullname of a <see cref="IDockerImage"/>.
+  /// The nature of the substitution is up to the implementation.
+  /// </summary>
+  public interface IImageNameSubstitutor
+  {
+    /// <summary>
+    /// Applies a substitution to the fullname of an image.
+    /// </summary>
+    /// <param name="originalImage">
+    /// The image to modify.
+    /// </param>
+    /// <returns>
+    /// The modified image.
+    /// </returns>
+    IDockerImage ApplyTo(IDockerImage originalImage);
+  }
+}

src/DotNet.Testcontainers/Builders/ImageNameSubstitutor.cs

@@ -0,0 +1,26 @@
+namespace DotNet.Testcontainers.Builders
+{
+  using DotNet.Testcontainers.Configurations;
+  using DotNet.Testcontainers.Images;
+
+  public class ImageNameSubstitutor
+  {
+    public static IImageNameSubstitutor Create()
+    {
+      if (TestcontainersSettings.DockerHubImagePrefix != null)
+      {
+        return new PrefixingImageNameSubstitutor(TestcontainersSettings.DockerHubImagePrefix);
+      }
+
+      return new NoopImageSubstitutor();
+    }
+
+    public class NoopImageSubstitutor : IImageNameSubstitutor
+    {
+      public IDockerImage ApplyTo(IDockerImage originalImage)
+      {
+        return originalImage;
+      }
+    }
+  }
+}

src/DotNet.Testcontainers/Builders/PrefixingImageNameSubstitutor.cs

@@ -0,0 +1,41 @@
+namespace DotNet.Testcontainers.Builders
+{
+  using DotNet.Testcontainers.Images;
+
+  /// <summary>
+  /// Prepends a prefix to the fullname of a Docker image.
+  /// Applies only to images hosted on Docker Hub.
+  /// </summary>
+  /// <example>
+  /// With a configured prefix of "my.proxy.com":
+  /// docker:latest -> my.proxy.com/docker:latest
+  /// my.azurecr.io/docker:latest -> my.azurecr.io/docker:latest
+  /// </example>
+  public class PrefixingImageNameSubstitutor : IImageNameSubstitutor
+  {
+    /// <summary>
+    /// The prefix to prepend to the fullname of the image.
+    /// </summary>
+    private readonly string prefix;
+
+    public PrefixingImageNameSubstitutor(string prefix)
+    {
+      Guard.Argument(prefix, nameof(prefix))
+        .NotNull();
+
+      this.prefix = prefix;
+    }
+
+    /// <inheritdoc />>
+    public IDockerImage ApplyTo(IDockerImage originalImage)
+    {
+      var imageHostedOnDockerHub = originalImage.GetHostname() == null;
+      if (!imageHostedOnDockerHub)
+      {
+        return originalImage;
+      }
+
+      return new DockerImage(originalImage.Repository.Length == 0 ? this.prefix : $"{this.prefix}/{originalImage.Repository}", originalImage.Name, originalImage.Tag);
+    }
+  }
+}

src/DotNet.Testcontainers/Builders/TestcontainersBuilder.cs

@@ -276,10 +276,12 @@ public TDockerContainer Build()
       Guard.Argument(this.DockerResourceConfiguration.Image, nameof(ITestcontainersConfiguration.Image))
         .NotNull();
 
+      var finalizedDockerResourceConfiguration = this.FinalizeConfiguration();
+
 #pragma warning disable S3011
 
       // Create container instance.
-      var container = (TDockerContainer)Activator.CreateInstance(typeof(TDockerContainer), BindingFlags.NonPublic | BindingFlags.Instance, null, new object[] { this.DockerResourceConfiguration, TestcontainersSettings.Logger }, null);
+      var container = (TDockerContainer)Activator.CreateInstance(typeof(TDockerContainer), BindingFlags.NonPublic | BindingFlags.Instance, null, new object[] { finalizedDockerResourceConfiguration, TestcontainersSettings.Logger }, null);
 
 #pragma warning restore S3011
 
@@ -289,6 +291,11 @@ public TDockerContainer Build()
       return container;
     }
 
+    private ITestcontainersConfiguration FinalizeConfiguration()
+    {
+      return this.DockerResourceConfiguration.Apply(ImageNameSubstitutor.Create());
+    }
+
 #pragma warning disable S107
 
     /// <inheritdoc />

src/DotNet.Testcontainers/Configurations/Containers/ITestcontainersConfiguration.cs

@@ -4,6 +4,7 @@ namespace DotNet.Testcontainers.Configurations
   using System.Collections.Generic;
   using System.Threading;
   using System.Threading.Tasks;
+  using Builders;
   using DotNet.Testcontainers.Containers;
   using DotNet.Testcontainers.Images;
   using DotNet.Testcontainers.Networks;
@@ -100,5 +101,16 @@ public interface ITestcontainersConfiguration : IDockerResourceConfiguration
     /// This callback will be executed after starting the container, but before executing the wait strategies.
     /// </remarks>
     Func<ITestcontainersContainer, CancellationToken, Task> StartupCallback { get; }
+
+    /// <summary>
+    /// Applies the given <see cref="IImageNameSubstitutor" /> to the configured <see cref="IDockerImage" />.
+    /// </summary>
+    /// <param name="imageNameSubstitutor">
+    /// The <see cref="IImageNameSubstitutor" /> to apply
+    /// </param>
+    /// <returns>
+    /// Configuration with the modified <see cref="IDockerImage" />
+    /// </returns>
+    ITestcontainersConfiguration Apply(IImageNameSubstitutor imageNameSubstitutor);
   }
 }

src/DotNet.Testcontainers/Configurations/Containers/TestcontainersConfiguration.cs

@@ -4,6 +4,7 @@ namespace DotNet.Testcontainers.Configurations
   using System.Collections.Generic;
   using System.Threading;
   using System.Threading.Tasks;
+  using Builders;
   using DotNet.Testcontainers.Containers;
   using DotNet.Testcontainers.Images;
   using DotNet.Testcontainers.Networks;
@@ -137,5 +138,31 @@ public TestcontainersConfiguration(
 
     /// <inheritdoc />
     public Func<ITestcontainersContainer, CancellationToken, Task> StartupCallback { get; }
+
+    /// <inheritdoc />
+    public ITestcontainersConfiguration Apply(IImageNameSubstitutor imageNameSubstitutor)
+    {
+      var substitutedImageName = imageNameSubstitutor.ApplyTo(this.Image);
+      return new TestcontainersConfiguration(
+        this.Endpoint,
+        this.DockerRegistryAuthConfig,
+        substitutedImageName,
+        this.Name,
+        this.Hostname,
+        this.WorkingDirectory,
+        this.Entrypoint,
+        this.Command,
+        this.Environments,
+        this.Labels,
+        this.ExposedPorts,
+        this.PortBindings,
+        this.Mounts,
+        this.Networks,
+        this.OutputConsumer,
+        this.WaitStrategies,
+        this.StartupCallback,
+        this.AutoRemove,
+        this.Privileged);
+    }
   }
 }

src/DotNet.Testcontainers/Configurations/TestcontainersSettings.cs

@@ -17,6 +17,11 @@ public static class TestcontainersSettings
     public static bool ResourceReaperEnabled { get; set; }
       = true;
 
+    /// <summary>
+    /// Gets or sets a prefix to prepend to image names for images hosted on DockerHub.
+    /// </summary>
+    public static string DockerHubImagePrefix { get; set; }
+
     /// <summary>
     /// Gets or sets the logger.
     /// </summary>

src/DotNet.Testcontainers/Containers/TestcontainersContainer.cs

@@ -103,6 +103,15 @@ public string Hostname
       }
     }
 
+    /// <inheritdoc />
+    public string ImageName
+    {
+      get
+      {
+        return this.configuration.Image.FullName;
+      }
+    }
+
     /// <inheritdoc />
     public TestcontainersState State
     {

tests/DotNet.Testcontainers.Tests/Unit/Builders/ImageNameSubstitutorTest.cs

@@ -0,0 +1,26 @@
+namespace DotNet.Testcontainers.Tests.Unit.Builders;
+
+using DotNet.Testcontainers.Builders;
+using DotNet.Testcontainers.Configurations;
+using Xunit;
+
+public class ImageNameSubstitutorTest
+{
+  [Fact]
+  public void CreatesNoopImageNameSubstitutorWhenNothingElseIsConfigured()
+  {
+    var substitutor = ImageNameSubstitutor.Create();
+
+    Assert.IsType<ImageNameSubstitutor.NoopImageSubstitutor>(substitutor);
+  }
+
+  [Fact]
+  public void CreatesPrefixingImageNameSubstitutorWhenDockerHubImagePrefixIsConfigured()
+  {
+    TestcontainersSettings.DockerHubImagePrefix = "my.proxy.com";
+
+    var substitutor = ImageNameSubstitutor.Create();
+
+    Assert.IsType<PrefixingImageNameSubstitutor>(substitutor);
+  }
+}

tests/DotNet.Testcontainers.Tests/Unit/Builders/PrefixingImageNameSubstitutorTest.cs

@@ -0,0 +1,28 @@
+namespace DotNet.Testcontainers.Tests.Unit.Builders;
+
+using DotNet.Testcontainers.Builders;
+using DotNet.Testcontainers.Images;
+using Xunit;
+
+public class PrefixingImageNameSubstitutorTest
+{
+
+  [Theory]
+  [InlineData("my.proxy.com", "bar", "my.proxy.com/bar:latest")]
+  [InlineData("my.proxy.com", "bar:latest", "my.proxy.com/bar:latest")]
+  [InlineData("my.proxy.com", "bar:1.0.0", "my.proxy.com/bar:1.0.0")]
+  [InlineData("my.proxy.com", "foo/bar:1.0.0", "my.proxy.com/foo/bar:1.0.0")]
+  [InlineData("my.proxy.com:443", "foo/bar:1.0.0", "my.proxy.com:443/foo/bar:1.0.0")]
+  [InlineData("my.proxy.com", "myregistry.azurecr.io/foo/bar:1.0.0", "myregistry.azurecr.io/foo/bar:1.0.0")]
+  [InlineData("my.proxy.com", "myregistry.azurecr.io:443/foo/bar:1.0.0", "myregistry.azurecr.io:443/foo/bar:1.0.0")]
+  public void ShouldAddPrefixForDockerHubImages(string prefix, string originalImageFullName, string expectedFullName)
+  {
+    var substitutor = new PrefixingImageNameSubstitutor(prefix);
+
+    var originalImage = new DockerImage(originalImageFullName);
+
+    var actual = substitutor.ApplyTo(originalImage);
+
+    Assert.Equal(expectedFullName, actual.FullName);
+  }
+}

tests/DotNet.Testcontainers.Tests/Unit/Builders/TestcontainerBuilderTest.cs

@@ -0,0 +1,33 @@
+namespace DotNet.Testcontainers.Tests.Unit.Builders;
+
+using DotNet.Testcontainers.Builders;
+using DotNet.Testcontainers.Configurations;
+using DotNet.Testcontainers.Containers;
+using Xunit;
+
+public class TestcontainerBuilderTest
+{
+  [Fact]
+  public void BuildAppliesDoesNotChangeImageNameWhenNoSubstitutorIsConfigured()
+  {
+    TestcontainersSettings.DockerHubImagePrefix = null;
+
+    var container = new TestcontainersBuilder<TestcontainersContainer>()
+      .WithImage("foo/bar:1.0.0")
+      .Build();
+
+    Assert.Equal("foo/bar:1.0.0", container.ImageName);
+  }
+
+  [Fact]
+  public void BuildAppliesPrexifingImageNameSubstitutorWhenDockerHubImagePrefixIsConfigured()
+  {
+    TestcontainersSettings.DockerHubImagePrefix = "my.proxy.com";
+
+    var container = new TestcontainersBuilder<TestcontainersContainer>()
+      .WithImage("foo/bar:1.0.0")
+      .Build();
+
+    Assert.Equal("my.proxy.com/foo/bar:1.0.0", container.ImageName);
+  }
+}