fastapi-reverse-proxy 0.1.0__tar.gz

fastapi_reverse_proxy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tomás
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_reverse_proxy-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: fastapi-reverse-proxy
+Version: 0.1.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
+Classifier: License :: OSI Approved :: MIT License
+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**.
+
+## Features
+
+- **Streaming Ready**: Efficiently handles SSE (Server-Sent Events) and large file uploads/downloads.
+- **WebSocket Support**: Seamless bidirectional tunneling with automated subprotocol negotiation.
+- **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.
+- **Robust Cancellation**: Specialized handling for `asyncio.CancelledError` to prevent resource leaks.
+- **Version Agnostic**: Automatically handles `websockets` library version differences (12.0+ vs Legacy).
+
+## Quick Start (Best Practice)
+
+The recommended way to use the library is within a FastAPI **lifespan** handler. This ensures all background monitoring tasks and HTTP clients start and stop cleanly.
+
+```python
+from fastapi import FastAPI, Request, WebSocket
+from contextlib import asynccontextmanager
+
+# Local import assuming library is in the current directory
+from __init__ import (
+     HealthChecker, LoadBalancer, 
+     create_httpx_client, close_httpx_client
+)
+
+# 1. Setup health monitoring and load balancing
+checker = HealthChecker(["http://localhost:8080", "http://localhost:8081"])
+lb = LoadBalancer(checker)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Initialize global resources
+    await create_httpx_client(app)
+    async with checker: # Starts background health loop
+        yield
+    await close_httpx_client(app)
+
+app = FastAPI(lifespan=lifespan)
+
+@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
+async def gateway(request: Request, path: str):
+    # Route to the fastest healthy backend
+    return await lb.proxy_pass(request, path=f"/{path}")
+
+@app.websocket("/ws/{path:path}")
+async def ws_tunnel(websocket: WebSocket, path: str):
+    # Automatic subprotocol negotiation + Tunneling
+    await lb.proxy_pass_websocket(websocket, path=f"/{path}")
+```
+
+## Advanced Proxying
+
+The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customization for upstream requests:
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `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`). |
+
+## Monitoring & Configuration
+
+### HealthChecker (The Loop Owner)
+The **proactive** component. It owns an internal `asyncio` background task that monitors backends.
+- **Immediate Start**: When you enter the `async with` block (or call `start()`), the checker performs an **immediate** check of all backends. This eliminates the "cold-start" window where backends are unknown.
+- **Configuration Modes**:
+  - **Standard**: `HealthChecker(["http://a", "http://b"], ping_path="/health")`
+  - **Personalized**: Pass a list of dictionaries for per-host settings:
+    ```python
+    checker = HealthChecker([
+        {"host": "http://api-1", "pingpath": "/v1/status", "maxrequests": 100},
+        {"host": "http://api-2", "pingpath": "/health"}
+    ])
+    ```
+- **Properties**:
+  - `ping_path`: Get or set the global health check path (default: `"/"`).
+
+### LoadBalancer (The Decision Utility)
+A **normal Python object** that makes routing decisions based on its source.
+- **Stateful**: While it has no background loop, it **does track state** (request counts for rate-limiting and the last time it pulled data from the health checker).
+- **No Lifecycle Needed**: It relies on the `HealthChecker` (or a static list) for data and doesn't need explicit `start`/`stop` calls.
+
+## WebSocket Refinements
+
+The library implements "deferred negotiation" for WebSockets:
+1. The proxy receives the client's supported subprotocols from `scope`.
+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.
+
+## 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.

fastapi_reverse_proxy-0.1.0/README.md

