Circles

Welcome to circles, a system designed to accomodate a peer-centric backend infrastructure for

This system is a distributed, context-aware application layer runtime where peers trigger script executions in each other’s logical environments. Execution always occurs within the target peer’s context, with the caller peer’s identity provided for authorization and provenance. Workers — whether serving single or multiple peers — enforce context isolation via namespaced filesystems and runtime boundaries. The system enables cross-peer logic to run safely and scalably without assuming global state or centralized coordination.

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

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