feat: add callback api to WebSocketProxy

CHANGELOG.md

@@ -22,6 +22,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- [#41](https://github.com/WSH032/fastapi-proxy-lib/pull/41) - feat: add `callback` api to `WebSocketProxy`. Thanks [@WSH032](https://github.com/WSH032) and [@IvesAwadi](https://github.com/IvesAwadi)!
+
 ### Changed
 
 - [#30](https://github.com/WSH032/fastapi-proxy-lib/pull/30) - fix(internal): use `websocket` in favor of `websocket_route`. Thanks [@WSH032](https://github.com/WSH032)!

README.md

@@ -32,8 +32,9 @@ Source Code: <https://github.com/WSH032/fastapi-proxy-lib/>
 - [x] Support both **reverse** proxy and **forward** proxy.
 - [x] **Transparently** and **losslessly** handle all proxy requests,
     Including **HTTP headers**, **cookies**, **query parameters**, **body**, etc.
+- [X] WebSocket proxy **callback**.
 - [x] Asynchronous streaming transfer, support **file proxy**.
-- [x] `fastapi-proxy-lib` value [privacy security](https://wsh032.github.io/fastapi-proxy-lib/Usage/Security/).
+- [x] `fastapi-proxy-lib` value [**privacy security**](https://wsh032.github.io/fastapi-proxy-lib/Usage/Security/).
 
 ### other features
 

docs/Usage/Advanced.md

@@ -4,7 +4,8 @@ For the following scenarios, you might prefer [fastapi_proxy_lib.core][]:
 
 - When you need to use proxies with **only** `Starlette` dependencies (without `FastAPI`).
 - When you need more fine-grained control over parameters and lifespan event.
-- When you need to further process the input and output before and after the proxy (similar to middleware).
+- When you need to further process the input and output before and after the http proxy (similar to `middleware`).
+- When you need `callback` to modify the websocket proxy messages.
 
 We will demonstrate with `FastAPI`,
 but you can completely switch to the `Starlette` approach,
@@ -19,13 +20,13 @@ Also (without annotations):
 - [`ForwardHttpProxy#examples`][fastapi_proxy_lib.core.http.ForwardHttpProxy--examples]
 - [`ReverseWebSocketProxy#examples`][fastapi_proxy_lib.core.websocket.ReverseWebSocketProxy--examples]
 
-## Modify request
+## Modify HTTP request
 
 In some cases, you may want to make final modifications before sending a request, such as performing behind-the-scenes authentication by modifying the headers of request.
 
 `httpx` provides comprehensive authentication support, and `fastapi-proxy-lib` offers first-class support for `httpx`.
 
-See <https://www.python-httpx.org/advanced/#customizing-authentication>
+See <https://www.python-httpx.org/advanced/authentication/>
 
 You can refer following example to implement a simple authentication:
 
@@ -35,7 +36,7 @@ from fastapi_proxy_lib.fastapi.app import reverse_http_app
 
 
 class MyCustomAuth(httpx.Auth):
-    # ref: https://www.python-httpx.org/advanced/#customizing-authentication
+    # ref: https://www.python-httpx.org/advanced/authentication/
 
     def __init__(self, token: str):
         self.token = token
@@ -55,7 +56,7 @@ app = reverse_http_app(
 
 visit `/headers` to see the result which contains `"X-Authentication": "bearer_token"` header.
 
-## Modify response
+## Modify HTTP response
 
 In some cases, you may want to make final modifications before return the response to the client, such as transcoding video response streams.
 
@@ -118,3 +119,19 @@ async def _(request: Request, path: str = ""):
 ```
 
 visit `/`, you will notice that the response body is printed to the console.
+
+## Modify WebSocket message
+
+In some cases, you might want to modify the content of the messages that the WebSocket proxy receives and sends to the client and target server.
+
+In version `0.2.0` of `fastapi-proxy-lib`, we introduced a [`callback API`][fastapi_proxy_lib.core.websocket.ReverseWebSocketProxy.proxy] for `WebSocketProxy` to allow you to do this.
+
+See example: [ReverseWebSocketProxy#with-callback][fastapi_proxy_lib.core.websocket.ReverseWebSocketProxy--with-callback]
+
+Also:
+
+- RFC: [#40](https://github.com/WSH032/fastapi-proxy-lib/issues/40)
+- PR: [#41](https://github.com/WSH032/fastapi-proxy-lib/pull/41)
+
+!!!example
+    The current implementation still has some defects. Read the [callback-implementation][fastapi_proxy_lib.core.websocket.BaseWebSocketProxy.send_request_to_target--callback-implementation] section, or you might accidentally shoot yourself in the foot.

docs/Usage/FastAPI-Helper.md

@@ -10,7 +10,7 @@ There are two helper modules to get FastAPI `app`/`router` for proxy convenientl
 
 ## app
 
-use `fastapi_proxy_lib.fastapi.app` is very convenient and out of the box, there are three helper functions:
+`fastapi_proxy_lib.fastapi.app` is very convenient and out of the box, there are three helper functions:
 
 - [forward_http_app][fastapi_proxy_lib.fastapi.app.forward_http_app]
 - [reverse_http_app][fastapi_proxy_lib.fastapi.app.reverse_http_app]
@@ -46,3 +46,9 @@ For the following scenarios, you might prefer [fastapi_proxy_lib.fastapi.router]
 - When you need to [mount the proxy on a route of larger app](https://fastapi.tiangolo.com/tutorial/bigger-applications/).
 
 **^^[Please refer to the documentation of `RouterHelper` for more information :material-file-document: ][fastapi_proxy_lib.fastapi.router.RouterHelper--examples]^^**.
+
+---
+
+## More
+
+**The `Helper Module` might not meet your further customization needs. Please refer to the [Advanced](Advanced.md) section, which is the core of `fastapi-proxy-lib`, for more personalization options.**

mkdocs.yml

@@ -108,6 +108,8 @@ plugins:
           import:
             - https://frankie567.github.io/httpx-ws/objects.inv
             - https://fastapi.tiangolo.com/objects.inv
+            - https://anyio.readthedocs.io/en/stable/objects.inv
+            - https://docs.python.org/3/objects.inv
           options:
             docstring_style: google
           paths: [src]

pyproject.toml

@@ -52,7 +52,8 @@ dependencies = [
     "httpx",
     "httpx-ws >= 0.4.2",
     "starlette",
-    "typing_extensions >=4.5.0",
+    "typing_extensions >= 4.12",
+    "anyio >= 4",
 ]
 
 [project.optional-dependencies]
@@ -91,13 +92,12 @@ dependencies = [
     #   NOTE: 👆
 
     # lint-check
-    "pyright == 1.1.356", # pyright must be installed in the runtime environment
+    "pyright == 1.1.372", # pyright must be installed in the runtime environment
     # test
     "pytest == 7.*",
     "pytest-cov ==  4.*",
     "uvicorn[standard] < 1.0.0", # TODO: Once it releases version 1.0.0, we will remove this restriction.
     "httpx[http2]",              # we don't set version here, instead set it in `[project].dependencies`.
-    "anyio",                     # we don't set version here, because fastapi has a dependency on it
     "asgi-lifespan==2.*",
     "pytest-timeout==2.*",
 ]

src/fastapi_proxy_lib/core/http.py

@@ -222,7 +222,7 @@ class BaseHttpProxy(BaseProxyModel):
     """
 
     @override
-    async def send_request_to_target(  # pyright: ignore [reportIncompatibleMethodOverride]
+    async def send_request_to_target(
         self, *, request: StarletteRequest, target_url: httpx.URL
     ) -> StarletteResponse:
         """Change request headers and send request to target url.
@@ -318,6 +318,8 @@ class ReverseHttpProxy(BaseHttpProxy):
 
     # # Examples
 
+    ## Basic usage
+
     ```python
     from contextlib import asynccontextmanager
     from typing import AsyncIterator
@@ -341,7 +343,7 @@ async def close_proxy_event(_: FastAPI) -> AsyncIterator[None]:  # (1)!
     async def _(request: Request, path: str = ""):
         return await proxy.proxy(request=request, path=path)  # (3)!
 
-    # Then run shell: `uvicorn <your.py>:app --host http://127.0.0.1:8000 --port 8000`
+    # Then run shell: `uvicorn <your_py>:app --host 127.0.0.1 --port 8000`
     # visit the app: `http://127.0.0.1:8000/`
     # you will get the response from `http://www.example.com/`
     ```
@@ -452,6 +454,8 @@ class ForwardHttpProxy(BaseHttpProxy):
 
     # # Examples
 
+    ## Basic usage
+
     ```python
     from contextlib import asynccontextmanager
     from typing import AsyncIterator
@@ -476,7 +480,7 @@ async def close_proxy_event(_: FastAPI) -> AsyncIterator[None]:
     async def _(request: Request, path: str = ""):
         return await proxy.proxy(request=request, path=path)
 
-    # Then run shell: `uvicorn <your.py>:app --host http://127.0.0.1:8000 --port 8000`
+    # Then run shell: `uvicorn <your_py>:app --host 127.0.0.1 --port 8000`
     # visit the app: `http://127.0.0.1:8000/http://www.example.com`
     # you will get the response from `http://www.example.com`
     ```