feat: platform config passing through ImageExt trait (#838)

~~Alternative approach to #800 #837~~

I think this approach gives more flexibility API-wise. I am happy to add
tests if the maintainers think this is a more suitable approach.

Fixes #500, #718

Thanks in advance!

---------

Co-authored-by: Artem Medvedev <i@ddtkey.com>

Author: mominul

testcontainers/src/core/client.rs

@@ -450,10 +450,18 @@ impl Client {
         Ok(())
     }
 
-    pub(crate) async fn pull_image(&self, descriptor: &str) -> Result<(), ClientError> {
+    pub(crate) async fn pull_image(
+        &self,
+        descriptor: &str,
+        platform: Option<String>,
+    ) -> Result<(), ClientError> {
         let pull_options = CreateImageOptionsBuilder::new()
             .from_image(descriptor)
-            .platform(self.config.platform().unwrap_or_default())
+            .platform(
+                platform
+                    .as_deref()
+                    .unwrap_or_else(|| self.config.platform().unwrap_or_default()),
+            )
             .build();
 
         let credentials = self.credentials_for_image(descriptor).await;
@@ -467,7 +475,7 @@ impl Client {
                 Err(BollardError::DockerResponseServerError {
                     status_code: _,
                     message: _,
-                }) => {
+                }) if !matches!(platform.as_deref(), Some("linux/amd64")) => {
                     self.pull_image_linux_amd64(descriptor).await?;
                 }
                 _ => {
@@ -731,7 +739,7 @@ mod tests {
             )
             .await;
 
-        client.pull_image(IMAGE).await?;
+        client.pull_image(IMAGE, None).await?;
 
         let image = client.bollard.inspect_image(IMAGE).await?;
 
@@ -746,7 +754,7 @@ mod tests {
             .remove_image(IMAGE, Option::<RemoveImageOptions>::None, credentials)
             .await?;
 
-        client.pull_image(IMAGE).await?;
+        client.pull_image(IMAGE, None).await?;
 
         let image = client.bollard.inspect_image(IMAGE).await?;
 

testcontainers/src/core/containers/request.rs

@@ -26,6 +26,7 @@ pub struct ContainerRequest<I: Image> {
     pub(crate) image_name: Option<String>,
     pub(crate) image_tag: Option<String>,
     pub(crate) container_name: Option<String>,
+    pub(crate) platform: Option<String>,
     pub(crate) network: Option<String>,
     pub(crate) hostname: Option<String>,
     pub(crate) labels: BTreeMap<String, String>,
@@ -97,6 +98,10 @@ impl<I: Image> ContainerRequest<I> {
         &self.container_name
     }
 
+    pub fn platform(&self) -> &Option<String> {
+        &self.platform
+    }
+
     pub fn env_vars(&self) -> impl Iterator<Item = (Cow<'_, str>, Cow<'_, str>)> {
         self.image
             .env_vars()
@@ -248,6 +253,7 @@ impl<I: Image> From<I> for ContainerRequest<I> {
             image_name: None,
             image_tag: None,
             container_name: None,
+            platform: None,
             network: None,
             hostname: None,
             labels: BTreeMap::default(),
@@ -307,6 +313,7 @@ impl<I: Image + Debug> Debug for ContainerRequest<I> {
             .field("image_name", &self.image_name)
             .field("image_tag", &self.image_tag)
             .field("container_name", &self.container_name)
+            .field("platform", &self.platform)
             .field("network", &self.network)
             .field("hostname", &self.hostname)
             .field("labels", &self.labels)

testcontainers/src/core/image/image_ext.rs

@@ -68,6 +68,20 @@ pub trait ImageExt<I: Image> {
     /// Sets the container name.
     fn with_container_name(self, name: impl Into<String>) -> ContainerRequest<I>;
 
+    /// Sets the platform the container will be run on.
+    ///
+    /// Platform in the format `os[/arch[/variant]]` used for image lookup.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// use testcontainers::{GenericImage, ImageExt};
+    ///
+    /// let image = GenericImage::new("image", "tag")
+    ///     .with_platform("linux/amd64");
+    /// ```
+    fn with_platform(self, platform: impl Into<String>) -> ContainerRequest<I>;
+
     /// Sets the network the container will be connected to.
     fn with_network(self, network: impl Into<String>) -> ContainerRequest<I>;
 
@@ -283,6 +297,15 @@ impl<RI: Into<ContainerRequest<I>>, I: Image> ImageExt<I> for RI {
         }
     }
 
+    fn with_platform(self, platform: impl Into<String>) -> ContainerRequest<I> {
+        let container_req = self.into();
+
+        ContainerRequest {
+            platform: Some(platform.into()),
+            ..container_req
+        }
+    }
+
     fn with_network(self, network: impl Into<String>) -> ContainerRequest<I> {
         let container_req = self.into();
         ContainerRequest {

testcontainers/src/runners/async_runner.rs

@@ -187,13 +187,27 @@ where
             None
         };
 
+        let mut options_builder: Option<CreateContainerOptionsBuilder> = None;
+
         // name of the container
         if let Some(name) = container_req.container_name() {
-            let options = CreateContainerOptionsBuilder::new()
-                .name(name)
-                .platform(client.config.platform().unwrap_or_default())
-                .build();
-            create_options = Some(options)
+            let options = CreateContainerOptionsBuilder::new().name(name);
+
+            options_builder = Some(options);
+        }
+
+        // platform of the container
+        if let Some(platform) = container_req.platform() {
+            let options = options_builder.unwrap_or(CreateContainerOptionsBuilder::new());
+            options_builder = Some(options.platform(platform));
+        } else {
+            // set platform from global platform setting if available
+            let options = options_builder.unwrap_or(CreateContainerOptionsBuilder::new());
+            options_builder = Some(options.platform(client.config.platform().unwrap_or_default()));
+        }
+
+        if let Some(options) = options_builder {
+            create_options = Some(options.build());
         }
 
         // handle environment variables
@@ -311,7 +325,12 @@ where
                     status_code: 404, ..
                 },
             )) => {
-                client.pull_image(&container_req.descriptor()).await?;
+                client
+                    .pull_image(
+                        &container_req.descriptor(),
+                        container_req.platform().clone(),
+                    )
+                    .await?;
                 client.create_container(create_options, config).await
             }
             res => res,
@@ -361,7 +380,12 @@ where
     async fn pull_image(self) -> Result<ContainerRequest<I>> {
         let container_req = self.into();
         let client = Client::lazy_client().await?;
-        client.pull_image(&container_req.descriptor()).await?;
+        client
+            .pull_image(
+                &container_req.descriptor(),
+                container_req.platform().clone(),
+            )
+            .await?;
 
         Ok(container_req)
     }