Tornado Proxy Options Need the Right HTTP Backend

Tornado exposes one asynchronous HTTP client interface with different implementations underneath it. Proxy options can therefore fail because of the selected implementation even when the proxy endpoint is correct.

The HTTP client documentation identifies SimpleAsyncHTTPClient as the default implementation and documents the curl-based alternative. Request options such as proxy_host have implementation-specific support notes. Read those notes before adding options to a fetch call.

Configure before constructing the client

For an environment already equipped with the curl backend, an application can select it before creating its shared client:

from tornado.httpclient import AsyncHTTPClient

AsyncHTTPClient.configure('tornado.curl_httpclient.CurlAsyncHTTPClient')
client = AsyncHTTPClient()

Then use the documented proxy host, port, authentication, and timeout request options for the intended call. Keep the hostname separate from the numeric port. Choosing the backend does not choose a proxy endpoint by itself. For a permitted public HTTP route, the HTTP proxy list supplies host and port candidates for those request options.

Client construction matters because an application or framework can create and retain an HTTP client before this code runs. Inspect the actual instance used for the failing request rather than constructing another client afterward and assuming it explains the first one.

For diagnosis, record the active backend and its underlying library version with the failed stage. Distinguish an unsupported request option from a network timeout and from an HTTP response returned by the proxy. Those observations lead to different fixes.