fastapi-reverse-proxy 0.3.0__tar.gz → 0.3.1__tar.gz

{fastapi_reverse_proxy-0.3.0/src/fastapi_reverse_proxy.egg-info → fastapi_reverse_proxy-0.3.1}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: fastapi-reverse-proxy
-Version: 0.3.0
+Version: 0.3.1
 Summary: A robust, streaming-capable reverse proxy for FastAPI including WebSocket support.
 Author-email: Tomás <tomas@suricatingss.xyz>
+License-Expression: MIT
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Framework :: FastAPI
 Classifier: Topic :: Internet :: Proxy Servers
@@ -97,6 +97,7 @@ The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customizati
 | `additional_headers` | `dict` | Append custom headers to the proxied request. |
 | `override_headers` | `dict` | Use these headers *instead* of original request headers. |
 | `forward_query` | `bool` | Whether to append the incoming query string (Default: `True`). |
+| `override_host` | `str` | Override the outbound `Host` header sent to the target (useful for multi-host/virtual-hosting backends that key off the original requested host). |
 
 ## Monitoring & Configuration
 
@@ -133,3 +134,50 @@ The library implements "deferred negotiation" for WebSockets:
 
 - **Termination Safety**: Resource cleanup (closing `httpx` clients and sockets) is triggered even on task cancellation (`BaseException`).
 - **Introspection-Based Compatibility**: Uses `inspect.signature` to automatically detect version-specific parameters in the `websockets` library.
