circles/examples/ourworld

OurWorld Example

This directory contains a complete example demonstrating a simulated "OurWorld" network, consisting of multiple interconnected "circles" (nodes). Each circle runs its own WebSocket server and a Rhai script worker, all managed by a central launcher.

This example is designed to showcase:

1. Multi-Circle Configuration: How to define and configure multiple circles in a single circles.json file.
2. Programmatic Launching: How to use the launcher library to start, manage, and monitor these circles from within a Rust application.
3. Dynamic Key Generation: The launcher generates unique cryptographic keypairs for each circle upon startup.
4. Output Generation: How to use the --output functionality to get a JSON file containing the connection details (public keys, WebSocket URLs, etc.) for each running circle.
5. Graceful Shutdown: How the launcher handles a Ctrl+C signal to shut down all running circles cleanly.

Directory Contents

• circles.json: The main configuration file that defines the 7 circles in the OurWorld network, including their names, ports, and associated Rhai scripts.
• scripts/: This directory contains the individual Rhai scripts that define the behavior of each circle.
• ourworld_output.json (Generated): This file is created after running the example and contains the runtime details of each circle.

How to Run the Example

There are two ways to run this example, each demonstrating a different way to use the launcher.

1. As a Root Example (Recommended)

This method runs the launcher programmatically from the root of the workspace and is the simplest way to see the system in action. It uses the examples/ourworld.rs file.

# From the root of the workspace
cargo run --example ourworld

2. As a Crate-Level Example

This method runs a similar launcher, but as an example within the launcher crate itself. It uses the src/launcher/examples/ourworld/main.rs file. This is useful for testing the launcher in a more isolated context.

# Navigate to the launcher's crate directory
cd src/launcher

# Run the 'ourworld' example using cargo
cargo run --example ourworld

3. Using the Launcher Binary

This method uses the main launcher binary to run the configuration, which is useful for testing the command-line interface.

# From the root of the workspace
cargo run -p launcher -- --config examples/ourworld/circles.json --output examples/ourworld/ourworld_output.json

What to Expect

When you run the example, you will see log output indicating that the launcher is starting up, followed by a table summarizing the running circles:

+-----------------+------------------------------------------------------------------+------------------------------------------+-----------------------+
| Name            | Public Key                                                       | Worker Queue                             | WS URL                |
+=================+==================================================================+==========================================+=======================+
| OurWorld        | 02...                                                            | rhai_tasks:02...                          | ws://127.0.0.1:9000/ws|
+-----------------+------------------------------------------------------------------+------------------------------------------+-----------------------+
| Dunia Cybercity | 03...                                                            | rhai_tasks:03...                          | ws://127.0.0.1:9001/ws|
+-----------------+------------------------------------------------------------------+------------------------------------------+-----------------------+
| ... (and so on for all 7 circles)                                                                                                                     |
+-----------------+------------------------------------------------------------------+------------------------------------------+-----------------------+

The launcher will then wait for you to press Ctrl+C to initiate a graceful shutdown of all services.