circles/src/launcher/README.md

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.

   [
     {
       "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:

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

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