@@ -0,0 +1,99 @@
+# FastAPI Reverse Proxy
+
+A robust, streaming-capable reverse proxy for FastAPI/Starlette with built-in **Latency-Based Load Balancing** and **Active Health Monitoring**.
+
+## Features
+
+- **Streaming Ready**: Efficiently handles SSE (Server-Sent Events) and large file uploads/downloads.
+- **WebSocket Support**: Seamless bidirectional tunneling with automated subprotocol negotiation.
+- **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.
+- **Robust Cancellation**: Specialized handling for `asyncio.CancelledError` to prevent resource leaks.
+- **Version Agnostic**: Automatically handles `websockets` library version differences (12.0+ vs Legacy).
+
+## Quick Start (Best Practice)
+
+The recommended way to use the library is within a FastAPI **lifespan** handler. This ensures all background monitoring tasks and HTTP clients start and stop cleanly.
+
+```python
+from fastapi import FastAPI, Request, WebSocket
+from contextlib import asynccontextmanager
+
+# Local import assuming library is in the current directory
+from __init__ import (
+     HealthChecker, LoadBalancer, 
+     create_httpx_client, close_httpx_client
+)
+
+# 1. Setup health monitoring and load balancing
+checker = HealthChecker(["http://localhost:8080", "http://localhost:8081"])
+lb = LoadBalancer(checker)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Initialize global resources
+    await create_httpx_client(app)
+    async with checker: # Starts background health loop
+        yield
+    await close_httpx_client(app)
+
+app = FastAPI(lifespan=lifespan)
+
+@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
+async def gateway(request: Request, path: str):
+    # Route to the fastest healthy backend
+    return await lb.proxy_pass(request, path=f"/{path}")
+
+@app.websocket("/ws/{path:path}")
+async def ws_tunnel(websocket: WebSocket, path: str):
+    # Automatic subprotocol negotiation + Tunneling
+    await lb.proxy_pass_websocket(websocket, path=f"/{path}")
+```
+
+## Advanced Proxying
+
+The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customization for upstream requests:
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `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`). |
+
+## Monitoring & Configuration
+
+### HealthChecker (The Loop Owner)
+The **proactive** component. It owns an internal `asyncio` background task that monitors backends.
+- **Immediate Start**: When you enter the `async with` block (or call `start()`), the checker performs an **immediate** check of all backends. This eliminates the "cold-start" window where backends are unknown.
+- **Configuration Modes**:
+  - **Standard**: `HealthChecker(["http://a", "http://b"], ping_path="/health")`
+  - **Personalized**: Pass a list of dictionaries for per-host settings:
+    ```python
+    checker = HealthChecker([
+        {"host": "http://api-1", "pingpath": "/v1/status", "maxrequests": 100},
+        {"host": "http://api-2", "pingpath": "/health"}
+    ])
+    ```
+- **Properties**:
+  - `ping_path`: Get or set the global health check path (default: `"/"`).
+
+### LoadBalancer (The Decision Utility)
+A **normal Python object** that makes routing decisions based on its source.
+- **Stateful**: While it has no background loop, it **does track state** (request counts for rate-limiting and the last time it pulled data from the health checker).
+- **No Lifecycle Needed**: It relies on the `HealthChecker` (or a static list) for data and doesn't need explicit `start`/`stop` calls.
+
+## WebSocket Refinements
+
+The library implements "deferred negotiation" for WebSockets:
+1. The proxy receives the client's supported subprotocols from `scope`.
+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.
+
+## 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.

