leeca_proxmox 0.1.2

A modern, safe, and async-first SDK for interacting with Proxmox Virtual Environment servers
Documentation

Leeca Proxmox VE SDK

Rust SDK for interacting with Proxmox Virtual Environment servers

CI Status Coverage Crates.io Downloads Docs Deps License MSRV Security

A modern, safe, and async-first SDK for interacting with Proxmox Virtual Environment servers, following industry best practices and clean architecture principles.

📋 Table of Contents

✨ Features

  • 🔒 Enterprise-Grade Security

    • Token-based authentication
    • Comprehensive input validation
    • Secure default configurations
    • Thread-safe operations
    • Built-in SSL/TLS support

  • 🚀 Modern Architecture

    • Async-first design using Tokio
    • Clean Architecture principles
    • Domain-Driven Design
    • SOLID principles
    • Immutable Value Objects

  • 💪 Robust Error Handling

    • Type-safe error propagation
    • Detailed error contexts
    • Stack traces for debugging
    • Custom error types
    • Validation error handling

🚀 Getting Started

Prerequisites

  • Rust (nightly)
  • Cargo
  • Tokio runtime

Installation

cargo add leeca_proxmox

📖 Usage

use leeca_proxmox::{ProxmoxClient, ProxmoxResult};
use std::time::UNIX_EPOCH;

#[tokio::main]
async fn main() -> ProxmoxResult<()> {
    let mut client = ProxmoxClient::builder()
        .host("192.168.1.182")?
        .port(8006)?
        .credentials("leeca", "Leeca_proxmox1!", "pam")?
        .secure(false)
        .build()
        .await?;

    println!("\n🔑 Authentication Status");
    println!("------------------------");
    println!(
        "Initial state: {}",
        if client.is_authenticated() {
            "✅ Authenticated"
        } else {
            "❌ Not authenticated"
        }
    );

    println!("\n📡 Connecting to Proxmox...");
    client.login().await?;
    println!(
        "Connection state: {}",
        if client.is_authenticated() {
            "✅ Authenticated"
        } else {
            "❌ Failed"
        }
    );

    if let Some(token) = client.auth_token() {
        println!("\n🎟️  Session Token");
        println!("------------------------");
        println!("Value: {}", token.value().await);
        let expires = token
            .expires_at()
            .await
            .duration_since(UNIX_EPOCH)
            .unwrap()
            .as_secs();
        println!("Expires at: {} (Unix timestamp)", expires);
    }

    if let Some(csrf) = client.csrf_token() {
        println!("\n🛡️  CSRF Protection");
        println!("------------------------");
        println!("Token: {}", csrf.value().await);
        let expires = csrf
            .expires_at()
            .await
            .duration_since(UNIX_EPOCH)
            .unwrap()
            .as_secs();
        println!("Expires at: {} (Unix timestamp)", expires);
    }

    println!("\n✨ Connection established successfully!\n");
    Ok(())
}

🛠️ Development

# Install development dependencies
cargo install cargo-llvm-cov cargo-audit

# Run tests
cargo test --all-features

# Check code coverage
cargo llvm-cov --all-features --lcov --output-path lcov.info

# Run security audit
cargo audit

# Run linters
cargo clippy --all-targets --all-features
cargo fmt --all -- --check

📊 Project Status

See our CHANGELOG for version history and ROADMAP for future plans.

📚 Documentation

🛡️ Security

See our Security Policy for reporting vulnerabilities.

📄 License

Licensed under Apache License 2.0 - see the LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

⚖️ Code of Conduct

Please read and follow our Code of Conduct.

👥 Community

📈 Versioning

This project follows Semantic Versioning. See our CHANGELOG for version history.

⚠️ Note: This project is in active development. APIs may change before 1.0.0 release.

🙏 Acknowledgments

  • Proxmox VE team for their excellent API documentation
  • Rust community for their tools and crates
  • All contributors

Built with ❤️ by Leeca Team && Rust Community

⭐ Star · 🐛 Report Bug · ✨ Request Feature · 🛡️ Security Report