Turn Server SDK

A Rust client SDK for interacting with the turn-server gRPC API exposed by the turn-rs project. This crate provides both client and server utilities for TURN server integration.

Features

• TurnService Client: Query server information, session details, and manage TURN sessions
• TurnHooksServer: Implement custom authentication and event handling for TURN server hooks
• Password Generation: Generate STUN/TURN authentication passwords using MD5 or SHA256

Installation

Add this to your Cargo.toml:

[dependencies]
turn-server-sdk = "0.1.0-beta.1"  # When published
turn-server-protos = "0.1.0-beta.1"

Client Usage

The TurnService client allows you to interact with a running TURN server's gRPC API:

use turn_server_sdk::{TurnService， tonic::transport::Channel};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the TURN server gRPC endpoint
    let channel = Channel::from_static("http://127.0.0.1:3000")
        .connect()
        .await?;

    // Create a client
    let mut client = TurnService::new(channel);

    // Get server information
    let info = client.get_info().await?;
    println!("Server version: {}", info.version);

    // Query a session by ID
    let session = client.get_session("session-id".to_string()).await?;
    println!("Session username: {}", session.username);

    // Get session statistics
    let stats = client.get_session_statistics("session-id".to_string()).await?;
    println!("Bytes sent: {}", stats.send_bytes);

    // Destroy a session
    client.destroy_session("session-id".to_string()).await?;

    Ok(())
}

Server Usage (Hooks Implementation)

Implement the TurnHooksServer trait to provide custom authentication and handle TURN events:

use turn_server_sdk::{
    Credential, TurnHooksServer,
    protos::PasswordAlgorithm,
    tonic::{Status, transport::Server},
};

struct MyHooksServer;

#[turn_server_sdk::tonic::async_trait]
impl TurnHooksServer for MyHooksServer {
    async fn get_password(
        &self,
        realm: &str,
        username: &str,
        algorithm: PasswordAlgorithm,
    ) -> Result<Credential, Status> {
        // Implement your authentication logic here
        // For example, look up the user in a database
        Ok(Credential {
            password: "user-password".to_string(),
            realm: realm.to_string(),
        })
    }

    async fn on_allocated(&self, id: String, username: String, port: u16) {
        println!("Session allocated: id={}, username={}, port={}", id, username, port);
        // Handle allocation event (e.g., log to database, update metrics)
    }

    async fn on_channel_bind(&self, id: String, username: String, channel: u16) {
        println!("Channel bound: id={}, username={}, channel={}", id, username, channel);
    }

    async fn on_create_permission(&self, id: String, username: String, ports: Vec<u16>) {
        println!("Permission created: id={}, username={}, ports={:?}", id, username, ports);
    }

    async fn on_refresh(&self, id: String, username: String, lifetime: u32) {
        println!("Session refreshed: id={}, username={}, lifetime={}", id, username, lifetime);
    }

    async fn on_destroy(&self, id: String, username: String) {
        println!("Session destroyed: id={}, username={}", id, username);
        // Handle session destruction (e.g., cleanup resources)
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Start the hooks server
    let mut server = Server::builder();
    let hooks = MyHooksServer;

    hooks.start_with_server(
        &mut server,
        "127.0.0.1:3000".parse()?,
    ).await?;

    Ok(())
}

Password Generation

Generate STUN/TURN authentication passwords for long-term credentials:

use turn_server_sdk::{generate_password, protos::PasswordAlgorithm};

// Generate MD5 password (RFC 5389)
let md5_password = generate_password(
    "username",
    "password",
    "realm",
    PasswordAlgorithm::Md5,
);

// Generate SHA256 password (RFC 8489)
let sha256_password = generate_password(
    "username",
    "password",
    "realm",
    PasswordAlgorithm::Sha256,
);

// Access the password bytes
match md5_password {
    turn_server_sdk::Password::Md5(bytes) => {
        println!("MD5 password: {:?}", bytes);
    }
    turn_server_sdk::Password::Sha256(bytes) => {
        println!("SHA256 password: {:?}", bytes);
    }
}

Event Handling

The TurnHooksServer trait provides hooks for various TURN server events:

• on_allocated: Called when a client allocates a relay port
• on_channel_bind: Called when a channel is bound to a peer
• on_create_permission: Called when permissions are created for peers
• on_refresh: Called when a session is refreshed
• on_destroy: Called when a session is destroyed

All event handlers are optional and have default no-op implementations. You only need to implement the ones you care about.

Error Handling

Most operations return Result<T, Status> where Status is a gRPC status code. Common error scenarios:

• Status::not_found: Session or resource not found
• Status::unavailable: Server is not available
• Status::unauthenticated: Authentication failed
• Status::internal: Internal server error

Re-exports

This crate re-exports:

• tonic: The gRPC framework used for communication
• protos: The generated protobuf bindings for TURN server messages

You can use these directly from turn_server_sdk:

use turn_server_sdk::{tonic, protos};

Documentation

For more detailed API documentation, see:

• API Documentation (when published)
• TURN Server Documentation
• RFC 8489 - Session Traversal Utilities for NAT (STUN)
• RFC 8656 - Traversal Using Relays around NAT (TURN)

License

This project is licensed under the MIT License - see the LICENSE file for details.