leeca_proxmox 0.2.0

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.

📋 Table of Contents

✨ Features

  • 🔒 Secure by default
    TLS 1.3, optional certificate validation, token‑based authentication.

  • ⚙️ Configurable validation
    Password strength, DNS resolution, reserved usernames – all opt‑in, off by default.

  • 🧱 Clean architecture
    Domain‑driven design with value objects, clear separation of concerns.

  • ⚡ Async/await
    Built on Tokio for high concurrency.

  • 🧾 Error handling
    Detailed, type‑safe errors with backtraces.

🚀 Getting Started

Prerequisites

  • Rust
  • Cargo
  • Tokio runtime

Installation

Add the dependency to your Cargo.toml:

cargo add leeca_proxmox

Or edit Cargo.toml manually:

[dependencies]
leeca_proxmox = "0.2"
tokio = { version = "1", features = ["full"] }

📖 Usage

Basic authentication example:

use leeca_proxmox::{ProxmoxClient, ProxmoxResult};

#[tokio::main]
async fn main() -> ProxmoxResult<()> {
    let mut client = ProxmoxClient::builder()
        .host("192.168.1.100")
        .port(8006)
        .credentials("apiuser", "strong-password", "pam")
        .secure(true)                     // HTTPS (default)
        .accept_invalid_certs(false)      // reject invalid certificates (default)
        .build()
        .await?;

    client.login().await?;
    println!("Authenticated! Ticket: {}", client.auth_token().unwrap().as_str());

    Ok(())
}

Enabling extra validation

By default, only basic format checks are performed. To enable additional checks:

let client = ProxmoxClient::builder()
    .host("...")
    .credentials("user", "pass", "pam")
    .enable_password_strength(3)          // require zxcvbn score ≥ 3
    .enable_dns_resolution()               // verify hostname resolves
    .block_reserved_usernames()            // reject root, admin, etc.
    .build()
    .await?;

See the examples directory for more.

🛠️ 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: APIs may change before 1.0.0.

🙏 Acknowledgments

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

Built with ❤️ by 4rkh4m and the Rust community.

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