Rename ReverseProxy to Relay (#286)

* Rename ReverseProxy to Relay

Author: tarsil

…s/en/docs/contrib/proxy/reverse-proxy.md docs/en/docs/contrib/proxy/relay.mddocs/en/docs/contrib/proxy/reverse-proxy.md renamed to docs/en/docs/contrib/proxy/relay.md docs/en/docs/contrib/proxy/reverse-proxy.md renamed to docs/en/docs/contrib/proxy/relay.md

@@ -1,6 +1,6 @@
-# ReverseProxy
+# Relay
 
-A **mountable ASGI reverse proxy** for Lilya that forwards HTTP **and optionally WebSocket** traffic to an upstream service.
+A **mountable ASGI relay** for Lilya that forwards HTTP **and optionally WebSocket** traffic to an upstream service.
 
 It preserves **methods, headers, cookies, query parameters, and streaming bodies**, while supporting retries,
 timeout handling, header policies, and structured logging.
@@ -10,7 +10,7 @@ Typical use case: you have **two Lilya apps**:
 - **App 1** (Authentication) handles login, logout, refresh, etc.
 - **App 2** (Your main API) wants to expose `GET/POST /auth/...` publicly but **forward** to App 1 under the hood.
 
-With `ReverseProxy`, you mount a single catch‑all route on App 2 (e.g., `/auth`) that **proxies everything** to App 1.
+With `Relay`, you mount a single catch‑all route on App 2 (e.g., `/auth`) that **proxies everything** to App 1.
 
 ## Why a Proxy?
 
@@ -26,7 +26,7 @@ With `ReverseProxy`, you mount a single catch‑all route on App 2 (e.g., `/auth
 
 ### Before continuing
 
-Lilya uses `httpx` to create the `ReverseProxy` object. This means, to work with it **you must**:
+Lilya uses `httpx` to create the `Relay` object. This means, to work with it **you must**:
 
 ```shell
 pip install httpx
@@ -38,12 +38,12 @@ pip install httpx
 # app.py
 from lilya.apps import Lilya
 from lilya.routing import Include
-from lilya.contrib.proxy.reverse import ReverseProxy
+from lilya.contrib.proxy.relay import Relay
 
-proxy = ReverseProxy(
+proxy = Relay(
     target_base_url="http://auth-service:8000",  # internal service base URL
-    upstream_prefix="/",                         # map "/auth/<path>" -> "/<path>" upstream
-    preserve_host=False,                         # set Host to auth-service
+    upstream_prefix="/",  # map "/auth/<path>" -> "/<path>" upstream
+    preserve_host=False,  # set Host to auth-service
     # Optional: drop the Domain attribute from Set-Cookie so it binds to current host
     rewrite_set_cookie_domain=lambda _original: "",
     max_retries=2,
@@ -53,10 +53,10 @@ proxy = ReverseProxy(
 # The Main Lilya application
 app = Lilya(
     routes=[
-        Include("/auth", app=proxy),             # Everything under /auth/** is proxied
+        Include("/auth", app=proxy),  # Everything under /auth/** is proxied
     ],
-    on_startup=[proxy.startup],                  # start shared HTTP client (pool)
-    on_shutdown=[proxy.shutdown],                # close it cleanly
+    on_startup=[proxy.startup],  # start shared HTTP client (pool)
+    on_shutdown=[proxy.shutdown],  # close it cleanly
 )
 ```
 
@@ -86,14 +86,14 @@ app = Lilya(
 You'll keep the proxy as part of your project's contrib code or ship it as `lilya.contrib.proxy`. The examples below assume a local module:
 
 ```python
-from lilya.contrib.proxy.reverse import ReverseProxy
+from lilya.contrib.proxy.relay import Relay
 ```
 ## API reference
 
-### `ReverseProxy(...)`
+### `Relay(...)`
 
 ```python
-ReverseProxy(
+Relay(
     target_base_url: str,
     *,
     upstream_prefix: str = "/",
@@ -149,7 +149,7 @@ pip install websockets
 You can proxy WS endpoints too:
 
 ```python
-proxy = ReverseProxy("http://chat-service.local")
+proxy = Relay("http://chat-service.local")
 app = Lilya(routes=[Include("/ws", app=proxy)])
 ```
 
@@ -244,7 +244,7 @@ When the browser calls only **App 2** (the proxy), and App 2 server‑side calls
 ### 1. Auth service under `/auth/**` with Domain drop
 
 ```python
-proxy = ReverseProxy(
+proxy = Relay(
     "http://auth-service:8000",
     upstream_prefix="/",
     rewrite_set_cookie_domain=lambda _: "",  # drop Domain
@@ -261,7 +261,7 @@ app = Lilya(
 ### 2. Proxy a versioned API under `/billing/**`:  `/api/v1/**` upstream
 
 ```python
-billing = ReverseProxy(
+billing = Relay(
     "http://billing-service.internal",
     upstream_prefix="/api/v1",
 )
@@ -279,7 +279,7 @@ app = Lilya(
 ```python
 secret = os.getenv("INTERNAL_SERVICE_TOKEN")
 
-proxy = ReverseProxy(
+proxy = Relay(
     "http://internal:9000",
     extra_request_headers={"X-Internal-Auth": secret},
     drop_request_headers=["x-forwarded-for"],  # example of additional drops
@@ -291,15 +291,15 @@ proxy = ReverseProxy(
 ### 4. Preserve the client `Host` header (rare, but occasionally required)
 
 ```python
-proxy = ReverseProxy("http://upstream:8000", preserve_host=True)
+proxy = Relay("http://upstream:8000", preserve_host=True)
 ```
 
 **Why**: Some upstreams compute logic based on `Host`. Most setups prefer `preserve_host=False`.
 
 ### 5. Follow upstream redirects (opt‑in)
 
 ```python
-proxy = ReverseProxy(
+proxy = Relay(
     "http://legacy:8080",
     follow_redirects=True,
 )
@@ -323,17 +323,19 @@ import httpx
 import pytest
 from lilya import Lilya
 from lilya.routing import Include
-from lilya.contrib.proxy.reverse import ReverseProxy
+from lilya.contrib.proxy.relay import Relay
+
 
 class DummyUpstream:
     async def __call__(self, scope, receive, send):
         if scope["type"] != "http":
-            await self._text(send, 404, "Not Found"); return
+            await self._text(send, 404, "Not Found");
+            return
 
         method, path = scope["method"], scope["path"]
         qs = scope.get("query_string", b"").decode("latin-1")
 
-        headers = {k.decode("latin-1"): v.decode("latin-1") for k,v in scope["headers"]}
+        headers = {k.decode("latin-1"): v.decode("latin-1") for k, v in scope["headers"]}
         body = b""
         while True:
             event = await receive()
@@ -370,7 +372,7 @@ class DummyUpstream:
                 "refresh=zzz; Path=/; Secure; SameSite=None",
             ]
             return await self._text(send, 200, "ok",
-                extra=[(b"set-cookie", c.encode("latin-1")) for c in cookies])
+                                    extra=[(b"set-cookie", c.encode("latin-1")) for c in cookies])
 
         if path.endswith("/large"):
             await send({"type": "http.response.start", "status": 200,
@@ -387,23 +389,25 @@ class DummyUpstream:
     async def _text(self, send, status, text, extra=None):
         headers = [(b"content-type", b"text/plain; charset=utf-8")]
         if extra: headers.extend(extra)
-        await send({"type":"http.response.start","status":status,"headers":headers})
-        await send({"type":"http.response.body","body":text.encode("utf-8")})
+        await send({"type": "http.response.start", "status": status, "headers": headers})
+        await send({"type": "http.response.body", "body": text.encode("utf-8")})
 
     async def _json(self, send, status, payload):
         data = json.dumps(payload).encode("utf-8")
-        await send({"type":"http.response.start","status":status,
-                    "headers":[(b"content-type", b"application/json")]})
-        await send({"type":"http.response.body","body":data})
+        await send({"type": "http.response.start", "status": status,
+                    "headers": [(b"content-type", b"application/json")]})
+        await send({"type": "http.response.body", "body": data})
+
 
 @pytest.fixture
 def upstream_app():
     return DummyUpstream()
 
+
 @pytest.fixture
 def proxy_and_app(upstream_app):
     upstream_transport = httpx.ASGITransport(app=upstream_app)
-    proxy = ReverseProxy(
+    proxy = Relay(
         "http://auth-service.local",
         upstream_prefix="/",
         preserve_host=False,
@@ -417,6 +421,7 @@ def proxy_and_app(upstream_app):
     )
     return proxy, app, upstream_app
 
+
 @pytest.fixture
 async def client(proxy_and_app):
     proxy, app, _ = proxy_and_app
@@ -563,13 +568,13 @@ async def test_ws_proxy(proxy_and_app):
 
     async with websockets.serve(echo, "127.0.0.1", 0) as server:
         uri = f"ws://{server.sockets[0].getsockname()[0]}:{server.sockets[0].getsockname()[1]}"
-        proxy = ReverseProxy(uri)
+        proxy = Relay(uri)
         ...
 ```
 
 ## Troubleshooting
 
-### ReverseProxy not started. Call startup() on app startup.
+### Relay not started. Call startup() on app startup.
 
 - **Cause**: App lifespan didn't run (common when using `httpx.ASGITransport(app=app)`).
 - **Fix**:
@@ -614,7 +619,7 @@ async def test_ws_proxy(proxy_and_app):
 import logging
 
 logger = logging.getLogger("proxy")
-proxy = ReverseProxy("http://upstream", logger=logger)
+proxy = Relay("http://upstream", logger=logger)
 ```
 
 Produces log lines like:

docs/en/docs/release-notes.md

@@ -9,7 +9,7 @@ hide:
 
 ### Added
 
-- [ReverseProxy](./contrib/proxy/reverse-proxy.md). This allows to create objects that are ASGI compatible and upstream services within your Lilya application.
+- [Relay](./contrib/proxy/relay.md). This allows to create objects that are ASGI compatible and upstream services within your Lilya application.
 - **WebSocket proxying**: Added full support for bidirectional WS proxying (text + binary frames).
 - **Retry & backoff**: Configurable retry logic with exponential backoff on retryable statuses/exceptions.
 - **Timeout mapping**: Upstream timeouts now map to `504 Gateway Timeout`.

docs/en/mkdocs.yml

@@ -136,7 +136,7 @@ nav:
     - contrib/files/send-file.md
     - contrib/files/jsonify.md
   - Proxy:
-    - contrib/proxy/reverse-proxy.md
+    - contrib/proxy/relay.md
   - contrib/mail.md
 - contributing.md
 - sponsorship.md

lilya/contrib/proxy/reverse.py lilya/contrib/proxy/relay.pylilya/contrib/proxy/reverse.py renamed to lilya/contrib/proxy/relay.py

@@ -15,9 +15,9 @@
     raise ImportError("httpx is required for lilya.contrib.proxy") from e
 
 
-class ReverseProxy:
+class Relay:
     """
-    ASGI reverse proxy middleware for Lilya.
+    ASGI relay middleware for Lilya.
 
     This component forwards incoming ASGI requests to an upstream server
     using `httpx.AsyncClient` and streams the response back to the caller.
@@ -38,7 +38,7 @@ class ReverseProxy:
     Typical usage
     -------------
     ```python
-    proxy = ReverseProxy("http://upstream.local", upstream_prefix="/api")
+    proxy = Relay("http://upstream.local", upstream_prefix="/api")
 
     app = Lilya(routes=[Include("/proxy", app=proxy)])
 
@@ -177,7 +177,7 @@ async def shutdown(self) -> None:
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         """
-        ASGI entrypoint for the reverse proxy.
+        ASGI entrypoint for the relay.
 
         This method is invoked by the ASGI server whenever a new
         connection is routed to the proxy. It inspects the `scope["type"]`
@@ -199,7 +199,7 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         Example:
             When mounted at `/auth`:
 
-                app = Lilya(routes=[Include("/auth", app=ReverseProxy(...))])
+                app = Lilya(routes=[Include("/auth", app=Relay(...))])
 
             The ASGI server will call `proxy(scope, receive, send)` whenever
             a request matches the `/auth` prefix.
@@ -213,7 +213,7 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         else:
             await self._send_text(send, 404, "Not Found")
 
-        assert self._client is not None, "ReverseProxy not started. Call startup() first."
+        assert self._client is not None, "Relay not started. Call startup() first."
 
     async def _handle_http(self, scope: Scope, receive: Receive, send: Send) -> None:
         """
@@ -239,7 +239,7 @@ async def _handle_http(self, scope: Scope, receive: Receive, send: Send) -> None
         Side effects:
             Emits structured logs for retries, timeouts, and errors.
         """
-        assert self._client is not None, "ReverseProxy not started. Call startup() first."
+        assert self._client is not None, "Relay not started. Call startup() first."
 
         method = scope["method"]
         upstream_url = self._build_upstream_url(scope)

tests/contrib/proxy/conftest.py

@@ -5,7 +5,7 @@
 import pytest
 
 from lilya.apps import Lilya
-from lilya.contrib.proxy.reverse import ReverseProxy
+from lilya.contrib.proxy.relay import Relay
 from lilya.routing import Include
 
 
@@ -144,7 +144,7 @@ def proxy_and_app(upstream_app):
     target_base = "http://auth-service.local"
 
     upstream_transport = httpx.ASGITransport(app=upstream_app)
-    proxy = ReverseProxy(
+    proxy = Relay(
         target_base_url=target_base,
         upstream_prefix="/",  # map /auth/<path> -> /<path> on upstream
         preserve_host=False,