feat: Add connect to network API

Author: HofmeisterAn

src/Testcontainers/Containers/DockerContainer.cs

@@ -12,6 +12,7 @@ namespace DotNet.Testcontainers.Containers
   using DotNet.Testcontainers.Clients;
   using DotNet.Testcontainers.Configurations;
   using DotNet.Testcontainers.Images;
+  using DotNet.Testcontainers.Networks;
   using JetBrains.Annotations;
   using Microsoft.Extensions.Logging;
 
@@ -373,6 +374,26 @@ await UnsafeUnpauseAsync(ct)
         .ConfigureAwait(false);
     }
 
+    /// <inheritdoc />
+    public async Task ConnectAsync(string network, CancellationToken ct = default)
+    {
+      using var disposable = await AcquireLockAsync(ct)
+        .ConfigureAwait(false);
+
+      await UnsafeConnectAsync(network, ct)
+        .ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    public async Task ConnectAsync(INetwork network, CancellationToken ct = default)
+    {
+      using var disposable = await AcquireLockAsync(ct)
+        .ConfigureAwait(false);
+
+      await UnsafeConnectAsync(network.Name, ct)
+        .ConfigureAwait(false);
+    }
+
     /// <inheritdoc />
     public Task CopyAsync(byte[] fileContent, string filePath, uint uid = 0, uint gid = 0, UnixFileModes fileMode = Unix.FileMode644, CancellationToken ct = default)
     {
@@ -688,6 +709,28 @@ await _client.UnpauseAsync(_container.ID, ct)
       Unpaused?.Invoke(this, EventArgs.Empty);
     }
 
+    /// <summary>
+    /// Connects the container to an existing network.
+    /// </summary>
+    /// <remarks>
+    /// Only the public members <see cref="ConnectAsync(string, CancellationToken)" /> and <see cref="ConnectAsync(INetwork, CancellationToken)" /> are thread-safe for now.
+    /// </remarks>
+    /// <param name="network">The network name.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Task that completes when the container has been connected to the network.</returns>
+    protected virtual async Task UnsafeConnectAsync(string network, CancellationToken ct = default)
+    {
+      ThrowIfLockNotAcquired();
+
+      ThrowIfResourceNotFound();
+
+      await _client.Network.ConnectAsync(network, _container.ID, ct)
+        .ConfigureAwait(false);
+
+      _container = await _client.Container.ByIdAsync(_container.ID, ct)
+        .ConfigureAwait(false);
+    }
+
     /// <inheritdoc />
     protected override bool Exists()
     {

src/Testcontainers/Containers/IContainer.cs

@@ -7,6 +7,7 @@ namespace DotNet.Testcontainers.Containers
   using System.Threading.Tasks;
   using DotNet.Testcontainers.Configurations;
   using DotNet.Testcontainers.Images;
+  using DotNet.Testcontainers.Networks;
   using JetBrains.Annotations;
   using Microsoft.Extensions.Logging;
 
@@ -252,6 +253,22 @@ public interface IContainer : IConnectionStringProvider, IAsyncDisposable
     /// <exception cref="TaskCanceledException">Thrown when a Testcontainers task gets canceled.</exception>
     Task UnpauseAsync(CancellationToken ct = default);
 
+    /// <summary>
+    /// Connects the running container to an existing network.
+    /// </summary>
+    /// <param name="network">The existing network to connect to.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Task that completes when the container has been connected to the network.</returns>
+    Task ConnectAsync(string network, CancellationToken ct = default);
+
+    /// <summary>
+    /// Connects the running container to an existing network.
+    /// </summary>
+    /// <param name="network">The existing network to connect to.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Task that completes when the container has been connected to the network.</returns>
+    Task ConnectAsync(INetwork network, CancellationToken ct = default);
+
     /// <summary>
     /// Copies a test host file to the container.
     /// </summary>
@@ -261,7 +278,7 @@ public interface IContainer : IConnectionStringProvider, IAsyncDisposable
     /// <param name="gid">The group ID to set for the copied file or directory. Defaults to 0 (root).</param>
     /// <param name="fileMode">The POSIX file mode permission.</param>
     /// <param name="ct">Cancellation token.</param>
-    /// <returns></returns>
+    /// <returns>A task that completes when the array content has been copied.</returns>
     Task CopyAsync(byte[] fileContent, string filePath, uint uid = 0, uint gid = 0, UnixFileModes fileMode = Unix.FileMode644, CancellationToken ct = default);
 
     /// <summary>

src/Testcontainers/Images/MatchImage.cs

@@ -44,7 +44,7 @@ static ReferenceRegex()
       }
 
       private ReferenceRegex()
-        : base(Pattern, RegexOptions.Compiled, TimeSpan.FromSeconds(1))
+        : base(Pattern, RegexOptions.Compiled, TimeSpan.FromSeconds(5))
       {
       }
 

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

@@ -0,0 +1,45 @@
+namespace Testcontainers.Tests;
+
+public sealed class NetworkConnectTest
+{
+    [Fact]
+    [Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]
+    public async Task ConnectsRunningContainerToExistingNetworks()
+    {
+        // Given
+        await using var networkByName = new NetworkBuilder()
+            .Build();
+
+        await using var networkByReference = new NetworkBuilder()
+            .Build();
+
+        await using var container = new ContainerBuilder(CommonImages.Alpine)
+            .WithCommand(CommonCommands.SleepInfinity)
+            .Build();
+
+        await networkByName.CreateAsync(TestContext.Current.CancellationToken)
+            .ConfigureAwait(true);
+
+        await networkByReference.CreateAsync(TestContext.Current.CancellationToken)
+            .ConfigureAwait(true);
+
+        await container.StartAsync(TestContext.Current.CancellationToken)
+            .ConfigureAwait(true);
+
+        using var dockerClient = TestcontainersSettings.OS.DockerEndpointAuthConfig.GetDockerClientBuilder(Guid.NewGuid()).Build();
+
+        // When
+        await container.ConnectAsync(networkByName.Name, TestContext.Current.CancellationToken)
+            .ConfigureAwait(true);
+
+        await container.ConnectAsync(networkByReference, TestContext.Current.CancellationToken)
+            .ConfigureAwait(true);
+
+        var response = await dockerClient.Containers.InspectContainerAsync(container.Id, TestContext.Current.CancellationToken)
+            .ConfigureAwait(true);
+
+        // Then
+        Assert.Contains(networkByName.Name, response.NetworkSettings.Networks.Keys);
+        Assert.Contains(networkByReference.Name, response.NetworkSettings.Networks.Keys);
+    }
+}