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

{fastapi_reverse_proxy-0.3.1 → fastapi_reverse_proxy-0.4.0}/PKG-INFO

@@ -1,9 +1,11 @@
 Metadata-Version: 2.4
 Name: fastapi-reverse-proxy
-Version: 0.3.1
+Version: 0.4.0
 Summary: A robust, streaming-capable reverse proxy for FastAPI including WebSocket support.
 Author-email: Tomás <tomas@suricatingss.xyz>
 License-Expression: MIT
+Project-URL: Repository, https://github.com/tfsantos05/fastapi-reverse-proxy
+Project-URL: Issues, https://github.com/tfsantos05/fastapi-reverse-proxy/issues
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
 Classifier: Framework :: FastAPI
@@ -93,7 +95,7 @@ The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customizati
 | :--- | :--- | :--- |
 | `timeout` | `float` | Total request timeout in seconds (Default: `60.0`). |
 | `method` | `str` | Force a specific HTTP method (e.g., `"POST"`). |
-| `override_body` | `bytes` | Send custom data instead of the incoming request body. |
+| `override_body` | `bytes \| str \| dict \| list` | Use this instead of streaming the request body. `str` is UTF-8 encoded; `dict`/`list` are JSON-serialized automatically (automatically sets `Content-Type: application/json` if not already set). |
 | `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`). |
@@ -129,6 +131,8 @@ The library implements "deferred negotiation" for WebSockets:
 3. Once the upstream accepts a protocol, the proxy calls `websocket.accept(subprotocol=...)` back to the client.
 4. This ensures the entire tunnel (Client <-> Proxy <-> Upstream) uses the same negotiated protocol.
 5. **Handshake Timeout**: Supports a customizable `timeout` parameter (default `10.0s`) to prevent hangs if the backend is unresponsive.
+6. **Error Handling**: Raises `fastapi.WebSocketException` when the upstream connection fails or is rejected with proper WS codes such as 1008 or 1011
+7. **Debug**: Disruptions from either side are logged on debug level.
 
 ## Robustness & Safety
 
@@ -139,6 +143,14 @@ The library implements "deferred negotiation" for WebSockets:
   `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.
+- **Content-Length Safety**: Always stripped from the outbound request and
+  recalculated by `httpx` (or sent chunked when streaming), preventing
+  `LocalProtocolError` when `override_body` differs in size from the original
+  request.
+- **Content-Encoding Passthrough**: Compressed upstream responses (`gzip`, `br`,
+  etc.) are streamed back to the client raw via `aiter_raw()`, with
+  `Content-Encoding` preserved — the client decompresses it itself, avoiding
+  corrupted/garbled response bodies.
 
 
 
@@ -181,3 +193,12 @@ location /ws/ {
 
 Without this configuration, `X-Forwarded-*` headers will be empty or missing by
 the time they reach your application.
+
+
+### Streaming & Response Buffering
+
+`X-Accel-Buffering: no` is set automatically on every proxied response to
+disable Nginx's response buffering for streamed content (SSE, chunked
+transfers, large file downloads). If deploying behind Apache instead, disable
+buffering via your Apache config (`mod_proxy` directives) — there's no
+equivalent response header Apache recognizes.

fastapi_reverse_proxy-0.3.1/src/fastapi_reverse_proxy.egg-info/PKG-INFO → fastapi_reverse_proxy-0.4.0/README.md

@@ -1,28 +1,3 @@
-Metadata-Version: 2.4
-Name: fastapi-reverse-proxy
-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: Operating System :: OS Independent
-Classifier: Framework :: FastAPI
-Classifier: Topic :: Internet :: Proxy Servers
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: fastapi>=0.129.0
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: starlette>=0.52.1
-Requires-Dist: uvicorn>=0.41.0
-Requires-Dist: anyio>=4.12.1
-Requires-Dist: certifi>=2026.1.4
-Requires-Dist: pydantic>=2.12.5
-Requires-Dist: url-normalize>=2.2.1
-Requires-Dist: typing_extensions>=4.15.0
-Requires-Dist: websockets>=16.0
-Dynamic: license-file
-
 # FastAPI Reverse Proxy
 
 A robust, streaming-capable reverse proxy for FastAPI/Starlette with built-in **Latency-Based Load Balancing** and **Active Health Monitoring**.
@@ -93,7 +68,7 @@ The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customizati
 | :--- | :--- | :--- |
 | `timeout` | `float` | Total request timeout in seconds (Default: `60.0`). |
 | `method` | `str` | Force a specific HTTP method (e.g., `"POST"`). |
-| `override_body` | `bytes` | Send custom data instead of the incoming request body. |
+| `override_body` | `bytes \| str \| dict \| list` | Use this instead of streaming the request body. `str` is UTF-8 encoded; `dict`/`list` are JSON-serialized automatically (automatically sets `Content-Type: application/json` if not already set). |
 | `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`). |
@@ -129,6 +104,8 @@ The library implements "deferred negotiation" for WebSockets:
 3. Once the upstream accepts a protocol, the proxy calls `websocket.accept(subprotocol=...)` back to the client.
 4. This ensures the entire tunnel (Client <-> Proxy <-> Upstream) uses the same negotiated protocol.
 5. **Handshake Timeout**: Supports a customizable `timeout` parameter (default `10.0s`) to prevent hangs if the backend is unresponsive.
+6. **Error Handling**: Raises `fastapi.WebSocketException` when the upstream connection fails or is rejected with proper WS codes such as 1008 or 1011
+7. **Debug**: Disruptions from either side are logged on debug level.
 
 ## Robustness & Safety
 
@@ -139,6 +116,14 @@ The library implements "deferred negotiation" for WebSockets:
   `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.
