Struct EasyHttpConnectorBuilder 

pub struct EasyHttpConnectorBuilder<C = (), S = (), D = ()> { /* private fields */ }

Available on crate features dns and http-backend and http and std and tcp only.

Builder that is designed to easily create a connector for super::EasyHttpWebClient from most basic use cases

Implementations

impl EasyHttpConnectorBuilder

pub fn new() -> Self

pub fn with_default_transport_connector( self, ) -> EasyHttpConnectorBuilder<TcpConnector, TransportStage>

pub fn with_custom_transport_connector<C>( self, connector: C, ) -> EasyHttpConnectorBuilder<C, TransportStage>

Add a custom transport connector that will be used by this client for the transport layer

impl<T, Stage, D> EasyHttpConnectorBuilder<T, Stage, D>

pub fn with_custom_connector<L>( self, connector_layer: L, ) -> EasyHttpConnectorBuilder<L::Service, Stage, D>

where L: Layer<T>,

Add a custom connector to this Stage.

Adding a custom connector to a stage will not change the state so this can be used to modify behaviour at a specific stage.

pub fn map_connector<T2>( self, map_fn: impl FnOnce(T) -> T2, ) -> EasyHttpConnectorBuilder<T2, Stage, D>

Map the current connector using the given fn.

Mapping a connector to a stage will not change the state so this can be used to modify behaviour at a specific stage.

impl<T> EasyHttpConnectorBuilder<T, TransportStage>

pub fn with_default_dns_connector( self, ) -> EasyHttpConnectorBuilder<DnsConnector<T>, DnsStage, DnsConnectorLayer>

Add the global DNS policy to both the stream and built-in QUIC transports.

pub fn with_dns_address_resolver<R: DnsAddressResolver + Clone>( self, resolver: R, ) -> EasyHttpConnectorBuilder<DnsConnector<T, R>, DnsStage, DnsConnectorLayer<R>>

Add a custom address resolver to both the stream and built-in QUIC transports.

pub fn without_dns_connector(self) -> EasyHttpConnectorBuilder<T, DnsStage>

Omit DNS resolution. Transports require IP targets or their own resolution.

pub fn with_dns_connector<L: Layer<T>>( self, layer: L, ) -> EasyHttpConnectorBuilder<L::Service, DnsStage, L>

Retain a custom DNS layer for both transport stacks.

The layer is applied to the stream transport here and to the built-in QUIC connector when with_http3_support is called. A layer specific to the stream transport can instead be paired with with_http3_connector, whose supplied connector owns its DNS policy independently.

impl<T, D> EasyHttpConnectorBuilder<T, DnsStage, D>

pub fn with_custom_tls_proxy_connector<L>( self, connector_layer: L, ) -> EasyHttpConnectorBuilder<L::Service, ProxyTunnelStage<true>, D>

where L: Layer<T>,

Add a custom proxy TLS connector used to establish TLS to an HTTPS proxy.

The layer must attach rama_tls::client::NegotiatedTlsParameters to the established connection. Rama uses this as positive proof that TLS was negotiated and to select the proxy-side HTTP version; missing evidence fails closed before proxy HTTP is sent.

pub fn with_tls_proxy_support_using_boringssl( self, ) -> EasyHttpConnectorBuilder<TlsConnector<T, ConnectorKindTunnel>, ProxyTunnelStage<true>, D>

Available on crate feature boring only.

Support a tls tunnel to the proxy itself using boringssl

Note that a tls proxy is not needed to make a https connection to the final target. It only has an influence on the initial connection to the proxy itself

pub fn with_tls_proxy_support_using_boringssl_config( self, config: TlsClientConfig, ) -> EasyHttpConnectorBuilder<TlsConnector<T, ConnectorKindTunnel>, ProxyTunnelStage<true>, D>

Available on crate feature boring only.

Support a tls tunnel to the proxy itself using boringssl and the provided config

