feat: Modernize ManagedHandler for proxy compatibility while preserving hijacked streams

[thomhurst]

Summary

Improves Unix socket connection handling for better proxy compatibility (e.g., Docker socket proxies in CI environments like custom GitHub runners with DinD) while preserving full support for hijacked streams required by exec, attach, and log operations.

Background

The initial approach used SocketsHttpHandler for .NET 8+ to leverage modern socket handling. However, testing revealed that SocketsHttpHandler cannot support stream hijacking because:

• It manages connections internally with pooling
• Response content doesn't expose the raw transport stream
• The HttpConnectionResponseContent.HijackStream() pattern requires direct transport access

This caused failures in exec, attach, logs, and port forwarding operations with:

System.NotSupportedException: message handler does not support hijacked streams

Solution

Instead of replacing ManagedHandler, we modernize it with configurable socket options for better proxy compatibility:

1. New SocketConfiguration class - Configurable socket options:

   • KeepAlive (default: true)
   • KeepAliveTime (default: 30s) - .NET 5.0+
   • KeepAliveInterval (default: 10s) - .NET 5.0+
   • KeepAliveRetryCount (default: 3) - .NET 7.0+
   • NoDelay (default: true)
   • SendBufferSize / ReceiveBufferSize

2. Updated ManagedHandler - Accepts SocketConfiguration and applies modern socket options

3. Modern .NET APIs - Uses Socket.ConnectAsync with CancellationToken on .NET 5.0+

Why This Works

• Preserves hijacking: ManagedHandler → HttpConnection → HttpConnectionResponseContent chain maintains direct transport stream access
• Better proxy compatibility: TCP keep-alive settings help maintain connections through proxies
• Configurable: Users can tune settings for their specific proxy environment

Files Changed

File	Change
SocketConfiguration.cs	NEW - Configurable socket options class
ManagedHandler.cs	Accept SocketConfiguration, use modern socket APIs
DockerClientConfiguration.cs	Add SocketConfiguration property, reorganize timeouts
DockerClient.cs	Remove SocketsHttpHandler, use ManagedHandler with config

Test Plan

• Unit tests pass
• Hijacked stream tests pass (exec, attach, logs)
• Multiplexed stream tests pass
• Build succeeds on all target frameworks (netstandard2.0/2.1, net8.0/9.0/10.0)

Usage

// Default configuration (good for most cases)
var config = new DockerClientConfiguration();

// Custom socket configuration for specific proxy environments
var config = new DockerClientConfiguration(
    socketConfiguration: new SocketConfiguration
    {
        KeepAlive = true,
        KeepAliveTime = 15,      // More aggressive keepalive
        KeepAliveInterval = 5,
        NoDelay = true
    }
);

---

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR improves Unix socket connection handling to better support Docker socket proxy wrappers commonly used in CI environments like custom GitHub runners with Docker-in-Docker (DinD). The implementation adds configurable connection timeouts and switches to modern SocketsHttpHandler for .NET 8+.

Key Changes:

• Introduced SocketConnectTimeout configuration property with a 30-second default timeout
• Migrated .NET 8+ Unix socket connections from ManagedHandler to SocketsHttpHandler with ConnectCallback
• Added KeepAlive socket option for improved proxy compatibility across all platforms

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
DockerClientConfiguration.cs	Adds SocketConnectTimeout parameter/property with default value of 30 seconds
DockerClient.cs	Implements modern SocketsHttpHandler for .NET 8+ and timeout handling with KeepAlive for all platforms
DockerClientConfigurationTests.cs	New unit tests validating default and custom timeout configuration values
IContainerOperationsTests.cs	Changes ThrowsAsync to ThrowsAnyAsync for more accurate cancellation exception assertions

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[thomhurst]

@HofmeisterAn are you free to take a look?

[HofmeisterAn]

Thanks. I need to test the changes locally as well using Testcontainers. Once everything works and we've addressed the suggestions, we can merge the PR.

[HofmeisterAn]

I did some brief tests on macOS. Most things look good, but everything related to running commands inside the container (exec), and probably retrieving logs does not work. At least these tests fail:

tests
  Testcontainers.Platform.Linux.Tests
  Testcontainers.Tests
    ExecResultExtensionsTest
    ExecAsyncShouldSucceedWhenCommandReturnsZeroExitCode
    ExecAsyncShouldThrowExecFailedExceptionWhenCommandFails
    PortForwardingTest
    PortForwardingDefaultConfiguration
      PortForwardingTest.EstablishesHostConnection
    PortForwardingNetworkConfiguration
      PortForwardingTest.EstablishesHostConnection
    SocatContainerTest
    RequestTargetContainer
      RequestTargetContainer(containerPort: 8080)
      RequestTargetContainer(containerPort: 8081)
    TarOutputMemoryStreamTest
    FromResourceMapping
      TestFileExistsInContainer
      TestFileHasExpectedOwnerGroupMode

with (which is the same failure in this CI run):

System.NotSupportedException
message handler does not support hijacked streams

[thomhurst]

Thanks for looking @HofmeisterAn !
I've just changed it for a 'dual-mode' approach for best of both worlds. ManagedHandler for hijacked streams, and native Sockets handler for everything else

[HofmeisterAn]

Thanks for looking @HofmeisterAn ! I've just changed it for a 'dual-mode' approach for best of both worlds. ManagedHandler for hijacked streams, and native Sockets handler for everything else

I don't think this is the right approach. Hijacking the stream is part of Docker.DotNet 1), 2). We should investigate why we're encountering this issue, gain a better understanding of SocketsHttpHandler, and support hijacking and multiplexing streams properly, as they are important.

I've just changed it for a 'dual-mode' approach for best of both worlds.

Sorry, this seems like a quick fix without really understanding the issue or considering a proper solution.

[bruegth]

@thomhurst For Proxy support some more settings were required for SocketsHttpHandler nor?
This is what AI says:

        // Use it in SocketsHttpHandler
        var handler = new SocketsHttpHandler
        {
            Proxy = WebRequest.DefaultWebProxy,
            UseProxy = true,
            PooledConnectionIdleTimeout = TimeSpan.FromMinutes(5),
            KeepAlivePingPolicy = HttpKeepAlivePingPolicy.Always,
            KeepAlivePingDelay = TimeSpan.FromSeconds(30),
            KeepAlivePingTimeout = TimeSpan.FromSeconds(15)
        };

        using var client = new HttpClient(handler);
        var response = await client.GetAsync("https://httpbin.org/get");
        Console.WriteLine(await response.Content.ReadAsStringAsync());

💡 Best Practice in 2026:
If you’re writing new code, don’t rely on WebRequest.DefaultWebProxy — explicitly set the proxy in SocketsHttpHandler for clarity and future compatibility.

[thomhurst]

@bruegth Looks like SocketsHttpHandler isn't the approach to go due to the hijacked streams limitation
@HofmeisterAn Thanks for the feedback. What about this now? Modernising the ManagedHandler?