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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-reverse-proxy
-Version: 0.1.1
+Version: 0.2.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
@@ -29,52 +29,51 @@ A robust, streaming-capable reverse proxy for FastAPI/Starlette with built-in **
 
 ## Features
 
-- **Streaming Ready**: Efficiently handles SSE (Server-Sent Events) and large file uploads/downloads.
+- **Async**: Async by default.
+- **Httpx Pool**: Async HTTPX Pool for proxying.
+- **Streaming Ready**: Handles SSE (Server-Sent Events) and large payloads (such as big files) while keeping RAM usage low.
 - **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)
+## Quick Start
 
-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.
+Use the **lifespan** handler as shown for an easy launch.
+
+The simplest way to use the proxy is to use **proxy_pass** and/or **proxy_pass_websocket** on the endpoints.
 
 ```python
 from fastapi import FastAPI, Request, WebSocket
 from contextlib import asynccontextmanager
 
-from fastapi_reverse_proxy 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)
+from fastapi_reverse_proxy import Proxy, proxy_pass, proxy_pass_websocket
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    # Initialize global resources
-    await create_httpx_client(app)
-    async with checker: # Starts background health loop
+    async with Proxy(app):
         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}")
+# catch-all route. recommended for a reverse proxy
+@app.api_route("/{path:path}", methods=["GET","POST","PUT","DELETE"]) # don't forget to add the methods.
+async def index(req: Request):
+    """
+    You always need to pass the "Request" object and to specify the host
+    If you don't add a path, it will be the same as the original (/login --> http://127.0.0.1/login)
+    """
+    return await proxy_pass(req, "http://127.0.0.1:8080")
 
-@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 Examples:
+
+Check [example.py](example.py) for full examples, including
+- **Websocket Proxy**
+- **Socket.IO Proxy** 
+
 ## Advanced Proxying
 
 The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customization for upstream requests:

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

@@ -4,52 +4,51 @@ A robust, streaming-capable reverse proxy for FastAPI/Starlette with built-in **
 
 ## Features
 
-- **Streaming Ready**: Efficiently handles SSE (Server-Sent Events) and large file uploads/downloads.
+- **Async**: Async by default.
+- **Httpx Pool**: Async HTTPX Pool for proxying.
+- **Streaming Ready**: Handles SSE (Server-Sent Events) and large payloads (such as big files) while keeping RAM usage low.
 - **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)
+## Quick Start
 
-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.
+Use the **lifespan** handler as shown for an easy launch.
+
+The simplest way to use the proxy is to use **proxy_pass** and/or **proxy_pass_websocket** on the endpoints.
 
 ```python
 from fastapi import FastAPI, Request, WebSocket
 from contextlib import asynccontextmanager
 
-from fastapi_reverse_proxy 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)
+from fastapi_reverse_proxy import Proxy, proxy_pass, proxy_pass_websocket
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    # Initialize global resources
-    await create_httpx_client(app)
-    async with checker: # Starts background health loop
+    async with Proxy(app):
         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}")
+# catch-all route. recommended for a reverse proxy
+@app.api_route("/{path:path}", methods=["GET","POST","PUT","DELETE"]) # don't forget to add the methods.
+async def index(req: Request):
+    """
+    You always need to pass the "Request" object and to specify the host
+    If you don't add a path, it will be the same as the original (/login --> http://127.0.0.1/login)
+    """
+    return await proxy_pass(req, "http://127.0.0.1:8080")
 
-@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 Examples:
+
+Check [example.py](example.py) for full examples, including
+- **Websocket Proxy**
+- **Socket.IO Proxy** 
+
 ## Advanced Proxying
 
 The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customization for upstream requests:

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

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

{fastapi_reverse_proxy-0.1.1 → fastapi_reverse_proxy-0.2.0}/src/fastapi_reverse_proxy/load_balance.py

@@ -158,12 +158,12 @@ class LoadBalancer:
 
         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, 
+            host=origin,
+            path=path,
             subprotocols=subprotocols, 
             forward_query=forward_query,
             additional_headers=additional_headers,

fastapi_reverse_proxy-0.2.0/src/fastapi_reverse_proxy/proxy_httpx.py

