Is it necessary to fix missed arguments for pools when init transports (Issue originating from httpx)

[CovnoHelangel]

I am opening this discussion to address an inconsistency regarding how HTTPTransport and AsyncHTTPTransport handle certain parameters when a proxy is configured, and to ask if we can fix this in the next release.

The Issue

As mentioned in the httpx repository (encode/httpx#2997), when a proxy is activated, several arguments passed to httpx.HTTPTransport and AsyncHTTPTransport are silently ignored.

For example, looking at httpx2/_transports/default.py (e.g., around L164-183), when a proxy is provided, the underlying connection pools are initialized without forwarding the uds, local_address, and retries arguments. This means that if a user explicitly sets retries=3 while configuring a proxy, the retry mechanism will fail to work as expected without any warning.

The Inconsistency

The underlying httpcore2.HTTPProxy and httpcore2.SOCKSProxy classes do actually accept and support these arguments. The limitation is purely within httpx2's wrapper layer, which simply fails to pass them down when initializing the proxy connection pool.

Documentation Gap

Currently, the official httpx2 documentation does not mention that uds, local_address, and retries become completely ineffective when a proxy is enabled. This silent failure can be quite confusing for developers who expect consistent transport behavior regardless of whether a proxy is used.

[minatofullstack-ops]

The main thing I'd check here is whether the behavior is coming from httpx2 itself or from the underlying transport layer.

A minimal reproduction using the same request with the default transport would help isolate that quickly. If the issue only appears with the affected transport/configuration, that should narrow down where the regression is.

[CovnoHelangel]

Looking at the code for both httpx2 and httpcore2, there are no issues with these parameters, because they are only effective within the ConnectionPool.create_connection (L120-L171) function when self._proxy is None.

As discussed in encode/httpx#2997, from a consistency standpoint, we should either add these parameters or add a note in the documentation warning about parameter conflicts.

Prior to 2023, I always assumed that the retries parameter worked with proxies :(

Ultimately, this is just a minor edge case. If the maintainers feel this doesn't warrant a change or has no significant impact, I am perfectly happy to close this discussion :)

[ChangkeunJ]

Confirmed on current main, and there's one detail in your write-up worth adjusting because it changes what the fix has to look like.

The sync path in src/httpx2/httpx2/_transports/default.py is exactly as you describe:

if proxy is None:
    self._pool = httpcore2.ConnectionPool(
        ...
        uds=uds,
        local_address=local_address,
        retries=retries,
        ...
    )
elif proxy.url.scheme in ("http", "https"):
    self._pool = httpcore2.HTTPProxy(
        ...
    )

None of the three make it into either proxy branch, and AsyncHTTPTransport is the same shape.

The adjustment is that HTTPProxy and SOCKSProxy don't share a signature. HTTPProxy.__init__ does take all three:

retries: int = 0,
local_address: str | None = None,
uds: str | None = None,

but SOCKSProxy.__init__ takes only retries. There's no local_address and no uds on it at all, in either the sync or the async version. So this isn't one fix applied in two places. HTTP proxies can be made to honour all three by forwarding them, SOCKS proxies can only ever honour retries.

Which I'd say makes the SOCKS case the more interesting half of your report rather than a footnote to it. The HTTP side is an uncontroversial oversight with a mechanical fix. On the SOCKS side uds and local_address genuinely can't be honoured, so what needs deciding is what should happen when someone passes them, and silently dropping them is precisely the behaviour you're objecting to. Raising on the combination fits your argument better than warning does, though it's technically breaking for anyone currently passing them and not noticing.

Either way I'd split those into two changes, since the first needs no discussion and the second needs a call from a maintainer.