fix: Ensure x-forwarded-port header is used in Forwarded header (#115)

## What I'm Changing

This PR ensures that a `x-forwarded-port` header is used when
constructing the `forwarded` header.

### Backstory

We have been experiencing an issue in a Kubernetes environment where
Links were being written with `href` values with incorrect origins. To
be specific, they would point to `localhost:8001` rather than
`localhost`, where `localhost` is the public-facing host and `:8001` is
the port of the internal upstream STAC API. The network layout was such
that we had a Traefik proxy in front of the STAC Auth Proxy. That proxy
sets the `x-forwarded-port` header on requests that were sent to the
STAC Auth Proxy. However, the request did _not_ contain a `forwarded`
header, so we would create one. The problem was that our current logic
would _not_ make use of the `x-forwarded-port` when created the
`forwarded` header. Despite us forwarding the `x-forwarded-port`, the
upstream STAC API would defer to the `forwarded` header and thus ignore
the provided `x-forwarded-port`. This meant that the upstream STAC API
would generate links for `http://localhost:8001`. Digging through
`stac-fastapi` code, we can see that the port first is read from the
`host` header and then possibly overridden by the value in `forwarded`:


https://github.com/stac-utils/stac-fastapi/blob/3b24f86bc538b8c1d6b86008845d5541f4f481e8/stac_fastapi/api/stac_fastapi/api/middleware.py#L87-L106

The current problematic flow looks something like this:


```mermaid
sequenceDiagram
    autonumber

    participant Client as Client
    participant Traefik as Traefik Proxy
    participant Auth as STAC Auth Proxy
    participant STAC as STAC API

    Client->>Traefik: HTTP request
    Note left of Traefik: host: http://localhost

    Traefik->>Auth: Forward request
    Note left of Auth: host: http://localhost
    Note left of Auth: x-forwarded-for: 192.168.65.1
    Note left of Auth: x-forwarded-host: localhost
    Note left of Auth: x-forwarded-port: 80
    Note left of Auth: x-forwarded-proto: http
    Note left of Auth: x-forwarded-server: 26a4cc50fa1a

    Auth->>STAC: Forward request (proxied)
    Note left of STAC: host: http://stac:8001
    Note left of STAC: x-forwarded-for: 192.168.65.1
    Note left of STAC: x-forwarded-host: localhost
    Note left of STAC: x-forwarded-port: 80
    Note left of STAC: x-forwarded-proto: http
    Note left of STAC: x-forwarded-server: 26a4cc50fa1a
    Note left of STAC: via: 1.1 stac-auth-proxy
    Note left of STAC: forwarded: for=192.168.65.1 host=localhost proto=http path=/stac

    STAC-->>Auth: Response document
    Note left of Auth: links point to http://localhost:8001/...

    Auth-->>Client: Response (unchanged body)
```

Unfortunately, our link rewriting middleware would miss these links as
it was looking for the internal upstream url `stac:8001` and not
`localhost:8001`. This is maybe besides the point, as the link rewriting
middleware is really about cleaning up paths and in an ideal world we
expect the upstream STAC API to properly make use of the `forwarded`
header to properly construct links (which stac-fastapi-pgstac does
decently well).

<details>

<summary>some more thoughts about
<code>x-forwarded-port</code></summary>

Reading the MDN docs on the `forwarded` header[^1], we see:

> The alternative and de-facto standard versions of this header are the
[X-forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-forwarded-For),
[X-forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-forwarded-Host)
and
[X-forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-forwarded-Proto)
headers.

The lack of mention of `x-forwarded-port` led me to believe that the
`X-forwarded-Host` included the port. However, that doesn't not seem
accurate when reviewing Traefik behavior.

</details>

## How I did it

The fix was pretty simple: ensure that the `host` within the `forwarded`
header contained the x-forwarded port.

## How you can test it

Docker image of this build available here:
https://github.com/developmentseed/stac-auth-proxy/releases/tag/v0.10.2-rc2

Author: alukach

src/stac_auth_proxy/handlers/reverse_proxy.py

@@ -35,7 +35,13 @@ def __post_init__(self):
         )
 
     def _prepare_headers(self, request: Request) -> MutableHeaders:
