Fixing proxy headers
====================

If you are serving Hypercorn behind a proxy e.g. a load balancer the
client-address, scheme, and host-header will match that of the
connection between the proxy and Hypercorn rather than the user-agent
(client). However, most proxies provide headers with the original
user-agent (client) values which can be used to "fix" the headers to
these values.

Modern proxies should provide this information via a ``Forwarded``
header from `RFC 7239
<https://datatracker.ietf.org/doc/html/rfc7239>`_. However, this is
rare in practice with legacy proxies using a combination of
``X-Forwarded-For``, ``X-Forwarded-Proto`` and
``X-Forwarded-Host``. It is important that you chose the correct mode
(legacy, or modern) based on the proxy you use.

To use the proxy fix middleware behind a single legacy proxy simply
wrap your app and serve the wrapped app,

.. code-block:: python

    from hypercorn.middleware import ProxyFixMiddleware

    fixed_app = ProxyFixMiddleware(app, mode="legacy", trusted_hops=1)

.. warning::

    The mode and number of trusted hops must match your setup or the
    user-agent (client) may be trusted and hence able to set
    alternative for, proto, and host values. This can, depending on
    your usage in the app, lead to security vulnerabilities.

The ``trusted_hops`` argument should be set to the number of proxies
that are chained in front of Hypercorn. You should set this to how
many proxies are setting the headers so the middleware knows what to
trust.
