feat(#318): expose compose restart at the service level (#338)

IComposeDriver.RestartAsync + ComposeRestartConfig (with a Services
target list) already existed and emit `docker compose restart [service…]`,
but IComposeService had no way to reach them: a user holding an
IComposeService could not restart the project or target an individual
service.

Add IComposeService.RestartAsync() (whole project) and
RestartAsync(IEnumerable<string> services) (specific services),
implemented in ComposeService mirroring StopAsync: build a
ComposeRestartConfig, delegate to driver.RestartAsync, throw
DriverException on failure, transition to Running.

Tests: whole-project (empty Services), specific-services list
pass-through, and DriverException on failure. Added SetupComposeRestart
mock helper.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: mariotoffia

FluentDocker.Tests/CoreTests/Service/ComposeServiceTests.Operations.cs

@@ -426,5 +426,73 @@ public void ServiceCapabilities_ReportsCorrectValues()
     }
 
     #endregion
+
+    #region RestartAsync (issue #318)
+
+    [Fact]
+    public async Task RestartAsync_WholeProject_CallsDriverWithNoServices()
+    {
+      var mockPack = new MockDriverPack();
+      mockPack.SetupComposeRestart();
+
+      var kernel = await MockKernelBuilderExtensions.CreateWithMockDriverAsync("docker", mockPack);
+      try
+      {
+        var service = CreateService(kernel);
+        await service.RestartAsync(TestContext.Current.CancellationToken);
+
+        Assert.Equal(ServiceRunningState.Running, service.State);
+        mockPack.ComposeDriver.Verify(d => d.RestartAsync(
+            It.IsAny<DriverContext>(),
+            It.Is<ComposeRestartConfig>(c => c.Services.Count == 0 && c.ProjectName == "test-project"),
+            It.IsAny<CancellationToken>()), Times.Once);
+      }
+      finally { kernel.Dispose(); }
+    }
+
+    [Fact]
+    public async Task RestartAsync_SpecificServices_PassesServiceList()
+    {
+      var mockPack = new MockDriverPack();
+      mockPack.SetupComposeRestart();
+
+      var kernel = await MockKernelBuilderExtensions.CreateWithMockDriverAsync("docker", mockPack);
+      try
+      {
+        var service = CreateService(kernel);
+        await service.RestartAsync(["web", "db"], TestContext.Current.CancellationToken);
+
+        mockPack.ComposeDriver.Verify(d => d.RestartAsync(
+            It.IsAny<DriverContext>(),
+            It.Is<ComposeRestartConfig>(c =>
+                c.Services.Count == 2 && c.Services[0] == "web" && c.Services[1] == "db"),
+            It.IsAny<CancellationToken>()), Times.Once);
+      }
+      finally { kernel.Dispose(); }
+    }
+
+    [Fact]
+    public async Task RestartAsync_Failure_ThrowsDriverException()
+    {
+      var mockPack = new MockDriverPack();
+      mockPack.ComposeDriver
+          .Setup(d => d.RestartAsync(
+              It.IsAny<DriverContext>(),
+              It.IsAny<ComposeRestartConfig>(),
+              It.IsAny<CancellationToken>()))
+          .ReturnsAsync(CommandResponse<Unit>.Fail("boom", "COMPOSE_RESTART_FAILED"));
+
+      var kernel = await MockKernelBuilderExtensions.CreateWithMockDriverAsync("docker", mockPack);
+      try
+      {
+        var service = CreateService(kernel);
+        var ex = await Assert.ThrowsAsync<DriverException>(
+            () => service.RestartAsync(TestContext.Current.CancellationToken));
+        Assert.Contains("restart compose project", ex.Message.ToLowerInvariant());
+      }
+      finally { kernel.Dispose(); }
+    }
+
+    #endregion
   }
 }

FluentDocker.Tests/Mocks/MockDriverPack.Compose.cs

@@ -140,6 +140,20 @@ public MockDriverPack SetupComposeStop()
       return this;
     }
 
+    /// <summary>
+    /// Sets up ComposeDriver.RestartAsync to return success.
+    /// </summary>
+    public MockDriverPack SetupComposeRestart()
+    {
+      ComposeDriver
+          .Setup(d => d.RestartAsync(
+              It.IsAny<DriverContext>(),
+              It.IsAny<ComposeRestartConfig>(),
+              It.IsAny<CancellationToken>()))
+          .ReturnsAsync(FluentDocker.Model.Drivers.CommandResponse<Unit>.Ok(Unit.Default));
+      return this;
+    }
+
     /// <summary>
     /// Sets up ComposeDriver.PauseAsync to return success.
     /// </summary>

FluentDocker/Services/IComposeService.cs

@@ -39,6 +39,20 @@ public interface IComposeService : IServiceAsync
     /// Scales a service to the specified number of instances.
     /// </summary>
     Task ScaleAsync(string service, int replicas, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Restarts the whole compose project (<c>docker compose restart</c>).
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    Task RestartAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Restarts specific services in the compose project
+    /// (<c>docker compose restart &lt;service&gt; …</c>).
+    /// </summary>
+    /// <param name="services">The services to restart. When null or empty, the whole project is restarted.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    Task RestartAsync(IEnumerable<string> services, CancellationToken cancellationToken = default);
   }
 }
 

FluentDocker/Services/Impl/ComposeService.cs

@@ -236,6 +236,35 @@ public async Task StopAsync(CancellationToken cancellationToken = default)
       await ExecuteHooksAsync(ServiceRunningState.Stopped).ConfigureAwait(false);
     }
 
+    public Task RestartAsync(CancellationToken cancellationToken = default) =>
+        RestartAsync(null, cancellationToken);
+
+    public async Task RestartAsync(IEnumerable<string> services, CancellationToken cancellationToken = default)
+    {
+      var driver = _kernel.SysCtl<IComposeDriver>(_driverId);
+      var context = new DriverContext(_driverId);
+
+      var config = new ComposeRestartConfig
+      {
+        ComposeFiles = _composeFiles,
+        ProjectName = _projectName,
+        Services = services is null ? [] : [.. services]
+      };
+
+      var response = await driver.RestartAsync(context, config, cancellationToken).ConfigureAwait(false);
+
+      if (!response.Success)
+      {
+        throw new DriverException(
+            $"Failed to restart compose project '{_projectName}': {response.Error}",
+            response.ErrorCode,
+            response.ErrorContext);
+      }
+
+      UpdateState(ServiceRunningState.Running);
+      await ExecuteHooksAsync(ServiceRunningState.Running).ConfigureAwait(false);
+    }
+
     public async Task RemoveAsync(bool force = false, CancellationToken cancellationToken = default)
     {
       var driver = _kernel.SysCtl<IComposeDriver>(_driverId);