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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-reverse-proxy
-Version: 0.2.0
+Version: 0.3.0
 Summary: A robust, streaming-capable reverse proxy for FastAPI including WebSocket support.
 Author-email: Tomás <tomas@suricatingss.xyz>
 Classifier: Programming Language :: Python :: 3
@@ -36,6 +36,8 @@ A robust, streaming-capable reverse proxy for FastAPI/Starlette with built-in **
 - **Unified Load Balancing**: Standard Round-Robin or Smart routing using a single utility.
 - **Latency-Based Routing**: Automatically routes traffic to the fastest healthy server (HEAD probe).
 - **Advanced Overrides**: Granular control over headers, body, and HTTP methods.
+- **Smart Error Mapping**: Automatically converts upstream connection failures into standard HTTP 502 (Bad Gateway) and 504 (Gateway Timeout) responses.
+- **Resilient Handshakes**: Customizable `open_timeout` for WebSockets to prevent proxy hangs during backend connection attempts.
 - **Version Agnostic**: Automatically handles `websockets` library version differences (12.0+ vs Legacy).
 
 ## Quick Start
@@ -68,11 +70,20 @@ async def index(req: Request):
 
 ```
 
+## 🛡️ Resilience & Error Handling
+
+Error Handlingfastapi-reverse-proxy transforms upstream crashes into meaningful HTTPException responses (e.g., 502 Bad Gateway or 504 Gateway Timeout). 
+
+This allows you to implement custom failover logic, retry mechanisms, or specific error pages.
+
+For a full implementation of a primary-to-backup failover system, see the [example](https://github.com/tfsantos05/fastapi-reverse-proxy/tree/main/examples/02_http_errors.py).
+
 ## Advanced Examples:
 
-Check [example.py](example.py) for full examples, including
+Check [examples](https://github.com/tfsantos05/fastapi-reverse-proxy/tree/main/examples) for full examples, including:
 - **Websocket Proxy**
 - **Socket.IO Proxy** 
+- **Error Handling & Failover** (`examples/error_handling_example.py`)
 
 ## Advanced Proxying
 
@@ -80,6 +91,7 @@ The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customizati
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
+| `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. |
 | `additional_headers` | `dict` | Append custom headers to the proxied request. |
@@ -115,6 +127,7 @@ The library implements "deferred negotiation" for WebSockets:
 2. It establishes an upstream connection first.
 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.
 
 ## Robustness & Safety
 

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

@@ -11,6 +11,8 @@ A robust, streaming-capable reverse proxy for FastAPI/Starlette with built-in **
 - **Unified Load Balancing**: Standard Round-Robin or Smart routing using a single utility.
 - **Latency-Based Routing**: Automatically routes traffic to the fastest healthy server (HEAD probe).
 - **Advanced Overrides**: Granular control over headers, body, and HTTP methods.
+- **Smart Error Mapping**: Automatically converts upstream connection failures into standard HTTP 502 (Bad Gateway) and 504 (Gateway Timeout) responses.
+- **Resilient Handshakes**: Customizable `open_timeout` for WebSockets to prevent proxy hangs during backend connection attempts.
 - **Version Agnostic**: Automatically handles `websockets` library version differences (12.0+ vs Legacy).
 
 ## Quick Start
@@ -43,11 +45,20 @@ async def index(req: Request):
 
 ```
 
+## 🛡️ Resilience & Error Handling
+
+Error Handlingfastapi-reverse-proxy transforms upstream crashes into meaningful HTTPException responses (e.g., 502 Bad Gateway or 504 Gateway Timeout). 
+
+This allows you to implement custom failover logic, retry mechanisms, or specific error pages.
+
+For a full implementation of a primary-to-backup failover system, see the [example](https://github.com/tfsantos05/fastapi-reverse-proxy/tree/main/examples/02_http_errors.py).
+
 ## Advanced Examples:
 
-Check [example.py](example.py) for full examples, including
+Check [examples](https://github.com/tfsantos05/fastapi-reverse-proxy/tree/main/examples) for full examples, including:
 - **Websocket Proxy**
 - **Socket.IO Proxy** 
+- **Error Handling & Failover** (`examples/error_handling_example.py`)
 
 ## Advanced Proxying
 
@@ -55,6 +66,7 @@ The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customizati
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
+| `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. |
 | `additional_headers` | `dict` | Append custom headers to the proxied request. |
@@ -90,6 +102,7 @@ The library implements "deferred negotiation" for WebSockets:
 2. It establishes an upstream connection first.
 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.
 
 ## Robustness & Safety
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-reverse-proxy"
-version = "0.2.0"
+version = "0.3.0"
 authors = [
   { name="Tomás", email="tomas@suricatingss.xyz" },
 ]

{fastapi_reverse_proxy-0.2.0 → fastapi_reverse_proxy-0.3.0}/src/fastapi_reverse_proxy/__init__.py

@@ -1,5 +1,5 @@
 from .proxy_pass import proxy_pass, proxy_pass_websocket
-from .proxy_httpx import create_httpx_client, close_httpx_client, get_httpx_client
+from .proxy_httpx import create_httpx_client, close_httpx_client, get_httpx_client, Proxy
 from .load_balance import LoadBalancer
 from .health_check import HealthChecker
 
@@ -9,6 +9,7 @@ __all__ = [
     "create_httpx_client",
     "close_httpx_client",
     "get_httpx_client",
+    "Proxy",
     "LoadBalancer",
     "HealthChecker",
 ]

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

@@ -1,4 +1,4 @@
-from fastapi import Request, WebSocket, Response
+from fastapi import Request, WebSocket, Response, HTTPException
 from fastapi.responses import StreamingResponse
 from starlette.background import BackgroundTask
 from url_normalize import url_normalize
