81 lines
3.9 KiB
Markdown
81 lines
3.9 KiB
Markdown
# 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](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](server/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`.
|
||
|
||
## 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
|
||
``` |