redis_cloud/

lib.rs

// Allow doc strings with quoted values like 'true'/'false' from OpenAPI spec
#![allow(clippy::doc_link_with_quotes)]
// Every public item must carry a docstring. Closed the 368 existing
// gaps under #80; this lint keeps the bar from regressing.
#![deny(missing_docs)]
#![deny(rustdoc::broken_intra_doc_links)]

//! Redis Cloud REST API Client
//!
//! A comprehensive Rust client for the Redis Cloud REST API, providing full access to
//! subscription management, database operations, billing, monitoring, and advanced features
//! like VPC peering, SSO/SAML, and Private Service Connect.
//!
//! ## Features
//!
//! - **Subscription Management**: Create, update, delete subscriptions across AWS, GCP, Azure
//! - **Database Operations**: Full CRUD operations, backups, imports, metrics
//! - **Advanced Networking**: VPC peering, Transit Gateway, Private Service Connect
//! - **Security & Access**: ACLs, SSO/SAML integration, API key management
//! - **Monitoring & Billing**: Comprehensive metrics, logs, billing and payment management
//! - **Enterprise Features**: Active-Active databases (CRDB), fixed/essentials plans
//!
//! ## Quick Start
//!
//! ```rust,no_run
//! use redis_cloud::CloudClient;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let client = CloudClient::builder()
//!         .api_key(std::env::var("REDIS_CLOUD_API_KEY")?)
//!         .api_secret(std::env::var("REDIS_CLOUD_API_SECRET")?)
//!         .build()?;
//!
//!     // List all databases in subscription 123 (Vec<Database>, no wrapper)
//!     let databases = client.databases().list(123).await?;
//!     println!("Found {} databases", databases.len());
//!
//!     Ok(())
//! }
//! ```
//!
//! ## Core Usage Patterns
//!
//! ### Client Creation
//!
//! The client uses a builder pattern for flexible configuration:
//!
//! ```rust,no_run
//! use redis_cloud::CloudClient;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Basic client with default settings
//! let client = CloudClient::builder()
//!     .api_key("your-api-key")
//!     .api_secret("your-api-secret")
//!     .build()?;
//!
//! // Custom configuration
//! let client2 = CloudClient::builder()
//!     .api_key("your-api-key")
//!     .api_secret("your-api-secret")
//!     .base_url("https://api.redislabs.com/v1".to_string())
//!     .timeout(std::time::Duration::from_secs(60))
//!     .build()?;
//! # Ok(())
//! # }
//! ```
//!
//! ### Typed vs Raw API
//!
//! This client offers typed handlers for common operations as well as raw helpers when you
//! need full control over request/response payloads:
//!
//! - Prefer typed handlers (e.g., `CloudDatabaseHandler`) for structured, ergonomic access.
//! - Use raw helpers for passthroughs: `get_raw`, `post_raw`, `put_raw`, `patch_raw`, `delete_raw`.
//!
//! ```rust,no_run
//! use redis_cloud::CloudClient;
//! use serde_json::json;
//!
//! # #[tokio::main]
//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let client = CloudClient::builder()
//!     .api_key("key")
//!     .api_secret("secret")
//!     .build()?;
//!
//! // Raw call example
//! let created = client.post_raw("/subscriptions", json!({ "name": "example" })).await?;
//! println!("{}", created);
//! # Ok(())
//! # }
//! ```
//!
//! ### Working with Subscriptions
//!
//! ```rust,no_run
//! use redis_cloud::{CloudClient, SubscriptionHandler};
//! use serde_json::json;
//!
//! # #[tokio::main]
//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let client = CloudClient::builder()
//!     .api_key("key")
//!     .api_secret("secret")
//!     .build()?;
//!
//! let sub_handler = SubscriptionHandler::new(client.clone());
//!
//! // List subscriptions
//! let subscriptions = sub_handler.list().await?;
//!
//! // Create a new subscription using raw API
//! let new_subscription = json!({
//!     "name": "my-redis-subscription",
//!     "provider": "AWS",
//!     "region": "us-east-1",
//!     "plan": "cache.m5.large"
//! });
//! let created = client.post_raw("/subscriptions", new_subscription).await?;
//! # Ok(())
//! # }
//! ```
//!
//! ### Database Management
//!
//! ```rust,no_run
//! use redis_cloud::{CloudClient, DatabaseHandler};
//! use serde_json::json;
//!
//! # #[tokio::main]
//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let client = CloudClient::builder()
//!     .api_key("key")
//!     .api_secret("secret")
//!     .build()?;
//!
//! let db_handler = DatabaseHandler::new(client.clone());
//!
//! // Create database using raw API
//! let database_config = json!({
//!     "name": "my-database",
//!     "memoryLimitInGb": 1.0,
//!     "support_oss_cluster_api": false,
//!     "replication": true
//! });
//! let database = client.post_raw("/subscriptions/123/databases", database_config).await?;
//!
//! // Get database info
//! let db_info = db_handler.get_subscription_database_by_id(123, 456).await?;
//! # Ok(())
//! # }
//! ```
//!
//! ### Advanced Features
//!
//! #### VPC Peering
//! ```rust,no_run
//! use redis_cloud::{CloudClient, VpcPeeringHandler};
//! use redis_cloud::connectivity::VpcPeeringCreateRequest;
//!
//! # #[tokio::main]
//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let client = CloudClient::builder()
//!     .api_key("key")
//!     .api_secret("secret")
//!     .build()?;
//!
//! let handler = VpcPeeringHandler::new(client);
//!
//! // Construct a provider-targeted body — `for_aws` pre-populates the
//! // spec's required AWS fields with the correct wire names.
//! let mut request = VpcPeeringCreateRequest::for_aws(
//!     "us-east-1",
//!     "123456789012",
//!     "vpc-12345678",
//! );
//! request.vpc_cidr = Some("10.0.0.0/16".to_string());
//!
//! let task = handler.create(123, &request).await?;
//! println!("Peering create task: {:?}", task.task_id);
//! # Ok(())
//! # }
//! ```
//!
//! #### SSO/SAML Management
//! ```rust,no_run
//! use redis_cloud::{CloudClient, AccountHandler};
//! use serde_json::json;
//!
//! # #[tokio::main]
//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let client = CloudClient::builder()
//!     .api_key("key")
//!     .api_secret("secret")
//!     .build()?;
//!
//! let sso_handler = AccountHandler::new(client.clone());
//!
//! // Configure SSO using raw API
//! let sso_config = json!({
//!     "enabled": true,
//!     "auto_provision": true
//! });
//! let config = client.put_raw("/sso", sso_config).await?;
//! # Ok(())
//! # }
//! ```
//!
//! #### Account Information (Typed)
//! ```rust,no_run
//! use redis_cloud::{AccountHandler, CloudClient};
//!
//! # #[tokio::main]
//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let client = CloudClient::builder()
//!     .api_key("key")
//!     .api_secret("secret")
//!     .build()?;
//!
//! let account = AccountHandler::new(client.clone());
//! let account_info = account.get_current_account().await?;
//! # let _ = account_info;
//! # Ok(())
//! # }
//! ```
//!
//! ## Error Handling
//!
//! The client provides comprehensive error handling for different failure scenarios:
//!
//! ```rust,no_run
//! use redis_cloud::{CloudClient, CloudError, DatabaseHandler};
//!
//! # #[tokio::main]
//! # async fn main() {
//! let client = CloudClient::builder()
//!     .api_key("key")
//!     .api_secret("secret")
//!     .build().unwrap();
//!
//! let db_handler = DatabaseHandler::new(client.clone());
//!
//! match db_handler.get_subscription_database_by_id(123, 456).await {
//!     Ok(database) => println!("Database: {:?}", database),
//!     Err(CloudError::ApiError { code: 404, .. }) => {
//!         println!("Database not found");
//!     },
//!     Err(CloudError::AuthenticationFailed { message }) => {
//!         println!("Invalid API credentials");
//!     },
//!     Err(e) => println!("Other error: {}", e),
//! }
//! # }
//! ```
//!
//! ## Handler Overview
//!
//! The client provides specialized handlers for different API domains:
//!
//! | Handler | Purpose | Key Operations |
//! |---------|---------|----------------|
//! | [`SubscriptionHandler`] | Pro subscriptions | create, list, update, delete, pricing |
//! | [`FixedSubscriptionHandler`] | Essentials subscriptions | fixed plans, create, update, delete |
//! | [`DatabaseHandler`] | Pro databases | create, backup, import, metrics, resize |
//! | [`FixedDatabaseHandler`] | Essentials databases | fixed capacity, backup, import |
//! | [`AccountHandler`] | Account management | info, API keys, payment methods, SSO |
//! | [`UserHandler`] | User management | create, update, delete, invite, roles |
//! | [`AclHandler`] | Access control | users, roles, Redis rules, database ACLs |
//! | [`VpcPeeringHandler`] | VPC peering | standard and Active-Active peering |
//! | [`TransitGatewayHandler`] | AWS Transit Gateway | attachments, invitations, CIDR updates |
//! | [`PscHandler`] | GCP Private Service Connect | endpoints (standard and Active-Active) |
//! | [`PrivateLinkHandler`] | AWS PrivateLink | services, connections, endpoints |
//! | [`CostReportHandler`] | Cost reports | FOCUS-format billing exports |
//! | [`CloudAccountHandler`] | Cloud providers | AWS, GCP, Azure account integration |
//! | [`TaskHandler`] | Async operations | track long-running operations |
//!
//! ## Authentication
//!
//! Redis Cloud uses API key authentication with two required headers:
//! - `x-api-key`: Your API key
//! - `x-api-secret-key`: Your API secret
//!
//! These credentials can be obtained from the Redis Cloud console under Account Settings > API Keys.
//!
//! Environment variables commonly used with this client:
//! - `REDIS_CLOUD_API_KEY`
//! - `REDIS_CLOUD_API_SECRET`
//! - Optional: set a custom base URL via the builder for non‑prod/test environments (defaults to `https://api.redislabs.com/v1`).