Note that a tls proxy is not needed to make a https connection to the final target. It only has an influence on the initial connection to the proxy itself

pub fn with_tls_proxy_support_using_rustls( self, ) -> EasyHttpConnectorBuilder<TlsConnector<T, ConnectorKindTunnel>, ProxyTunnelStage<true>, D>

Available on crate feature rustls only.

Support a tls tunnel to the proxy itself using rustls

Note that a tls proxy is not needed to make a https connection to the final target. It only has an influence on the initial connection to the proxy itself

pub fn with_tls_proxy_support_using_rustls_config( self, config: TlsClientConfig, ) -> EasyHttpConnectorBuilder<TlsConnector<T, ConnectorKindTunnel>, ProxyTunnelStage<true>, D>

Available on crate feature rustls only.

Support a tls tunnel to the proxy itself using rustls and the provided config

Note that a tls proxy is not needed to make a https connection to the final target. It only has an influence on the initial connection to the proxy itself

pub fn without_tls_proxy_support( self, ) -> EasyHttpConnectorBuilder<T, ProxyTunnelStage<false>, D>

Don’t support a tls tunnel to the proxy itself

Note that a tls proxy is not needed to make a https connection to the final target. It only has an influence on the initial connection to the proxy itself

impl<T, D, const TLS_PROXY: bool> EasyHttpConnectorBuilder<T, ProxyTunnelStage<TLS_PROXY>, D>

pub fn with_custom_proxy_connector<L>( self, connector_layer: L, ) -> EasyHttpConnectorBuilder<L::Service, ProxyStage<true>, D>

where L: Layer<T>,

Add a custom proxy connector that will be used by this client

pub fn with_http_proxy_support( self, ) -> EasyHttpConnectorBuilder<HttpProxyConnector<T>, ProxyStage<true>, D>

Add support for usage of a http(s) ProxyAddress to this client

Note that a tls proxy is not needed to make a https connection to the final target. It only has an influence on the initial connection to the proxy itself

pub fn with_socks5_proxy_support( self, ) -> EasyHttpConnectorBuilder<Socks5ProxyConnector<T>, ProxyStage<true>, D>

Available on crate feature socks5 only.

Add support for usage of a socks5(h) ProxyAddress to this client

pub fn without_proxy_support( self, ) -> EasyHttpConnectorBuilder<T, ProxyStage<false>, D>

Make a client without proxy support

impl<T: Clone, D, const TLS_PROXY: bool> EasyHttpConnectorBuilder<T, ProxyTunnelStage<TLS_PROXY>, D>

pub fn with_proxy_support( self, ) -> EasyHttpConnectorBuilder<ProxyConnector<T>, ProxyStage<true>, D>

Available on crate feature socks5 only.

Add support for usage of a http(s) and socks5(h) ProxyAddress to this client

Note that a tls proxy is not needed to make a https connection to the final target. It only has an influence on the initial connection to the proxy itself

impl<T, D, const PROXY: bool> EasyHttpConnectorBuilder<T, ProxyStage<PROXY>, D>

pub fn with_custom_tls_connector<L>( self, connector_layer: L, ) -> EasyHttpConnectorBuilder<L::Service, TlsStage<PROXY>, D>

where L: Layer<T>,

Add a custom tls connector that will be used by the client.

TLS connectors publish connection reuse policies on their established transports. Custom secure connectors without this metadata are not pooled; implement the generic connection reuse policy to support safe pooling.

The final HTTP transition applies a RequestVersionAdapter outside the complete connection attempt so it can apply the negotiated version to the original HTTP request.

pub fn with_tls_support_using_boringssl( self, config: TlsClientConfig, ) -> EasyHttpConnectorBuilder<TlsConnector<T>, TlsStage<PROXY>, D>

Available on crate feature boring only.

Support https connections by using boringssl for tls

The final HTTP transition automatically applies the HTTP version negotiated through TLS to the original request.

