Add watchdog feature to allow cleanup on kill

The watchdog will spawn a background thread that registers signal
handlers for SIGTERM, SIGINT, and SIGQUIT, if any such signal is
observed it will clean up currently running containers that are not
marked as `Keep`.

Signed-off-by: Heinz N. Gies <heinz@licenser.net>

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added `watchdog` feature that spawns a background thread keeping track of docker containers that are started by the test suite and removes them in the case of a `CTRL+C` or `kill` of the test process.
+
 ## [0.13.0] - 2022-04-04
 
 ### Added

testcontainers/Cargo.toml

@@ -14,6 +14,7 @@ description = "A library for integration-testing against docker containers from
 async-trait = { version = "0.1", optional = true }
 bollard = { version = "0.11", optional = true }
 bollard-stubs = "1.41"
+conquer-once = { version = "0.3", optional = true }
 futures = "0.3"
 hex = "0.4"
 hmac = "0.12"
@@ -22,9 +23,12 @@ rand = "0.8"
 serde = { version = "1", features = [ "derive" ] }
 serde_json = "1"
 sha2 = "0.10"
+signal-hook = { version = "0.3", optional = true }
 tokio = { version = "1", features = [ "macros" ], optional = true }
 
 [features]
+default = [ ]
+watchdog = [ "signal-hook", "conquer-once" ]
 experimental = [ "async-trait", "bollard", "tokio" ]
 
 [dev-dependencies]

testcontainers/src/clients/cli.rs

@@ -50,6 +50,12 @@ impl Cli {
             .expect("output is not valid utf8")
             .trim()
             .to_string();
+
+        #[cfg(feature = "watchdog")]
+        if self.inner.command == env::Command::Remove {
+            crate::watchdog::register(container_id.clone());
+        }
+
         self.inner.register_container_started(container_id.clone());
 
         self.block_until_ready(&container_id, image.ready_conditions());

testcontainers/src/clients/http.rs

@@ -170,6 +170,11 @@ impl Http {
             }
         };
 
+        #[cfg(feature = "watchdog")]
+        if self.inner.command == env::Command::Remove {
+            crate::watchdog::Watchdog::register(container_id.clone());
+        }
+
         self.inner
             .bollard
             .start_container::<String>(&id, None)

testcontainers/src/core/container.rs

@@ -186,6 +186,8 @@ where
             Command::Keep => {}
             Command::Remove => self.rm(),
         }
+        #[cfg(feature = "watchdog")]
+        crate::watchdog::unregister(self.id());
     }
 }
 

testcontainers/src/core/container_async.rs

@@ -115,6 +115,8 @@ where
             env::Command::Remove => self.docker_client.rm(&self.id).await,
             env::Command::Keep => {}
         }
+        #[cfg(feature = "watchdog")]
+        crate::watchdog::unregister(self.id());
     }
 }
 

testcontainers/src/lib.rs

@@ -40,6 +40,9 @@ pub use crate::core::{Container, Image, ImageArgs, RunnableImage};
 #[cfg(feature = "experimental")]
 pub use crate::core::ContainerAsync;
 
+#[cfg(feature = "watchdog")]
+pub(crate) mod watchdog;
+
 /// All available Docker clients.
 pub mod clients;
 pub mod core;

testcontainers/src/watchdog.rs

@@ -0,0 +1,52 @@
+use crate::{clients::Cli, core::Docker};
+use conquer_once::Lazy;
+use signal_hook::{
+    consts::{SIGINT, SIGQUIT, SIGTERM},
+    iterator::Signals,
+};
+use std::{collections::BTreeSet, sync::Mutex, thread};
+
+static WATCHDOG: Lazy<Mutex<Watchdog>> = Lazy::new(|| {
+    thread::spawn(move || {
+        let signal_docker = Cli::default();
+        let mut signals =
+            Signals::new(&[SIGTERM, SIGINT, SIGQUIT]).expect("failed to register signal handler");
+
+        for signal in &mut signals {
+            for container_id in WATCHDOG
+                .lock()
+                .map(|s| s.containers.clone())
+                .unwrap_or_default()
+            {
+                signal_docker.stop(&container_id);
+                signal_docker.rm(&container_id);
+            }
+
+            let _ = signal_hook::low_level::emulate_default_handler(signal);
+        }
+    });
+
+    Mutex::new(Watchdog::default())
+});
+
+#[derive(Default)]
+pub(crate) struct Watchdog {
+    containers: BTreeSet<String>,
+}
+
+/// Register a container for observation
+pub(crate) fn register(container_id: String) {
+    WATCHDOG
+        .lock()
+        .expect("failed to access watchdog")
+        .containers
+        .insert(container_id);
+}
+/// Unregisters a container for observation
+pub(crate) fn unregister(container_id: &str) {
+    WATCHDOG
+        .lock()
+        .expect("failed to access watchdog")
+        .containers
+        .remove(container_id);
+}