The gRPC and Unix domain sockets doc lacks warnings about supportability

[skyline75489]

Description

The documentation is very helpful, but it can easily lead to the following exception:

System.InvalidOperationException: Channel is configured with an HTTP transport doesn't support client-side load balancing or connectivity state tracking. The underlying HTTP transport must be a SocketsHttpHandler with no SocketsHttpHandler.ConnectCallback configured. The HTTP transport must be configured on the channel using GrpcChannelOptions.HttpHandler.
at Grpc.Net.Client.GrpcChannel.ValidateHttpHandlerSupportsConnectivity() in /_/src/Grpc.Net.Client/GrpcChannel.cs:line 427 
at Grpc.Net.Client.GrpcChannel..ctor(Uri address, GrpcChannelOptions channelOptions) in /_/src/Grpc.Net.Client/GrpcChannel.cs:line 131
at Grpc.Net.Client.GrpcChannel.ForAddress(Uri address, GrpcChannelOptions channelOptions) in /_/src/Grpc.Net.Client/GrpcChannel.cs:line 708
at Grpc.Net.Client.GrpcChannel.ForAddress(String address, GrpcChannelOptions channelOptions) in /_/src/Grpc.Net.Client/GrpcChannel.cs:line 678

Based on various existence of ValidateHttpHandlerSupportsConnectivity for example here : https://github.com/grpc/grpc-dotnet/blob/f31cd71abfc0e8a8a7b93f447868405b0baebed0/src/Grpc.Net.Client/GrpcChannel.cs#L138C1-L139C1, one needs to make sure:

• ServiceConfig?.LoadBalancingConfigs can't exist
• Neither ConnectivityState nor WaitForStateChangedAsync can be invoked.

I think we need to clarify this in the documentation.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/grpc/interprocess-uds?view=aspnetcore-9.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/grpc/interprocess-uds.md

Document ID

9af2ca8f-eefb-ae3d-ba52-d6b2a826945d

Platform Id

52d86246-3466-b842-2ee0-35cdd744c0c4

Article author

@JamesNK

Metadata

• ID: 9af2ca8f-eefb-ae3d-ba52-d6b2a826945d
• PlatformId: 52d86246-3466-b842-2ee0-35cdd744c0c4
• Service: aspnet-core
• Sub-service: grpc

Related Issues

[wadepickett]

@skyline75489, thanks very much for taking the time to make this suggestion.

@JamesNK, do you want some sort of warning statement? Something like the following if this is accurate?

⚠️ Warning
When using gRPC with Unix domain sockets in .NET, the following features are not supported:

• Client-side load balancing (ServiceConfig?.LoadBalancingConfigs)
• Connectivity state tracking (ConnectivityState, WaitForStateChangedAsync)

Attempting to use these features will result in an exception such as:

System.InvalidOperationException: Channel is configured with an HTTP transport doesn't support client-side load balancing or connectivity state tracking. ...

Ensure that your gRPC client uses a SocketsHttpHandler with no ConnectCallback configured. Set this via GrpcChannelOptions.HttpHandler.

For more details, see grpc-dotnet source and related issues.

[JamesNK]

Looks good, but it applies to UDS and named pipes. Should change text to apply to both and put it on this page: https://learn.microsoft.com/en-us/aspnet/core/grpc/interprocess?view=aspnetcore-9.0

[skyline75489]

Hi @wadepickett I think the last sentence should be removed:

Ensure that your gRPC client uses a SocketsHttpHandler with no ConnectCallback configured. Set this via GrpcChannelOptions.HttpHandler.

I see you took it from the error message:

The underlying HTTP transport must be a SocketsHttpHandler with no SocketsHttpHandler.ConnectCallback

But for Unix socket we do use SocketsHttpHandler.ConnectCallback. So it might be confusing. It seems to me that removing this line make it better.

[skyline75489]

Come to this page again, I found that @JamesNK actually added the note in aaa21d4

I don't know if I overlooked it or it's not very obvious as we thought it would be. Feel free to close the ticket if you found the existing note is sufficient. Thanks for the response.