+- **Content-Length Safety**: Always stripped from the outbound request and
+  recalculated by `httpx` (or sent chunked when streaming), preventing
+  `LocalProtocolError` when `override_body` differs in size from the original
+  request.
+- **Content-Encoding Passthrough**: Compressed upstream responses (`gzip`, `br`,
+  etc.) are streamed back to the client raw via `aiter_raw()`, with
+  `Content-Encoding` preserved — the client decompresses it itself, avoiding
+  corrupted/garbled response bodies.
 
 
 
@@ -181,3 +166,12 @@ location /ws/ {
 
 Without this configuration, `X-Forwarded-*` headers will be empty or missing by
 the time they reach your application.
+
+
+### Streaming & Response Buffering
+
+`X-Accel-Buffering: no` is set automatically on every proxied response to
+disable Nginx's response buffering for streamed content (SSE, chunked
+transfers, large file downloads). If deploying behind Apache instead, disable
+buffering via your Apache config (`mod_proxy` directives) — there's no
+equivalent response header Apache recognizes.

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-reverse-proxy"
-version = "0.3.1"
+version = "0.4.0"
 authors = [
   { name="Tomás", email="tomas@suricatingss.xyz" },
 ]
@@ -31,5 +31,9 @@ dependencies = [
   "websockets>=16.0"
 ]
 
+[project.urls]
+Repository = "https://github.com/tfsantos05/fastapi-reverse-proxy"
+Issues = "https://github.com/tfsantos05/fastapi-reverse-proxy/issues"
+
 [tool.setuptools.packages.find]
 where = ["src"]

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

@@ -1,10 +1,13 @@
-from fastapi import Request, WebSocket, Response, HTTPException
+from fastapi import Request, WebSocket, HTTPException, WebSocketException
+from fastapi import status as http_codes
+from fastapi.websockets import WebSocketState
 from fastapi.responses import StreamingResponse
 from starlette.background import BackgroundTask
 from url_normalize import url_normalize
 import httpx
 import websockets
 import asyncio
+import json
 import logging
 import inspect
 from typing import Optional
@@ -50,7 +53,7 @@ async def proxy_pass(
     forward_query: bool = True,
     additional_headers: Optional[dict] = None,
     override_headers: Optional[dict] = None,
-    override_body: Optional[bytes] = None,
+    override_body: Optional[bytes | list | dict | str] = None,
     method: Optional[str] = None,
     override_host: Optional[str] = None
 ):
