dns_orchestrator_provider/lib.rs
1//! # dns-orchestrator-provider
2//!
3//! A unified DNS provider abstraction library for managing DNS records across
4//! multiple cloud platforms.
5//!
6//! ## Supported Providers
7//!
8//! | Provider | Feature Flag | Auth Method |
9//! |----------|-------------|-------------|
10//! | [Cloudflare](https://www.cloudflare.com/) | `cloudflare` | Bearer Token |
11//! | [Aliyun DNS](https://www.aliyun.com/product/dns) | `aliyun` | HMAC-SHA256 (V3) |
12//! | [DNSPod (Tencent Cloud)](https://www.dnspod.cn/) | `dnspod` | TC3-HMAC-SHA256 |
13//! | [Huawei Cloud DNS](https://www.huaweicloud.com/product/dns.html) | `huaweicloud` | AK/SK Signing |
14//!
15//! ## Feature Flags
16//!
17//! ### Provider Selection
18//!
19//! - **`all-providers`** *(default)* — Enable all providers listed above.
20//! - **`cloudflare`** — Enable only the Cloudflare provider.
21//! - **`aliyun`** — Enable only the Aliyun DNS provider.
22//! - **`dnspod`** — Enable only the Tencent Cloud `DNSPod` provider.
23//! - **`huaweicloud`** — Enable only the Huawei Cloud DNS provider.
24//!
25//! ### TLS Backend
26//!
27//! - **`native-tls`** — Use the platform's native TLS implementation.
28//! - **`rustls`** *(default)* — Use rustls, a pure-Rust TLS implementation.
29//!
30//! ## Quick Start
31//!
32//! Add to your `Cargo.toml`:
33//!
34//! ```toml
35//! [dependencies]
36//! dns-orchestrator-provider = { version = "0.1", features = ["all-providers"] }
37//! ```
38//!
39//! Or enable only the providers you need:
40//!
41//! ```toml
42//! [dependencies]
43//! dns-orchestrator-provider = { version = "0.1", default-features = false, features = ["cloudflare", "rustls"] }
44//! ```
45//!
46//! ## Usage
47//!
48//! ```rust,no_run
49//! use dns_orchestrator_provider::{
50//! create_provider, DnsProvider, PaginationParams, ProviderCredentials,
51//! };
52//!
53//! #[tokio::main]
54//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
55//! // 1. Create a provider from credentials
56//! let credentials = ProviderCredentials::Cloudflare {
57//! api_token: "your-token".to_string(),
58//! };
59//! let provider = create_provider(credentials)?;
60//!
61//! // 2. Validate credentials against the remote API
62//! provider.validate_credentials().await?;
63//!
64//! // 3. List domains
65//! let domains = provider.list_domains(&PaginationParams::default()).await?;
66//! for domain in &domains.items {
67//! println!("{} ({:?})", domain.name, domain.status);
68//! }
69//!
70//! // 4. List DNS records for the first domain
71//! let records = provider
72//! .list_records(&domains.items[0].id, &Default::default())
73//! .await?;
74//! for record in &records.items {
75//! println!(
76//! "{} {:?} -> {}",
77//! record.name,
78//! record.data.record_type(),
79//! record.data.display_value()
80//! );
81//! }
82//!
83//! Ok(())
84//! }
85//! ```
86//!
87//! ## Creating Records
88//!
89//! ```rust,no_run
90//! # use dns_orchestrator_provider::*;
91//! # async fn example(provider: std::sync::Arc<dyn DnsProvider>) -> Result<()> {
92//! let request = CreateDnsRecordRequest {
93//! domain_id: "example.com".to_string(),
94//! name: "www".to_string(),
95//! ttl: 600,
96//! data: RecordData::A { address: "1.2.3.4".to_string() },
97//! proxied: None,
98//! };
99//! let record = provider.create_record(&request).await?;
100//! # Ok(())
101//! # }
102//! ```
103//!
104//! ## Error Handling
105//!
106//! All provider operations return [`Result<T, ProviderError>`](ProviderError).
107//! The error enum provides structured variants for common failure modes:
108//!
109//! - [`ProviderError::InvalidCredentials`] — authentication failed
110//! - [`ProviderError::RecordNotFound`] — DNS record not found
111//! - [`ProviderError::RateLimited`] — API rate limit exceeded (retryable)
112//! - [`ProviderError::NetworkError`] — network connectivity issue (retryable)
113//!
114//! Transient errors (`NetworkError`, `Timeout`, `RateLimited`) are automatically
115//! retried with exponential backoff. See [`ProviderError`] for the full list.
116
117mod error;
118mod factory;
119mod http_client;
120mod providers;
121mod traits;
122mod types;
123mod utils;
124
125// Re-export error types
126pub use error::{ProviderError, Result};
127
128// Re-export factory functions
129pub use factory::{create_provider, get_all_provider_metadata};
130
131// Re-export core trait only (internal traits are not exported)
132pub use traits::DnsProvider;
133
134// Re-export types
135pub use types::{
136 BatchCreateFailure, BatchCreateResult, BatchDeleteFailure, BatchDeleteResult,
137 BatchUpdateFailure, BatchUpdateItem, BatchUpdateResult, CreateDnsRecordRequest,
138 CredentialValidationError, DnsRecord, DnsRecordType, DomainStatus, FieldType,
139 PaginatedResponse, PaginationParams, ProviderCredentialField, ProviderCredentials,
140 ProviderDomain, ProviderFeatures, ProviderLimits, ProviderMetadata, ProviderType, RecordData,
141 RecordQueryParams, UpdateDnsRecordRequest,
142};
143
144// Re-export utils module
145pub use utils::datetime;
146
147// Re-export concrete providers (behind feature flags)
148#[cfg(feature = "cloudflare")]
149pub use providers::CloudflareProvider;
150
151#[cfg(feature = "aliyun")]
152pub use providers::AliyunProvider;
153
154#[cfg(feature = "dnspod")]
155pub use providers::DnspodProvider;
156
157#[cfg(feature = "huaweicloud")]
158pub use providers::HuaweicloudProvider;