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