75 lines
3.9 KiB
Markdown
75 lines
3.9 KiB
Markdown
# `launcher`: The Circles Orchestration Utility
|
|
|
|
The `launcher` is a command-line utility designed to spawn, manage, and monitor multiple, isolated "Circle" instances. It reads a simple JSON configuration file and, for each entry, launches a dedicated `worker` process and a corresponding WebSocket server.
|
|
|
|
This new architecture emphasizes isolation and robustness by running each Circle's worker as a separate OS process, identified by a unique public key.
|
|
|
|
## Core Architectural Concepts
|
|
|
|
- **Process-Based Isolation**: Instead of spawning workers as in-process tasks, the `launcher` spawns the `worker` binary as a separate OS process for each Circle. This ensures that a crash in one worker does not affect the launcher or other Circles.
|
|
- **Public Key as Unique Identifier**: Each Circle is identified by a unique `secp256k1` public key, which is generated on startup. This key is used to name Redis queues and identify the Circle across the system, replacing the old numeric `id`.
|
|
- **Task Submission via Redis**: The launcher uses the `rhai_client` library to submit initialization scripts as tasks to the worker's dedicated Redis queue. The worker listens on this queue, executes the script, and posts the result back to Redis.
|
|
- **Dynamic Configuration**: All Circle instances are defined in a `circles.json` file, specifying their name, port, and an optional initialization script.
|
|
|
|
## Features
|
|
|
|
- **Multi-Circle Management**: Run multiple, independent WebSocket servers and Rhai script workers from a single command.
|
|
- **Dynamic Key Generation**: Automatically generates a unique `secp256k1` keypair for each Circle on startup.
|
|
- **Configuration via JSON**: Define all your Circle instances in a `circles.json` file.
|
|
- **Graceful Shutdown**: Listens for `Ctrl+C` to initiate a graceful shutdown of all spawned servers and worker processes.
|
|
- **Status Display**: On startup, it displays a convenient table showing the name, unique public key, worker queue, and WebSocket URL for each running Circle.
|
|
- **Verbose Logging**: Supports multiple levels of verbosity (`-v`, `-vv`, `-vvv`) and a debug flag (`-d`) for detailed logging.
|
|
|
|
## How to Use
|
|
|
|
1. **Create `circles.json`**: Create a `circles.json` file. The launcher will look for it in the current directory by default. You can also provide a path as a command-line argument.
|
|
|
|
*The `id` field is now obsolete and has been removed.*
|
|
|
|
```json
|
|
[
|
|
{
|
|
"name": "OurWorld",
|
|
"port": 8090,
|
|
"script_path": "scripts/ourworld.rhai"
|
|
},
|
|
{
|
|
"name": "Dunia Cybercity",
|
|
"port": 8091,
|
|
"script_path": "scripts/dunia_cybercity.rhai"
|
|
}
|
|
]
|
|
```
|
|
|
|
2. **Run the Launcher**: Execute the following command from the root of the `circles` project:
|
|
|
|
```bash
|
|
# The launcher will find './circles.json' by default
|
|
cargo run --package launcher
|
|
|
|
# Or specify a path to the config file
|
|
cargo run --package launcher -- ./examples/test_circles.json
|
|
```
|
|
|
|
3. **Add Verbosity (Optional)**: For more detailed logs, use the verbosity flags:
|
|
|
|
```bash
|
|
# Info-level logging for Actix
|
|
cargo run --package launcher -- -v
|
|
|
|
# Debug-level logging for project crates
|
|
cargo run --package launcher -- -vv
|
|
|
|
# Full debug logging
|
|
cargo run --package launcher -- -vvv
|
|
```
|
|
|
|
## What It Does
|
|
|
|
For each entry in `circles.json`, the launcher will:
|
|
1. Generate a new `secp256k1` keypair. The public key becomes the Circle's unique identifier.
|
|
2. Spawn the `worker` binary as a child OS process, passing it the public key and Redis URL.
|
|
3. Initialize a `server_ws` instance on the specified port.
|
|
4. If a `script_path` is provided, it reads the script and submits it as a task to the worker's Redis queue. The `CALLER_PUBLIC_KEY` for this initial script is set to the Circle's own public key.
|
|
|
|
This makes it an ideal tool for setting up complex, multi-instance development environments or for deploying a full suite of Circle services with strong process isolation. |