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 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.

   [
     {
       "id": "circle-1",
       "port": 9001,
       "db_path": "/tmp/circle-1.db",
       "rhai_path": "/path/to/your/scripts"
     }
   ]
   

2. Run the Launcher:

   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 file.

Crates

• server_ws: Detailed documentation for the server library.
• client_ws: Detailed documentation for the client library.
• launcher: Detailed documentation for the launcher utility.
• app: 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:

cargo install trunk wasm-bindgen-cli

Once trunk is installed, you can serve the app with:

cd src/app && trunk serve