Skip to content

Commit 1c6f6dd

Browse files
joshrotenbergjoshrotenberg
authored
docs(redis-enterprise): add comprehensive field-level documentation for all API structs (#273)
* docs(redis-enterprise): add comprehensive field documentation from REST API - CRDB: documented all fields with descriptions from API docs - CrdbInstance: added field descriptions for instance configuration - CreateCrdbRequest: documented request fields for Active-Active setup - CreateCrdbInstance: documented instance creation fields - DiagnosticRequest: documented diagnostic check request fields - DiagnosticResult: documented check result fields - DiagnosticReport: documented report structure fields - DiagnosticSummary: documented summary statistics fields All field descriptions based on Redis Enterprise REST API documentation to provide clear guidance for developers using these structs. * docs(redis-enterprise): add comprehensive field-level documentation for all API structs Added detailed documentation for every field in all API response structs across the redis-enterprise crate, based on official Redis Enterprise REST API docs. Files documented (17 files, 50+ structs, 300+ fields): - actions.rs: Action struct with status, progress, timestamps - alerts.rs: Alert, AlertSettings, and alert configuration structs - bdb_groups.rs: BdbGroup database group management - bootstrap.rs: Bootstrap configuration and status structs - cm_settings.rs: CmSettings cluster manager configuration - crdb_tasks.rs: CrdbTask CRDB operation tracking - debuginfo.rs: DebugInfo request and status structs - job_scheduler.rs: ScheduledJob and JobExecution structs - ldap_mappings.rs: LDAP configuration and mapping structs - license.rs: License and usage tracking structs - logs.rs: LogEntry and query structs - migrations.rs: Migration and endpoint configuration - ocsp.rs: OCSP configuration and status structs - services.rs: Service configuration and status - stats.rs: Statistics query and response structs - suffixes.rs: DNS suffix management structs - usage_report.rs: Usage reporting and summary structs Documentation includes: - Field purposes and usage descriptions - Data types and formats (ISO 8601, percentages, bytes) - Enum values for status/state fields - Read-only indicators for system fields - Units of measurement where applicable - References to related API concepts This significantly improves developer experience with better IDE support, code completion, and self-documenting API structures. * fix(tests): correct JSON field name for license type in tests The License struct has #[serde(rename = "type")] annotation, so JSON responses should use "type" not "type_". This was causing test failures after adding field documentation. Fixed all occurrences in license_tests.rs where mock responses were using "type_" instead of "type".
1 parent df7c8b2 commit 1c6f6dd

20 files changed

+300
-13
lines changed

‎crates/redis-enterprise/src/actions.rs‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,23 @@ use serde_json::Value;
1414
/// Represents an action (operation) in the cluster
1515
#[derive(Debug, Clone, Serialize, Deserialize)]
1616
pub struct Action {
17+
/// Action's unique identifier (read-only)
1718
pub action_uid: String,
19+
/// Action's name (read-only)
1820
pub name: String,
21+
/// Current status of the action
22+
///
23+
/// Possible values: 'queued', 'starting', 'running', 'cancelling', 'cancelled', 'completed', 'failed'
1924
pub status: String,
25+
/// Percent of completed steps in current action (0-100)
2026
pub progress: Option<f32>,
27+
/// ISO 8601 timestamp when the action was started
2128
pub start_time: Option<String>,
29+
/// ISO 8601 timestamp when the action completed or failed
2230
pub end_time: Option<String>,
31+
/// Human-readable description of the action
2332
pub description: Option<String>,
33+
/// Error message if the action failed
2434
pub error: Option<String>,
2535
/// Database UID associated with the action
2636
pub bdb_uid: Option<u32>,

‎crates/redis-enterprise/src/alerts.rs‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,25 +11,37 @@ use serde::{Deserialize, Serialize};
1111
use serde_json::Value;
1212

1313
/// Alert information
14+
/// Represents an alert state for a cluster object (database, node, or cluster)
1415
#[derive(Debug, Clone, Serialize, Deserialize)]
1516
pub struct Alert {
17+
/// Unique identifier for the alert
1618
pub uid: String,
19+
/// Name/type of the alert
1720
pub name: String,
21+
/// Alert severity level: DEBUG, INFO, WARNING, ERROR, CRITICAL
1822
pub severity: String,
23+
/// Current alert state - true if alert is currently triggered
1924
pub state: String,
2025
#[serde(skip_serializing_if = "Option::is_none")]
26+
/// Type of entity this alert is associated with (e.g., "bdb", "node", "cluster")
2127
pub entity_type: Option<String>,
2228
#[serde(skip_serializing_if = "Option::is_none")]
29+
/// Name of the entity this alert is associated with
2330
pub entity_name: Option<String>,
2431
#[serde(skip_serializing_if = "Option::is_none")]
32+
/// UID of the entity this alert is associated with
2533
pub entity_uid: Option<String>,
2634
#[serde(skip_serializing_if = "Option::is_none")]
35+
/// String representing an alert threshold when applicable
2736
pub threshold: Option<Value>,
2837
#[serde(skip_serializing_if = "Option::is_none")]
38+
/// ISO 8601 timestamp when alert state last changed
2939
pub change_time: Option<String>,
3040
#[serde(skip_serializing_if = "Option::is_none")]
41+
/// Object containing data relevant to the evaluation time when the alert went on/off (thresholds/sampled values/etc.)
3142
pub change_value: Option<Value>,
3243
#[serde(skip_serializing_if = "Option::is_none")]
44+
/// Human-readable description of the alert
3345
pub description: Option<String>,
3446
/// Error code associated with the alert
3547
#[serde(skip_serializing_if = "Option::is_none")]
@@ -42,19 +54,25 @@ pub struct Alert {
4254
/// Generic alert settings (legacy - kept for compatibility)
4355
#[derive(Debug, Clone, Serialize, Deserialize)]
4456
pub struct AlertSettings {
57+
/// True if alert is enabled
4558
pub enabled: bool,
4659
#[serde(skip_serializing_if = "Option::is_none")]
60+
/// Alert threshold value when applicable
4761
pub threshold: Option<Value>,
4862
#[serde(skip_serializing_if = "Option::is_none")]
63+
/// List of email addresses to notify when alert triggers
4964
pub email_recipients: Option<Vec<String>>,
5065
#[serde(skip_serializing_if = "Option::is_none")]
66+
/// Webhook URL to call when alert triggers
5167
pub webhook_url: Option<String>,
5268
}
5369

5470
/// Database alert settings with threshold
5571
#[derive(Debug, Clone, Serialize, Deserialize)]
5672
pub struct BdbAlertSettingsWithThreshold {
73+
/// True if alert is enabled
5774
pub enabled: bool,
75+
/// String representing the alert threshold value
5876
pub threshold: String,
5977
}
6078

@@ -140,11 +158,15 @@ pub struct DbAlertsSettings {
140158
/// Cluster alert settings with threshold
141159
#[derive(Debug, Clone, Serialize, Deserialize)]
142160
pub struct ClusterAlertSettingsWithThreshold {
161+
/// True if alert is enabled
143162
pub enabled: bool,
163+
/// String representing the alert threshold value
144164
pub threshold: String,
145165
#[serde(skip_serializing_if = "Option::is_none")]
166+
/// List of email addresses to notify when alert triggers
146167
pub email: Option<Vec<String>>,
147168
#[serde(skip_serializing_if = "Option::is_none")]
169+
/// Webhook URL to call when alert triggers
148170
pub webhook_url: Option<String>,
149171
}
150172

‎crates/redis-enterprise/src/bdb_groups.rs‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,19 @@ use serde::{Deserialize, Serialize};
1111
use serde_json::Value;
1212

1313
/// Database group information
14+
/// Represents a group of databases that share a memory pool
1415
#[derive(Debug, Clone, Serialize, Deserialize)]
1516
pub struct BdbGroup {
17+
/// Cluster unique ID of the database group
1618
pub uid: u32,
19+
/// Group name (may be auto-generated if not specified)
1720
pub name: String,
21+
/// The common memory pool size limit for all databases in the group, expressed in bytes
22+
#[serde(skip_serializing_if = "Option::is_none")]
23+
pub memory_size: Option<u64>,
24+
/// A list of UIDs of member databases (read-only)
25+
#[serde(skip_serializing_if = "Option::is_none")]
26+
pub members: Option<Vec<String>>,
1827
#[serde(flatten)]
1928
pub extra: Value,
2029
}

‎crates/redis-enterprise/src/bootstrap.rs‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,16 @@ use serde_json::Value;
1313
/// Bootstrap configuration for cluster initialization
1414
#[derive(Debug, Clone, Serialize, Deserialize)]
1515
pub struct BootstrapConfig {
16+
/// Action to perform (e.g., 'create', 'join', 'recover_cluster')
1617
pub action: String,
1718
#[serde(skip_serializing_if = "Option::is_none")]
19+
/// Cluster configuration for initialization
1820
pub cluster: Option<ClusterBootstrap>,
1921
#[serde(skip_serializing_if = "Option::is_none")]
22+
/// Node configuration for bootstrap
2023
pub node: Option<NodeBootstrap>,
2124
#[serde(skip_serializing_if = "Option::is_none")]
25+
/// Admin credentials for cluster access
2226
pub credentials: Option<CredentialsBootstrap>,
2327

2428
#[serde(flatten)]
@@ -28,43 +32,54 @@ pub struct BootstrapConfig {
2832
/// Cluster bootstrap configuration
2933
#[derive(Debug, Clone, Serialize, Deserialize)]
3034
pub struct ClusterBootstrap {
35+
/// Cluster name for identification
3136
pub name: String,
3237
#[serde(skip_serializing_if = "Option::is_none")]
38+
/// DNS suffixes for cluster FQDN resolution
3339
pub dns_suffixes: Option<Vec<String>>,
3440
#[serde(skip_serializing_if = "Option::is_none")]
41+
/// Enable rack-aware placement for high availability
3542
pub rack_aware: Option<bool>,
3643
}
3744

3845
/// Node bootstrap configuration
3946
#[derive(Debug, Clone, Serialize, Deserialize)]
4047
pub struct NodeBootstrap {
4148
#[serde(skip_serializing_if = "Option::is_none")]
49+
/// Storage paths configuration for the node
4250
pub paths: Option<NodePaths>,
4351
}
4452

4553
/// Node paths configuration
4654
#[derive(Debug, Clone, Serialize, Deserialize)]
4755
pub struct NodePaths {
4856
#[serde(skip_serializing_if = "Option::is_none")]
57+
/// Path for persistent storage (databases, configuration, logs)
4958
pub persistent_path: Option<String>,
5059
#[serde(skip_serializing_if = "Option::is_none")]
60+
/// Path for ephemeral storage (temporary files, caches)
5161
pub ephemeral_path: Option<String>,
5262
}
5363

5464
/// Credentials bootstrap configuration
5565
#[derive(Debug, Clone, Serialize, Deserialize)]
5666
pub struct CredentialsBootstrap {
67+
/// Admin username for cluster management
5768
pub username: String,
69+
/// Admin password for authentication
5870
pub password: String,
5971
}
6072

6173
/// Bootstrap status response
6274
#[derive(Debug, Clone, Serialize, Deserialize)]
6375
pub struct BootstrapStatus {
76+
/// Current status of the bootstrap operation
6477
pub status: String,
6578
#[serde(skip_serializing_if = "Option::is_none")]
79+
/// Progress percentage (0.0-100.0) of the bootstrap operation
6680
pub progress: Option<f32>,
6781
#[serde(skip_serializing_if = "Option::is_none")]
82+
/// Status message or error description
6883
pub message: Option<String>,
6984

7085
#[serde(flatten)]

‎crates/redis-enterprise/src/cm_settings.rs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,25 @@ use serde_json::Value;
1313
/// Cluster Manager settings
1414
#[derive(Debug, Clone, Serialize, Deserialize)]
1515
pub struct CmSettings {
16+
/// Port number for the Cluster Manager service
1617
#[serde(skip_serializing_if = "Option::is_none")]
1718
pub cm_port: Option<u16>,
19+
/// Session timeout for Cluster Manager connections in seconds
1820
#[serde(skip_serializing_if = "Option::is_none")]
1921
pub cm_session_timeout: Option<u32>,
22+
/// Enable automatic recovery of failed databases
2023
#[serde(skip_serializing_if = "Option::is_none")]
2124
pub auto_recovery: Option<bool>,
25+
/// Enable automatic failover for high availability
2226
#[serde(skip_serializing_if = "Option::is_none")]
2327
pub auto_failover: Option<bool>,
28+
/// Enable slave high availability for replica databases
2429
#[serde(skip_serializing_if = "Option::is_none")]
2530
pub slave_ha: Option<bool>,
31+
/// Grace period in seconds before triggering slave high availability
2632
#[serde(skip_serializing_if = "Option::is_none")]
2733
pub slave_ha_grace_period: Option<u32>,
34+
/// Maximum number of simultaneous backup operations allowed
2835
#[serde(skip_serializing_if = "Option::is_none")]
2936
pub max_simultaneous_backups: Option<u32>,
3037

‎crates/redis-enterprise/src/crdb.rs‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,23 @@ use typed_builder::TypedBuilder;
1414
/// CRDB (Active-Active Database) information
1515
#[derive(Debug, Clone, Serialize, Deserialize)]
1616
pub struct Crdb {
17+
/// The GUID of the Active-Active database
1718
pub guid: String,
19+
/// Name of Active-Active database
1820
pub name: String,
21+
/// Current status of the Active-Active database
1922
pub status: String,
23+
/// Database memory size limit, in bytes
2024
pub memory_size: u64,
25+
/// List of participating instances in the Active-Active setup
2126
pub instances: Vec<CrdbInstance>,
27+
/// Whether communication encryption is enabled
2228
pub encryption: Option<bool>,
29+
/// Database on-disk persistence policy
2330
pub data_persistence: Option<String>,
31+
/// Whether database replication is enabled
2432
pub replication: Option<bool>,
33+
/// Data eviction policy (e.g., 'allkeys-lru', 'volatile-lru')
2534
pub eviction_policy: Option<String>,
2635

2736
#[serde(flatten)]
@@ -31,10 +40,15 @@ pub struct Crdb {
3140
/// CRDB instance information
3241
#[derive(Debug, Clone, Serialize, Deserialize)]
3342
pub struct CrdbInstance {
43+
/// Unique instance ID
3444
pub id: u32,
45+
/// Cluster fully qualified name
3546
pub cluster: String,
47+
/// Human-readable cluster name
3648
pub cluster_name: Option<String>,
49+
/// Current status of this instance
3750
pub status: String,
51+
/// List of endpoint addresses for this instance
3852
pub endpoints: Option<Vec<String>>,
3953

4054
#[serde(flatten)]
@@ -71,16 +85,22 @@ pub struct CrdbInstance {
7185
/// ```
7286
#[derive(Debug, Serialize, TypedBuilder)]
7387
pub struct CreateCrdbRequest {
88+
/// Name of the Active-Active database
7489
#[builder(setter(into))]
7590
pub name: String,
91+
/// Database memory size limit, in bytes
7692
pub memory_size: u64,
93+
/// List of participating cluster instances
7794
pub instances: Vec<CreateCrdbInstance>,
95+
/// Whether to encrypt communication between instances
7896
#[serde(skip_serializing_if = "Option::is_none")]
7997
#[builder(default, setter(strip_option))]
8098
pub encryption: Option<bool>,
99+
/// Database on-disk persistence policy ('disabled', 'aof', 'snapshot')
81100
#[serde(skip_serializing_if = "Option::is_none")]
82101
#[builder(default, setter(into, strip_option))]
83102
pub data_persistence: Option<String>,
103+
/// Data eviction policy when memory limit is reached
84104
#[serde(skip_serializing_if = "Option::is_none")]
85105
#[builder(default, setter(into, strip_option))]
86106
pub eviction_policy: Option<String>,
@@ -89,14 +109,18 @@ pub struct CreateCrdbRequest {
89109
/// Create CRDB instance
90110
#[derive(Debug, Serialize, TypedBuilder)]
91111
pub struct CreateCrdbInstance {
112+
/// Cluster fully qualified name, used to uniquely identify the cluster
92113
#[builder(setter(into))]
93114
pub cluster: String,
115+
/// Cluster access URL (e.g., 'https://cluster1.example.com:9443')
94116
#[serde(skip_serializing_if = "Option::is_none")]
95117
#[builder(default, setter(into, strip_option))]
96118
pub cluster_url: Option<String>,
119+
/// Username for cluster authentication
97120
#[serde(skip_serializing_if = "Option::is_none")]
98121
#[builder(default, setter(into, strip_option))]
99122
pub username: Option<String>,
123+
/// Password for cluster authentication
100124
#[serde(skip_serializing_if = "Option::is_none")]
101125
#[builder(default, setter(into, strip_option))]
102126
pub password: Option<String>,

‎crates/redis-enterprise/src/crdb_tasks.rs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,16 +14,24 @@ use typed_builder::TypedBuilder;
1414
/// CRDB task information
1515
#[derive(Debug, Clone, Serialize, Deserialize)]
1616
pub struct CrdbTask {
17+
/// Unique task identifier
1718
pub task_id: String,
19+
/// Globally unique Active-Active database ID (GUID)
1820
pub crdb_guid: String,
21+
/// Type of task being executed
1922
pub task_type: String,
23+
/// Current status of the task (queued, running, completed, failed)
2024
pub status: String,
25+
/// Task completion progress as a percentage (0.0-100.0)
2126
#[serde(skip_serializing_if = "Option::is_none")]
2227
pub progress: Option<f32>,
28+
/// Timestamp when the task was started (ISO 8601 format)
2329
#[serde(skip_serializing_if = "Option::is_none")]
2430
pub start_time: Option<String>,
31+
/// Timestamp when the task was completed or failed (ISO 8601 format)
2532
#[serde(skip_serializing_if = "Option::is_none")]
2633
pub end_time: Option<String>,
34+
/// Error description if the task failed
2735
#[serde(skip_serializing_if = "Option::is_none")]
2836
pub error: Option<String>,
2937

@@ -34,10 +42,13 @@ pub struct CrdbTask {
3442
/// CRDB task creation request
3543
#[derive(Debug, Clone, Serialize, Deserialize, TypedBuilder)]
3644
pub struct CreateCrdbTaskRequest {
45+
/// Globally unique Active-Active database ID (GUID) for the target CRDB
3746
#[builder(setter(into))]
3847
pub crdb_guid: String,
48+
/// Type of task to create (e.g., "flush", "purge", "update_config")
3949
#[builder(setter(into))]
4050
pub task_type: String,
51+
/// Optional parameters specific to the task type
4152
#[serde(skip_serializing_if = "Option::is_none")]
4253
#[builder(default, setter(strip_option))]
4354
pub params: Option<Value>,

‎crates/redis-enterprise/src/debuginfo.rs‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,21 +14,27 @@ use typed_builder::TypedBuilder;
1414
/// Debug info collection request
1515
#[derive(Debug, Clone, Serialize, Deserialize, TypedBuilder)]
1616
pub struct DebugInfoRequest {
17+
/// List of node UIDs to collect debug info from (if not specified, collects from all nodes)
1718
#[serde(skip_serializing_if = "Option::is_none")]
1819
#[builder(default, setter(strip_option))]
1920
pub node_uids: Option<Vec<u32>>,
21+
/// List of database UIDs to collect debug info for (if not specified, collects for all databases)
2022
#[serde(skip_serializing_if = "Option::is_none")]
2123
#[builder(default, setter(strip_option))]
2224
pub bdb_uids: Option<Vec<u32>>,
25+
/// Whether to include log files in the debug info collection
2326
#[serde(skip_serializing_if = "Option::is_none")]
2427
#[builder(default, setter(strip_option))]
2528
pub include_logs: Option<bool>,
29+
/// Whether to include system and database metrics in the debug info
2630
#[serde(skip_serializing_if = "Option::is_none")]
2731
#[builder(default, setter(strip_option))]
2832
pub include_metrics: Option<bool>,
33+
/// Whether to include configuration files and settings
2934
#[serde(skip_serializing_if = "Option::is_none")]
3035
#[builder(default, setter(strip_option))]
3136
pub include_configs: Option<bool>,
37+
/// Time range for collecting historical data and logs
3238
#[serde(skip_serializing_if = "Option::is_none")]
3339
#[builder(default, setter(strip_option))]
3440
pub time_range: Option<TimeRange>,
@@ -37,19 +43,26 @@ pub struct DebugInfoRequest {
3743
/// Time range for debug info collection
3844
#[derive(Debug, Clone, Serialize, Deserialize)]
3945
pub struct TimeRange {
46+
/// Start time for data collection (ISO 8601 format)
4047
pub start: String,
48+
/// End time for data collection (ISO 8601 format)
4149
pub end: String,
4250
}
4351

4452
/// Debug info status
4553
#[derive(Debug, Clone, Serialize, Deserialize)]
4654
pub struct DebugInfoStatus {
55+
/// Unique identifier for the debug info collection task
4756
pub task_id: String,
57+
/// Current status of the debug info collection (queued, running, completed, failed)
4858
pub status: String,
59+
/// Completion progress as a percentage (0.0-100.0)
4960
#[serde(skip_serializing_if = "Option::is_none")]
5061
pub progress: Option<f32>,
62+
/// URL for downloading the collected debug info package
5163
#[serde(skip_serializing_if = "Option::is_none")]
5264
pub download_url: Option<String>,
65+
/// Error description if the collection task failed
5366
#[serde(skip_serializing_if = "Option::is_none")]
5467
pub error: Option<String>,
5568

0 commit comments

Comments
 (0)