feat: allow customizations of host-config

Addresses the needs of customizing specific docker params without expossing all available options.

Initial discussion is here: #890

Author: DDtKey

docs/features/configuration.md

@@ -32,6 +32,22 @@ Configuration is fetched in the following order:
 2. `DOCKER_CONFIG` environment variable, as an alternative path to the directory containing Docker `config.json` file.
 3. else it will load the default Docker config file, which lives in the user's home, e.g. `~/.docker/config.json`.
 
+## Advanced container configuration
+
+If you need to tweak Docker `HostConfig` fields that are not exposed by the high-level API, use
+`ImageExt::with_host_config_modifier` to apply a single callback just before container creation.
+The modifier runs after `testcontainers` fills in its defaults.
+
+```rust
+use testcontainers::{GenericImage, ImageExt};
+
+let image = GenericImage::new("testcontainers/helloworld", "1.3.0")
+    .with_host_config_modifier(|host_config| {
+        host_config.cpu_period = Some(100_000);
+        host_config.cpu_quota = Some(200_000);
+    });
+```
+
 ## bollard, rustls and SSL Cryptography providers
 
 `testcontainers` uses [`bollard`](https://docs.rs/bollard/latest/bollard/) to interact with the Docker API.

testcontainers/src/core/containers/request.rs

@@ -8,7 +8,7 @@ use std::{
 
 #[cfg(feature = "device-requests")]
 use bollard::models::DeviceRequest;
-use bollard::models::ResourcesUlimits;
+use bollard::models::{HostConfig, ResourcesUlimits};
 
 use crate::{
     core::{
@@ -49,6 +49,7 @@ pub struct ContainerRequest<I: Image> {
     pub(crate) startup_timeout: Option<Duration>,
     pub(crate) working_dir: Option<String>,
     pub(crate) log_consumers: Vec<Box<dyn LogConsumer + 'static>>,
+    pub(crate) host_config_modifier: Option<Box<dyn Fn(&mut HostConfig) + Send + Sync + 'static>>,
     #[cfg(feature = "reusable-containers")]
     pub(crate) reuse: crate::ReuseDirective,
     pub(crate) user: Option<String>,
@@ -239,6 +240,12 @@ impl<I: Image> ContainerRequest<I> {
         self.health_check.as_ref()
     }
 
+    pub fn host_config_modifier(
+        &self,
+    ) -> Option<&(dyn Fn(&mut HostConfig) + Send + Sync + 'static)> {
+        self.host_config_modifier.as_deref()
+    }
+
     #[cfg(feature = "device-requests")]
     pub fn device_requests(&self) -> Option<&[DeviceRequest]> {
         self.device_requests.as_deref()
@@ -276,6 +283,7 @@ impl<I: Image> From<I> for ContainerRequest<I> {
             startup_timeout: None,
             working_dir: None,
             log_consumers: vec![],
+            host_config_modifier: None,
             #[cfg(feature = "reusable-containers")]
             reuse: crate::ReuseDirective::Never,
             user: None,
@@ -336,7 +344,11 @@ impl<I: Image + Debug> Debug for ContainerRequest<I> {
             .field("working_dir", &self.working_dir)
             .field("user", &self.user)
             .field("ready_conditions", &self.ready_conditions)
-            .field("health_check", &self.health_check);
+            .field("health_check", &self.health_check)
+            .field(
+                "has_host_config_modifier",
+                &self.host_config_modifier.is_some(),
+            );
 
         #[cfg(feature = "reusable-containers")]
         repr.field("reusable", &self.reuse);

testcontainers/src/core/image/image_ext.rs

@@ -2,7 +2,7 @@ use std::time::Duration;
 
 #[cfg(feature = "device-requests")]
 use bollard::models::DeviceRequest;
-use bollard::models::ResourcesUlimits;
+use bollard::models::{HostConfig, ResourcesUlimits};
 
 use crate::{
     core::{
@@ -210,6 +210,15 @@ pub trait ImageExt<I: Image> {
     /// Allows to follow the container logs for the whole lifecycle of the container, starting from the creation.
     fn with_log_consumer(self, log_consumer: impl LogConsumer + 'static) -> ContainerRequest<I>;
 
+    /// Applies a custom modifier to the Docker `HostConfig` used for container creation.
+    ///
+    /// The modifier runs after `testcontainers` finishes applying its defaults and settings.
+    /// If called multiple times, the last modifier replaces the previous one.
+    fn with_host_config_modifier(
+        self,
+        modifier: impl Fn(&mut HostConfig) + Send + Sync + 'static,
+    ) -> ContainerRequest<I>;
+
     /// Flag the container as being exempt from the default `testcontainers` remove-on-drop lifecycle,
     /// indicating that the container should be kept running, and that executions with the same configuration
     /// reuse it instead of starting a "fresh" container instance.
@@ -526,6 +535,17 @@ impl<RI: Into<ContainerRequest<I>>, I: Image> ImageExt<I> for RI {
         container_req
     }
 
+    fn with_host_config_modifier(
+        self,
+        modifier: impl Fn(&mut HostConfig) + Send + Sync + 'static,
+    ) -> ContainerRequest<I> {
+        let container_req = self.into();
+        ContainerRequest {
+            host_config_modifier: Some(Box::new(modifier)),
+            ..container_req
+        }
+    }
+
     #[cfg(feature = "reusable-containers")]
     fn with_reuse(self, reuse: ReuseDirective) -> ContainerRequest<I> {
         ContainerRequest {

testcontainers/src/runners/async_runner.rs

@@ -326,6 +326,13 @@ where
             }
         }
 
+        if let Some(modifier) = container_req.host_config_modifier() {
+            config.host_config = config.host_config.map(|mut host_config| {
+                modifier(&mut host_config);
+                host_config
+            });
+        }
+
         let cmd: Vec<_> = container_req.cmd().map(|v| v.to_string()).collect();
         if !cmd.is_empty() {
             config.cmd = Some(cmd);

testcontainers/src/runners/sync_runner.rs

@@ -329,6 +329,24 @@ mod tests {
         Ok(())
     }
 
+    #[test]
+    fn sync_run_command_should_apply_host_config_modifier() -> anyhow::Result<()> {
+        let image = GenericImage::new("testcontainers/helloworld", "1.3.0");
+        let container = image
+            .with_host_config_modifier(|host_config| {
+                host_config.cpu_period = Some(100_000);
+                host_config.cpu_quota = Some(200_000);
+            })
+            .start()?;
+
+        let container_details = inspect(container.id());
+        let host_config = container_details.host_config.expect("HostConfig");
+
+        assert_eq!(host_config.cpu_period, Some(100_000));
+        assert_eq!(host_config.cpu_quota, Some(200_000));
+        Ok(())
+    }
+
     #[test]
     fn sync_should_create_network_if_image_needs_it_and_drop_it_in_the_end() -> anyhow::Result<()> {
         {