pub fn with_tls_support_using_boringssl_and_default_http_version( self, config: TlsClientConfig, default_http_version: Version, ) -> EasyHttpConnectorBuilder<AddInputExtension<TlsConnector<T>, FallbackHttpVersion>, TlsStage<PROXY>, D>

Available on crate feature boring only.

Same as Self::with_tls_support_using_boringssl but also setting a fallback HTTP version in case no ALPN is negotiated. The fallback does not constrain the ALPN protocols offered by TLS.

This is a fairly important detail for proxy purposes given otherwise you might come in situations where the ingress traffic is negotiated to h2, but the egress traffic has no negotiation which would without a default http version remain on h2… In such a case you can get failed requests if the egress server does not handle multiple http versions.

pub fn with_tls_support_using_rustls( self, config: TlsClientConfig, ) -> EasyHttpConnectorBuilder<TlsConnector<T>, TlsStage<PROXY>, D>

Available on crate feature rustls only.

Support https connections by using ruslts for tls

The final HTTP transition automatically applies the HTTP version negotiated through TLS to the original request.

pub fn with_tls_support_using_rustls_and_default_http_version( self, config: TlsClientConfig, default_http_version: Version, ) -> EasyHttpConnectorBuilder<AddInputExtension<TlsConnector<T>, FallbackHttpVersion>, TlsStage<PROXY>, D>

Available on crate feature rustls only.

Same as Self::with_tls_support_using_rustls but also setting a fallback HTTP version in case no ALPN is negotiated. The fallback does not constrain the ALPN protocols offered by TLS.

This is a fairly important detail for proxy purposes given otherwise you might come in situations where the ingress traffic is negotiated to h2, but the egress traffic has no negotiation which would without a default http version remain on h2… In such a case you can get failed requests if the egress server does not handle multiple http versions.

pub fn without_tls_support( self, ) -> EasyHttpConnectorBuilder<T, TlsStage<PROXY>, D>

Don’t support https on this connector

impl<T, D, const PROXY: bool> EasyHttpConnectorBuilder<T, TlsStage<PROXY>, D>

pub fn with_default_http_connector<Body>( self, exec: Executor, ) -> EasyHttpConnectorBuilder<HttpConnector<T, Body>, HttpStage<PROXY>, D>

Add http support to this connector

pub fn with_custom_http_connector<L>( self, connector_layer: L, ) -> EasyHttpConnectorBuilder<L::Service, HttpStage<PROXY>, D>

where L: Layer<T>,

Add a custom http connector that will be run just after tls

impl<T, Body, D, const PROXY: bool> EasyHttpConnectorBuilder<HttpConnector<T, Body>, HttpStage<PROXY>, D>

pub fn with_http3_connector<C>( self, connector: C, ) -> EasyHttpConnectorBuilder<HttpConnector<HttpTransportConnector<T, C>, Body>, HttpStage<PROXY>, D>

Add a separately configured QUIC transport below the common HTTP handshake. The connector supplies its own transport, DNS and TLS policy. Its policy publishes connection reuse metadata for its effective policy. Custom connectors without that metadata are not pooled. Use Self::with_http3_support for the built-in connector.

pub fn with_http3_support( self, connector: Http3Connector, ) -> EasyHttpConnectorBuilder<HttpConnector<HttpTransportConnector<T, D::Service>, Body>, HttpStage<PROXY>, D>

where D: Layer<Http3Connector>,

Enable the built-in QUIC connector with the same DNS layer as the stream transport.

The retained layer must support the QUIC connector as its inner service. This does not copy a custom stream transport or its routing policy. Use Self::with_http3_connector for an equivalent custom QUIC path.

impl<T> EasyHttpConnectorBuilder<RequestVersionAdapter<HttpConnectRequestAdapter<MapEstablishedConnection<HttpServiceConnector<ProxyRoutesConnector<T>>, AltSvcConnectionLayer>>>, PoolStage>

