feat: Implement cancellation token support for teardown and removal operations across resources

Author: mariotoffia

FluentDocker.Testing.Xunit/XunitComposeFixtureBase.cs

@@ -23,7 +23,7 @@ namespace FluentDocker.Testing.Xunit
   /// public class AppFixture : XunitComposeFixtureBase
   /// {
   ///   protected override void ConfigureCompose(IComposeBuilder b)
-  ///       => b.FromFile("docker-compose.yml");
+  ///       => b.WithComposeFile("docker-compose.yml");
   /// }
   ///
   /// public class AppTests : IClassFixture<AppFixture>

FluentDocker/Testing/Core/ComposeResource.cs

@@ -81,26 +81,26 @@ protected override async Task ProvisionAsync(CancellationToken cancellationToken
     }
 
     /// <inheritdoc />
-    protected override async Task TeardownAsync()
+    protected override async Task TeardownAsync(CancellationToken cancellationToken)
     {
       if (Service == null)
         return;
 
-      await Service.StopAsync();
-      await Service.RemoveAsync(force: false);
+      await Service.StopAsync(cancellationToken);
+      await Service.RemoveAsync(force: false, cancellationToken);
       Service = null;
     }
 
     /// <inheritdoc />
-    protected override async Task ForceRemoveAsync()
+    protected override async Task ForceRemoveAsync(CancellationToken cancellationToken)
     {
       var s = Service;
       Service = null;
       if (s == null)
         return;
 
       try
-      { await s.RemoveAsync(force: true); }
+      { await s.RemoveAsync(force: true, cancellationToken); }
       catch { /* best effort */ }
     }
 

FluentDocker/Testing/Core/ContainerResource.cs

@@ -89,26 +89,26 @@ protected override async Task ProvisionAsync(CancellationToken cancellationToken
     }
 
     /// <inheritdoc />
-    protected override async Task TeardownAsync()
+    protected override async Task TeardownAsync(CancellationToken cancellationToken)
     {
       if (Container == null)
         return;
 
-      await Container.StopAsync();
-      await Container.RemoveAsync(force: false);
+      await Container.StopAsync(cancellationToken);
+      await Container.RemoveAsync(force: false, cancellationToken);
       Container = null;
     }
 
     /// <inheritdoc />
-    protected override async Task ForceRemoveAsync()
+    protected override async Task ForceRemoveAsync(CancellationToken cancellationToken)
     {
       var c = Container;
       Container = null;
       if (c == null)
         return;
 
       try
-      { await c.RemoveAsync(force: true); }
+      { await c.RemoveAsync(force: true, cancellationToken); }
       catch { /* best effort */ }
     }
 

FluentDocker/Testing/Core/DockerResourceOptions.cs

@@ -31,5 +31,11 @@ public class DockerResourceOptions
     /// Maximum log lines to capture on failure.
     /// </summary>
     public int MaxDiagnosticLogLines { get; set; } = 200;
+
+    /// <summary>
+    /// Timeout for teardown (stop + remove) during disposal.
+    /// Prevents hung cleanup from blocking CI pipelines indefinitely.
+    /// </summary>
+    public TimeSpan TeardownTimeout { get; set; } = TimeSpan.FromSeconds(60);
   }
 }

FluentDocker/Testing/Core/PodmanKubernetesResource.cs

@@ -99,36 +99,35 @@ protected override async Task ProvisionAsync(CancellationToken cancellationToken
             $"Podman kube play failed for '{_config.YamlPath}': {result.Error}");
       }
 
-      PlayResult = result.Data;
+      PlayResult = result.Data
+          ?? throw new FluentDockerException(
+              $"Podman kube play for '{_config.YamlPath}' returned Success " +
+              "but no result payload.");
       ResourceName = _config.YamlPath;
     }
 
     /// <inheritdoc />
-    protected override async Task TeardownAsync()
+    protected override async Task TeardownAsync(CancellationToken cancellationToken)
     {
-      if (PlayResult == null)
-        return;
-
       var driver = Kernel.SysCtl<IPodmanKubernetesDriver>(DriverId);
       var context = new DriverContext(DriverId);
-      var result = await driver.DownAsync(context, _config.YamlPath);
+      var result = await driver.DownAsync(
+          context, _config.YamlPath, cancellationToken);
       if (!result.Success)
         throw new FluentDockerException(
             $"Failed to tear down Podman kube for '{_config.YamlPath}': {result.Error}");
       PlayResult = null;
     }
 
     /// <inheritdoc />