@@ -0,0 +1,30 @@
+import httpx
+from fastapi import FastAPI, Request
+
+class Proxy:
+    def __init__(self, app: FastAPI):
+        """Initializes the HTTP client and stores it in the app state."""
+        self.__app = app # store the app as internal variable
+        self.__app.state.http_proxy_client = httpx.AsyncClient()
+        
+    async def close(self):
+        """Closes the HTTP client stored in the app state."""
+        if hasattr(self.__app.state, "http_proxy_client"):
+            await self.__app.state.http_proxy_client.aclose() # close it
+            
+    async def __aenter__(self): return self # __init__ on async with
+        
+    async def __aexit__(self, exc_type, exc_val, exc_tb): await self.close() # self-close on async with
+
+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.1 → fastapi_reverse_proxy-0.2.0}/src/fastapi_reverse_proxy/proxy_pass.py

@@ -9,6 +9,7 @@ import logging
 import inspect
 from typing import Optional
 from .proxy_httpx import get_httpx_client
+from urllib.parse import urlparse
 
 logger = logging.getLogger("fastapi_reverse_proxy")
 
@@ -19,6 +20,11 @@ EXCLUDED_HEADERS = {
     "proxy-authorization", "te", "trailers", "transfer-encoding", "upgrade"
 }
 
+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 proxy_pass(
     request: Request, 
     host: str,
@@ -33,7 +39,7 @@ async def proxy_pass(
     """
     Forwards incoming HTTP requests to the target service using streaming.
     - host: The host itself (without ending slash)
-    - path: The path with beggining slash
+    - path: The path w/ beggining slash (by default copies requests's path)
     - 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.
@@ -153,7 +159,8 @@ async def proxy_pass(
 
 async def proxy_pass_websocket(
     websocket: WebSocket, 
-    target_url: str, 
+    host: str,
+    path: Optional[str] = None,
     subprotocols: Optional[list[str]] = None, 
     forward_query: bool = True,
     additional_headers: Optional[dict] = None,
@@ -161,10 +168,14 @@ async def proxy_pass_websocket(
 ):
     """
     Forwards incoming WebSocket connections to the target service.
-    - target_url: The full destination WS(S) URL.
+    - 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.
     """
-    url = target_url
+    
+    if path is None: path = websocket.url.path
+    url = url_normalize_ws(host + path)
+    
     if forward_query and websocket.url.query:
         url = f"{url}?{websocket.url.query}" if "?" not in url else f"{url}&{websocket.url.query}"
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-reverse-proxy
-Version: 0.1.1
+Version: 0.2.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
@@ -29,52 +29,51 @@ A robust, streaming-capable reverse proxy for FastAPI/Starlette with built-in **
 
 ## Features
 
-- **Streaming Ready**: Efficiently handles SSE (Server-Sent Events) and large file uploads/downloads.
+- **Async**: Async by default.
+- **Httpx Pool**: Async HTTPX Pool for proxying.
+- **Streaming Ready**: Handles SSE (Server-Sent Events) and large payloads (such as big files) while keeping RAM usage low.
 - **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)
+## Quick Start
 
-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.
+Use the **lifespan** handler as shown for an easy launch.
+
+The simplest way to use the proxy is to use **proxy_pass** and/or **proxy_pass_websocket** on the endpoints.
 
 ```python
 from fastapi import FastAPI, Request, WebSocket
 from contextlib import asynccontextmanager
 
-from fastapi_reverse_proxy 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)
+from fastapi_reverse_proxy import Proxy, proxy_pass, proxy_pass_websocket
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    # Initialize global resources
-    await create_httpx_client(app)
-    async with checker: # Starts background health loop
+    async with Proxy(app):
         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}")
+# catch-all route. recommended for a reverse proxy
+@app.api_route("/{path:path}", methods=["GET","POST","PUT","DELETE"]) # don't forget to add the methods.
+async def index(req: Request):
+    """
+    You always need to pass the "Request" object and to specify the host
+    If you don't add a path, it will be the same as the original (/login --> http://127.0.0.1/login)
+    """
+    return await proxy_pass(req, "http://127.0.0.1:8080")
 
-@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 Examples:
+
+Check [example.py](example.py) for full examples, including
+- **Websocket Proxy**
+- **Socket.IO Proxy** 
+
 ## Advanced Proxying
 
 The `proxy_pass` function and `LoadBalancer.proxy_pass` provide deep customization for upstream requests:

fastapi_reverse_proxy-0.1.1/src/fastapi_reverse_proxy/proxy_httpx.py

@@ -1,15 +0,0 @@
-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