# 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`)