74 lines
3.3 KiB
Markdown
74 lines
3.3 KiB
Markdown
# Circles Project
|
|
|
|
Welcome to the `circles` project, a full-stack system featuring a WebSocket server, a cross-platform client, and a launcher to manage multiple instances. This project is designed for executing Rhai scripts in isolated environments, with an optional layer of `secp256k1` cryptographic authentication.
|
|
|
|
## Overview
|
|
|
|
The `circles` project provides two core library crates and a utility application:
|
|
|
|
- **`server_ws`**: The core WebSocket server library, built with `Actix`. It handles client connections, processes JSON-RPC messages, and executes Rhai scripts.
|
|
- **`client_ws`**: The core cross-platform WebSocket client library, compatible with both native Rust and WebAssembly (WASM) environments.
|
|
- **`launcher`**: A convenient command-line utility that uses the `server_ws` library to read a `circles.json` configuration file and spawn multiple, isolated "Circle" instances.
|
|
- **`openrpc.json`**: An OpenRPC specification that formally defines the JSON-RPC 2.0 API used for client-server communication.
|
|
|
|
## Architecture
|
|
|
|
The system is designed around a client-server model, with `client_ws` and `server_ws` as the core components. The `launcher` is provided as a utility for orchestrating multiple server instances, each configured as an isolated "Circle" environment.
|
|
|
|
Clients connect to a `server_ws` instance via WebSocket and interact with it using the JSON-RPC protocol. The server can be configured to require authentication, in which case the client must complete a signature-based challenge-response flow over the WebSocket connection before it can execute protected methods like `play`.
|
|
|
|
For a more detailed explanation of the system's design, please see the [ARCHITECTURE.md](ARCHITECTURE.md) file.
|
|
|
|
## Getting Started
|
|
|
|
To run the system, you will need to use the `launcher`.
|
|
|
|
1. **Configure Your Circles**: Create a `circles.json` file at the root of the project to define the instances you want to run. Each object in the top-level array defines a "Circle" with a unique `id`, `port`, and associated database and script paths.
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id": "circle-1",
|
|
"port": 9001,
|
|
"db_path": "/tmp/circle-1.db",
|
|
"rhai_path": "/path/to/your/scripts"
|
|
}
|
|
]
|
|
```
|
|
|
|
2. **Run the Launcher**:
|
|
```bash
|
|
cargo run --package launcher
|
|
```
|
|
|
|
The launcher will start a WebSocket server for each configured circle on its specified port.
|
|
|
|
## API
|
|
|
|
The client-server communication is handled via JSON-RPC 2.0 over WebSocket. The available methods are:
|
|
|
|
- `play`: Executes a Rhai script.
|
|
- `authenticate`: Authenticates the client.
|
|
|
|
For a complete definition of the API, including request parameters and response objects, please refer to the [openrpc.json](openrpc.json) file.
|
|
|
|
## Crates
|
|
|
|
- **[server_ws](server_ws/README.md)**: Detailed documentation for the server library.
|
|
- **[client_ws](client_ws/README.md)**: Detailed documentation for the client library.
|
|
- **[launcher](launcher/README.md)**: Detailed documentation for the launcher utility.
|
|
- **[app](src/app/README.md)**: A Yew frontend application that uses the `client_ws` to interact with the `server_ws`.
|
|
|
|
## Running the App
|
|
|
|
To run the `circles-app`, you'll need to have `trunk` installed. If you don't have it, you can install it with:
|
|
|
|
```bash
|
|
cargo install trunk wasm-bindgen-cli
|
|
```
|
|
|
|
Once `trunk` is installed, you can serve the app with:
|
|
|
|
```bash
|
|
cd src/app && trunk serve
|
|
``` |