circles/server_ws/README.md

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 RhaiClientErrors: 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)