pub fn without_alt_svc(self) -> Self

Disable advertised alternatives and response learning for every HTTP version.

pub fn maybe_with_alt_svc_cache(self, cache: Option<AltSvcCache>) -> Self

Share an alternative-service cache across HTTP clients; None disables discovery.

pub fn maybe_set_alt_svc_cache( &mut self, cache: Option<AltSvcCache>, ) -> &mut Self

Share an alternative-service cache across HTTP clients; None disables discovery.

pub fn with_alt_svc_cache(self, cache: AltSvcCache) -> Self

Share an alternative-service cache across HTTP clients; None disables discovery.

pub fn set_alt_svc_cache(&mut self, cache: AltSvcCache) -> &mut Self

Share an alternative-service cache across HTTP clients; None disables discovery.

pub fn without_alt_svc_cache(self) -> Self

Share an alternative-service cache across HTTP clients; None disables discovery.

pub fn unset_alt_svc_cache(&mut self) -> &mut Self

Share an alternative-service cache across HTTP clients; None disables discovery.

impl<T, D, const PROXY: bool> EasyHttpConnectorBuilder<T, HttpStage<PROXY>, D>

pub fn with_proxy_route_failure_cache( self, cache: ProxyRouteFailureCache, ) -> EasyHttpConnectorBuilder<ProxyRouteFailureCacheConnector<BoxService<ConnectRequest, EstablishedClientConnection<T::Connection, ConnectRequest>, ConnectionError>>, ProxyRouteFailureCacheStage, D>

where T: ConnectorService<ConnectRequest>,

Explicitly use the given shared proxy route failure cache.

This selects the failure-cache policy for the final connection stage. The configured connector is type-erased at this boundary to keep the combined connector future stack-safe.

pub fn without_proxy_route_failure_cache( self, ) -> EasyHttpConnectorBuilder<T, ProxyRouteFailureCacheStage, D>

Disable negative caching of temporarily failing proxy routes.

impl<T, D> EasyHttpConnectorBuilder<T, HttpStage<true>, D>

pub fn without_connection_pool( self, ) -> EasyHttpConnectorBuilder<RequestVersionAdapter<HttpConnectRequestAdapter<MapEstablishedConnection<HttpServiceConnector<ProxyRoutesConnector<ProxyRouteFailureCacheConnector<BoxService<ConnectRequest, EstablishedClientConnection<T::Connection, ConnectRequest>, ConnectionError>>>>, AltSvcConnectionLayer>>>, PoolStage>

where T: ConnectorService<ConnectRequest>,

Finish the default HTTP connector stack without adding a connection pool.

This still installs HTTP request adaptation and ordered proxy-route fallback. It also installs the default proxy-route failure cache. The only omitted component is the pool itself.

pub fn try_with_connection_pool( self, config: HttpPooledConnectorConfig, ) -> Result<EasyHttpConnectorBuilder<RequestVersionAdapter<HttpConnectRequestAdapter<MapEstablishedConnection<HttpServiceConnector<ProxyRoutesConnector<HttpPooledConnector<ProxyRouteFailureCacheConnector<BoxService<ConnectRequest, EstablishedClientConnection<T::Connection, ConnectRequest>, ConnectionError>>>>>, AltSvcConnectionLayer>>>, PoolStage>, BoxError>

where T: ConnectorService<ConnectRequest>,

Use the default connection pool for this super::EasyHttpWebClient

This will create a MultiplexPool using the provided limits and will use super::HttpConnIdentifier to group connections on protocol, authority, selected route, physical transport, any HTTP version requirement, and the selected plaintext HTTP proxy mode. This keeps forward-proxy connections separate from CONNECT tunnels to the same proxy. The default proxy-route failure cache is installed behind the pool, so reusable connections bypass negative-cache checks.

Use wait_for_pool_timeout to limit how long we wait for the pool to give us a connection