+- **RFC 7230 Compliant Header Handling**: Hop-by-hop headers (`Connection`,
+  `Transfer-Encoding`, `TE`, `Trailers`, `Keep-Alive`, `Proxy-Authenticate`,
+  `Proxy-Authorization`) are stripped from both outbound requests and responses,
+  per spec. WebSocket handshake headers (`Sec-WebSocket-Key`, `Upgrade`, etc.)
+  from the client are never forwarded to the target, avoiding handshake collisions.
+
+
+
+## Running Behind a Reverse Proxy (Nginx/Apache)
+
+By default, `proxy_pass` and `proxy_pass_websocket` forward the client's original
+headers as-is — they do **not** set or rewrite `X-Real-IP`, `X-Forwarded-For`,
+`X-Forwarded-Proto`, or `X-Forwarded-Host`. If this library sits behind Nginx or
+Apache (the common setup), your upstream server is responsible for setting those
+headers before the request reaches this proxy:
+
+```nginx
+location / {
+    proxy_pass http://your-fastapi-app;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header Host $host;
+}
+```
+
+For WebSocket routes, Nginx also needs explicit upgrade handling:
+
+```nginx
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+location /ws/ {
+    proxy_pass http://your-fastapi-app;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $connection_upgrade;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+Without this configuration, `X-Forwarded-*` headers will be empty or missing by
+the time they reach your application.

{fastapi_reverse_proxy-0.3.0 → fastapi_reverse_proxy-0.3.1}/README.md

@@ -72,6 +72,7 @@ The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customizati
 | `additional_headers` | `dict` | Append custom headers to the proxied request. |
 | `override_headers` | `dict` | Use these headers *instead* of original request headers. |
 | `forward_query` | `bool` | Whether to append the incoming query string (Default: `True`). |
+| `override_host` | `str` | Override the outbound `Host` header sent to the target (useful for multi-host/virtual-hosting backends that key off the original requested host). |
 
 ## Monitoring & Configuration
 
@@ -108,3 +109,50 @@ The library implements "deferred negotiation" for WebSockets:
 
 - **Termination Safety**: Resource cleanup (closing `httpx` clients and sockets) is triggered even on task cancellation (`BaseException`).
 - **Introspection-Based Compatibility**: Uses `inspect.signature` to automatically detect version-specific parameters in the `websockets` library.
+- **RFC 7230 Compliant Header Handling**: Hop-by-hop headers (`Connection`,
+  `Transfer-Encoding`, `TE`, `Trailers`, `Keep-Alive`, `Proxy-Authenticate`,
+  `Proxy-Authorization`) are stripped from both outbound requests and responses,
+  per spec. WebSocket handshake headers (`Sec-WebSocket-Key`, `Upgrade`, etc.)
+  from the client are never forwarded to the target, avoiding handshake collisions.
+
+
+
+## Running Behind a Reverse Proxy (Nginx/Apache)
+
+By default, `proxy_pass` and `proxy_pass_websocket` forward the client's original
+headers as-is — they do **not** set or rewrite `X-Real-IP`, `X-Forwarded-For`,
+`X-Forwarded-Proto`, or `X-Forwarded-Host`. If this library sits behind Nginx or
+Apache (the common setup), your upstream server is responsible for setting those
+headers before the request reaches this proxy:
+
+```nginx
+location / {
+    proxy_pass http://your-fastapi-app;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header Host $host;
+}
+```
+
+For WebSocket routes, Nginx also needs explicit upgrade handling:
+
+```nginx
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+location /ws/ {
+    proxy_pass http://your-fastapi-app;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $connection_upgrade;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+Without this configuration, `X-Forwarded-*` headers will be empty or missing by
+the time they reach your application.

{fastapi_reverse_proxy-0.3.0 → fastapi_reverse_proxy-0.3.1}/pyproject.toml

@@ -4,16 +4,16 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-reverse-proxy"
-version = "0.3.0"
+version = "0.3.1"
 authors = [
   { name="Tomás", email="tomas@suricatingss.xyz" },
 ]
 description = "A robust, streaming-capable reverse proxy for FastAPI including WebSocket support."
 readme = "README.md"
 requires-python = ">=3.8"
+license = "MIT"
 classifiers = [
     "Programming Language :: Python :: 3",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Framework :: FastAPI",
     "Topic :: Internet :: Proxy Servers",

{fastapi_reverse_proxy-0.3.0 → fastapi_reverse_proxy-0.3.1}/src/fastapi_reverse_proxy/proxy_pass.py

@@ -13,13 +13,20 @@ from urllib.parse import urlparse
 
 logger = logging.getLogger("fastapi_reverse_proxy")
 
-# Hop-by-hop headers that should typically not be forwarded by a proxy
-# https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/TE
+# RFC 7230 §6.1 — hop-by-hop headers, strip on every proxied HTTP request/response
 EXCLUDED_HEADERS = {
-    "connection", "keep-alive", "proxy-authenticate", 
+    "connection", "keep-alive", "proxy-authenticate",
     "proxy-authorization", "te", "trailers", "transfer-encoding", "upgrade"
 }
 
+# WebSocket handshake headers — belong to ONE handshake (client<->you),
+# must not be reused for the separate handshake you<->target
+WS_HANDSHAKE_HEADERS = {
+    "connection", "upgrade", "host", "sec-websocket-key",
+    "sec-websocket-version", "sec-websocket-extensions",
+    "sec-websocket-protocol"
+}
+
 def url_normalize_ws(url:str):
     u = urlparse(url)
     return url_normalize(url.replace(u.scheme, "http", 1)).replace("http", u.scheme, 1)
@@ -44,7 +51,8 @@ async def proxy_pass(
     additional_headers: Optional[dict] = None,
     override_headers: Optional[dict] = None,
     override_body: Optional[bytes] = None,
-    method: Optional[str] = None
+    method: Optional[str] = None,
+    override_host: Optional[str] = None
 ):
     """
     Forwards incoming HTTP requests to the target service using streaming.
@@ -78,23 +86,32 @@ async def proxy_pass(
         headers = dict(request.headers)
         # Identify the client's real IP and forward it
         client_host = request.client.host if request.client else "unknown"
-        headers["X-Real-IP"] = client_host
-        if "X-Forwarded-For" in headers:
-            headers["X-Forwarded-For"] = f"{headers['X-Forwarded-For']}, {client_host}"
-        else:
-            headers["X-Forwarded-For"] = client_host
+        #headers["X-Real-IP"] = client_host
+        #if "X-Forwarded-For" in headers:
+        #    headers["X-Forwarded-For"] = f"{headers['X-Forwarded-For']}, {client_host}"
+        #else:
+        #    headers["X-Forwarded-For"] = client_host
         
-        headers["X-Forwarded-Proto"] = request.url.scheme
-        headers["X-Forwarded-Host"] = headers.get("host", request.url.netloc)
+        #headers["X-Forwarded-Proto"] = request.url.scheme
+        #headers["X-Forwarded-Host"] = headers.get("host", request.url.netloc)
     
     # Apply additional headers
     if additional_headers:
         headers.update(additional_headers)
     
-    # Let httpx handle the host header and connection management
-    headers.pop("host", None)
+    if override_host:
+        # use the supplied host header
+        headers['host'] = override_host
+    else:
+        # Let httpx handle the host header 
+        headers.pop("host", None)
+
+    # Let httpx handle connection management    
     headers.pop("connection", None)
 
+    # Remove hop-to-hop headers
+    headers = {k: v for k, v in headers.items() if k.lower() not in EXCLUDED_HEADERS}
+
     client = None
     try:
         client = await get_httpx_client(request)
@@ -140,7 +157,7 @@ async def proxy_pass(
                 resp_headers[k] = v
             
             resp_headers["X-Accel-Buffering"] = "no"
-            resp_headers["Cache-Control"] = "no-cache"
+            #resp_headers["Cache-Control"] = "no-cache"
 
             async def cleanup():
                 await rp_resp.aclose()
@@ -205,12 +222,13 @@ async def proxy_pass_websocket(
         headers = dict(override_headers)
     else:
         client_host = websocket.client.host if websocket.client else "unknown"
-        headers = {
-            "X-Real-IP": client_host,
-            "X-Forwarded-For": client_host,
-            "X-Forwarded-Proto": websocket.url.scheme,
-            "X-Forwarded-Host": websocket.headers.get("host", websocket.url.netloc)
-        }
+        headers = dict(websocket.headers)
+        #headers = {
+        #    "X-Real-IP": client_host,
+        #    "X-Forwarded-For": client_host,
+        #   "X-Forwarded-Proto": websocket.url.scheme,
+        #    "X-Forwarded-Host": websocket.headers.get("host", websocket.url.netloc)
+        #}
     
     if additional_headers:
         headers.update(additional_headers)
@@ -218,6 +236,9 @@ async def proxy_pass_websocket(
     # Use subprotocols from scope if not provided explicitly
     supported_subprotocols = subprotocols or websocket.scope.get("subprotocols")
 
+    # Strip hop-to-hop headers
+    headers = {k: v for k, v in headers.items() if k.lower() not in WS_HANDSHAKE_HEADERS}
+
     try:
         # Determine the correct header parameter name for this version of websockets
         # Modern (12.0+): additional_headers, Legacy: extra_headers
@@ -235,6 +256,15 @@ async def proxy_pass_websocket(
             await websocket.accept(subprotocol=target_ws.subprotocol)
             await _handle_ws_bidirectional(websocket, target_ws)
 
+    except websockets.exceptions.InvalidStatus as e:
+        status = e.response.status_code
+        logger.error(f"WebSocket handshake rejected by upstream: {status}")
+        try:
+            raise HTTPException(status_code=status, detail=f"Upstream rejected WebSocket handshake: {status}")
+        except RuntimeError: # If already accepted, we can't raise HTTPException
+            pass
+        raise e
+
     except BaseException as e:
         if not isinstance(e, asyncio.CancelledError):
             # If the connection fails before accept(), we can raise a proper 502

{fastapi_reverse_proxy-0.3.0 → fastapi_reverse_proxy-0.3.1/src/fastapi_reverse_proxy.egg-info}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: fastapi-reverse-proxy
-Version: 0.3.0
+Version: 0.3.1
 Summary: A robust, streaming-capable reverse proxy for FastAPI including WebSocket support.
 Author-email: Tomás <tomas@suricatingss.xyz>
+License-Expression: MIT
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Framework :: FastAPI
 Classifier: Topic :: Internet :: Proxy Servers
@@ -97,6 +97,7 @@ The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customizati
 | `additional_headers` | `dict` | Append custom headers to the proxied request. |
 | `override_headers` | `dict` | Use these headers *instead* of original request headers. |
 | `forward_query` | `bool` | Whether to append the incoming query string (Default: `True`). |
+| `override_host` | `str` | Override the outbound `Host` header sent to the target (useful for multi-host/virtual-hosting backends that key off the original requested host). |
 
 ## Monitoring & Configuration
 
@@ -133,3 +134,50 @@ The library implements "deferred negotiation" for WebSockets:
 
 - **Termination Safety**: Resource cleanup (closing `httpx` clients and sockets) is triggered even on task cancellation (`BaseException`).
 - **Introspection-Based Compatibility**: Uses `inspect.signature` to automatically detect version-specific parameters in the `websockets` library.
+- **RFC 7230 Compliant Header Handling**: Hop-by-hop headers (`Connection`,
+  `Transfer-Encoding`, `TE`, `Trailers`, `Keep-Alive`, `Proxy-Authenticate`,
+  `Proxy-Authorization`) are stripped from both outbound requests and responses,
+  per spec. WebSocket handshake headers (`Sec-WebSocket-Key`, `Upgrade`, etc.)
+  from the client are never forwarded to the target, avoiding handshake collisions.
+
+
+
+## Running Behind a Reverse Proxy (Nginx/Apache)
+
+By default, `proxy_pass` and `proxy_pass_websocket` forward the client's original
+headers as-is — they do **not** set or rewrite `X-Real-IP`, `X-Forwarded-For`,
+`X-Forwarded-Proto`, or `X-Forwarded-Host`. If this library sits behind Nginx or
+Apache (the common setup), your upstream server is responsible for setting those
+headers before the request reaches this proxy:
+
+```nginx
+location / {
+    proxy_pass http://your-fastapi-app;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header Host $host;
+}
+```
+
+For WebSocket routes, Nginx also needs explicit upgrade handling:
+
+```nginx
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+location /ws/ {
+    proxy_pass http://your-fastapi-app;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $connection_upgrade;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+Without this configuration, `X-Forwarded-*` headers will be empty or missing by
+the time they reach your application.