Remnawave Rust SDK

A 🚀 blazingly fast high-performance Rust SDK for interacting with the Remnawave API. This library provides a type-safe, async interface for managing and monitoring your Remnawave server, including user management, subscription handling, node monitoring, and comprehensive statistics.

Features

• Type-safe Rust API - Leveraging Rust's type system for compile-time guarantees
• Async/Await Support - Built on tokio and reqwest for high-performance async operations
• Controller-based Architecture - Organized API endpoints into logical controllers
• Comprehensive Management - Users, subscriptions, nodes, hosts, billing, and more
• Error Handling - Detailed error types with context and debugging information
• Rich Type Definitions - Complete request/response DTOs with serde support

Installation

Add this to your Cargo.toml:

[dependencies]
remnawave = "2.1.5" # { version = "2.1.5", features = ["native-tls"] }
tokio = { version = "1.0", features = ["full"] }

Or install via cargo:

cargo add remnawave
cargo add tokio --features full

Quick Start

use remnawave::RemnawaveApiClient;
use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize the API client
    let client = RemnawaveApiClient::new(
        "https://your-panel.com".to_string(),
        Some("your-bearer-token".to_string())
    )?;

    // Get all users
    let users_response = client.users.get_all_users(Some(10), Some(0)).await?;
    println!("Total users: {}", users_response.total);

    // Get system statistics
    let stats = client.system.get_stats().await?;
    println!("System stats: {:?}", stats);

    Ok(())
}

Core Features

User Management

use remnawave::types::{CreateUserRequestDto, UpdateUserRequestDto};
use uuid::Uuid;

// Create a new user
let new_user = CreateUserRequestDto {
    username: "john_doe".to_string(),
    email: Some("john@example.com".to_string()),
    // ... other fields
};
let user = client.users.create_user(new_user).await?;

// Get user by UUID
let user_uuid = Uuid::parse_str("550e8400-e29b-41d4-a716-446655440000")?;
let user = client.users.get_user_by_uuid(user_uuid).await?;

// Update user
let update_data = UpdateUserRequestDto {
    // ... update fields
};
let updated_user = client.users.update_user(update_data).await?;

// Bulk operations
let bulk_delete = client.users.bulk_delete_users(delete_request).await?;
let bulk_update = client.users.bulk_update_users(update_request).await?;

Subscription Management

// Get all subscriptions
let subscriptions = client.subscriptions.get_all_subscriptions(Some(20), Some(0)).await?;

// Get subscription by username
let subscription = client.subscriptions.get_subscription_by_username("john_doe").await?;

// Get subscription settings
let settings = client.subscription_settings.get_subscription_settings().await?;

// Update subscription settings
let new_settings = UpdateSubscriptionSettingsRequestDto {
    // ... settings
};
client.subscription_settings.update_subscription_settings(new_settings).await?;

Node and Host Management

// Get all nodes
let nodes = client.nodes.get_all_nodes().await?;

// Get node statistics
let node_stats = client.nodes.get_nodes_statistics().await?;

// Get real-time usage
let realtime_usage = client.nodes.get_nodes_realtime_usage().await?;

// Restart a node
let node_uuid = Uuid::parse_str("550e8400-e29b-41d4-a716-446655440000")?;
client.nodes.restart_node(node_uuid).await?;

// Host management
let hosts = client.hosts.get_all_hosts().await?;
let host = client.hosts.get_one_host(host_uuid).await?;

Authentication

use remnawave::types::{LoginRequestDto, RegisterRequestDto};

// Login
let login_request = LoginRequestDto {
    username: "admin".to_string(),
    password: "secure_password".to_string(),
};
let login_response = client.auth.login(login_request).await?;

// Register (if enabled)
let register_request = RegisterRequestDto {
    username: "new_user".to_string(),
    password: "secure_password".to_string(),
    email: "user@example.com".to_string(),
};
let register_response = client.auth.register(register_request).await?;

API Reference

RemnawaveApiClient

Main client struct for interacting with the Remnawave API.

impl RemnawaveApiClient {
    pub fn new(base_url: String, token: Option<String>) -> Result<Self>
    pub fn set_token(&mut self, token: Option<String>)
    pub fn base_url(&self) -> &str
}

Available Controllers

Bulk Operations

The SDK supports efficient bulk operations for user management:

// Bulk delete users by status
let bulk_delete_request = BulkDeleteUsersByStatusRequestDto {
    statuses: vec![UserStatus::Disabled],
};
client.users.bulk_delete_users_by_status(bulk_delete_request).await?;

// Bulk update users
let bulk_update_request = BulkUpdateUsersRequestDto {
    user_uuids: vec![user_uuid1, user_uuid2],
    update_data: UpdateUserRequestDto {
        // ... update fields
    },
};
client.users.bulk_update_users(bulk_update_request).await?;

// Bulk reset traffic
let reset_request = BulkResetTrafficUsersRequestDto {
    user_uuids: vec![user_uuid1, user_uuid2],
};
client.users.bulk_reset_user_traffic(reset_request).await?;

Usage Statistics

// Get node usage by date range
let usage = client.nodes_usage.get_nodes_usage_by_range(
    start_date,
    end_date,
    Some(node_uuid)
).await?;

// Get user usage by range
let user_usage = client.nodes_usage.get_user_usage_by_range(
    user_uuid,
    start_date,
    end_date
).await?;

// Get node user usage
let node_user_usage = client.nodes_usage.get_node_user_usage_by_range(
    node_uuid,
    start_date,
    end_date
).await?;

Error Handling

The SDK provides comprehensive error handling through the ApiError type:

use remnawave::ApiError;

match client.users.get_user_by_uuid(user_uuid).await {
    Ok(user) => println!("User: {:?}", user),
    Err(e) => {
        eprintln!("API Error [{}]: {}", e.status_code, e);
        eprintln!("Response: {}", e.response_body);
    }
} 

Configuration

Client Configuration

// With token
let client = RemnawaveApiClient::new(
    "https://your-panel.com".to_string(),
    Some("your-token".to_string())
)?;

// Without token
let client = RemnawaveApiClient::new(
    "https://your-panel.com".to_string(),
    None
)?;

// With token and Caddy API key
let client = RemnawaveApiClient::with_caddy_token(
    "https://your-panel.com".to_string(),
    Some("your-token".to_string()),
    Some("your-caddy-api-key".to_string())
)?;

// Update token later
client.set_token(Some("new-token".to_string()));

// Update Caddy token later
client.set_caddy_token(Some("new-caddy-api-key".to_string()));

Examples

Check out the tests/ directory for comprehensive examples:

• integration_tests.rs - Real API integration examples
• unit_tests.rs - Unit test examples and mocking

Compatible Versions

Contributors

We ❤️‍🔥 contributors! If you'd like to contribute, feel free to submit a pull request or open an issue.

Check open issues to help the progress of this project.

License

MIT License