53 lines
3.7 KiB
Markdown
53 lines
3.7 KiB
Markdown
# Circle Server WebSocket (`server_ws`)
|
|
|
|
## Overview
|
|
|
|
The `server_ws` component is an Actix-based WebSocket server designed to handle client connections and execute Rhai scripts. It acts as a bridge between WebSocket clients and a Rhai scripting engine, facilitating remote script execution and result retrieval.
|
|
|
|
## Key Features
|
|
|
|
* **WebSocket Communication:** Establishes and manages WebSocket connections with clients.
|
|
* **Rhai Script Execution:** Receives Rhai scripts from clients, submits them for execution via `rhai_client`, and returns the results.
|
|
* **Timeout Management:** Implements timeouts for Rhai script execution to prevent indefinite blocking, returning specific error codes on timeout.
|
|
* **Asynchronous Processing:** Leverages Actix actors for concurrent handling of multiple client connections and script executions.
|
|
|
|
## Core Components
|
|
|
|
* **`CircleWs` Actor:** The primary Actix actor responsible for handling individual WebSocket sessions. It manages the lifecycle of a client connection, processes incoming messages (Rhai scripts), and sends back results or errors.
|
|
* **`rhai_client` Integration:** Utilizes the `rhai_client` crate to submit scripts to a shared Rhai processing service (likely Redis-backed for task queuing and result storage) and await their completion.
|
|
|
|
## Dependencies
|
|
|
|
* `actix`: Actor framework for building concurrent applications.
|
|
* `actix-web-actors`: WebSocket support for Actix.
|
|
* `rhai_client`: Client library for interacting with the Rhai scripting service.
|
|
* `serde_json`: For serializing and deserializing JSON messages exchanged over WebSockets.
|
|
* `uuid`: For generating unique task identifiers.
|
|
|
|
## Workflow
|
|
|
|
1. A client establishes a WebSocket connection to the `/ws/` endpoint.
|
|
2. The server upgrades the connection and spawns a `CircleWs` actor instance for that session.
|
|
3. The client sends a JSON-RPC formatted message containing the Rhai script to be executed.
|
|
4. The `CircleWs` actor parses the message and uses `rhai_client::RhaiClient::submit_script_and_await_result` to send the script for execution. This method handles the interaction with the underlying task queue (e.g., Redis) and waits for the script's outcome.
|
|
5. The `rhai_client` will return the script's result or an error (e.g., timeout, script error).
|
|
6. `CircleWs` formats the result/error into a JSON-RPC response and sends it back to the client over the WebSocket.
|
|
|
|
## Configuration
|
|
|
|
* **`REDIS_URL`**: The `rhai_client` component (and thus `server_ws` indirectly) relies on a Redis instance. The connection URL for this Redis instance is typically configured via an environment variable or a constant that `rhai_client` uses.
|
|
* **Timeout Durations**:
|
|
* `TASK_TIMEOUT_DURATION` (e.g., 30 seconds): The maximum time the server will wait for a Rhai script to complete execution.
|
|
* `TASK_POLL_INTERVAL_DURATION` (e.g., 200 milliseconds): The interval at which the `rhai_client` polls for task completion (this is an internal detail of `rhai_client` but relevant to understanding its behavior).
|
|
|
|
## Error Handling
|
|
|
|
The server implements specific JSON-RPC error responses for various scenarios:
|
|
* **Script Execution Timeout:** If a script exceeds `TASK_TIMEOUT_DURATION`, a specific error (e.g., code -32002) is returned.
|
|
* **Other `RhaiClientError`s:** Other errors originating from `rhai_client` (e.g., issues with the Redis connection, script compilation errors detected by the remote Rhai engine) are also translated into appropriate JSON-RPC error responses.
|
|
* **Message Parsing Errors:** Invalid incoming messages will result in error responses.
|
|
|
|
## How to Run
|
|
|
|
(Instructions on how to build and run the server would typically go here, e.g., `cargo run --bin circle_server_ws`)
|