fastapi_reverse_proxy-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fastapi-reverse-proxy"
+version = "0.1.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"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Framework :: FastAPI",
+    "Topic :: Internet :: Proxy Servers",
+]
+dependencies = [
+  "fastapi>=0.129.0",
+  "httpx>=0.28.1",
+  "starlette>=0.52.1",
+  "uvicorn>=0.41.0",
+  "anyio>=4.12.1",
+  "certifi>=2026.1.4",
+  "pydantic>=2.12.5",
+  "url-normalize>=2.2.1",
+  "typing_extensions>=4.15.0",
+  "websockets>=16.0"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

fastapi_reverse_proxy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fastapi_reverse_proxy-0.1.0/src/fastapi_reverse_proxy/__init__.py

@@ -0,0 +1,14 @@
+from .proxy_pass import proxy_pass, proxy_pass_websocket
+from .proxy_httpx import create_httpx_client, close_httpx_client, get_httpx_client
+from .load_balance import LoadBalancer
+from .health_check import HealthChecker
+
+__all__ = [
+    "proxy_pass",
+    "proxy_pass_websocket",
+    "create_httpx_client",
+    "close_httpx_client",
+    "get_httpx_client",
+    "LoadBalancer",
+    "HealthChecker",
+]

fastapi_reverse_proxy-0.1.0/src/fastapi_reverse_proxy/health_check.py

@@ -0,0 +1,166 @@
+import asyncio
+import httpx
+import logging
+import time
+from typing import Optional, Union, Dict
+from urllib.parse import urlparse
+
+logger = logging.getLogger("fastapi_reverse_proxy")
+
+
+class HealthChecker:
+    def __init__(self, targets: list[str] | list[dict], interval: int = 10, timeout: int = 10, httpx_client: httpx.AsyncClient | None = None):
+        if not targets:
+            raise ValueError("Targets list cannot be empty")
+        if interval < 1:
+            raise ValueError("Interval must be at least 1")
+        if timeout < 1:
+            raise ValueError("Timeout must be at least 1")
+
+        self.interval = interval
+        self.timeout = timeout
+        
+        # Determine and enforce strict type (no mixing)
+        first_type = type(targets[0])
+        if first_type not in (str, dict):
+             raise TypeError("Targets must be a list of strings or a list of dictionaries")
+        
+        self.is_personalized = (first_type is dict)
+        self._global_ping_path = "/"
+
+        # Internal storage
+        self._targets_map: Dict[str, str] = {}
+        # Stores extra config like 'maxrequests' from the dictionary
+        self.target_configs: Dict[str, Dict] = {}
+
+        for idx, t in enumerate(targets):
+            if not isinstance(t, first_type):
+                raise TypeError(f"Mixed types in targets at index {idx}. Total list must be same type.")
+            
+            if self.is_personalized:
+                if "host" not in t:
+                    raise KeyError(f"Target dictionary at index {idx} missing required 'host' key")
+                u = urlparse(t["host"])
+                host = f"{u.scheme}://{u.netloc}"
+                self._targets_map[host] = t.get("pingpath", "/")
+                self.target_configs[host] = t
+            else:
+                u = urlparse(t)
+                host = f"{u.scheme}://{u.netloc}"
+                self._targets_map[host] = self._global_ping_path
+                self.target_configs[host] = {}
+
+        self.targets = list(self._targets_map.keys())
+        # Stores latency in ms or False if down
+        self.status: Dict[str, Union[float, bool]] = {host: 0.0 for host in self.targets}
+        self.last_update: float = time.perf_counter()
+
+        self._task: Optional[asyncio.Task] = None
+
+        # Track if WE created the client so we know if we should close it
+        self._owns_client = httpx_client is None
+        self._client = httpx_client or httpx.AsyncClient(timeout=self.timeout)
+
+    @property
+    def ping_path(self) -> str:
+        if self.is_personalized:
+            raise RuntimeError("Global ping_path is not supported when using personalized hosts")
+        return self._global_ping_path
+
+    @ping_path.setter
+    def ping_path(self, value: str):
+        if self.is_personalized:
+            raise RuntimeError("Global ping_path is not supported when using personalized hosts")
+        self._global_ping_path = value
+        # Update all targets in map since we are in global mode
+        for host in self._targets_map:
+            self._targets_map[host] = value
+
+    def __del__(self):
+        """
+        Class-built function for deletion
+        
+        WARNING: This one is last resort! Consider using .destroy() before exiting instead !
+        Complete GC of this class is NOT guaranteed
+        """
+        if hasattr(self, '_client') and self._client is not None:
+            try:
+                logger.warning("You did not call .destroy() . Attempting cleanup via __del__ ... \n(Don't forget to add .destroy() at the end of your program)")
+                loop = asyncio.get_running_loop()
+                if loop.is_running():
+                    loop.create_task(self.destroy())
+            except RuntimeError:
+                pass
+
+    async def _check_target(self, host: str):
+        path = self._targets_map[host]
+        url = f"{host.rstrip('/')}/{path.lstrip('/')}"
+        
+        start_time = time.perf_counter()
+        try:
+            response = await self._client.head(url)
+            if response.status_code < 400:
+                latency = (time.perf_counter() - start_time) * 1000
+                self.status[host] = latency
+            else:
+                self.status[host] = False
+        except Exception:
+            self.status[host] = False
+            logger.warning(f"Target {host} is DOWN")
+
+    async def _loop(self):
+        """The background loop."""
+        while True:
+            await self.check_all()
+            await asyncio.sleep(self.interval)
+
+    async def start(self):
+        """Start the background health check loop."""
+        if not self._task:
+            await self.check_all() # Perform a check right on start
+            self._task = asyncio.create_task(self._loop())
+
+    async def __aenter__(self):
+        await self.start()
+        return self
+
+    async def __aexit__(self, *args):
+        await self.destroy()
+
+    async def stop(self):
+        """Stop the background loop."""
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError: pass
+            self._task = None
+
+    async def destroy(self):
+        """Stop the loop AND close the httpx client."""
+        await self.stop()
+        if self._owns_client and self._client:
+            await self._client.aclose()
+            self._client = None
+
+    async def check_all(self):
+        """Pings all targets and updates their status."""
+        tasks = [self._check_target(host) for host in self.targets]
+        await asyncio.gather(*tasks)
+        self.last_update = time.perf_counter()
+
+    def get_healthy_targets(self):
+        return [h for h in self.targets if self.status.get(h) is not False]
+
+    def get_response_times(self) -> Dict[str, float]:
+        return {t: float(v) for t, v in self.status.items() if v is not False}
+
+    def get_fastest(self) -> str | None:
+        r = self.get_response_times()
+        return min(r, key=lambda t: r[t]) if r else None
+
+    def is_healthy(self, target: str) -> bool:
+        u = urlparse(target)
+        host = f"{u.scheme}://{u.netloc}"
+        status = self.status.get(host)
+        return status is not False and status is not None

fastapi_reverse_proxy-0.1.0/src/fastapi_reverse_proxy/load_balance.py

@@ -0,0 +1,172 @@
+from .health_check import HealthChecker
+from fastapi import Request, Response, WebSocket
+from urllib.parse import urlparse
+from typing import Dict, Optional
+import asyncio, logging
+from url_normalize import url_normalize
+
+logger = logging.getLogger("fastapi_reverse_proxy")
+
+class LoadBalancer:
+    """
+    Dual-mode Load Balancer.
+    - Round-robin: if passed a list of strings.
+    - Health-based: if passed a HealthChecker object.
+    
+    Includes request limits that reset every health-check interval.
+    """
+    
+    def __init__(self, servers: list | HealthChecker):
+        self.servers = servers
+        self.__index = 0
+        self.__healthMode: bool = isinstance(servers, HealthChecker)
+        
+        # Local request tracking
+        self._request_counts: Dict[str, int] = {}
+        self._last_health_update: float = 0.0
+        
+        # Limits: host -> max_requests
+        self._limits_map: Dict[str, Optional[int]] = {}
+        self._global_max_requests: Optional[int] = None
+        
+        if self.__healthMode:
+             # Populate initial limits if targets were dictionaries (Manual mode)
+             for host in self.servers.targets:
+                 # Check 'maxrequests' in the target_configs from the health checker
+                 config = self.servers.target_configs.get(host, {})
+                 self._limits_map[host] = config.get("maxrequests")
+                 
+    @property
+    def max_requests(self) -> Optional[int]:
+        if self.__healthMode and self.servers.is_personalized:
+             raise RuntimeError("Global max_requests is not supported when using personalized hosts")
+        return self._global_max_requests
+
+    @max_requests.setter
+    def max_requests(self, value: Optional[int]):
+        if self.__healthMode and self.servers.is_personalized:
+             raise RuntimeError("Global max_requests is not supported when using personalized hosts")
+        self._global_max_requests = value
+        # Update current limits map since we are in global/auto mode
+        if self.__healthMode:
+            for host in self._limits_map:
+                self._limits_map[host] = value
+
+    def _get_best_healthy(self) -> str | None:
+        """Returns the fastest healthy host that hasn't hit its request limit."""
+        # Detect if HealthChecker performed a new check and reset counts
+        if self.servers.last_update > self._last_health_update:
+            self._request_counts = {h: 0 for h in self.servers.targets}
+            self._last_health_update = self.servers.last_update
+        
+        # Get healthy hosts with their latencies
+        r = self.servers.get_response_times()
+        
+        # Filter out those over their limit
+        available = {}
+        for host, latency in r.items():
+            # Use specific limit from _limits_map OR the global one if it's not set per-host
+            limit = self._limits_map.get(host) if self.servers.is_personalized else self._global_max_requests
+            
+            if limit is None or self._request_counts.get(host, 0) < limit:
+                available[host] = latency
+        
+        if not available:
+            return None
+        
+        return min(available, key=lambda t: available[t])
+    def peek(self) -> str | None:
+        if self.__healthMode:
+            return self._get_best_healthy()
+        else:
+            if not self.servers: return None
+            return self.servers[self.__index]
+    
+    def get(self) -> str | None:
+        if self.__healthMode:
+            best = self._get_best_healthy()
+            if best:
+                self._request_counts[best] = self._request_counts.get(best, 0) + 1
+            return best
+        else:
+            if not self.servers: return None
+            try:
+                return self.servers[self.__index]
+            finally:
+                self.__index = (self.__index + 1) % len(self.servers)
+        
+    def get_all(self) -> list:
+        if self.__healthMode: return self.servers.targets
+        else: return self.servers
+
+    def set_index(self, index: int) -> None:
+        if self.__healthMode:
+            raise RuntimeError("set_index() is not supported in health mode")
+        if index < 0 or (self.servers and index >= len(self.servers)):
+            raise IndexError("Index out of range")
+        self.__index = index
+
+    async def proxy_pass(
+        self, 
+        req: Request, 
+        path: str, 
+        timeout: float = 60.0, 
+        forward_query: bool = True,
+        additional_headers: Optional[dict] = None,
+        override_headers: Optional[dict] = None,
+        override_body: Optional[bytes] = None,
+        method: Optional[str] = None
+    ):
+        from .proxy_pass import proxy_pass as _proxy_pass  # Late import
+        
+        target = self.get()
+        if not target:
+            return Response("Service Unavailable: No healthy backends available or all over limit", status_code=503)
+            
+        #u = urlparse(target)
+        #origin = f"{u.scheme}://{u.netloc}"
+        # Smart pathing: combine origin and user-provided path
+        #dest_url = f"{origin.rstrip('/')}/{path.lstrip('/')}"
+        
+        return await _proxy_pass(
+            request=req, 
+            host=url_normalize(target, default_scheme="http"),
+            path=path,
+            timeout=timeout, 
+            forward_query=forward_query,
+            additional_headers=additional_headers,
+            override_headers=override_headers,
+            override_body=override_body,
+            method=method
+        )
+
+    async def proxy_pass_websocket(
+        self, 
+        websocket: WebSocket, 
+        path: Optional[str] = None, 
+        subprotocols: list[str] | None = None, 
+        forward_query: bool = True,
+        additional_headers: Optional[dict] = None,
+        override_headers: Optional[dict] = None
+    ):
+        from .proxy_pass import proxy_pass_websocket as _proxy_pass_ws  # Late import
+        
+        target = self.get()
+        if not target:
+            await websocket.close(code=1011)
+            return
+
+        u = urlparse(target)
+        origin = f"{u.scheme}://{u.netloc}"
+        # Smart pathing: combine origin and user-provided path (or default path)
+        dest_url = f"{origin.rstrip('/')}/{path.lstrip('/') if path is not None else websocket.url.path}"
+
+        return await _proxy_pass_ws(
+            websocket, 
+            dest_url, 
+            subprotocols=subprotocols, 
+            forward_query=forward_query,
+            additional_headers=additional_headers,
+            override_headers=override_headers
+        )
+

fastapi_reverse_proxy-0.1.0/src/fastapi_reverse_proxy/proxy_httpx.py

@@ -0,0 +1,15 @@
+import httpx
+from fastapi import FastAPI, Request
+
+async def create_httpx_client(app: FastAPI):
+    """Initializes the HTTP client and stores it in the app state."""
+    app.state.http_proxy_client = httpx.AsyncClient()
+
+async def close_httpx_client(app: FastAPI):
+    """Closes the HTTP client stored in the app state."""
+    if hasattr(app.state, "http_proxy_client"):
+        await app.state.http_proxy_client.aclose() # close it
+
+async def get_httpx_client(req: Request) -> httpx.AsyncClient:
+    """Retrieves the HTTP client from the app state."""
+    return req.app.state.http_proxy_client

fastapi_reverse_proxy-0.1.0/src/fastapi_reverse_proxy/proxy_pass.py

@@ -0,0 +1,267 @@
+from fastapi import Request, WebSocket, Response
+from fastapi.responses import StreamingResponse
+from starlette.background import BackgroundTask
+from url_normalize import url_normalize
+import httpx
+import websockets
+import asyncio
+import logging
+import inspect
+from typing import Optional
+from .proxy_httpx import get_httpx_client
+
+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
+EXCLUDED_HEADERS = {
+    "connection", "keep-alive", "proxy-authenticate", 
+    "proxy-authorization", "te", "trailers", "transfer-encoding", "upgrade"
+}
+
+async def proxy_pass(
+    request: Request, 
+    host: str,
+    path: Optional[str] = None,
+    timeout: float = 60.0, 
+    forward_query: bool = True,
+    additional_headers: Optional[dict] = None,
+    override_headers: Optional[dict] = None,
+    override_body: Optional[bytes] = None,
+    method: Optional[str] = None
+):
+    """
+    Forwards incoming HTTP requests to the target service using streaming.
+    - host: The host itself (without ending slash)
+    - path: The path with beggining slash
+    - forward_query: If True, automatically appends the request's query string.
+    - additional_headers: Headers to add to the upstream request.
+    - override_headers: Use these headers instead of original request headers.
+    - override_body: Use this body instead of streaming the request body.
+    - method: HTTP method to use (e.g., 'POST'). Defaults to original request method.
+    """
+    
+    if path is None: path = request.url.path # set to path
+    
+    # normalize host + path
+    url = url_normalize(host + path, default_scheme="http")
+    
+    if forward_query and request.url.query:
+        url = f"{url}?{request.url.query}" if "?" not in url else f"{url}&{request.url.query}"
+        
+    # normalize again
+    url = url_normalize(url ,default_scheme="http")
+    
+    # Determine method
+    final_method = method or request.method
+
+    # Resolve headers
+    if override_headers is not None:
+        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)
+    headers.pop("connection", None)
+
+    client = None
+    try:
+        client = await get_httpx_client(request)
+        is_global_client = True
+    except Exception:
+        # Fallback for testing or standalone usage
+        client = httpx.AsyncClient()
+        is_global_client = False
+
+    try:
+        # Prepare content
+        if override_body is not None:
+            content = override_body
+        else:
+            # Stream the request body to the target (efficient for large uploads)
+            async def request_generator():
+                async for chunk in request.stream():
+                    yield chunk
+            content = request_generator() if final_method in ("POST", "PUT", "PATCH", "DELETE") else None
+
+        # Create the upstream request
+        rp_req = client.build_request(
+            method=final_method,
+            url=url,
+            headers=headers,
+            content=content,
+            timeout=timeout
+        )
+
+        # Send the request and stream the response
+        rp_resp = await client.send(rp_req, stream=True)
+
+        try:
+            # Filter response headers
+            resp_headers = {}
+            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
+            
+            resp_headers["X-Accel-Buffering"] = "no"
+            resp_headers["Cache-Control"] = "no-cache"
+
+            async def cleanup():
+                await rp_resp.aclose()
+                if not is_global_client:
+                    await client.aclose()
+
+            return StreamingResponse(
+                rp_resp.aiter_bytes(),
+                status_code=rp_resp.status_code,
+                headers=resp_headers,
+                background=BackgroundTask(cleanup)
+            )
+        except BaseException as e:
+            # If we fail here, the ownership hasn't passed to StreamingResponse yet
+            await rp_resp.aclose()
+            raise e
+            
+    except BaseException as e:
+        # 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
+        raise e
+
+
+
+async def proxy_pass_websocket(
+    websocket: WebSocket, 
+    target_url: str, 
+    subprotocols: Optional[list[str]] = None, 
+    forward_query: bool = True,
+    additional_headers: Optional[dict] = None,
+    override_headers: Optional[dict] = None
+):
+    """
+    Forwards incoming WebSocket connections to the target service.
+    - target_url: The full destination WS(S) URL.
+    - forward_query: If True, automatically appends the request's query string.
+    """
+    url = target_url
+    if forward_query and websocket.url.query:
+        url = f"{url}?{websocket.url.query}" if "?" not in url else f"{url}&{websocket.url.query}"
+
+    # Ensure we use ws:// or wss://
+    if url.startswith("http://"):
+        url = url.replace("http://", "ws://", 1)
+    elif url.startswith("https://"):
+        url = url.replace("https://", "wss://", 1)
+
+    # Resolve headers
+    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)
+        }
+    
+    if additional_headers:
+        headers.update(additional_headers)
+
+    # Use subprotocols from scope if not provided explicitly
+    supported_subprotocols = subprotocols or websocket.scope.get("subprotocols")
+
+    try:
+        # Determine the correct header parameter name for this version of websockets
+        # Modern (12.0+): additional_headers, Legacy: extra_headers
+        _params = inspect.signature(websockets.connect).parameters
+        header_param = "additional_headers" if "additional_headers" in _params else "extra_headers"
+        
+        connect_kwargs = {
+            header_param: headers,
+            "subprotocols": supported_subprotocols
+        }
+
+        async with websockets.connect(url, **connect_kwargs) as target_ws:
+            # Accept once we know the negotiated subprotocol
+            await websocket.accept(subprotocol=target_ws.subprotocol)
+            await _handle_ws_bidirectional(websocket, target_ws)
+
+    except BaseException as e:
+        if not isinstance(e, asyncio.CancelledError):
+            logger.error(f"WebSocket Proxy Error: {e}")
+        raise e
+    finally:
+        try:
+            await websocket.close()
+        except Exception:
+            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():
+        try:
+            while True:
+                message = await websocket.receive()
+                if message["type"] == "websocket.receive":
+                    if "text" in message:
+                        await target_ws.send(message["text"])
+                    elif "bytes" in message:
+                        await target_ws.send(message["bytes"])
+                elif message["type"] == "websocket.disconnect":
+                    break
+        except (Exception, asyncio.CancelledError):
+            # Exit loop on error or cancellation
+            pass
+
+    async def target_to_client():
+        try:
+            while True:
+                message = await target_ws.recv()
+                if isinstance(message, str):
+                    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
+
+    # Wrap in tasks for cancellation
+    tasks = [
+        asyncio.create_task(client_to_target()),
+        asyncio.create_task(target_to_client())
+    ]
+    
+    try:
+        await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+    finally:
+        for task in tasks:
+            if not task.done():
+                task.cancel()
+        # Ensure all tasks are gathered and exceptions (including CancelledError) are handled
+        await asyncio.gather(*tasks, return_exceptions=True)

