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

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

@@ -1,10 +1,12 @@
 Metadata-Version: 2.4
 Name: fastapi-reverse-proxy
-Version: 0.3.0
+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: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Framework :: FastAPI
 Classifier: Topic :: Internet :: Proxy Servers
@@ -93,10 +95,11 @@ 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`). |
+| `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
 
@@ -128,8 +131,74 @@ 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
 
 - **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.
+- **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.
+
+
+
+## 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.
+
+
+### 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.0 → fastapi_reverse_proxy-0.4.0}/README.md

@@ -68,10 +68,11 @@ 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`). |
+| `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
 
@@ -103,8 +104,74 @@ 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
 
 - **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.
+- **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.
+
+
+
+## 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.
+
+
+### 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.0 → fastapi_reverse_proxy-0.4.0}/pyproject.toml

@@ -4,16 +4,16 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-reverse-proxy"
-version = "0.3.0"
+version = "0.4.0"
 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",
@@ -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.0 → 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
@@ -13,13 +16,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)
@@ -43,8 +53,9 @@ async def proxy_pass(
     forward_query: bool = True,
     additional_headers: Optional[dict] = None,
     override_headers: Optional[dict] = None,
-    override_body: Optional[bytes] = None,
-    method: Optional[str] = None
+    override_body: Optional[bytes | list | dict | str] = None,
+    method: Optional[str] = None,
+    override_host: Optional[str] = None
 ):
     """
     Forwards incoming HTTP requests to the target service using streaming.
@@ -76,25 +87,27 @@ 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:
         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)
 
+    # 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}
+
     client = None
     try:
         client = await get_httpx_client(request)
@@ -107,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():
@@ -133,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()
@@ -148,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)
@@ -204,13 +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"
-        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)
-        }
+        #client_host = websocket.client.host if websocket.client else "unknown"
+        headers = dict(websocket.headers)
     
     if additional_headers:
         headers.update(additional_headers)
@@ -218,6 +233,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,24 +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}")
+        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):
@@ -268,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:
@@ -280,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.0 → fastapi_reverse_proxy-0.4.0/src/fastapi_reverse_proxy.egg-info}/PKG-INFO

@@ -1,10 +1,12 @@
 Metadata-Version: 2.4
 Name: fastapi-reverse-proxy
-Version: 0.3.0
+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: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Framework :: FastAPI
 Classifier: Topic :: Internet :: Proxy Servers
@@ -93,10 +95,11 @@ 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`). |
+| `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
 
@@ -128,8 +131,74 @@ 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
 
 - **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.
+- **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.
+
+
+
+## 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.
+
+
+### 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.