@@ -23,8 +23,18 @@ EXCLUDED_HEADERS = {
 def url_normalize_ws(url:str):
     u = urlparse(url)
     return url_normalize(url.replace(u.scheme, "http", 1)).replace("http", u.scheme, 1)
-    
 
+async def handle_proxy_exception(e: Exception):
+    """Maps internal exceptions to FastAPI HTTPExceptions for the client."""
+    if isinstance(e, httpx.ConnectTimeout):
+        raise HTTPException(status_code=504, detail="Gateway Timeout")
+    if isinstance(e, (httpx.ConnectError, httpx.RemoteProtocolError)):
+        raise HTTPException(status_code=502, detail="Bad Gateway")
+    if isinstance(e, httpx.ReadTimeout):
+        raise HTTPException(status_code=504, detail="Upstream Read Timeout")
+    # Re-raise other exceptions (like CancelledError or internal bugs) to avoid masking
+    raise e
+    
 async def proxy_pass(
     request: Request, 
     host: str,
@@ -152,11 +162,14 @@ async def proxy_pass(
         # Catch EVERY exception (including CancelledError) for local client cleanup
         if not is_global_client and client:
             await client.aclose()
-        # Re-raise so the server can handle the cancellation/error
+        
+        # Transform httpx errors into proper HTTP responses
+        if not isinstance(e, asyncio.CancelledError):
+            await handle_proxy_exception(e)
+            
         raise e
 
 
-
 async def proxy_pass_websocket(
     websocket: WebSocket, 
     host: str,
@@ -164,13 +177,15 @@ async def proxy_pass_websocket(
     subprotocols: Optional[list[str]] = None, 
     forward_query: bool = True,
     additional_headers: Optional[dict] = None,
-    override_headers: Optional[dict] = None
+    override_headers: Optional[dict] = None,
+    timeout: float = 10.0
 ):
     """
     Forwards incoming WebSocket connections to the target service.
     - host: The host itself (without ending slash)
     - path: The path with beggining slash (by default copies requests's path)
     - forward_query: If True, automatically appends the request's query string.
+    - timeout: Time to wait for the connection handshake (open_timeout).
     """
     
     if path is None: path = websocket.url.path
@@ -211,7 +226,8 @@ async def proxy_pass_websocket(
         
         connect_kwargs = {
             header_param: headers,
-            "subprotocols": supported_subprotocols
+            "subprotocols": supported_subprotocols,
+            "open_timeout": timeout
         }
 
         async with websockets.connect(url, **connect_kwargs) as target_ws:
@@ -221,7 +237,16 @@ async def proxy_pass_websocket(
 
     except BaseException as e:
         if not isinstance(e, asyncio.CancelledError):
-            logger.error(f"WebSocket Proxy Error: {e}")
+            # If the connection fails before accept(), we can raise a proper 502
+            if not websocket.client.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
+            else:
+                logger.error(f"WebSocket Proxy Error: {e}")
         raise e
     finally:
         try:
@@ -230,9 +255,6 @@ async def proxy_pass_websocket(
             pass
 
 
-
-
-
 async def _handle_ws_bidirectional(websocket: WebSocket, target_ws):
     """Internal helper to manage bidirectional WS traffic with clean cancellation."""
     async def client_to_target():

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-reverse-proxy
-Version: 0.2.0
+Version: 0.3.0
 Summary: A robust, streaming-capable reverse proxy for FastAPI including WebSocket support.
 Author-email: Tomás <tomas@suricatingss.xyz>
 Classifier: Programming Language :: Python :: 3
@@ -36,6 +36,8 @@ A robust, streaming-capable reverse proxy for FastAPI/Starlette with built-in **
 - **Unified Load Balancing**: Standard Round-Robin or Smart routing using a single utility.
 - **Latency-Based Routing**: Automatically routes traffic to the fastest healthy server (HEAD probe).
 - **Advanced Overrides**: Granular control over headers, body, and HTTP methods.
+- **Smart Error Mapping**: Automatically converts upstream connection failures into standard HTTP 502 (Bad Gateway) and 504 (Gateway Timeout) responses.
+- **Resilient Handshakes**: Customizable `open_timeout` for WebSockets to prevent proxy hangs during backend connection attempts.
 - **Version Agnostic**: Automatically handles `websockets` library version differences (12.0+ vs Legacy).
 
 ## Quick Start
@@ -68,11 +70,20 @@ async def index(req: Request):
 
 ```
 
+## 🛡️ Resilience & Error Handling
+
+Error Handlingfastapi-reverse-proxy transforms upstream crashes into meaningful HTTPException responses (e.g., 502 Bad Gateway or 504 Gateway Timeout). 
+
+This allows you to implement custom failover logic, retry mechanisms, or specific error pages.
+
+For a full implementation of a primary-to-backup failover system, see the [example](https://github.com/tfsantos05/fastapi-reverse-proxy/tree/main/examples/02_http_errors.py).
+
 ## Advanced Examples:
 
-Check [example.py](example.py) for full examples, including
+Check [examples](https://github.com/tfsantos05/fastapi-reverse-proxy/tree/main/examples) for full examples, including:
 - **Websocket Proxy**
 - **Socket.IO Proxy** 
+- **Error Handling & Failover** (`examples/error_handling_example.py`)
 
 ## Advanced Proxying
 
@@ -80,6 +91,7 @@ The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customizati
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
+| `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. |
 | `additional_headers` | `dict` | Append custom headers to the proxied request. |
@@ -115,6 +127,7 @@ The library implements "deferred negotiation" for WebSockets:
 2. It establishes an upstream connection first.
 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.
 
 ## Robustness & Safety