fastapi_reverse_proxy-0.1.0/src/fastapi_reverse_proxy.egg-info/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: fastapi-reverse-proxy
+Version: 0.1.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
+Classifier: License :: OSI Approved :: MIT License
+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**.
+
+## Features
+
+- **Streaming Ready**: Efficiently handles SSE (Server-Sent Events) and large file uploads/downloads.
+- **WebSocket Support**: Seamless bidirectional tunneling with automated subprotocol negotiation.
+- **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.
+- **Robust Cancellation**: Specialized handling for `asyncio.CancelledError` to prevent resource leaks.
+- **Version Agnostic**: Automatically handles `websockets` library version differences (12.0+ vs Legacy).
+
+## Quick Start (Best Practice)
+
+The recommended way to use the library is within a FastAPI **lifespan** handler. This ensures all background monitoring tasks and HTTP clients start and stop cleanly.
+
+```python
+from fastapi import FastAPI, Request, WebSocket
+from contextlib import asynccontextmanager
+
+# Local import assuming library is in the current directory
+from __init__ import (
+     HealthChecker, LoadBalancer, 
+     create_httpx_client, close_httpx_client
+)
+
+# 1. Setup health monitoring and load balancing
+checker = HealthChecker(["http://localhost:8080", "http://localhost:8081"])
+lb = LoadBalancer(checker)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Initialize global resources
+    await create_httpx_client(app)
+    async with checker: # Starts background health loop
+        yield
+    await close_httpx_client(app)
+
+app = FastAPI(lifespan=lifespan)
+
+@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
+async def gateway(request: Request, path: str):
+    # Route to the fastest healthy backend
+    return await lb.proxy_pass(request, path=f"/{path}")
+
+@app.websocket("/ws/{path:path}")
+async def ws_tunnel(websocket: WebSocket, path: str):
+    # Automatic subprotocol negotiation + Tunneling
+    await lb.proxy_pass_websocket(websocket, path=f"/{path}")
+```
+
+## Advanced Proxying
+
+The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customization for upstream requests:
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `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`). |
+
+## Monitoring & Configuration
+
+### HealthChecker (The Loop Owner)
+The **proactive** component. It owns an internal `asyncio` background task that monitors backends.
+- **Immediate Start**: When you enter the `async with` block (or call `start()`), the checker performs an **immediate** check of all backends. This eliminates the "cold-start" window where backends are unknown.
+- **Configuration Modes**:
+  - **Standard**: `HealthChecker(["http://a", "http://b"], ping_path="/health")`
+  - **Personalized**: Pass a list of dictionaries for per-host settings:
+    ```python
+    checker = HealthChecker([
+        {"host": "http://api-1", "pingpath": "/v1/status", "maxrequests": 100},
+        {"host": "http://api-2", "pingpath": "/health"}
+    ])
+    ```
+- **Properties**:
+  - `ping_path`: Get or set the global health check path (default: `"/"`).
+
+### LoadBalancer (The Decision Utility)
+A **normal Python object** that makes routing decisions based on its source.
+- **Stateful**: While it has no background loop, it **does track state** (request counts for rate-limiting and the last time it pulled data from the health checker).
+- **No Lifecycle Needed**: It relies on the `HealthChecker` (or a static list) for data and doesn't need explicit `start`/`stop` calls.
+
+## WebSocket Refinements
+
+The library implements "deferred negotiation" for WebSockets:
+1. The proxy receives the client's supported subprotocols from `scope`.
+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.
+
+## 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.

