leaf/examples

Framework Examples

This directory contains examples demonstrating how to use the Hero Framework components.

WebSocket Manager Demo

The ws_manager_demo.rs example demonstrates the complete usage of the WsManager for connecting to multiple WebSocket servers, handling authentication, and executing scripts.

Prerequisites

1. Start Hero WebSocket Server(s):

   # Terminal 1 - Start first server
   cd ../hero/interfaces/websocket/server
   cargo run --example circle_auth_demo -- --port 3030
   
   # Terminal 2 - Start second server (optional)
   cargo run --example circle_auth_demo -- --port 3031
   

2. Run the Example:

   # From the framework directory
   cargo run --example ws_manager_demo
   

What the Demo Shows

The example demonstrates:

• Multi-server Connection: Connecting to multiple WebSocket servers simultaneously
• Authentication: Using private keys for server authentication
• Script Execution: Running JavaScript/Rhai scripts on connected servers
• Connection Management: Connecting, disconnecting, and reconnecting to specific servers
• Status Monitoring: Checking connection and authentication status
• Runtime Management: Adding new connections dynamically
• Error Handling: Graceful handling of connection and execution errors

Key Code Patterns

Creating and Connecting

let manager = WsManager::builder()
    .private_key("your_private_key_hex".to_string())
    .add_server_url("ws://localhost:3030".to_string())
    .add_server_url("ws://localhost:3031".to_string())
    .build();

manager.connect().await?;

Executing Scripts on Specific Servers

if let Some(result) = manager.with_client("ws://localhost:3030", |client| {
    client.play("console.log('Hello World!');".to_string())
}).await {
    match result {
        Ok(output) => println!("Script output: {}", output),
        Err(e) => eprintln!("Script error: {}", e),
    }
}

Working with All Connected Clients

manager.with_all_clients(|clients| {
    for (url, client) in clients {
        if client.is_connected() {
            // Use the client for operations
            println!("Connected to: {}", url);
        }
    }
});

Connection Management

// Disconnect from specific server
manager.disconnect_from_server("ws://localhost:3031").await?;

// Reconnect
manager.connect_to_server("ws://localhost:3031").await?;

// Add new connection at runtime
manager.add_connection(
    "ws://localhost:3032".to_string(),
    Some(private_key.to_string())
);

Expected Output

When running the demo with servers available, you should see output like:

🚀 Starting WebSocket Manager Demo
📡 Connecting to WebSocket servers...
✅ Successfully initiated connections
🔍 Checking connection status...
  ws://localhost:3030 -> Connected
  ws://localhost:3031 -> Connected
🎯 Executing script on specific server...
  📤 Sending script to ws://localhost:3030
  ✅ Script output: Script executed successfully
🌐 Executing operations on all connected clients...
  📤 Pinging ws://localhost:3030
  📤 Pinging ws://localhost:3031
  ✅ ws://localhost:3030 responded: pong from 2024-01-15T10:30:45.123Z
  ✅ ws://localhost:3031 responded: pong from 2024-01-15T10:30:45.124Z
🎉 WebSocket Manager Demo completed!

Website Example

The website directory contains a complete Yew-based web application demonstrating the framework's browser capabilities, including:

• WebSocket client management in WASM
• Browser-based authentication
• Interactive script execution
• Real-time connection monitoring

See website/README.md for details on running the web application.

Tips for Development

1. Logging: Set RUST_LOG=debug for detailed connection logs
2. Testing: Use multiple terminal windows to run servers on different ports
3. Authentication: In production, load private keys from secure storage, not hardcoded strings
4. Error Handling: The examples show basic error handling patterns - extend as needed for production use

Common Issues

• Connection Refused: Make sure the WebSocket servers are running before starting the demo
• Authentication Failures: Verify that the private key format is correct (64-character hex string)
• Port Conflicts: Use different ports if the default ones (3030, 3031) are already in use