feat(async, network): add support for aliases, dynamic connect & disconnect

amab8901 · amab8901 · commit a1b52f16ac7b · 2025-08-01T15:43:16.000+02:00
diff --git a/testcontainers/src/core/client.rs b/testcontainers/src/core/client.rs
@@ -101,6 +101,11 @@ pub enum ClientError {
     #[error("failed to remove a network: {0}")]
     RemoveNetwork(BollardError),
 
+    #[error("failed to connect container to network")]
+    ConnectionError(BollardError),
+    #[error("failed to disconnect container from network")]
+    DisconnectionError(BollardError),
+
     #[error("failed to initialize exec command: {0}")]
     InitExec(BollardError),
     #[error("failed to inspect exec command: {0}")]
@@ -114,7 +119,7 @@ pub enum ClientError {
 /// The internal client.
 pub(crate) struct Client {
     pub(crate) config: env::Config,
-    bollard: Docker,
+    pub(crate) bollard: Docker,
 }
 
 impl Client {
@@ -429,11 +434,11 @@ impl Client {
             match result {
                 Ok(r) => {
                     if let Some(s) = r.stream {
-                        log::info!("{}", s);
+                        log::info!("{s}");
                     }
                 }
                 Err(err) => {
-                    log::error!("{:?}", err);
+                    log::error!("{err:?}");
                     return Err(ClientError::BuildImage {
                         descriptor: descriptor.into(),
                         err,
diff --git a/testcontainers/src/core/containers/async_container.rs b/testcontainers/src/core/containers/async_container.rs
@@ -1,5 +1,6 @@
 use std::{fmt, net::IpAddr, pin::Pin, str::FromStr, sync::Arc, time::Duration};
 
+use bollard::models::{EndpointSettings, NetworkConnectRequest, NetworkDisconnectRequest};
 use tokio::io::{AsyncBufRead, AsyncReadExt};
 use tokio_stream::StreamExt;
 
@@ -8,7 +9,7 @@ use crate::{
         async_drop,
         client::Client,
         env,
-        error::{ContainerMissingInfo, ExecError, Result, TestcontainersError},
+        error::{ClientError, ContainerMissingInfo, ExecError, Result, TestcontainersError},
         network::Network,
         ports::Ports,
         wait::WaitStrategy,
@@ -59,7 +60,9 @@ where
         network: Option<Arc<Network>>,
     ) -> Result<ContainerAsync<I>> {
         let ready_conditions = container_req.ready_conditions();
-        let container = Self::construct(id, docker_client, container_req, network);
+        let mut container = Self::construct(id, docker_client, container_req, network.clone());
+        container.connect(network).await?;
+
         let state = ContainerState::from_container(&container).await?;
         for cmd in container.image().exec_before_ready(state)? {
             container.exec(cmd).await?;
@@ -68,6 +71,63 @@ where
         Ok(container)
     }
 
+    pub async fn connect(&mut self, net: Option<Arc<Network>>) -> Result<()> {
+        let container_id = self.id().into();
+        let net = if let Some(net) = net {
+            net
+        } else {
+            return Ok(());
+        };
+
+        let net_aliases_vec = net.aliases.clone().into_iter().collect();
+        let endpoint_settings = EndpointSettings {
+            aliases: Some(net_aliases_vec),
+            ..Default::default()
+        };
+
+        let bollard_netword_connect_request = NetworkConnectRequest {
+            container: Some(container_id),
+            endpoint_config: Some(endpoint_settings),
+        };
+        self.docker_client
+            .bollard
+            .connect_network(&net.name, bollard_netword_connect_request)
+            .await
+            .map_err(|err| TestcontainersError::Client(ClientError::ConnectionError(err)))?;
+
+        Ok(())
+    }
+
+    pub async fn disconnect(&mut self, name: &str) -> Result<()> {
+        let container_id = self.id().into();
+        let network_disconnect_request = NetworkDisconnectRequest {
+            container: Some(container_id),
+            force: Some(false),
+        };
+        self.docker_client
+            .bollard
+            .disconnect_network(name, network_disconnect_request)
+            .await
+            .map_err(|err| TestcontainersError::Client(ClientError::DisconnectionError(err)))?;
+
+        Ok(())
+    }
+
+    pub async fn force_disconnect(&mut self, name: &str) -> Result<()> {
+        let container_id = self.id().into();
+        let network_disconnect_request = NetworkDisconnectRequest {
+            container: Some(container_id),
+            force: Some(true),
+        };
+        self.docker_client
+            .bollard
+            .disconnect_network(name, network_disconnect_request)
+            .await
+            .map_err(|err| TestcontainersError::Client(ClientError::DisconnectionError(err)))?;
+
+        Ok(())
+    }
+
     pub(crate) fn construct(
         id: String,
         docker_client: Arc<Client>,
@@ -221,7 +281,7 @@ where
             cmd_ready_condition,
         } = cmd;
 
-        log::debug!("Executing command {:?}", cmd);
+        log::debug!("Executing command {cmd:?}",);
 
         let mut exec = self.docker_client.exec(&self.id, cmd).await?;
         self.block_until_ready(container_ready_conditions).await?;
@@ -442,7 +502,7 @@ where
                 match command {
                     env::Command::Remove => {
                         if let Err(e) = client.rm(&id).await {
-                            log::error!("Failed to remove container on drop: {}", e);
+                            log::error!("Failed to remove container on drop: {e}");
                         }
                     }
                     env::Command::Keep => {}
@@ -573,7 +633,7 @@ mod tests {
             while let Some(result) = stderr_lines.next_line().await.transpose() {
                 match result {
                     Ok(line) => {
-                        log::debug!(target: "container", "[{container_id}]:{}", line);
+                        log::debug!(target: "container", "[{container_id}]:{line}");
                     }
                     Err(err) if err.kind() == std::io::ErrorKind::UnexpectedEof => {
                         log::debug!(target: "container", "[{container_id}] EOF");
diff --git a/testcontainers/src/core/containers/request.rs b/testcontainers/src/core/containers/request.rs
@@ -1,6 +1,6 @@
 use std::{
     borrow::Cow,
-    collections::BTreeMap,
+    collections::{BTreeMap, HashSet},
     fmt::{Debug, Formatter},
     net::IpAddr,
     time::Duration,
@@ -25,6 +25,7 @@ pub struct ContainerRequest<I: Image> {
     pub(crate) image_tag: Option<String>,
     pub(crate) container_name: Option<String>,
     pub(crate) network: Option<String>,
+    pub(crate) network_aliases: HashSet<String>,
     pub(crate) labels: BTreeMap<String, String>,
     pub(crate) env_vars: BTreeMap<String, String>,
     pub(crate) hosts: BTreeMap<String, Host>,
@@ -228,6 +229,7 @@ impl<I: Image> From<I> for ContainerRequest<I> {
             image_tag: None,
             container_name: None,
             network: None,
+            network_aliases: HashSet::new(),
             labels: BTreeMap::default(),
             env_vars: BTreeMap::default(),
             hosts: BTreeMap::default(),
diff --git a/testcontainers/src/core/image/image_ext.rs b/testcontainers/src/core/image/image_ext.rs
@@ -69,6 +69,9 @@ pub trait ImageExt<I: Image> {
     /// Sets the network the container will be connected to.
     fn with_network(self, network: impl Into<String>) -> ContainerRequest<I>;
 
+    // Adds the specified network alias to the container.
+    fn with_net_alias(self, network_alias: impl Into<String>) -> ContainerRequest<I>;
+
     /// Adds the specified label to the container.
     ///
     /// **Note**: all keys in the `org.testcontainers.*` namespace should be regarded
@@ -249,6 +252,12 @@ impl<RI: Into<ContainerRequest<I>>, I: Image> ImageExt<I> for RI {
         }
     }
 
+    fn with_net_alias(self, network_alias: impl Into<String>) -> ContainerRequest<I> {
+        let mut container_req = self.into();
+        container_req.network_aliases.insert(network_alias.into());
+        container_req
+    }
+
     fn with_label(self, key: impl Into<String>, value: impl Into<String>) -> ContainerRequest<I> {
         let mut container_req = self.into();
 
diff --git a/testcontainers/src/core/network.rs b/testcontainers/src/core/network.rs
@@ -1,5 +1,5 @@
 use std::{
-    collections::HashMap,
+    collections::{HashMap, HashSet},
     fmt,
     sync::{Arc, OnceLock, Weak},
 };
@@ -19,16 +19,18 @@ fn created_networks() -> &'static Mutex<HashMap<String, Weak<Network>>> {
     CREATED_NETWORKS.get_or_init(|| Mutex::new(HashMap::new()))
 }
 
-pub(crate) struct Network {
-    name: String,
-    id: String,
-    client: Arc<Client>,
+pub struct Network {
+    pub name: String,
+    pub id: String,
+    pub(crate) client: Arc<Client>,
+    pub aliases: HashSet<String>,
 }
 
 impl Network {
     pub(crate) async fn new(
         name: impl Into<String>,
         client: Arc<Client>,
+        aliases: HashSet<String>,
     ) -> Result<Option<Arc<Self>>, ClientError> {
         let name = name.into();
         let mut guard = created_networks().lock().await;
@@ -46,6 +48,7 @@ impl Network {
                 name: name.clone(),
                 id,
                 client,
+                aliases,
             });
 
             guard.insert(name, Arc::downgrade(&created));
diff --git a/testcontainers/src/core/ports.rs b/testcontainers/src/core/ports.rs
@@ -101,17 +101,13 @@ impl TryFrom<PortMap> for Ports {
                     let mapping = match binding.host_ip.map(|ip| ip.parse()) {
                         Some(Ok(IpAddr::V4(_))) => {
                             log::debug!(
-                                "Registering IPv4 port mapping: {} -> {}",
-                                container_port,
-                                host_port
+                                "Registering IPv4 port mapping: {container_port} -> {host_port}",
                             );
                             &mut ipv4_mapping
                         }
                         Some(Ok(IpAddr::V6(_))) => {
                             log::debug!(
-                                "Registering IPv6 port mapping: {} -> {}",
-                                container_port,
-                                host_port
+                                "Registering IPv6 port mapping: {container_port} -> {host_port}",
                             );
                             &mut ipv6_mapping
                         }
diff --git a/testcontainers/src/runners/async_runner.rs b/testcontainers/src/runners/async_runner.rs
@@ -172,7 +172,12 @@ where
                 host_config.network_mode = Some(network.to_string());
                 host_config
             });
-            Network::new(network, client.clone()).await?
+            Network::new(
+                network,
+                client.clone(),
+                container_req.network_aliases.clone(),
+            )
+            .await?
         } else {
             None
         };
diff --git a/testcontainers/tests/async_runner.rs b/testcontainers/tests/async_runner.rs
@@ -284,7 +284,7 @@ async fn async_copy_files_to_container() -> anyhow::Result<()> {
     let mut out = String::new();
     container.stdout(false).read_to_string(&mut out).await?;
 
-    println!("{}", out);
+    println!("{out}");
     assert!(out.contains("foofoofoo"));
     assert!(out.contains("barbarbar"));
 