-    protected override async Task ForceRemoveAsync()
+    protected override async Task ForceRemoveAsync(CancellationToken cancellationToken)
     {
-      if (PlayResult == null)
-        return;
-
       try
       {
         var driver = Kernel.SysCtl<IPodmanKubernetesDriver>(DriverId);
         var context = new DriverContext(DriverId);
-        await driver.DownAsync(context, _config.YamlPath);
+        await driver.DownAsync(
+            context, _config.YamlPath, cancellationToken);
       }
       catch
       {

FluentDocker/Testing/Core/ResourceBase.cs

@@ -142,18 +142,19 @@ public async ValueTask DisposeAsync()
         // Hooks should not prevent cleanup
       }
 
+      using var cts = new CancellationTokenSource(Options.TeardownTimeout);
       Exception teardownFailure = null;
 
       try
       {
-        await TeardownAsync();
+        await TeardownAsync(cts.Token);
       }
       catch (Exception ex)
       {
         if (Options.ForceRemoveOnDispose)
         {
           try
-          { await ForceRemoveAsync(); }
+          { await ForceRemoveAsync(cts.Token); }
           catch { /* best effort */ }
         }
         else
@@ -194,12 +195,16 @@ public async ValueTask DisposeAsync()
     /// <summary>
     /// Gracefully stops and removes the resource.
     /// </summary>
-    protected abstract Task TeardownAsync();
+    /// <param name="cancellationToken">Cancellation token bound to
+    /// <see cref="DockerResourceOptions.TeardownTimeout"/>.</param>
+    protected abstract Task TeardownAsync(CancellationToken cancellationToken);
 
     /// <summary>
     /// Force-removes the resource when graceful teardown fails.
     /// </summary>
-    protected abstract Task ForceRemoveAsync();
+    /// <param name="cancellationToken">Cancellation token bound to
+    /// <see cref="DockerResourceOptions.TeardownTimeout"/>.</param>
+    protected abstract Task ForceRemoveAsync(CancellationToken cancellationToken);
 
     /// <summary>
     /// Collects diagnostic information when initialization fails.

FluentDocker/Testing/Core/SwarmStackResource.cs

@@ -102,36 +102,35 @@ protected override async Task ProvisionAsync(CancellationToken cancellationToken
             $"Stack deploy failed for '{_config.StackName}': {result.Error}");
       }
 
-      DeployResult = result.Data;
+      DeployResult = result.Data
+          ?? throw new FluentDockerException(
+              $"Stack deploy for '{_config.StackName}' returned Success " +
+              "but no result payload.");
       ResourceName = _config.StackName;
     }
 
     /// <inheritdoc />
-    protected override async Task TeardownAsync()
+    protected override async Task TeardownAsync(CancellationToken cancellationToken)
     {
-      if (DeployResult == null)
-        return;
-
       var driver = Kernel.SysCtl<IStackDriver>(DriverId);
       var context = new DriverContext(DriverId);
-      var result = await driver.RemoveAsync(context, new[] { _config.StackName });
+      var result = await driver.RemoveAsync(
+          context, new[] { _config.StackName }, cancellationToken);
       if (!result.Success)
         throw new FluentDockerException(
             $"Failed to remove stack '{_config.StackName}': {result.Error}");
       DeployResult = null;
     }
 
     /// <inheritdoc />
-    protected override async Task ForceRemoveAsync()
+    protected override async Task ForceRemoveAsync(CancellationToken cancellationToken)
     {
-      if (DeployResult == null)
-        return;
-
       try
       {
         var driver = Kernel.SysCtl<IStackDriver>(DriverId);
         var context = new DriverContext(DriverId);
-        await driver.RemoveAsync(context, new[] { _config.StackName });
+        await driver.RemoveAsync(
+            context, new[] { _config.StackName }, cancellationToken);
       }
       catch
       {

FluentDocker/Testing/Core/TopologyResource.cs

@@ -86,19 +86,19 @@ protected override async Task ProvisionAsync(CancellationToken cancellationToken
     }
 
     /// <inheritdoc />
-    protected override async Task TeardownAsync()
+    protected override async Task TeardownAsync(CancellationToken cancellationToken)
     {
       var failures = new List<Exception>();
 
       // Tear down in reverse order for dependency safety.
       for (var i = _services.Count - 1; i >= 0; i--)
       {
         try
-        { await _services[i].StopAsync(); }
+        { await _services[i].StopAsync(cancellationToken); }
         catch { /* stop failure must not prevent removal */ }
 
         try
-        { await _services[i].RemoveAsync(force: false); }
+        { await _services[i].RemoveAsync(force: false, cancellationToken); }
         catch (Exception ex) { failures.Add(ex); }
       }
 
@@ -111,12 +111,12 @@ protected override async Task TeardownAsync()
     }
 
     /// <inheritdoc />
-    protected override async Task ForceRemoveAsync()
+    protected override async Task ForceRemoveAsync(CancellationToken cancellationToken)
     {
       for (var i = _services.Count - 1; i >= 0; i--)
       {
         try
-        { await _services[i].RemoveAsync(force: true); }
+        { await _services[i].RemoveAsync(force: true, cancellationToken); }
         catch { /* best effort */ }
       }