Proxies

A client can route all of its connections through a proxy, configured with a single URL. HTTP and SOCKS5 proxies are supported.

Configuring a Proxy

Set config::proxy to the proxy URL, with any credentials in its userinfo:

burl::client::config cfg;
cfg.proxy = urls::url("socks5h://user:pass@localhost:1080");

burl::client client(co_await capy::this_coro::executor, tls_ctx, cfg);

// established through the proxy
auto r = co_await client.get("https://example.com").send();

Supported Schemes

The proxy URL’s scheme selects the kind of proxy:

Scheme Proxy

http

An HTTP proxy. https targets are tunnelled with CONNECT.

socks5

A SOCKS5 proxy. The client resolves the target hostname itself.

socks5h

A SOCKS5 proxy that resolves the target hostname on the proxy’s side.

The difference between socks5 and socks5h is where DNS resolution happens: with socks5h, the proxy resolves the name, which keeps the lookup off the client’s network and is the right choice when the proxy can reach names the client cannot. Any scheme not listed above fails the request with error::unsupported_proxy_scheme.

Proxy Errors

Failures negotiating with the proxy have their own error codes, distinct from failures reaching the target:

error Meaning

unsupported_proxy_scheme

The proxy URL’s scheme is not supported.

proxy_connect_failed

The proxy could not connect to the target.

proxy_auth_failed

Authentication with the proxy failed.

proxy_unsupported_version

The proxy replied with an unsupported protocol version.

Next Steps

Edit this Page