-        """Prepare headers for the proxied request."""
+        """
+        Prepare headers for the proxied request. Construct a Forwarded header to inform
+        the upstream API about the original request context, which will allow it to
+        properly construct URLs in responses (namely, in the Links). If there are
+        existing X-Forwarded-*/Forwarded headers (typically, in situations where the
+        STAC Auth Proxy is behind a proxy like Traefik or NGINX), we use those values.
+        """
         headers = MutableHeaders(request.headers)
         headers.setdefault("Via", f"1.1 {self.proxy_name}")
 
@@ -44,18 +50,29 @@ def _prepare_headers(self, request: Request) -> MutableHeaders:
         )
         proxy_proto = headers.get("X-Forwarded-Proto", request.url.scheme)
         proxy_host = headers.get("X-Forwarded-Host", request.url.netloc)
+        proxy_port = str(headers.get("X-Forwarded-Port", request.url.port))
         proxy_path = headers.get("X-Forwarded-Path", request.base_url.path)
+
+        # NOTE: If we don't include a port, it's possible that the upstream server may
+        # mistakenly use the port from the Host header (which may be the internal port
+        # of the upstream server) when constructing URLs.
+        forwarded_host = proxy_host
+        if proxy_port:
+            forwarded_host = f"{forwarded_host}:{proxy_port}"
+
         headers.setdefault(
             "Forwarded",
-            f"for={proxy_client};host={proxy_host};proto={proxy_proto};path={proxy_path}",
+            f"for={proxy_client};host={forwarded_host};proto={proxy_proto};path={proxy_path}",
         )
 
         # NOTE: This is useful if the upstream API does not support the Forwarded header
+        # and there were no existing X-Forwarded-* headers on the incoming request.
         if self.legacy_forwarded_headers:
             headers.setdefault("X-Forwarded-For", proxy_client)
             headers.setdefault("X-Forwarded-Host", proxy_host)
             headers.setdefault("X-Forwarded-Path", proxy_path)
             headers.setdefault("X-Forwarded-Proto", proxy_proto)
+            headers.setdefault("X-Forwarded-Port", proxy_port)
 
         # Set host to the upstream host
         if self.override_host:

tests/test_reverse_proxy.py

@@ -282,3 +282,31 @@ async def test_nginx_headers_behavior(scope_overrides, headers, expected_forward
         assert f"{key}={expected_value}" in forwarded, (
             f"Expected {key}={expected_value} in {forwarded}"
         )
+
+
+@pytest.mark.parametrize("legacy_headers", [False, True])
+@pytest.mark.asyncio
+async def test_x_forwarded_port_in_forwarded_header(legacy_headers):
+    """Test that x-forwarded-port is included in the Forwarded header."""
+    headers = [
+        (b"host", b"localhost:8000"),
+        (b"user-agent", b"test-agent"),
+        (b"x-forwarded-port", b"443"),
+        (b"x-forwarded-proto", b"https"),
+        (b"x-forwarded-host", b"api.example.com"),
+    ]
+    request = create_request(headers=headers)
+    handler = ReverseProxyHandler(
+        upstream="http://upstream-api.com", legacy_forwarded_headers=legacy_headers
+    )
+    result_headers = handler._prepare_headers(request)
+
+    # Check that the Forwarded header includes the port
+    forwarded = result_headers["Forwarded"]
+    assert "host=api.example.com:443" in forwarded, (
+        f"Expected host=api.example.com:443 in {forwarded}"
+    )
+    assert "proto=https" in forwarded
+
+    # Check that the x-forwarded-port header is preserved
+    assert result_headers["X-Forwarded-Port"] == "443"