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

{fastapi_reverse_proxy-0.2.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.2.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
@@ -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,11 +91,13 @@ 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. |
 | `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
 
@@ -115,8 +128,56 @@ 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
 
 - **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.2.0 → fastapi_reverse_proxy-0.3.1}/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,11 +66,13 @@ 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. |
 | `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
 
@@ -90,8 +103,56 @@ 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
 
 - **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.2.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.2.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.2.0 → fastapi_reverse_proxy-0.3.1}/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.1}/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
@@ -13,18 +13,35 @@ 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)
-    
 
+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,
@@ -34,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.
@@ -68,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)
@@ -130,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()
@@ -152,11 +179,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 +194,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
@@ -190,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)
@@ -203,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
@@ -211,7 +247,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:
@@ -219,9 +256,27 @@ 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):
-            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 +285,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.1/src/fastapi_reverse_proxy.egg-info}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: fastapi-reverse-proxy
-Version: 0.2.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
@@ -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,11 +91,13 @@ 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. |
 | `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
 
@@ -115,8 +128,56 @@ 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
 
 - **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.