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),