If you need a different pool or custom way to group connection you can use EasyHttpConnectorBuilder::with_custom_connection_pool() to provide you own.

This also applies a RequestVersionAdapter layer to make sure that request versions are adapted when pooled connections are used, which you almost always need, but in case that is unwanted, you can use Self::with_custom_connection_pool instead.

pub fn with_default_connection_pool( self, ) -> EasyHttpConnectorBuilder<RequestVersionAdapter<HttpConnectRequestAdapter<MapEstablishedConnection<HttpServiceConnector<ProxyRoutesConnector<HttpPooledConnector<ProxyRouteFailureCacheConnector<BoxService<ConnectRequest, EstablishedClientConnection<T::Connection, ConnectRequest>, ConnectionError>>>>>, AltSvcConnectionLayer>>>, PoolStage>

where T: ConnectorService<ConnectRequest>,

Use Rama’s default connection pool and default proxy-route failure cache.

This operation is infallible because Rama’s built-in pool limits are known to be valid and non-zero.

pub fn with_custom_connection_pool<P, R>( self, pool: P, req_to_conn_id: R, wait_for_pool_timeout: Option<Duration>, ) -> EasyHttpConnectorBuilder<PooledConnector<ProxyRouteFailureCacheConnector<BoxService<ConnectRequest, EstablishedClientConnection<T::Connection, ConnectRequest>, ConnectionError>>, P, R>, PoolStage>

where T: ConnectorService<ConnectRequest>,

Configure this client to use the provided Pool and ReqToConnId

Use wait_for_pool_timeout to limit how long we wait for the pool to give us a connection

Warning: this does not apply a RequestVersionAdapter layer to make sure that request versions are adapted when pooled connections are used, which you almost always. This should be manually added by using Self::with_custom_connector after configuring this pool and providing a RequestVersionAdapter there. Unlike Self::try_with_connection_pool, this fully generic method also does not install the HTTP connect-request adapter or proxy-route connector. It installs the default proxy-route failure cache behind the custom pool. Callers that want route-aware fallback around a custom pool can compose those layers explicitly around their PooledConnector.

When the connector supports plaintext HTTP through an HTTP proxy, the custom ReqToConnId must keep ordinary forward-proxy connections separate from CONNECT tunnels to the same proxy. Rama’s super::HttpConnIdentifier includes this distinction automatically.

The supplied ReqToConnID partitions routes and application protocols. The pool must also honor connection-owned reuse policies published by transport connectors. Return a non-reusable ConnID to require a fresh connection that must not return to the pool.

impl<T, D> EasyHttpConnectorBuilder<T, HttpStage<false>, D>

pub fn without_connection_pool( self, ) -> EasyHttpConnectorBuilder<RequestVersionAdapter<HttpConnectRequestAdapter<MapEstablishedConnection<HttpServiceConnector<ProxyRoutesConnector<T>>, AltSvcConnectionLayer>>>, PoolStage>

where T: ConnectorService<ConnectRequest>,

Finish the proxy-free HTTP connector stack without a connection pool.

No proxy-route failure cache is installed. Call Self::with_proxy_route_failure_cache before this method to explicitly add one for a custom transport.

pub fn try_with_connection_pool( self, config: HttpPooledConnectorConfig, ) -> Result<EasyHttpConnectorBuilder<RequestVersionAdapter<HttpConnectRequestAdapter<MapEstablishedConnection<HttpServiceConnector<ProxyRoutesConnector<HttpPooledConnector<T>>>, AltSvcConnectionLayer>>>, PoolStage>, BoxError>

where T: ConnectorService<ConnectRequest>,

Use the default connection pool without a proxy-route failure cache.

pub fn with_default_connection_pool( self, ) -> EasyHttpConnectorBuilder<RequestVersionAdapter<HttpConnectRequestAdapter<MapEstablishedConnection<HttpServiceConnector<ProxyRoutesConnector<HttpPooledConnector<T>>>, AltSvcConnectionLayer>>>, PoolStage>

