Crate redis_enterprise

Expand description

Redis Enterprise REST API client

A comprehensive Rust client library for the Redis Enterprise REST API, providing full cluster management, database operations, security configuration, and monitoring capabilities. This crate offers both typed and untyped API access with comprehensive coverage of all Enterprise REST endpoints.

§Features

Complete API Coverage: Full coverage of v1 endpoints plus select v2 endpoints where they exist (e.g., actions, modules)
Type-Safe Operations: Strongly typed request/response models
Flexible Authentication: Basic auth with optional SSL verification
Async/Await Support: Built on Tokio for high-performance async operations
Error Handling: Comprehensive error types with context
Builder Patterns: Ergonomic API for complex request construction
Versioned APIs: Clear accessors for v1 and v2 where both exist

§Quick Start

Add to your Cargo.toml:

[dependencies]
redis-enterprise = "0.2.0"
tokio = { version = "1", features = ["full"] }

§Environment Variables

The client supports configuration via environment variables:

REDIS_ENTERPRISE_URL: Base URL for the cluster (e.g., https://cluster:9443)
REDIS_ENTERPRISE_USER: Username for authentication
REDIS_ENTERPRISE_PASSWORD: Password for authentication
REDIS_ENTERPRISE_INSECURE: Set to true to skip SSL verification (dev only)

§Module Organization

The library is organized into domain-specific modules:

Core Resources: bdb, cluster, nodes, users, roles
Monitoring: stats, alerts, logs, diagnostics
Advanced: crdb, shards, proxies, redis_acls
Configuration: services, cm_settings, suffixes

§Return Types

Most methods return strongly-typed structs. Methods returning serde_json::Value:

Stats/Metrics: Dynamic keys based on metric names
Legacy endpoints: start(), stop() - use typed action methods instead
Variable schemas: Endpoints with version-dependent responses
Passthrough access: For direct API access via the CLI

§Examples

§Creating a Client

use redis_enterprise::EnterpriseClient;

// From environment variables
let client = EnterpriseClient::from_env()?;

// Or using the builder
let client = EnterpriseClient::builder()
    .base_url("https://cluster.example.com:9443")
    .username("admin@example.com")
    .password("password")
    .insecure(false)
    .build()?;

§Working with Databases

use redis_enterprise::{EnterpriseClient, BdbHandler, CreateDatabaseRequest};

// List all databases
let handler = BdbHandler::new(client.clone());
let databases = handler.list().await?;
for db in databases {
    println!("Database: {} ({})", db.name, db.uid);
}

// Create a new database
let request = CreateDatabaseRequest::builder()
    .name("my-database")
    .memory_size(1024 * 1024 * 1024) // 1GB
    .port(12000)
    .replication(false)
    .persistence("aof")
    .build();

let new_db = handler.create(request).await?;
println!("Created database: {}", new_db.uid);

// Get database stats
let stats = handler.stats(new_db.uid).await?;
println!("Ops/sec: {:?}", stats);

§Managing Nodes

use redis_enterprise::{EnterpriseClient, NodeHandler};

let handler = NodeHandler::new(client);

// List all nodes in the cluster
let nodes = handler.list().await?;
for node in nodes {
    println!("Node {}: {:?} ({})", node.uid, node.addr, node.status);
}

// Get detailed node information
let node_info = handler.get(1).await?;
println!("Node memory: {:?} bytes", node_info.total_memory);

// Check node stats
let stats = handler.stats(1).await?;
println!("CPU usage: {:?}", stats);

§Cluster Operations

use redis_enterprise::{EnterpriseClient, ClusterHandler};

let handler = ClusterHandler::new(client);

// Get cluster information
let cluster_info = handler.info().await?;
println!("Cluster name: {}", cluster_info.name);
println!("Nodes: {:?}", cluster_info.nodes);

// Get cluster statistics
let stats = handler.stats().await?;
println!("Total memory: {:?}", stats);

// Check license status
let license = handler.license().await?;
println!("License expires: {:?}", license);

§Versioned Endpoints (v1/v2)

Some Enterprise endpoints have both v1 and v2 flavors. Use versioned sub-handlers to make intent explicit and keep models clean.

use redis_enterprise::{EnterpriseClient, ActionHandler, ModuleHandler};

// Actions: v1 and v2
let actions = ActionHandler::new(client.clone());
let v1_actions = actions.v1().list().await?; // GET /v1/actions
let v2_actions = actions.v2().list().await?; // GET /v2/actions

// Modules
let modules = ModuleHandler::new(client.clone());
let all = modules.list().await?;            // GET /v1/modules
// Upload uses v2 endpoint with fallback to v1
let uploaded = modules.upload(b"module_data".to_vec(), "module.zip").await?;

§Typed-Only Client

The Enterprise client exposes typed request/response APIs by default. Raw JSON passthroughs are avoided except for intentionally opaque operations (for example, database command passthrough or module uploads). This keeps CLI and library usage consistent and safer while maintaining flexibility where the wire format is open.

§User Management

use redis_enterprise::{EnterpriseClient, UserHandler, CreateUserRequest};

let handler = UserHandler::new(client);

// List all users
let users = handler.list().await?;
for user in users {
    println!("User: {} ({})", user.email, user.role);
}

// Create a new user
let request = CreateUserRequest::builder()
    .email("newuser@example.com")
    .password("secure_password")
    .role("db_member")
    .name("New User")
    .email_alerts(true)
    .build();

let new_user = handler.create(request).await?;
println!("Created user: {}", new_user.uid);

§Monitoring and Alerts

use redis_enterprise::{EnterpriseClient, AlertHandler, StatsHandler};

// Check active alerts
let alert_handler = AlertHandler::new(client.clone());
let alerts = alert_handler.list().await?;
for alert in alerts {
    println!("Alert: {} - {}", alert.name, alert.severity);
}

// Get cluster statistics
let stats_handler = StatsHandler::new(client);
let cluster_stats = stats_handler.cluster(None).await?;
println!("Cluster stats: {:?}", cluster_stats);

§Active-Active Databases (CRDB)

use redis_enterprise::{EnterpriseClient, CrdbHandler, CreateCrdbRequest};

let handler = CrdbHandler::new(client);

// List Active-Active databases
let crdbs = handler.list().await?;
for crdb in crdbs {
    println!("CRDB: {} ({})", crdb.name, crdb.guid);
}

// Create an Active-Active database
let request = CreateCrdbRequest {
    name: "global-cache".to_string(),
    memory_size: 1024 * 1024 * 1024, // 1GB per instance
    instances: vec![
        // Define instances for each participating cluster
    ],
    encryption: Some(false),
    data_persistence: Some("aof".to_string()),
    eviction_policy: Some("allkeys-lru".to_string()),
};

let new_crdb = handler.create(request).await?;
println!("Created CRDB: {}", new_crdb.guid);

§Error Handling

The library provides detailed error information for all API operations with convenient error variants and helper methods:

use redis_enterprise::{EnterpriseClient, bdb::DatabaseHandler, RestError};

let handler = DatabaseHandler::new(client);

match handler.get(999).await {
    Ok(db) => println!("Found database: {}", db.name),
    Err(RestError::NotFound) => println!("Database not found"),
    Err(RestError::Unauthorized) => println!("Invalid credentials"),
    Err(RestError::ServerError(msg)) => println!("Server error: {}", msg),
    Err(e) if e.is_not_found() => println!("Not found: {}", e),
    Err(e) => println!("Unexpected error: {}", e),
}

§Handler Overview

The library exposes focused handlers per API domain to keep code organized and discoverable:

Handler	Purpose	Key Operations
`ClusterHandler`	Cluster lifecycle	info, update, license, services
`BdbHandler`	Databases (BDB)	list, get, create, update, delete, stats
`NodeHandler`	Node management	list, get, stats
`UserHandler`	Users	list, get, create, update, delete
`RoleHandler`	Roles	list, get, assign
`ModuleHandler`	Modules	list (v1), upload (v2)
`AlertHandler`	Alerts	list, acknowledge
`StatsHandler`	Monitoring	cluster/node/database stats
`LogsHandler`	Logs	cluster and database logs
`ActionHandler`	Actions	v1/v2 workflows

§Production Best Practices

Connection Pooling: The client reuses HTTP connections automatically
Timeout Configuration: Set appropriate timeouts for your environment
SSL Verification: Always enable in production (disable only for development)
Error Handling: Implement retry logic for transient failures
Monitoring: Log all API operations and track response times

§API Coverage

This crate provides complete coverage of the Redis Enterprise REST API:

Cluster Management: Bootstrap, configuration, licenses
Database Operations: CRUD, backup/restore, configuration
Security: Users, roles, ACLs, LDAP integration
Monitoring: Stats, alerts, logs, diagnostics
High Availability: Active-Active (CRDB), replication
Modules: Redis module management
Maintenance: Upgrades, migrations, debug info

Re-exports§

pub use client::EnterpriseClient;
pub use client::EnterpriseClientBuilder;
pub use error::RestError;
pub use error::Result;
pub use bdb::BdbHandler;
pub use bdb::CreateDatabaseRequest;
pub use bdb::Database;
pub use bdb::ModuleConfig;
pub use bdb_groups::BdbGroup;
pub use bdb_groups::BdbGroupsHandler;
pub use cluster::BootstrapRequest;
pub use cluster::ClusterHandler;
pub use cluster::ClusterInfo;
pub use cluster::ClusterNode;
pub use cluster::LicenseInfo;
pub use cluster::NodeInfo;
pub use nodes::Node;
pub use nodes::NodeActionRequest;
pub use nodes::NodeHandler;
pub use nodes::NodeStats;
pub use users::CreateUserRequest;
pub use users::Role;
pub use users::RoleHandler;
pub use users::UpdateUserRequest;
pub use users::User;
pub use users::UserHandler;
pub use modules::Module;
pub use modules::ModuleHandler;
pub use actions::Action;
pub use actions::ActionHandler;
pub use logs::LogEntry;
pub use logs::LogsHandler;
pub use logs::LogsQuery;
pub use crdb::Crdb;
pub use crdb::CrdbHandler;
pub use crdb::CrdbInstance;
pub use crdb::CreateCrdbInstance;
pub use crdb::CreateCrdbRequest;
pub use stats::StatsHandler;
pub use stats::StatsInterval;
pub use stats::StatsQuery;
pub use stats::StatsResponse;
pub use alerts::Alert;
pub use alerts::AlertHandler;
pub use alerts::AlertSettings;
pub use redis_acls::CreateRedisAclRequest;
pub use redis_acls::RedisAcl;
pub use redis_acls::RedisAclHandler;
pub use shards::Shard;
pub use shards::ShardHandler;
pub use shards::ShardStats;
pub use proxies::Proxy;
pub use proxies::ProxyHandler;
pub use proxies::ProxyStats;
pub use ldap_mappings::CreateLdapMappingRequest;
pub use ldap_mappings::LdapConfig;
pub use ldap_mappings::LdapMapping;
pub use ldap_mappings::LdapMappingHandler;
pub use ldap_mappings::LdapServer;
pub use ocsp::OcspConfig;
pub use ocsp::OcspHandler;
pub use ocsp::OcspStatus;
pub use ocsp::OcspTestResult;
pub use local::LocalHandler;
pub use bootstrap::BootstrapConfig;
pub use bootstrap::BootstrapHandler;
pub use bootstrap::BootstrapStatus;
pub use bootstrap::ClusterBootstrap;
pub use bootstrap::CredentialsBootstrap;
pub use bootstrap::NodeBootstrap;
pub use bootstrap::NodePaths;
pub use cm_settings::CmSettings;
pub use cm_settings::CmSettingsHandler;
pub use crdb_tasks::CrdbTask;
pub use crdb_tasks::CrdbTasksHandler;
pub use crdb_tasks::CreateCrdbTaskRequest;
pub use debuginfo::DebugInfoHandler;
pub use debuginfo::DebugInfoRequest;
pub use debuginfo::DebugInfoStatus;
pub use debuginfo::TimeRange;
pub use diagnostics::DiagnosticReport;
pub use diagnostics::DiagnosticRequest;
pub use diagnostics::DiagnosticResult;
pub use diagnostics::DiagnosticSummary;
pub use diagnostics::DiagnosticsHandler;
pub use endpoints::Endpoint;
pub use endpoints::EndpointStats;
pub use endpoints::EndpointsHandler;
pub use job_scheduler::CreateScheduledJobRequest;
pub use job_scheduler::JobExecution;
pub use job_scheduler::JobSchedulerHandler;
pub use job_scheduler::ScheduledJob;
pub use jsonschema::JsonSchemaHandler;
pub use license::License;
pub use license::LicenseHandler;
pub use license::LicenseUpdateRequest;
pub use license::LicenseUsage;
pub use migrations::CreateMigrationRequest;
pub use migrations::Migration;
pub use migrations::MigrationEndpoint;
pub use migrations::MigrationsHandler;
pub use roles::BdbRole;
pub use roles::CreateRoleRequest;
pub use roles::RoleInfo;
pub use roles::RolesHandler;
pub use services::NodeServiceStatus;
pub use services::Service;
pub use services::ServiceConfigRequest;
pub use services::ServiceStatus;
pub use services::ServicesHandler;
pub use suffixes::CreateSuffixRequest;
pub use suffixes::Suffix;
pub use suffixes::SuffixesHandler;
pub use usage_report::DatabaseUsage;
pub use usage_report::NodeUsage;
pub use usage_report::UsageReport;
pub use usage_report::UsageReportConfig;
pub use usage_report::UsageReportHandler;
pub use usage_report::UsageSummary;

Modules§

actions: Action management for Redis Enterprise async operations
alerts: Alert configuration and management
bdb: Database (BDB) management for Redis Enterprise
bdb_groups: Database group configuration
bootstrap: Cluster bootstrap and node joining operations
client: REST API client implementation
cluster: Cluster management for Redis Enterprise
cm_settings: Cluster Manager configuration
crdb: Active-Active (CRDB) database management
crdb_tasks: Active-Active database task operations
debuginfo: Debuginfo management for Redis Enterprise
diagnostics: Diagnostics management for Redis Enterprise
endpoints: Database endpoint configuration and monitoring
error: Error types for REST API operations
job_scheduler: Scheduled job management
jsonschema: JSON Schema definitions for API validation
ldap_mappings: LDAP integration and role mapping
license: License management and validation
local: Local node operations and health checks
logs: Log management and retrieval
migrations: Database migration operations
modules: Redis module management
nodes: Nodes management for Redis Enterprise
ocsp: OCSP certificate validation
proxies: Proxies management for Redis Enterprise
redis_acls: Redis ACL management
roles: Role-based access control
services: Service configuration and management
shards: Shards management for Redis Enterprise
stats: Statistics and metrics collection for Redis Enterprise
suffixes: Database name suffix management
types: Specialized types for Redis Enterprise API objects
usage_report: Usage reporting and telemetry
users: Users management for Redis Enterprise