pub mod client;
pub mod error;

#[cfg(test)]
mod lib_tests;

// Re-export client types
pub use client::{CloudClient, CloudClientBuilder};

// Re-export error types
pub use error::{CloudError, Result};

// Re-export Tower integration when feature is enabled
#[cfg(feature = "tower-integration")]
pub use client::tower_support;

// Test support module - only available with test-support feature
#[cfg(feature = "test-support")]
pub mod testing;

// Types module for shared models
pub mod types;

// Handler modules - each handles a specific API domain
pub mod account;
pub mod acl;
pub mod cloud_accounts;
pub mod connectivity;
pub mod cost_report;
pub mod fixed;
pub mod flexible;
pub mod tasks;
pub mod users;

// Backward compatibility module aliases
pub use fixed::databases as fixed_databases;
pub use fixed::subscriptions as fixed_subscriptions;
pub use flexible::databases;
pub use flexible::subscriptions;

// Re-export handlers with standard naming
pub use account::AccountHandler;
pub use acl::AclHandler;
pub use cloud_accounts::CloudAccountsHandler as CloudAccountHandler;

// Connectivity handlers
pub use connectivity::private_link::PrivateLinkHandler;
pub use connectivity::psc::PscHandler;
pub use connectivity::transit_gateway::TransitGatewayHandler;
pub use connectivity::vpc_peering::VpcPeeringHandler;
// Connectivity types
pub use connectivity::{PrincipalType, PrivateLinkAddPrincipalRequest, PrivateLinkCreateRequest};
// Legacy connectivity export for backward compatibility
pub use connectivity::ConnectivityHandler;

// Fixed plan handlers
pub use fixed::databases::FixedDatabaseHandler;
pub use fixed::subscriptions::FixedSubscriptionHandler;
// Legacy exports for backward compatibility
pub use fixed::databases::FixedDatabaseHandler as FixedDatabasesHandler;
pub use fixed::subscriptions::FixedSubscriptionHandler as FixedSubscriptionsHandler;

// Flexible plan handlers (pay-as-you-go)
pub use flexible::databases::DatabaseHandler;
pub use flexible::subscriptions::SubscriptionHandler;
// Legacy exports for backward compatibility
pub use flexible::databases::DatabaseHandler as DatabasesHandler;
pub use flexible::subscriptions::SubscriptionHandler as SubscriptionsHandler;

pub use cost_report::CostReportHandler;
pub use cost_report::{CostReportCreateRequest, CostReportFormat, SubscriptionType, Tag};
pub use tasks::TasksHandler as TaskHandler;
pub use users::UsersHandler as UserHandler;