fastapi_reverse_proxy-0.1.0/src/fastapi_reverse_proxy.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/fastapi_reverse_proxy/__init__.py
+src/fastapi_reverse_proxy/health_check.py
+src/fastapi_reverse_proxy/load_balance.py
+src/fastapi_reverse_proxy/proxy_httpx.py
+src/fastapi_reverse_proxy/proxy_pass.py
+src/fastapi_reverse_proxy.egg-info/PKG-INFO
+src/fastapi_reverse_proxy.egg-info/SOURCES.txt
+src/fastapi_reverse_proxy.egg-info/dependency_links.txt
+src/fastapi_reverse_proxy.egg-info/requires.txt
+src/fastapi_reverse_proxy.egg-info/top_level.txt

fastapi_reverse_proxy-0.1.0/src/fastapi_reverse_proxy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fastapi_reverse_proxy-0.1.0/src/fastapi_reverse_proxy.egg-info/requires.txt

@@ -0,0 +1,10 @@
+fastapi>=0.129.0
+httpx>=0.28.1
+starlette>=0.52.1
+uvicorn>=0.41.0
+anyio>=4.12.1
+certifi>=2026.1.4
+pydantic>=2.12.5
+url-normalize>=2.2.1
+typing_extensions>=4.15.0
+websockets>=16.0

fastapi_reverse_proxy-0.1.0/src/fastapi_reverse_proxy.egg-info/top_level.txt

@@ -0,0 +1 @@
+fastapi_reverse_proxy