where T: ConnectorService<ConnectRequest>,

Use Rama’s known-valid default connection pool configuration without a proxy-route failure cache.

pub fn with_custom_connection_pool<P, R>( self, pool: P, req_to_conn_id: R, wait_for_pool_timeout: Option<Duration>, ) -> EasyHttpConnectorBuilder<PooledConnector<T, P, R>, PoolStage>

Use a custom connection pool without a proxy-route failure cache.

The supplied ReqToConnID partitions routes and application protocols. The pool must also honor connection-owned reuse policies published by transport connectors. Return a non-reusable ConnID to require a fresh connection that must not return to the pool.

impl<T, D> EasyHttpConnectorBuilder<T, ProxyRouteFailureCacheStage, D>

pub fn without_connection_pool( self, ) -> EasyHttpConnectorBuilder<RequestVersionAdapter<HttpConnectRequestAdapter<MapEstablishedConnection<HttpServiceConnector<ProxyRoutesConnector<T>>, AltSvcConnectionLayer>>>, PoolStage>

where T: ConnectorService<ConnectRequest>,

Finish the default HTTP connector stack without a connection pool.

pub fn try_with_connection_pool( self, config: HttpPooledConnectorConfig, ) -> Result<EasyHttpConnectorBuilder<RequestVersionAdapter<HttpConnectRequestAdapter<MapEstablishedConnection<HttpServiceConnector<ProxyRoutesConnector<HttpPooledConnector<T>>>, AltSvcConnectionLayer>>>, PoolStage>, BoxError>

where T: ConnectorService<ConnectRequest>,

Use the default connection pool with the selected failure-cache policy.

pub fn with_default_connection_pool( self, ) -> EasyHttpConnectorBuilder<RequestVersionAdapter<HttpConnectRequestAdapter<MapEstablishedConnection<HttpServiceConnector<ProxyRoutesConnector<HttpPooledConnector<T>>>, AltSvcConnectionLayer>>>, PoolStage>

where T: ConnectorService<ConnectRequest>,

Use Rama’s known-valid default connection pool configuration with the selected failure-cache policy.

pub fn with_custom_connection_pool<P, R>( self, pool: P, req_to_conn_id: R, wait_for_pool_timeout: Option<Duration>, ) -> EasyHttpConnectorBuilder<PooledConnector<T, P, R>, PoolStage>

Use a custom connection pool with the selected failure-cache policy.

For a proxy-capable connector, the custom ReqToConnID must partition plaintext HTTP forward-proxy connections from CONNECT tunnels to the same proxy. super::HttpConnIdentifier does so by default.

The supplied ReqToConnID partitions routes and application protocols. The pool must also honor connection-owned reuse policies published by transport connectors. Return a non-reusable ConnID to require a fresh connection that must not return to the pool.

impl<T> EasyHttpConnectorBuilder<T, PoolStage>

pub fn build_client<Body, ModifiedBody, ConnResponse>( self, ) -> EasyHttpWebClient<Body, T::Output, ()>

where Body: StreamingBody<Data: Send + 'static, Error: Into<BoxError>> + Unpin + Send + 'static, ModifiedBody: StreamingBody<Data: Send + 'static, Error: Into<BoxError>> + Unpin + Send + 'static, T: Service<Request<Body>, Output = EstablishedClientConnection<ConnResponse, Request<ModifiedBody>>, Error: Into<BoxError>>, ConnResponse: ExtensionsRef,

Build a super::EasyHttpWebClient using the currently configured connector

impl<T, S, D> EasyHttpConnectorBuilder<T, S, D>

pub fn build_connector(self) -> T

Build a connector from the currently configured setup

Trait Implementations

impl<C: Default, S: Default, D: Default> Default for EasyHttpConnectorBuilder<C, S, D>

fn default() -> Self

Returns the “default value” for a type.