diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9acc27b0..6b034147 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -48,6 +48,12 @@ jobs:
cert_path: ""
native_http: 0
needs_dind: false
+ - name: unix-native
+ docker_host: unix:///var/run/docker.sock
+ tls_verify: ""
+ cert_path: ""
+ native_http: 1
+ needs_dind: false
- name: tcp-2375
docker_host: tcp://localhost:2375
tls_verify: ""
diff --git a/README.md b/README.md
index eff27f3f..56e696b9 100644
--- a/README.md
+++ b/README.md
@@ -103,6 +103,18 @@ var client = new DockerClientBuilder()
This is achieved by setting the environment variable `DOCKER_DOTNET_NATIVE_HTTP_ENABLED` to `1`.
By doing so, the handler used to communicate with the Docker Engine will switch to the .NET built-in one, potentially improving performance and reliability.
+The native handler supports `tcp://`, `http://`, and `https://` endpoints and, on .NET 8 or later, `unix://` endpoints. To select it without the environment variable:
+
+```csharp
+using Docker.DotNet;
+using Docker.DotNet.NativeHttp;
+
+var client = new DockerClientBuilder()
+ .WithEndpoint(new Uri("unix:///var/run/docker.sock"))
+ .WithTransportOptions(new NativeHttpTransportOptions())
+ .Build();
+```
+
### Transport-specific options
Use `WithTransportOptions` to select a transport explicitly and configure transport-specific options.
diff --git a/src/Docker.DotNet.NativeHttp/Docker.DotNet.NativeHttp.csproj b/src/Docker.DotNet.NativeHttp/Docker.DotNet.NativeHttp.csproj
index 84632d93..600e02a5 100644
--- a/src/Docker.DotNet.NativeHttp/Docker.DotNet.NativeHttp.csproj
+++ b/src/Docker.DotNet.NativeHttp/Docker.DotNet.NativeHttp.csproj
@@ -2,7 +2,7 @@
Docker.DotNet.NativeHttp
Docker.DotNet.Enhanced.NativeHttp
- A Docker.DotNet transport implementation for HTTP(S) Docker Engine connections.
+ A Docker.DotNet transport implementation for HTTP(S) and Unix domain socket Docker Engine connections.
@@ -11,8 +11,10 @@
+
+
diff --git a/src/Docker.DotNet.NativeHttp/DockerHandlerFactory.cs b/src/Docker.DotNet.NativeHttp/DockerHandlerFactory.cs
index e2673b9f..29cf1869 100644
--- a/src/Docker.DotNet.NativeHttp/DockerHandlerFactory.cs
+++ b/src/Docker.DotNet.NativeHttp/DockerHandlerFactory.cs
@@ -28,12 +28,9 @@ public ResolvedTransport CreateHandler(NativeHttpTransportOptions transportOptio
throw new ArgumentNullException(nameof(clientOptions));
}
- var endpoint = clientOptions.Endpoint;
+ var uri = clientOptions.Endpoint;
- Validate(endpoint);
-
- var scheme = clientOptions.AuthProvider.TlsEnabled ? Uri.UriSchemeHttps : Uri.UriSchemeHttp;
- var uri = new UriBuilder(endpoint) { Scheme = scheme }.Uri;
+ Validate(uri);
#if NET
var handler = new SocketsHttpHandler
@@ -43,8 +40,24 @@ public ResolvedTransport CreateHandler(NativeHttpTransportOptions transportOptio
PooledConnectionIdleTimeout = PooledConnectionIdleTimeout,
};
+ if (IsUnixSocket(uri))
+ {
+ var socketName = uri.Segments.Last();
+ var socketPath = uri.LocalPath;
+ uri = new UriBuilder(Uri.UriSchemeHttp, socketName).Uri;
+
+ // Proxies do not apply to Unix domain sockets.
+ handler.UseProxy = false;
+ handler.ConnectCallback = (_, cancellationToken) => ConnectUnixSocketAsync(socketPath, cancellationToken);
+ }
+ else
+ {
+ uri = CreateHttpUri(uri, clientOptions);
+ }
+
transportOptions.ConfigureHandler(handler);
#else
+ uri = CreateHttpUri(uri, clientOptions);
var handler = new HttpClientHandler();
transportOptions.ConfigureHandler(handler);
#endif
@@ -64,11 +77,53 @@ private static void Validate(Uri endpoint)
{
var scheme = endpoint.Scheme;
+#if NET
+ if (IsUnixSocket(endpoint))
+ {
+ return;
+ }
+#endif
+
if (!string.Equals(scheme, "tcp", StringComparison.OrdinalIgnoreCase)
&& !string.Equals(scheme, Uri.UriSchemeHttp, StringComparison.OrdinalIgnoreCase)
&& !string.Equals(scheme, Uri.UriSchemeHttps, StringComparison.OrdinalIgnoreCase))
{
+#if NET
+ throw new InvalidOperationException($"The selected '{nameof(NativeHttpTransportOptions)}' can only be used with endpoint schemes 'tcp', 'http', 'https', or 'unix', but '{scheme}' was provided.");
+#else
throw new InvalidOperationException($"The selected '{nameof(NativeHttpTransportOptions)}' can only be used with endpoint schemes 'tcp', 'http', or 'https', but '{scheme}' was provided.");
+#endif
+ }
+ }
+
+#if NET
+ private static bool IsUnixSocket(Uri endpoint)
+ {
+ return string.Equals(endpoint.Scheme, "unix", StringComparison.OrdinalIgnoreCase);
+ }
+
+ private static async ValueTask ConnectUnixSocketAsync(string socketPath, CancellationToken cancellationToken)
+ {
+ var socket = new Socket(AddressFamily.Unix, SocketType.Stream, ProtocolType.Unspecified);
+
+ try
+ {
+ await socket.ConnectAsync(new UnixDomainSocketEndPoint(socketPath), cancellationToken)
+ .ConfigureAwait(false);
+
+ return new NetworkStream(socket, ownsSocket: true);
+ }
+ catch
+ {
+ socket.Dispose();
+ throw;
}
}
+#endif
+
+ private static Uri CreateHttpUri(Uri endpoint, ResolvedClientOptions clientOptions)
+ {
+ var scheme = clientOptions.AuthProvider.TlsEnabled ? Uri.UriSchemeHttps : Uri.UriSchemeHttp;
+ return new UriBuilder(endpoint) { Scheme = scheme }.Uri;
+ }
}
\ No newline at end of file
diff --git a/src/Docker.DotNet/DockerClientBuilder.cs b/src/Docker.DotNet/DockerClientBuilder.cs
index b96c6d72..8a475b6c 100644
--- a/src/Docker.DotNet/DockerClientBuilder.cs
+++ b/src/Docker.DotNet/DockerClientBuilder.cs
@@ -294,7 +294,14 @@ protected virtual IDockerHandlerFactory ResolveTransportFactory(string scheme)
return scheme.ToLowerInvariant() switch
{
"npipe" => NPipe.DockerHandlerFactory.Instance,
+#if NET
+ "unix" => NativeHttpEnabled
+ ? NativeHttp.DockerHandlerFactory.Instance
+ : Unix.DockerHandlerFactory.Instance,
+#else
+ // The native transport needs SocketsHttpHandler to reach a Unix domain socket.
"unix" => Unix.DockerHandlerFactory.Instance,
+#endif
"tcp" or "http" or "https" => NativeHttpEnabled
? NativeHttp.DockerHandlerFactory.Instance
: LegacyHttp.DockerHandlerFactory.Instance,
diff --git a/test/Docker.DotNet.TestsV2/DockerClientBuilderTests.cs b/test/Docker.DotNet.TestsV2/DockerClientBuilderTests.cs
index b4c009a1..fbef1038 100644
--- a/test/Docker.DotNet.TestsV2/DockerClientBuilderTests.cs
+++ b/test/Docker.DotNet.TestsV2/DockerClientBuilderTests.cs
@@ -293,14 +293,26 @@ public void PreservesEndpointInClientOptionsWhenTransportNormalizesEndpoint()
Assert.Equal(expectedEndpoint, transportFactory.LastClientOptions.Endpoint);
}
- [Theory]
- [InlineData("npipe://./pipe/docker_engine", typeof(NPipe.DockerHandlerFactory))]
- [InlineData("unix:/var/run/docker.sock", typeof(Unix.DockerHandlerFactory))]
- public void UsesExpectedFactoryWhenSocketSchemeIsProvided(string endpoint, Type expectedFactoryType)
+ [Fact]
+ public void UsesExpectedFactoryWhenNamedPipeSchemeIsProvided()
{
var builder = new TestDockerClientBuilder();
- var actualFactory = builder.ResolveTransportFactory(new Uri(endpoint));
+ var actualFactory = builder.ResolveTransportFactory(new Uri("npipe://./pipe/docker_engine"));
+
+ Assert.IsType(actualFactory);
+ }
+
+ [Fact]
+ public void UsesExpectedFactoryWhenUnixSchemeIsProvided()
+ {
+ var builder = new TestDockerClientBuilder();
+
+ var actualFactory = builder.ResolveTransportFactory(new Uri("unix:/var/run/docker.sock"));
+
+ var expectedFactoryType = Environment.GetEnvironmentVariable("DOCKER_DOTNET_NATIVE_HTTP_ENABLED") == "1"
+ ? typeof(NativeHttp.DockerHandlerFactory)
+ : typeof(Unix.DockerHandlerFactory);
Assert.IsType(expectedFactoryType, actualFactory);
}
diff --git a/test/Docker.DotNet.TestsV2/DockerHandlerFactoryValidationTests.cs b/test/Docker.DotNet.TestsV2/DockerHandlerFactoryValidationTests.cs
index 470f2a2e..9430be3a 100644
--- a/test/Docker.DotNet.TestsV2/DockerHandlerFactoryValidationTests.cs
+++ b/test/Docker.DotNet.TestsV2/DockerHandlerFactoryValidationTests.cs
@@ -14,9 +14,9 @@ public static TheoryData, Uri, st
},
{
options => NativeHttp.DockerHandlerFactory.Instance.CreateHandler(options, NullLogger.Instance),
- new Uri("unix:/var/run/docker.sock"),
+ new Uri("npipe://./pipe/docker_engine"),
"NativeHttpTransportOptions",
- "tcp', 'http', or 'https"
+ "tcp', 'http', 'https', or 'unix"
},
{
options => NPipe.DockerHandlerFactory.Instance.CreateHandler(options, NullLogger.Instance),