@@ -84,16 +87,6 @@ async def proxy_pass(
         headers = dict(override_headers)
     else:
         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-Forwarded-Proto"] = request.url.scheme
-        #headers["X-Forwarded-Host"] = headers.get("host", request.url.netloc)
     
     # Apply additional headers
     if additional_headers:
@@ -109,6 +102,9 @@ async def proxy_pass(
     # Let httpx handle connection management    
     headers.pop("connection", None)
 
+    # HTTPX should calculate this one automatically. No point in keeping it
+    headers.pop("content-length", None)
+
     # Remove hop-to-hop headers
     headers = {k: v for k, v in headers.items() if k.lower() not in EXCLUDED_HEADERS}
 
@@ -124,7 +120,16 @@ async def proxy_pass(
     try:
         # Prepare content
         if override_body is not None:
-            content = override_body
+            if isinstance(override_body, (list, dict)):
+                # Stringify the JSON and convert to binary
+                content = json.dumps(override_body).encode()
+                # If no content type is set, set to JSON 
+                headers.setdefault("content-type","application/json")
+            elif isinstance(override_body, str): 
+                # Convert to binary if it's a string
+                content = override_body.encode()
+            else:
+                content = override_body
         else:
             # Stream the request body to the target (efficient for large uploads)
             async def request_generator():
@@ -150,14 +155,12 @@ async def proxy_pass(
             for k, v in rp_resp.headers.items():
                 if k.lower() in EXCLUDED_HEADERS:
                     continue
-                if k.lower() == "content-encoding":
-                    continue
                 if k.lower() == "content-length":
                     continue
                 resp_headers[k] = v
-            
+
+            # Prevents NGINX from buffering
             resp_headers["X-Accel-Buffering"] = "no"
-            #resp_headers["Cache-Control"] = "no-cache"
 
             async def cleanup():
                 await rp_resp.aclose()
@@ -165,7 +168,7 @@ async def proxy_pass(
                     await client.aclose()
 
             return StreamingResponse(
-                rp_resp.aiter_bytes(),
+                rp_resp.aiter_raw(),
                 status_code=rp_resp.status_code,
                 headers=resp_headers,
                 background=BackgroundTask(cleanup)
@@ -221,14 +224,8 @@ async def proxy_pass_websocket(
     if override_headers is not None:
         headers = dict(override_headers)
     else:
-        client_host = websocket.client.host if websocket.client else "unknown"
+        #client_host = websocket.client.host if websocket.client else "unknown"
         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)
@@ -256,33 +253,28 @@ async def proxy_pass_websocket(
             await websocket.accept(subprotocol=target_ws.subprotocol)
             await _handle_ws_bidirectional(websocket, target_ws)
 
+        # Graceful close
+        if websocket.client_state == WebSocketState.CONNECTED:
+            await websocket.close()
+
     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
+        raise WebSocketException(code=http_codes.WS_1008_POLICY_VIOLATION, reason=f"WebSocket handshake rejected by upstream: {status}"[:123])
 
     except BaseException as e:
         if not isinstance(e, asyncio.CancelledError):
-            # If the connection fails before accept(), we can raise a proper 502
-            if not websocket.client.connected: # Roughly checking if handshake finished
+            if websocket.client_state != WebSocketState.CONNECTED: # Roughly checking if handshake finished
                 logger.error(f"WebSocket Connection Error: {e}")
-                # This is a bit tricky in WS, but if we haven't accepted yet, we can raise
-                try:
-                    raise HTTPException(status_code=502, detail="Bad Gateway: WebSocket connection failed")
-                except RuntimeError: # If already accepted, we can't raise HTTPException
-                    pass
+                raise WebSocketException(code=http_codes.WS_1011_INTERNAL_ERROR, reason=f"Bad Gateway: {e}"[:123])
             else:
                 logger.error(f"WebSocket Proxy Error: {e}")
-        raise e
-    finally:
-        try:
-            await websocket.close()
-        except Exception:
-            pass
+                raise WebSocketException(code=http_codes.WS_1008_POLICY_VIOLATION, reason=f"WebSocket Proxy Error: {e}"[:123]) # max 123 byte
+        else: 
+            if websocket.client_state == WebSocketState.CONNECTED:
+                try: await websocket.close(code=http_codes.WS_1012_SERVICE_RESTART)
+                except: pass
+            raise e
 
 
 async def _handle_ws_bidirectional(websocket: WebSocket, target_ws):
@@ -298,9 +290,12 @@ async def _handle_ws_bidirectional(websocket: WebSocket, target_ws):
                         await target_ws.send(message["bytes"])
                 elif message["type"] == "websocket.disconnect":
                     break
-        except (Exception, asyncio.CancelledError):
-            # Exit loop on error or cancellation
-            pass
+        # Exit the loop on error or in cancellation
+        except asyncio.CancelledError: pass  # Just cancelled, no error
+        except Exception as e:
+            # Log on Debug level
+            logger.debug(f"WS relay (client→target) ended: {e}")
+
 
     async def target_to_client():
         try:
@@ -310,9 +305,10 @@ async def _handle_ws_bidirectional(websocket: WebSocket, target_ws):
                     await websocket.send_text(message)
                 else:
                     await websocket.send_bytes(message)
-        except (Exception, asyncio.CancelledError, websockets.ConnectionClosed):
-            # Exit loop on error, closure, or cancellation
-            pass
+        except (asyncio.CancelledError, websockets.ConnectionClosed): pass # cancelled or close -> no error
+        except Exception as e:
+            # Log on Debug Level
+            logger.debug(f"WS relay (target→client) ended: {e}")
 
     # Wrap in tasks for cancellation
     tasks = [

fastapi_reverse_proxy-0.3.1/README.md → fastapi_reverse_proxy-0.4.0/src/fastapi_reverse_proxy.egg-info/PKG-INFO

@@ -1,3 +1,30 @@
+Metadata-Version: 2.4
+Name: fastapi-reverse-proxy
+Version: 0.4.0
+Summary: A robust, streaming-capable reverse proxy for FastAPI including WebSocket support.
+Author-email: Tomás <tomas@suricatingss.xyz>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/tfsantos05/fastapi-reverse-proxy
+Project-URL: Issues, https://github.com/tfsantos05/fastapi-reverse-proxy/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Internet :: Proxy Servers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.129.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: starlette>=0.52.1
+Requires-Dist: uvicorn>=0.41.0
+Requires-Dist: anyio>=4.12.1
+Requires-Dist: certifi>=2026.1.4
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: url-normalize>=2.2.1
+Requires-Dist: typing_extensions>=4.15.0
+Requires-Dist: websockets>=16.0
+Dynamic: license-file
+
 # FastAPI Reverse Proxy
 
 A robust, streaming-capable reverse proxy for FastAPI/Starlette with built-in **Latency-Based Load Balancing** and **Active Health Monitoring**.
@@ -68,7 +95,7 @@ The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customizati
 | :--- | :--- | :--- |
 | `timeout` | `float` | Total request timeout in seconds (Default: `60.0`). |
 | `method` | `str` | Force a specific HTTP method (e.g., `"POST"`). |
-| `override_body` | `bytes` | Send custom data instead of the incoming request body. |
+| `override_body` | `bytes \| str \| dict \| list` | Use this instead of streaming the request body. `str` is UTF-8 encoded; `dict`/`list` are JSON-serialized automatically (automatically sets `Content-Type: application/json` if not already set). |
 | `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`). |
@@ -104,6 +131,8 @@ The library implements "deferred negotiation" for WebSockets:
 3. Once the upstream accepts a protocol, the proxy calls `websocket.accept(subprotocol=...)` back to the client.
 4. This ensures the entire tunnel (Client <-> Proxy <-> Upstream) uses the same negotiated protocol.
 5. **Handshake Timeout**: Supports a customizable `timeout` parameter (default `10.0s`) to prevent hangs if the backend is unresponsive.
+6. **Error Handling**: Raises `fastapi.WebSocketException` when the upstream connection fails or is rejected with proper WS codes such as 1008 or 1011
+7. **Debug**: Disruptions from either side are logged on debug level.
 
 ## Robustness & Safety
 
@@ -114,6 +143,14 @@ The library implements "deferred negotiation" for WebSockets:
   `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.
+- **Content-Length Safety**: Always stripped from the outbound request and
+  recalculated by `httpx` (or sent chunked when streaming), preventing
+  `LocalProtocolError` when `override_body` differs in size from the original
+  request.
+- **Content-Encoding Passthrough**: Compressed upstream responses (`gzip`, `br`,
+  etc.) are streamed back to the client raw via `aiter_raw()`, with
+  `Content-Encoding` preserved — the client decompresses it itself, avoiding
+  corrupted/garbled response bodies.
 
 
 
@@ -156,3 +193,12 @@ location /ws/ {
 
 Without this configuration, `X-Forwarded-*` headers will be empty or missing by
 the time they reach your application.
+
+
+### Streaming & Response Buffering
+
+`X-Accel-Buffering: no` is set automatically on every proxied response to
+disable Nginx's response buffering for streamed content (SSE, chunked
+transfers, large file downloads). If deploying behind Apache instead, disable
+buffering via your Apache config (`mod_proxy` directives) — there's no
+equivalent response header Apache recognizes.