[API Proposal]: Allow a custom IP lookup function for `HttpClient`.

[billpg]

Background and motivation

In security-conscious or policy-driven environments, it's often necessary to inspect the resolved IP address of an outbound HTTP request before initiating the connection. This enables applications to enforce custom traffic governance rules such as blocking requests to internal subnets, applying geolocation constraints, or logging outbound targets for audit and compliance.

In my project, the service connects to external websites at the initiation of an untrusted external user. To uphold our anti-abuse policy, we must prevent traffic to internal IPs or restricted networks. However, HttpClient does not expose the resolved IP prior to connection, making it impossible to enforce these policies without bypassing the class entirely.

For one-shot requests, we're currently bypassing HttpClient entirely using:

• Dns.GetHostAddressesAsync() for resolution
• TcpClient for socket connection
• SslStream for TLS
• Manual HTTP request construction

This approach works, but it's fragile and circumvents the benefits of HttpClient including redirect handling, decompression, proxy support, and connection pooling.

API Proposal

API Proposal

Introduce a pluggable IP resolution mechanism in SocketsHttpHandler to allow the caller to introduce their own DNS resolution before connection. The default behavior would remain unchanged unless explicitly configured.

public class SocketsHttpHandler : HttpMessageHandler
{
    /// <summary>
    /// Optional delegate for custom IP resolution. If set, this function is invoked
    /// with the target hostname before establishing a connection.
    /// </summary>
    public Func<string, Task<IPAddress[]>>? ResolveIPAddressesAsync { get; set; }
}

Behavior Notes:

• If ResolveIPAddressesAsync is null, the default DNS resolution is used.
  • Alternatively, the default delegate could be Dns.GetHostAddressesAsync; setting null would then result in a NullReferenceException.
• If set, the delegate is invoked before connection, allowing inspection, filtering, or substitution of resolved IP addresses.
• The delegate may return multiple IPs. The handler selects one using the same logic as when the system DNS resolver returns multiple IPs.
• All other HttpClient features—such as redirects, proxy support, decompression, and connection pooling—remain fully functional.
• The delegate should be thread-safe. SocketsHttpHandler does not enforce thread safety.
• If the delegate throws an exception, it propagates out of the HttpClient call, leaving the handler in a consistent state for reuse.
• If the delegate hangs beyond the configured timeout, HttpClient should throw an exception indicating that IP resolution timed out.
• The delegate may implement its own caching logic. SocketsHttpHandler does not cache the delegate’s response.

API Usage

API Usage

var handler = new SocketsHttpHandler
{
    ResolveIPAddressesAsync = async (host) =>
    {
        var addresses = await Dns.GetHostAddressesAsync(host);

        foreach (var ip in addresses)
        {
            if (IsBlocked(ip))
                throw new SecurityException($"Outbound IP {ip} blocked by policy.");
        }

        return addresses;
    }
};

var client = new HttpClient(handler);
await client.GetAsync("https://example.com");

Alternative Designs

Alternative Designs

• A simpler model could allow the caller to perform DNS resolution independently and pass a single IPAddress to HttpClient. This would shift responsibility for resolution and selection entirely to the caller.
  (In this situation, the Host header would continue to be the host string from the URL as normal, not the supplied IP address.)

• Instead of returning an array, the delegate could return a single IPAddress. This would simplify the API but reduce flexibility in multi-IP scenarios (e.g., round-robin DNS, CDN edge nodes). Returning an array allows the caller to inspect all candidates and apply stricter policies if needed, while still enabling single-IP enforcement by returning a one-element array.

• An OnIPAddressResolved event could pass the selected IP to the configured delegate, which would either allow it or throw an exception. The caller code could not provide their own IP but would be empowered to prevent connections to IPs it prefers to avoid.

These alternatives offer varying degrees of control and complexity, but the proposed delegate-based model strikes a balance between flexibility, safety, and compatibility with existing HttpClient behavior.

Risks

Risks

• Increased API surface complexity: Introducing a delegate-based IP resolution hook adds another layer of configuration to SocketsHttpHandler, which may complicate usage for developers unfamiliar with DNS or traffic governance.

• Misuse or misunderstanding: Developers might use the delegate for purposes better served by other mechanisms (e.g., hostname validation, proxy routing), leading to fragile or inconsistent behavior.

• Thread-safety concerns: If the delegate is not implemented with thread safety in mind, it could introduce concurrency issues in high-throughput scenarios. This risk is mitigated by clearly documenting that thread safety is the caller’s responsibility.

• Timeout handling: If the delegate hangs or performs slow resolution, it could delay outbound requests. This risk is mitigated by enforcing timeouts and surfacing clear exceptions when resolution exceeds configured thresholds.

• Caching inconsistencies: Custom resolvers may implement their own caching logic, which could diverge from system-level DNS caching behavior. This could lead to unexpected results unless clearly documented.

• Security implications: Allowing custom resolution logic introduces a new surface for policy enforcement—but also for policy bypass if misconfigured. Careful documentation and default behavior safeguards are essential.

[MihuBot]

I'm a bot. Here is a possible related and/or duplicate issue (I may be wrong):

• Option to have more control when resolving endpoint IP address in SocketsHttpHandler #25401

[stephentoub]

Are you aware of SocketsHttpHandler.ConnectCallback? While it requires writing a few more lines, you can replace just the DNS resolution mechanism, like this:

