VSTP Documentation

⚡ Quick Tip

VSTP v0.2.1 introduces a new simplified API that makes it much easier to build networked applications. This guide focuses on the new API.

Installation

Add VSTP to your project by adding the following to your Cargo.toml:

[dependencies]
vstp = "0.2.1"
tokio = { version = "1.0", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }

Basic Usage

VSTP v0.2.1 makes it incredibly easy to send and receive typed messages. Here's a simple example:

use serde::{Serialize, Deserialize};
use vstp::easy::{VstpClient, VstpServer};

#[derive(Serialize, Deserialize)]
struct Message {
    content: String,
}

// Server
let server = VstpServer::bind_tcp("127.0.0.1:8080").await?;
server.serve(|msg: Message| async move {
    println!("Got message: {}", msg.content);
    Ok(msg) // Echo the message back
}).await?;

// Client
let client = VstpClient::connect_tcp("127.0.0.1:8080").await?;
client.send(Message { content: "Hello!".to_string() }).await?;
let response: Message = client.receive().await?;

💡 Key Features

Automatic serialization/deserialization
Type-safe message passing
Built-in error handling
Timeouts and retries

TCP Example: Chat Server

Here's a complete example of a chat server using TCP with automatic message routing:

use serde::{Serialize, Deserialize};
use vstp::easy::{VstpClient, VstpServer};

#[derive(Serialize, Deserialize)]
struct ChatMessage {
    from: String,
    content: String,
}

// Chat Server
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = VstpServer::bind_tcp("127.0.0.1:8080").await?;
    println!("Chat server running on 127.0.0.1:8080");
    
    server.serve(|msg: ChatMessage| async move {
        println!("{}: {}", msg.from, msg.content);
        Ok(msg) // Broadcast message back to all clients
    }).await?;

    Ok(())
}

// Chat Client
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = VstpClient::connect_tcp("127.0.0.1:8080").await?;
    
    // Send a message
    let msg = ChatMessage {
        from: "Alice".to_string(),
        content: "Hello everyone!".to_string(),
    };
    client.send(msg).await?;
    
    // Receive messages
    while let Ok(msg) = client.receive::<ChatMessage>().await {
        println!("{}: {}", msg.from, msg.content);
    }

    Ok(())
}

UDP Example: Real-time Data

For real-time applications, you can use UDP mode. The API remains the same:

use serde::{Serialize, Deserialize};
use vstp::easy::{VstpClient, VstpServer};

#[derive(Serialize, Deserialize)]
struct SensorData {
    sensor_id: String,
    temperature: f32,
    humidity: f32,
}

// UDP Server
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = VstpServer::bind_udp("127.0.0.1:8080").await?;
    
    server.serve(|data: SensorData| async move {
        println!("Sensor {}: {}°C, {}%", data.sensor_id, data.temperature, data.humidity);
        Ok(data)
    }).await?;

    Ok(())
}

// UDP Client
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = VstpClient::connect_udp("127.0.0.1:8080").await?;
    
    // Send data periodically
    loop {
        let data = SensorData {
            sensor_id: "sensor1".to_string(),
            temperature: 25.5,
            humidity: 60.0,
        };
        client.send(data).await?;
        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
    }
}