From 83c30439b63e22d5d4dad56b5759aeeb987c4e18 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mose=20M=C3=BCller?= Date: Tue, 20 May 2025 20:25:53 +0200 Subject: [PATCH] docs: adds SOCKS5 proxy section --- docs/user-guide/advanced/SOCKS-Proxy.md | 48 ++++++++++++++++++++ docs/user-guide/interaction/Python-Client.md | 16 +++++-- mkdocs.yml | 1 + 3 files changed, 61 insertions(+), 4 deletions(-) create mode 100644 docs/user-guide/advanced/SOCKS-Proxy.md diff --git a/docs/user-guide/advanced/SOCKS-Proxy.md b/docs/user-guide/advanced/SOCKS-Proxy.md new file mode 100644 index 0000000..fd1eb2b --- /dev/null +++ b/docs/user-guide/advanced/SOCKS-Proxy.md @@ -0,0 +1,48 @@ +# Connecting Through a SOCKS5 Proxy + +If your target service is only reachable via an SSH gateway or resides behind a +firewall, you can route your [`pydase.Client`][pydase.Client] connection through a local +SOCKS5 proxy. This is particularly useful in network environments where direct access to +the service is not possible. + +## Setting Up a SOCKS5 Proxy + +You can create a local [SOCKS5 proxy](https://en.wikipedia.org/wiki/SOCKS) using SSH's +`-D` option: + +```bash +ssh -D 2222 user@gateway.example.com +``` + +This command sets up a SOCKS5 proxy on `localhost:2222`, securely forwarding traffic +over the SSH connection. + +## Using the Proxy in Your Python Client + +Once the proxy is running, configure the [`pydase.Client`][pydase.Client] to route +traffic through it using the `proxy_url` parameter: + +```python +import pydase + +client = pydase.Client( + url="ws://target-service:8001", + proxy_url="socks5://localhost:2222" +).proxy +``` + +* You can also use this setup with `wss://` URLs for encrypted WebSocket connections. + +## Installing Required Dependencies + +To use this feature, you must install the optional `socks` dependency group, which +includes [`aiohttp_socks`](https://pypi.org/project/aiohttp-socks/): + +- `poetry` + ```bash + poetry add "pydase[socks]" + ``` +- `pip` + ```bash + pip install "pydase[socks]" + ``` diff --git a/docs/user-guide/interaction/Python-Client.md b/docs/user-guide/interaction/Python-Client.md index 34e575f..2ac5190 100644 --- a/docs/user-guide/interaction/Python-Client.md +++ b/docs/user-guide/interaction/Python-Client.md @@ -1,6 +1,6 @@ # Python RPC Client -The [`pydase.Client`][pydase.Client] allows you to connect to a remote `pydase` service using socket.io, facilitating interaction with the service as though it were running locally. +The [`pydase.Client`][pydase.Client] allows you to connect to a remote `pydase` service using Socket.IO, facilitating interaction with the service as though it were running locally. ## Basic Usage @@ -9,6 +9,7 @@ import pydase # Replace and with the appropriate values for your service client_proxy = pydase.Client(url="ws://:").proxy + # For SSL-encrypted services, use the wss protocol # client_proxy = pydase.Client(url="wss://your-domain.ch").proxy @@ -22,6 +23,12 @@ The proxy acts as a local representation of the remote service, enabling intuiti The proxy class automatically synchronizes with the server's attributes and methods, keeping itself up-to-date with any changes. This dynamic synchronization essentially mirrors the server's API, making it feel like you're working with a local object. +### Accessing Services Behind Firewalls or SSH Gateways + +If your service is only reachable through a private network or SSH gateway, you can route your connection through a local SOCKS5 proxy using the `proxy_url` parameter. + +See [Connecting Through a SOCKS5 Proxy](../advanced/SOCKS-Proxy.md) for details. + ## Context Manager Support You can also use the client within a context manager, which automatically handles connection management (i.e., opening and closing the connection): @@ -53,6 +60,7 @@ class MyService(pydase.DataService): block_until_connected=False, client_id="my_pydase_client_id", ).proxy + # For SSL-encrypted services, use the wss protocol # proxy = pydase.Client( # url="wss://your-domain.ch", @@ -68,12 +76,12 @@ if __name__ == "__main__": In this example: - The `MyService` class has a `proxy` attribute that connects to a `pydase` service at `:`. -- By setting `block_until_connected=False`, the service can start without waiting for the connection to succeed, which is particularly useful in distributed systems where services may initialize in any order. -- By setting `client_id`, the server will provide more accurate logs of the connecting client. If set, this ID is sent as `X-Client-Id` header in the HTTP(s) request. +- By setting `block_until_connected=False`, the service can start without waiting for the connection to succeed. +- By setting `client_id`, the server will log a descriptive identifier for this client via the `X-Client-Id` HTTP header. ## Custom `socketio.AsyncClient` Connection Parameters -You can also configure advanced connection options by passing additional arguments to the underlying [`AsyncClient`][socketio.AsyncClient] via `sio_client_kwargs`. This allows you to fine-tune reconnection behaviour, delays, and other settings: +You can configure advanced connection options by passing arguments to the underlying [`AsyncClient`][socketio.AsyncClient] via `sio_client_kwargs`. For example: ```python client = pydase.Client( diff --git a/mkdocs.yml b/mkdocs.yml index 45fc799..a3d6496 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,6 +19,7 @@ nav: - Logging in pydase: user-guide/Logging.md - Advanced: - Deploying behind a Reverse Proxy: user-guide/advanced/Reverse-Proxy.md + - Connecting through a SOCKS Proxy: user-guide/advanced/SOCKS-Proxy.md - Developer Guide: - Developer Guide: dev-guide/README.md - API Reference: dev-guide/api.md