cpanel_rs/lib.rs
1//! # cpanel-rs
2//!
3//! An unofficial Rust client for the [cPanel](https://cpanel.net/) &
4//! [WHM](https://www.cpanel.net/products/whm/) APIs. This crate lets you manage
5//! hosting accounts, DNS records, email, databases, files, SSL certificates, and
6//! backups programmatically via UAPI and WHM JSON API endpoints.
7//!
8//! **This project is not affiliated with or endorsed by WebPros.**
9//!
10//! # Quick Start
11//!
12//! ```toml
13//! # Cargo.toml
14//! [dependencies]
15//! cpanel-rs = "0.3"
16//! ```
17//!
18//! ```
19//! use cpanel_rs::{CpanelClient, CpanelBuilder};
20//!
21//! // Simple construction
22//! let client = CpanelClient::simple("server.example.com", 2087, "root", "yourpass").unwrap();
23//!
24//! // Or with the builder for full control
25//! let client = CpanelBuilder::new("server.example.com", 2087, "root")
26//! .password("secret")
27//! .timeout(std::time::Duration::from_secs(30))
28//! .disable_tls_verification()
29//! .build()
30//! .unwrap();
31//! ```
32//!
33//! # Supported Operations
34//!
35//! | Module | Functionality |
36//! |--------|---------------|
37//! | [`account`] | List, create, delete, suspend, modify accounts (WHM) |
38//! | [`backup`] | Backup creation, listing, restoration, scheduling (UAPI) |
39//! | [`cron`] | List, add, edit, delete scheduled cron jobs (UAPI) |
40//! | [`database`] | MySQL databases, users, and privileges (UAPI) |
41//! | [`dns`] | List, add, delete DNS records; import/export zones (UAPI) |
42//! | [`domains`] | Addon domains, parked domains (aliases), and subdomains (UAPI) |
43//! | [`email`] | Email accounts, forwarders, autoresponders, mailing lists (UAPI) |
44//! | [`filemanager`] | List, create, delete, upload, download, compress files (UAPI) |
45//! | [`ftp`] | FTP account management: list, create, modify, delete (UAPI) |
46//! | [`security`] | ModSecurity rules and IP blocker (blacklist/whitelist) (UAPI) |
47//! | [`ssl`] | SSL certificate management and Let's Encrypt issuance (UAPI) |
48//! | [`resources`] | Disk/quota usage, PHP version management (UAPI) |
49//!
50//! # Authentication
51//!
52//! Three auth methods are supported:
53//!
54//! - **Password** — Basic HTTP auth. Works for both cPanel (2083) and WHM (2087).
55//! - **Raw Key** — `WHM user:key` header. Requires WHM access and a raw access key
56//! generated in WHM > Manage Remote Access Key.
57//! - **API Token** — `Authorization: cpanel <user>:<token>`. Generates granular,
58//! scoped permissions without requiring a full account password or root access.
59//! Create tokens in cPanel > Home > Security Center > API Tokens.
60//!
61//! ```no_run
62//! use cpanel_rs::CpanelBuilder;
63//!
64//! // Password auth
65//! let client = CpanelBuilder::new("myhost.com", 2087, "user").password("pass").build().unwrap();
66//!
67//! // Raw key auth (WHM only)
68//! let client = CpanelBuilder::new("myhost.com", 2087, "root").key("abc123...").build().unwrap();
69//!
70//! // API Token auth (cPanel UAPI)
71//! let client = CpanelBuilder::new("myhost.com", 2083, "user").token("uI7fX2aB9cD...").build().unwrap();
72//! ```
73//!
74//! # Retry & Backoff
75//!
76//! Enable the `retry` feature for automatic exponential backoff on transient errors
77//! (429 rate limits, 503 service unavailable, connection resets):
78//!
79//! ```toml
80//! [dependencies]
81//! cpanel-rs = { version = "0.3", features = ["retry"] }
82//! ```
83//!
84//! ```
85//! use cpanel_rs::{CpanelClient, RetryPolicy};
86//!
87//! let client = CpanelClient::simple("server.example.com", 2087, "root", "pass").unwrap();
88//! let client = client.with_retry_policy(
89//! RetryPolicy::default().max_retries(5).base_delay(std::time::Duration::from_millis(500)),
90//! );
91//! ```
92//!
93//! # Auto-Paginating Streams
94//!
95//! Enable the `stream` feature to use async streams for large listings:
96//!
97//! ```toml
98//! [dependencies]
99//! cpanel-rs = { version = "0.3", features = ["stream"] }
100//! ```
101//!
102//! ```no_run
103//! #[cfg(feature = "stream")]
104//! {
105//! use cpanel_rs::CpanelClient;
106//! use futures::StreamExt;
107//!
108//! #[tokio::main]
109//! async fn main() -> Result<(), cpanel_rs::CpanelError> {
110//! let client = CpanelClient::simple("server.example.com", 2087, "root", "pass").unwrap();
111//!
112//! // Stream all accounts without manual pagination
113//! let mut stream = client.stream_accounts();
114//! while let Some(acct) = stream.next().await {
115//! let acct = acct?;
116//! println!("{} @ {}", acct.username, acct.domain);
117//! }
118//! Ok(())
119//! }
120//! }
121//! ```
122//!
123//! # Streaming File Operations
124//!
125//! Upload large files from an async reader without loading them entirely into memory:
126//!
127//! ```no_run
128//! use cpanel_rs::CpanelClient;
129//! use tokio::fs::File;
130//! use tokio::io::AsyncReadExt;
131//!
132//! #[tokio::main]
133//! async fn main() -> Result<(), cpanel_rs::CpanelError> {
134//! let client = CpanelClient::simple("server.example.com", 2083, "user", "pass").unwrap();
135//! let mut file = File::open("large_upload.zip").await?;
136//! client.upload_file_from_reader("user", "/public_html/large_upload.zip", &mut file, "large_upload.zip", 1024 * 1024).await?;
137//! Ok(())
138//! }
139//! ```
140//!
141//! # Environment Variables (opt-in)
142//!
143//! Enable the `dotenv` feature to load credentials from a `.env` file:
144//!
145//! ```toml
146//! [dependencies]
147//! cpanel-rs = { version = "0.3", features = ["dotenv"] }
148//! ```
149//!
150//! Then create a `.env` file:
151//!
152//! ```text
153//! CPANEL_HOST=server.example.com
154//! CPANEL_PORT=2087
155//! CPANEL_USER=root
156//! CPANEL_PASSWORD=yourpass
157//! ```
158//!
159//! # Error Handling
160//!
161//! All methods return [`Result<_, CpanelError>`]. Errors fall into these categories:
162//!
163//! - **[`CpanelError::Http`]** — network or connection failure
164//! - **[`CpanelError::ApiError`]** — the API returned a non-success status
165//! - **[`CpanelError::ApiWarning`]** — the API returned success but with warnings
166//! - **[`CpanelError::Auth`]** — missing or invalid credentials
167//! - **[`CpanelError::Serialization`]** — invalid JSON response
168//!
169//! Use [`CpanelError::ApiError`] to inspect structured
170//! failure details including all error messages, warnings, and stack traces.
171
172#![warn(missing_docs, clippy::missing_errors_doc)]
173#![allow(
174 clippy::missing_errors_doc,
175 clippy::result_large_err,
176 clippy::type_complexity
177)]
178
179/// cPanel & WHM account management (WHM API).
180pub mod account;
181/// Backup management (UAPI).
182pub mod backup;
183/// Core client: [`CpanelClient`], [`CpanelBuilder`], [`AuthMethod`], and [`RetryPolicy`].
184pub mod client;
185/// Cron job management (UAPI).
186pub mod cron;
187/// MySQL database management (UAPI).
188pub mod database;
189/// DNS record management (UAPI).
190pub mod dns;
191/// Domain and subdomain management (UAPI).
192pub mod domains;
193/// Email account management (UAPI).
194pub mod email;
195/// File manager operations (UAPI).
196pub mod filemanager;
197/// FTP account management (UAPI).
198pub mod ftp;
199/// Data models shared across modules.
200pub mod models;
201/// Resource usage and PHP version management (UAPI).
202pub mod resources;
203/// Security: ModSecurity rules and IP blocker (UAPI).
204pub mod security;
205/// SSL certificate management (UAPI).
206pub mod ssl;
207/// Auto-paginating async streams for large listings (requires `stream` feature).
208#[cfg(feature = "stream")]
209pub mod streams;
210/// Core types: errors, response envelopes, and query builders.
211pub mod types;
212
213pub use client::{AuthMethod, CpanelBuilder, CpanelClient, RetryPolicy};
214pub use types::CpanelError;