SocketsHttpHandler handler = new()
{
    ConnectCallback = static async (context, cancellationToken) =>
    {
        DnsEndPoint ep = context.DnsEndPoint;

        // Replace this with whatever you want:
        IPAddress[] addresses = await Dns.GetHostAddressesAsync(ep.Host, cancellationToken);

        Socket s = new(SocketType.Stream, ProtocolType.Tcp) { NoDelay = true };
        try
        {
            await s.ConnectAsync(addresses, ep.Port, cancellationToken);
            return new NetworkStream(s, ownsSocket: true);
        }
        catch
        {
            s.Dispose();
            throw;
        }
    }
};

The above is basically what the default implementation does (it actually passes the endpoint directly to Socket.ConnectAsync, but functionally it's the same). Everything else in the stack remains the same.

[billpg]

Thanks for the pointer! I reviewed #45144 and agree there’s thematic overlap around DNS resolution, but I believe this proposal addresses a distinct use case:

#45144 focuses on DNS TTL and stale connections due to pooling.

This proposal introduces a delegate for preflight IP inspection, enabling applications to enforce outbound traffic policies before connection.

My suggestion to allow the caller to supply their own IP resolution code was intended for maximum flexibility. If that introduces significant complications for connection pooling, I’d be happy to fall back to the alternative proposal: an OnIPAddressResolved event, where the caller is given an opportunity to stop the connection once the IP address is known.

The goal here isn’t to control connection reuse or TTL behavior—it’s to support principled governance of outbound targets, especially in scenarios where requests are initiated by untrusted users and internal IPs must be blocked.

Happy to refine the scope or merge if maintainers feel it fits better elsewhere.

[billpg]

I wasn’t aware ConnectCallback could do that—thanks for pointing it out. I did review the available API before raising this ticket, but didn’t dig deeper into this one as it seemed more concerned with TCP than DNS.

I haven’t tried it yet, but your sample code appears to do what I need, assuming that throwing an exception would cleanly abort the connection attempt and leave the handler in a consistent state for future use.

My concern is that using ConnectCallback would permanently lock the service into TCP-based connections, since the delegate replaces both DNS resolution and the TCP connect logic. Would this prevent the client from ever using UDP-based HTTP/3 via QUIC?

[billpg]

Suggested area tag: area-System.Net.Http (for outbound connection and DNS resolution logic)

[stephentoub]

My concern is that using ConnectCallback would permanently lock the service into TCP-based connections, since the delegate replaces both DNS resolution and the TCP connect logic.

You can see where it's used here:

runtime/src/libraries/System.Net.Http/src/System/Net/Http/SocketsHttpHandler/ConnectionPool/HttpConnectionPool.cs

Lines 657 to 698 in 98f102a

	// If a ConnectCallback was supplied, use that to establish the connection.
	if (Settings._connectCallback != null)
	{
	ValueTask<Stream> streamTask = Settings._connectCallback(new SocketsHttpConnectionContext(endPoint, initialRequest), cancellationToken);
	if (!async && !streamTask.IsCompleted)
	{
	// User-provided ConnectCallback is completing asynchronously but the user is making a synchronous request; if the user cares, they should
	// set it up so that synchronous requests are made on a handler with a synchronously-completing ConnectCallback supplied. If in the future,
	// we could add a Boolean to SocketsHttpConnectionContext (https://github.com/dotnet/runtime/issues/44876) to let the callback know whether
	// this request is sync or async.
	Trace($"{nameof(SocketsHttpHandler.ConnectCallback)} completing asynchronously for a synchronous request.");
	}
	stream = await streamTask.ConfigureAwait(false) ?? throw new HttpRequestException(SR.net_http_null_from_connect_callback);
	}
	else
	{
	// Otherwise, create and connect a socket using default settings.
	Socket socket = new Socket(SocketType.Stream, ProtocolType.Tcp) { NoDelay = true };
	try
	{
	if (async)
	{
	await socket.ConnectAsync(endPoint, cancellationToken).ConfigureAwait(false);
	}
	else
	{
	using (cancellationToken.UnsafeRegister(static s => ((Socket)s!).Dispose(), socket))
	{
	socket.Connect(endPoint);
	}
	}
	stream = new NetworkStream(socket, ownsSocket: true);
	}
	catch
	{
	socket.Dispose();
	throw;
	}
	}

It only replaces hardcoded logic almost identical to what I wrote with your provided callback.

assuming that throwing an exception would cleanly abort the connection attempt

Yes, exceptions propagate out from here just as they would with any other connection failure.

Would this prevent the client from ever using UDP-based HTTP/3 via QUIC?

No, it's not used for HTTP/3. #64449 proposes adding a QuicConnectCallback; it hasn't been added yet mainly due to lack of broad interest.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/ncl
See info in area-owners.md if you want to be subscribed.

[billpg]

If ConnectCallback isn't used at all for HTTP/3, would I be able to apply my policy of which IPs to connect to if HTTP/3 is in play? I don't know. If it always needs to talk to port TCP/443 first before the HTTP/3 can start, that that's not a problem.

[billpg]

If ConnectCallback disables QUIC, forces TCP-only behavior, or can be bypassed when HTTP/3 is in use, that would be a strong argument for a DNS-only override mechanism—either via a dedicated delegate or an inspection event like OnIPAddressResolved.

Personally, I’d rather not be involved in dealing with TCP or UDP at all. I’d prefer to delegate that responsibility to the HttpClient class, which already handles it with great care. I see a need to step in and take control at one critical point in the process, but beyond that, I’d much rather follow a policy of minimal interference and let the excellent HttpClient class do its thing—without my stupid head thinking it knows better.